# rect-tri

**Repository Path**: nodets/rect-tri

## Basic Information

- **Project Name**: rect-tri
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-22
- **Last Updated**: 2025-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# rect-tri

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


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


## 安装
```bash
npm install rect-tri
```


## 快速开始

### 1. ESM环境（现代浏览器/Node.js 14+）
```typescript
import { tri, normal } from 'rect-tri';

// 定义网格尺寸（100列 × 100行）
const gridWidth = 100;
const gridHeight = 100;

// 1. 生成顶点和索引（无需预分配数组，函数内部自动创建）
const { positions, indices } = tri(gridWidth, gridHeight);

// 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传统模块）
```javascript
const { tri, normal } = require('rect-tri');

// 用法同上...
```

### 3. 浏览器IIFE（直接通过`<script>`引入）
```html
<!-- 引入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);
  
  // 计算法线
  const normals = normal(positions, indices);
  console.log('法线数据:', normals);
</script>
```


## API

### `tri(width, height)`
生成矩形网格的顶点位置和三角形索引（内部自动创建数组）。

#### 参数
- `width`: `number`  
  网格宽度（列数，必须为正整数）。
- `height`: `number`  
  网格高度（行数，必须为正整数）。

#### 返回值
`{ positions: Float32Array; indices: Uint32Array }`  
- `positions`: 顶点坐标数组，格式为`[x0,y0,z0, x1,y1,z1, ...]`（z初始化为0，可后续修改）。
- `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