パッケージの詳細

bounding-rect

jvy170MIT2.0.0

A high-performance 2D rectangle manipulation library, providing efficient rectangle creation, transformation, and intersection detection capabilities

bounding-box, rectangle, 2d, collision-detection

readme

bounding-rect

高性能2D矩形操作库，提供高效的矩形创建、变换和相交检测功能，专为图形应用和碰撞检测优化。

安装

npm install bounding-rect

特性

  • 高性能设计：基于Float32Array实现，优化CPU缓存利用率
  • SIMD友好：固定长度数组结构，适配并行计算指令
  • 无分支逻辑：减少CPU预测错误，提升执行效率
  • 丰富的创建方式：支持从点集、线段、贝塞尔曲线等创建矩形
  • 完善的相交检测：包括基础检测、方向约束检测和批量检测
  • 矩阵变换支持：兼容mat3库，支持各种2D变换操作

快速开始

import { 
  createRect, 
  set, 
  fromPoints, 
  intersects,
  createVec2 
} from 'bounding-rect';

// 创建矩形
const rect = createRect();
set(rect, 10, 20, 100, 200);

// 从点集创建包围矩形
const points = new Float32Array([0,0, 50,30, 20,60]);
const boundingRect = createRect();
fromPoints(boundingRect, points);

// 相交检测
const rectA = createRect();
set(rectA, 0, 0, 100, 100);
const rectB = createRect();
set(rectB, 50, 50, 100, 100);
const mtv = createVec2();
const hasIntersection = intersects(rectA, rectB, mtv);

console.log('是否相交:', hasIntersection);
console.log('最小平移向量:', mtv);

API 文档

实例创建

createRect(): Float32Array

创建一个矩形实例，结构为[x, y, width, height]，初始值全为0。

createVec2(): Float32Array

创建一个2D向量实例，结构为[x, y, _, _]，后两位预留用于16字节对齐。

createIntersectOpt(): Float32Array

创建相交检测选项实例，结构为[direction, bidirectional, touchThreshold, clamp]，带有默认配置。

矩形创建

set(out: Float32Array, x: number, y: number, width: number, height: number): void

设置矩形的位置和尺寸，自动修正负的宽高值。

fromCenter(out: Float32Array, cx: number, cy: number, width: number, height: number): void

从中心点创建矩形。

fromPoints(out: Float32Array, points: Float32Array): void

从点集创建包围矩形，计算能够包含所有点的最小矩形。

fromLine(out: Float32Array, x0: number, y0: number, x1: number, y1: number): void

从线段创建包围矩形。

fromCubic(out: Float32Array, x0: number, y0: number, x1: number, y1: number, x2: number, y2: number, x3: number, y3: number): void

从三阶贝塞尔曲线创建包围矩形，考虑曲线的极值点。

矩形操作

copy(out: Float32Array, a: Float32Array): void

复制矩形数据。

union(out: Float32Array, a: Float32Array, b: Float32Array): void

合并两个矩形，计算能够同时包含两个矩形的最小矩形。

expand(out: Float32Array, rect: Float32Array, amount: number): void

向矩形的四周均匀扩展指定的距离。

contract(out: Float32Array, rect: Float32Array, amount: number): void

从矩形的四周均匀收缩指定的距离。

getCenter(out: Float32Array, rect: Float32Array): void

获取矩形的中心点坐标。

contains(rect: Float32Array, x: number, y: number): 0 | 1

检查点是否在矩形内，返回1表示在矩形内，0表示不在。

矩阵变换

transformNoRotate(out: Float32Array, rect: Float32Array, m: Float32Array): void

矩形应用无旋转变换（快速路径），适用于仅包含平移和缩放的变换。

transform(out: Float32Array, rect: Float32Array, m: Float32Array): void

矩形应用通用变换，适用于包含旋转、剪切等的复杂变换。

相交检测

intersects(a: Float32Array, b: Float32Array, mtv: Float32Array): 0 | 1

基础相交检测，检测两个矩形是否相交，并计算最小平移向量（MTV）。

intersectsSmall(a: Float32Array, b: Float32Array, mtv: Float32Array): 0 | 1

小矩形专用相交检测，针对尺寸较小的矩形优化。

intersectsWithDir(a: Float32Array, b: Float32Array, mtv: Float32Array, dir: number): 0 | 1

带方向约束的相交检测，仅检测特定方向上的相交。

intersectsWithOpt(a: Float32Array, b: Float32Array, mtv: Float32Array, opt: Float32Array): 0 | 1

带选项的相交检测，支持配置接触阈值、检测方向等参数。

intersectsBatch(rect: Float32Array, others: Float32Array[], count: number, outResults: Uint8Array): void

批量检测矩形与矩形数组的相交情况，高效处理多个检测。

批量计算

areaBatchSIMD(rects: Float32Array[], count: number, outAreas: Float32Array): void

批量计算矩形面积，高效计算多个矩形的面积。

辅助工具

isEmpty(rect: Float32Array): 0 | 1

检查矩形是否为空，返回1表示为空，0表示非空。

isFinite(rect: Float32Array): 0 | 1

检查矩形是否有效（所有值均为有限数），返回1表示有效，0表示无效。

area(rect: Float32Array): number

计算矩形的面积。

distance(a: Float32Array, b: Float32Array): number

计算两个矩形之间的距离。

性能优化

  • 内存布局：使用连续的Float32Array存储，提升CPU缓存利用率
  • 循环展开：对批量操作采用4元素一组的循环展开，提升并行处理效率
  • 无分支逻辑：通过数学运算代替条件判断，减少CPU预测错误
  • SIMD友好：数据结构设计考虑CPU的单指令多数据指令优化

依赖

本库依赖mat3库进行矩阵运算，会自动安装。

许可证

MIT