bounding-rect

bounding-rect

A high-performance 2D rectangle manipulation library, providing efficient rectangle creation, transformation, and intersection detection capabilities, optimized for graphics applications and collision detection.

Installation

npm install bounding-rect

Features

• High-performance design: Based on Float32Array for optimized CPU cache utilization
• SIMD-friendly: Fixed-length array structure, adapted for parallel computing instructions
• Branchless logic: Reduces CPU prediction errors and improves execution efficiency
• Versatile creation methods: Supports creating rectangles from point sets, line segments, Bézier curves, etc.
• Comprehensive intersection detection: Including basic detection, direction-constrained detection, and batch detection
• Matrix transformation support: Compatible with mat3 library, supporting various 2D transformation operations

Quick Start

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

// Create a rectangle
const rect = createRect();
set(rect, 10, 20, 100, 200);

// Create bounding rectangle from points
const points = new Float32Array([0,0, 50,30, 20,60]);
const boundingRect = createRect();
fromPoints(boundingRect, points);

// Intersection detection
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('Intersecting:', hasIntersection);
console.log('Minimum translation vector:', mtv);

API Documentation

Instance Creation

createRect(): Float32Array

Creates a rectangle instance with structure [x, y, width, height], initialized to all zeros.

createVec2(): Float32Array

Creates a 2D vector instance with structure [x, y, _, _], with the last two elements reserved for 16-byte alignment.

createIntersectOpt(): Float32Array

Creates an intersection detection options instance with structure [direction, bidirectional, touchThreshold, clamp] with default configurations.

Rectangle Creation

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

Sets the position and dimensions of a rectangle, automatically correcting negative width and height values.

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

Creates a rectangle from a center point.

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

Creates a bounding rectangle from a set of points, calculating the smallest rectangle that can contain all points.

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

Creates a bounding rectangle from a line segment.

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

Creates a bounding rectangle from a cubic Bézier curve, considering the curve's extrema points.

Rectangle Operations

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

Copies rectangle data from one rectangle to another.

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

Merges two rectangles, calculating the smallest rectangle that can contain both.

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

Uniformly expands a rectangle in all directions by a specified distance.

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

Uniformly contracts a rectangle from all sides by a specified distance.

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

Gets the center point coordinates of a rectangle.

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

Checks if a point is inside a rectangle, returns 1 if inside, 0 if outside.

Matrix Transformations

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

Applies a non-rotational transformation to a rectangle (fast path), suitable for transformations containing only translation and scaling.

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

Applies a general transformation to a rectangle, suitable for complex transformations including rotation and shearing.

Intersection Detection

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

Basic intersection detection, checks if two rectangles intersect and calculates the minimum translation vector (MTV).

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

Specialized intersection detection for small rectangles, optimized for rectangles with smaller dimensions.

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

Direction-constrained intersection detection, only detects intersections in a specific direction.

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

Intersection detection with options, supporting configuration of contact threshold, detection direction, etc.

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

Batch detection of intersections between a rectangle and an array of rectangles, efficiently handling multiple detections.

Batch Calculations

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

Batch calculates the area of rectangles, efficiently computing areas for multiple rectangles.

Utility Functions

isEmpty(rect: Float32Array): 0 | 1

Checks if a rectangle is empty, returns 1 if empty, 0 if non-empty.

isFinite(rect: Float32Array): 0 | 1

Checks if a rectangle is valid (all values are finite numbers), returns 1 if valid, 0 if invalid.

area(rect: Float32Array): number

Calculates the area of a rectangle.

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

Calculates the distance between two rectangles.

Performance Optimizations

• Memory layout: Uses contiguous Float32Array storage for improved CPU cache utilization
• Loop unrolling: Uses 4-element loop unrolling for batch operations to improve parallel processing efficiency
• Branchless logic: Replaces conditional judgments with mathematical operations to reduce CPU prediction errors
• SIMD-friendly: Data structure design considers CPU's Single Instruction Multiple Data (SIMD) optimization

Dependencies

This library depends on the mat3 library for matrix operations, which will be installed automatically.

License

MIT