@maxellabs/math

Maxellabs 3D Engine 的高性能数学库，提供3D图形和游戏开发所需的核心数学运算和数据结构。

🚀 特性

核心数学类型

• Vector2/3/4: 高性能向量运算，支持SIMD优化
• Matrix3/4: 矩阵运算，针对3D变换优化
• Quaternion: 四元数旋转，避免万向锁问题
• Euler: 欧拉角转换和运算
• Color: 颜色空间转换和运算

几何计算

• Ray: 射线投射和相交检测
• Box3: 3D轴对齐包围盒
• Sphere: 3D球体碰撞检测
• Plane: 平面方程和距离计算

性能优化

• 对象池: 减少GC压力，提高内存利用率
• SIMD支持: 利用现代CPU的向量指令集
• 内存对齐: 优化缓存访问模式
• 批量运算: 支持数组批量处理

规范兼容

• USD兼容: 完全兼容USD格式的数据类型
• TypeScript: 完整的类型定义和智能提示
• 模块化: 支持按需导入，减少包体积

📦 安装

npm install @maxellabs/math
# 或
yarn add @maxellabs/math
# 或
pnpm add @maxellabs/math

🔧 使用示例

基础向量运算

import { Vector3, Matrix4, Quaternion } from '@maxellabs/math';

// 创建向量（使用对象池）
const v1 = Vector3.create(1, 2, 3);
const v2 = Vector3.create(4, 5, 6);

// 向量运算
const result = v1.add(v2).normalize();

// 释放到对象池
Vector3.release(v1);
Vector3.release(v2);
Vector3.release(result);

矩阵变换

import { Matrix4, Vector3, Quaternion } from '@maxellabs/math';

// 创建变换矩阵
const transform = Matrix4.create();
const position = Vector3.create(10, 0, 0);
const rotation = Quaternion.create().setFromEuler(0, Math.PI / 2, 0);
const scale = Vector3.create(2, 2, 2);

// 组合变换
transform.compose(position, rotation, scale);

// 应用变换
const point = Vector3.create(1, 1, 1);
transform.transformPoint(point);

批量运算

import { Vector3Batch, Matrix4 } from '@maxellabs/math';

// 批量向量运算
const positions = new Float32Array([
  1, 2, 3,
  4, 5, 6,
  7, 8, 9
]);

const transform = Matrix4.create().makeRotationY(Math.PI / 4);

// 批量变换（SIMD优化）
Vector3Batch.transformArray(positions, transform);

几何相交检测

import { Ray, Box3, Sphere } from '@maxellabs/math';

// 射线与包围盒相交
const ray = new Ray(Vector3.ZERO, Vector3.X);
const box = new Box3(Vector3.create(-1, -1, -1), Vector3.create(1, 1, 1));

const intersection = ray.intersectBox(box);
if (intersection) {
  console.log('相交点:', intersection);
}

// 球体碰撞检测
const sphere1 = new Sphere(Vector3.ZERO, 1);
const sphere2 = new Sphere(Vector3.create(1.5, 0, 0), 1);

if (sphere1.intersectsSphere(sphere2)) {
  console.log('球体相交');
}

�� API 文档

核心类型

Vector3

class Vector3 {
  // 构造函数
  constructor(x?: number, y?: number, z?: number);
  
  // 静态方法（对象池）
  static create(x?: number, y?: number, z?: number): Vector3;
  static release(vector: Vector3): void;
  
  // 基础运算
  add(v: Vector3 | number): this;
  subtract(v: Vector3 | number): this;
  multiply(v: Vector3 | number): this;
  divide(v: Vector3 | number): this;
  
  // 向量运算
  dot(v: Vector3): number;
  cross(v: Vector3): this;
  normalize(): this;
  length(): number;
  
  // 变换
  applyMatrix4(m: Matrix4): this;
  applyQuaternion(q: Quaternion): this;
}

Matrix4

class Matrix4 {
  // 构造函数
  constructor();
  
  // 静态方法（对象池）
  static create(): Matrix4;
  static release(matrix: Matrix4): void;
  
  // 矩阵运算
  multiply(m: Matrix4): this;
  invert(): this;
  transpose(): this;
  
  // 变换构建
  makeTranslation(v: Vector3): this;
  makeRotationFromQuaternion(q: Quaternion): this;
  makeScale(v: Vector3): this;
  compose(position: Vector3, rotation: Quaternion, scale: Vector3): this;
  
  // 投影矩阵
  makePerspective(fov: number, aspect: number, near: number, far: number): this;
  makeOrthographic(left: number, right: number, bottom: number, top: number, near: number, far: number): this;
}

Quaternion

class Quaternion {
  // 构造函数
  constructor(x?: number, y?: number, z?: number, w?: number);
  
  // 静态方法（对象池）
  static create(x?: number, y?: number, z?: number, w?: number): Quaternion;
  static release(quaternion: Quaternion): void;
  
  // 旋转构建
  setFromEuler(x: number, y: number, z: number, order?: string): this;
  setFromAxisAngle(axis: Vector3, angle: number): this;
  setFromRotationMatrix(m: Matrix4): this;
  
  // 四元数运算
  multiply(q: Quaternion): this;
  slerp(q: Quaternion, t: number): this;
  conjugate(): this;
  normalize(): this;
}

批量运算

Vector3Batch

class Vector3Batch {
  // 批量变换（SIMD优化）
  static transformArray(vectors: Float32Array, matrix: Matrix4): void;
  static normalizeArray(vectors: Float32Array): void;
  static addArrays(a: Float32Array, b: Float32Array, result: Float32Array): void;
  
  // 批量计算
  static computeBounds(vectors: Float32Array): Box3;
  static computeCenter(vectors: Float32Array): Vector3;
}

几何类型

Ray

class Ray {
  constructor(origin: Vector3, direction: Vector3);
  
  // 相交检测
  intersectBox(box: Box3): Vector3 | null;
  intersectSphere(sphere: Sphere): Vector3 | null;
  intersectPlane(plane: Plane): Vector3 | null;
  
  // 距离计算
  distanceToPoint(point: Vector3): number;
  closestPointToPoint(point: Vector3): Vector3;
}

Box3

class Box3 {
  constructor(min?: Vector3, max?: Vector3);
  
  // 包围盒运算
  expandByPoint(point: Vector3): this;
  expandByBox(box: Box3): this;
  intersectsBox(box: Box3): boolean;
  containsPoint(point: Vector3): boolean;
  
  // 属性计算
  getCenter(): Vector3;
  getSize(): Vector3;
  getVolume(): number;
}

⚡ 性能优化

对象池使用

// 推荐：使用对象池
const v1 = Vector3.create(1, 2, 3);
const v2 = Vector3.create(4, 5, 6);
const result = v1.add(v2);

// 使用完毕后释放
Vector3.release(v1);
Vector3.release(v2);
Vector3.release(result);

// 不推荐：频繁创建新对象
const v1 = new Vector3(1, 2, 3); // 会产生GC压力

SIMD优化

// 自动检测SIMD支持
if (Vector3.hasSIMDSupport()) {
  // 使用SIMD优化的批量运算
  Vector3Batch.transformArray(positions, transform);
} else {
  // 回退到标准实现
  for (let i = 0; i < positions.length; i += 3) {
    const v = Vector3.create(positions[i], positions[i + 1], positions[i + 2]);
    v.applyMatrix4(transform);
    positions[i] = v.x;
    positions[i + 1] = v.y;
    positions[i + 2] = v.z;
    Vector3.release(v);
  }
}

内存对齐

// 使用TypedArray提高性能
const positions = new Float32Array(vertexCount * 3);
const normals = new Float32Array(vertexCount * 3);

// 批量处理，减少函数调用开销
Vector3Batch.normalizeArray(normals);

🔧 配置选项

import { MathConfig } from '@maxellabs/math';

// 配置对象池大小
MathConfig.setPoolSize({
  Vector3: 2000,
  Matrix4: 100,
  Quaternion: 500
});

// 启用SIMD优化
MathConfig.enableSIMD(true);

// 设置精度
MathConfig.setEpsilon(1e-6);

🧪 测试

# 运行单元测试
npm test

# 运行性能测试
npm run test:performance

# 运行覆盖率测试
npm run test:coverage

📈 性能基准

| 操作 | 标准实现 | 优化实现 | 提升 | |------|----------|----------|------| | Vector3.add | 100ns | 45ns | 2.2x | | Matrix4.multiply | 500ns | 180ns | 2.8x | | 批量变换(1000个点) | 50ms | 12ms | 4.2x | | Quaternion.slerp | 200ns | 85ns | 2.4x |

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT

开发计划

详细的开发计划请参考 DEVELOPMENT_PLAN.md