rect-tri

一个高性能的TypeScript库，用于矩形网格三角化，生成3D渲染所需的顶点坐标、三角形索引和顶点法线。支持ESM、CJS和IIFE多种模块格式，适配不同开发环境。

特性

• 通过tri函数生成矩形网格的顶点位置（x, y, z）和三角形索引，支持自定义原点偏移
• 通过normal函数计算顶点法线（支持复用已有数组，优化内存）
• 性能优化：最小化循环开销，采用缓存友好的内存访问模式
• 支持大型网格（使用Uint32Array索引，可处理超过65535个顶点）
• 多模块格式：同时提供ESM（ES模块）、CJS（CommonJS）和IIFE（立即执行函数），适配浏览器、Node.js及打包工具

安装

npm install rect-tri

快速开始

1. ESM环境（现代浏览器/Node.js 14+）

import { tri, normal } from 'rect-tri';

// 定义网格尺寸（100列 × 100行）和原点偏移（可选，默认[0,0]）
const gridWidth = 100;
const gridHeight = 100;
const origin = [50, 30]; // 网格原点偏移（x方向+50，y方向+30）

// 1. 生成顶点和索引（支持自定义原点）
const { positions, indices } = tri(gridWidth, gridHeight, origin);

// 2.（可选）修改z坐标（添加高度数据，如地形高度图）
for (let i = 0; i < positions.length; i += 3) {
  positions[i + 2] = Math.sin(i / 30) * 5; // 示例：正弦波高度
}

// 3. 计算法线（两种方式）
// 方式1：自动创建法线数组
const normals1 = normal(positions, indices);

// 方式2：复用已有法线数组（适合频繁更新场景，减少内存分配）
const normals2 = new Float32Array(positions.length);
normal(positions, indices, normals2); // 结果直接写入normals2

// 在3D渲染中使用（WebGL、Three.js等）
console.log('顶点数据:', positions);
console.log('索引数据:', indices);
console.log('自动创建的法线:', normals1);
console.log('复用的法线数组:', normals2);

2. CJS环境（Node.js传统模块）

const { tri, normal } = require('rect-tri');

// 用法同上，支持origin参数...

3. 浏览器IIFE（直接通过<script>引入）

<!-- 引入IIFE格式文件 -->
<script src="https://unpkg.com/rect-tri@latest/dist/index.global.js"></script>

<script>
  // 通过全局变量rectTri访问
  const { tri, normal } = recttri;

  // 定义网格尺寸和原点偏移
  const { positions, indices } = tri(50, 50, [10, 20]);
  
  // 计算法线
  const normals = normal(positions, indices);
  console.log('法线数据:', normals);
</script>

API

tri(width, height, origin?)

生成矩形网格的顶点位置和三角形索引（内部自动创建数组），支持通过原点偏移调整网格位置。

参数

• width: number
  网格宽度（列数，必须为正整数）。
• height: number
  网格高度（行数，必须为正整数）。
• origin（可选）: [number, number]
  网格原点偏移量，格式为[xOffset, yOffset]，用于调整整个网格的x和y坐标。默认值为[0, 0]。

返回值

{ positions: Float32Array; indices: Uint32Array }

• positions: 顶点坐标数组，格式为[x0,y0,z0, x1,y1,z1, ...]（z初始化为0，x和y会叠加origin偏移）。
• indices: 三角形索引数组，每个网格单元生成2个三角形（共6个索引）。

normal(positions, indices, normals?)

通过平均相邻三角形的面法线计算顶点法线（支持复用数组）。

参数

• positions: Float32Array
  顶点坐标数组（由tri生成，长度必须为3的倍数）。
• indices: Uint32Array
  三角形索引数组（由tri生成，长度必须为3的倍数）。
• normals（可选）: Float32Array
  预分配的法线数组（长度需与positions一致），用于存储结果。若不传入，将自动创建新数组。

返回值

Float32Array
归一化的顶点法线数组，格式为[nx0,ny0,nz0, nx1,ny1,nz1, ...]。

注意事项

• 若传入normals数组，函数会先清零数组以避免残留数据影响结果。
• 法线最终会被归一化为单位向量，确保光照计算的一致性。

模块格式说明

| 模块格式 | 适用环境 | 导入方式 | 输出文件路径 | |----------|-------------------------|------------------------------|-------------------------------| | ESM | 现代浏览器、Webpack/Vite | import { tri } from 'rect-tri' | dist/index.js | | CJS | Node.js、旧版打包工具 | const { tri } = require('rect-tri') | dist/index.cjs | | IIFE | 传统浏览器（直接引入） | 全局变量rectTri | dist/rect-tri.iife.js |

性能优化

• 减少算术运算：用基于加法的行偏移替代循环内的乘法运算，降低计算开销。
• 消除分支判断：通过限制索引生成范围（仅处理非边缘网格），避免循环内条件判断，提升分支预测效率。
• 缓存友好：采用连续内存访问模式，提高顶点/索引数据的缓存命中率。
• 数组复用：normal函数支持传入预分配数组，减少频繁内存分配的开销（适合动画等实时场景）。
• 批量写入：使用Uint32Array.set批量写入索引数据，减少单个数组赋值的性能损耗。

许可证

MIT