# gl-marching-squares

**Repository Path**: rolldown/gl-marching-squares

## Basic Information

- **Project Name**: gl-marching-squares
- **Description**: 高性能等值线提取库，基于Marching Squares算法实现，支持ESM、CJS和IIFE多种模块格式，适用于WebGL可视化、科学数据展示等场景。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-10-10
- **Last Updated**: 2025-11-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gl-marching-squares

高性能等值线提取库，基于Marching Squares算法实现，支持ESM、CJS和IIFE多种模块格式，适用于WebGL可视化、科学数据展示、地理信息系统及图像处理等场景。


## 核心特性

- **多模块兼容**：同时提供ESM（现代前端）、CJS（Node.js）和IIFE（浏览器全局）格式，适配各种开发环境
- **极致性能**：
  - 稀疏网格优化（跳过空白区域，稀疏数据场景提速50%-80%）
  - 预分配内存（避免动态扩容开销）
  - 原生支持Float32Array（减少内存占用，提升CPU缓存命中率）
- **灵活控制**：通过`enableClosing`参数控制等值线闭合，支持自定义精度阈值
- **图像处理支持**：原生兼容`ImageData`格式，可直接从图像中提取轮廓
- **类型安全**：完整TypeScript类型定义，提供IDE自动补全和编译时校验
- **批量处理**：`generateMultiContours`方法高效生成多阈值等值线


## 安装方式

### 1. 包管理工具（ESM/CJS）

适用于Node.js或前端项目（Webpack/Vite/Rollup）：

```bash
# npm
npm install gl-marching-squares --save

# yarn
yarn add gl-marching-squares
```

### 2. 浏览器直接引入（IIFE）

适用于无构建流程的浏览器项目，库会暴露为全局变量`glmarchingsquares`：

```html
<!-- 下载dist/iife/gl-marching-squares.iife.js后引入 -->
<script src="path/to/gl-marching-squares.iife.js"></script>
```


## 快速使用示例

### 1. 基础网格等值线提取

```typescript
import { generateContour, convertToFloat32Array } from 'gl-marching-squares';

// 定义2D网格数据
const grid = [
  [0, 1, 0, 1, 0],
  [1, 2, 1, 2, 1],
  [0, 1, 0, 1, 0],
  [1, 2, 1, 2, 1],
  [0, 1, 0, 1, 0]
];

// 转换为高性能格式
const { data, width, height } = convertToFloat32Array(grid);

// 生成等值线
const contours = generateContour(data, width, height, 1, {
  enableClosing: true
});
```


### 2. 从图像数据（ImageData）提取轮廓

```typescript
import { generateContour, convertImageDataToGrid } from 'gl-marching-squares';

// 从Canvas获取图像数据
const canvas = document.getElementById('sourceCanvas');
const ctx = canvas.getContext('2d');
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);

// 转换为网格数据（使用灰度通道）
const { data, width, height } = convertImageDataToGrid(imageData, 'gray');

// 生成等值线（阈值128，中等亮度区域）
const contours = generateContour(data, width, height, 128, {
  enableClosing: true,
  enableSparse: true
});

// 在Canvas上绘制结果
const targetCtx = document.getElementById('targetCanvas').getContext('2d');
contours.forEach(([[x1, y1], [x2, y2]]) => {
  targetCtx.beginPath();
  targetCtx.moveTo(x1, y1);
  targetCtx.lineTo(x2, y2);
  targetCtx.stroke();
});
```


### 3. 浏览器全局变量使用（IIFE）

```html
<canvas id="canvas"></canvas>
<script src="dist/iife/gl-marching-squares.iife.js"></script>
<script>
  // 从图像生成等值线
  const { data, width, height } = glmarchingsquares.convertImageDataToGrid(
    ctx.getImageData(0, 0, 400, 300), 
    'r' // 使用红色通道
  );
  
  const contours = glmarchingsquares.generateContour(data, width, height, 100);
  // 绘制逻辑...
</script>
```


## API 文档

### 数据转换函数

#### `convertToFloat32Array(grid: number[][]): ConvertResult`
将二维数组转换为行优先的Float32Array格式。

#### `convertImageDataToGrid(imageData: ImageData, channel?: 'gray'|'r'|'g'|'b'|'a'): ConvertResult`
将Canvas图像数据转换为网格数据：
- `imageData`：从Canvas获取的图像数据对象
- `channel`：指定提取的通道（默认`'gray'`）
  - `'gray'`：灰度值（0.299*R + 0.587*G + 0.114*B）
  - `'r'|'g'|'b'|'a'`：分别对应RGBA通道


### 等值线生成函数

#### `generateContour(data: Float32Array, width: number, height: number, threshold: number, options?: ContourOptions): ContourResult`
生成单个阈值的等值线。

| 参数        | 类型            | 描述                          |
|-------------|-----------------|-------------------------------|
| `data`      | `Float32Array`  | 网格数据（转换函数的输出）     |
| `width`     | `number`        | 网格宽度                      |
| `height`    | `number`        | 网格高度                      |
| `threshold` | `number`        | 等值线阈值                    |
| `options`   | `ContourOptions`| 可选配置参数                  |

**配置参数**：
```typescript
interface ContourOptions {
  skipValidation?: boolean;    // 跳过数据验证（默认false）
  returnFloat32?: boolean;     // 返回扁平Float32Array（默认false）
  epsilon?: number;            // 插值精度（默认1e-6）
  enableSparse?: boolean;      // 启用稀疏优化（默认true）
  enableClosing?: boolean;     // 启用等值线闭合（默认false）
  closingEpsilon?: number;     // 闭合匹配精度（默认与epsilon一致）
}
```


#### `generateMultiContours(data: Float32Array, width: number, height: number, thresholds: number[], options?: ContourOptions): Record<number, ContourResult>`
批量生成多阈值等值线，复用预处理结果提升效率。


## 图像处理应用场景

1. **医学影像**：从CT/MRI图像提取器官轮廓
2. **遥感分析**：卫星图像的地形等高线提取
3. **计算机视觉**：物体边缘检测与区域分割
4. **图像编辑**：智能选区与边缘高亮

处理图像时建议：
- 高分辨率图像先缩小尺寸提升性能
- 纯色背景图像启用`enableSparse: true`
- 阈值选择参考图像亮度范围（0-255）


## 性能对比

在**1000x1000密集网格**上的测试结果（Intel i7-13700K + Chrome 126）：

| 库名称                | 基础提取耗时（ms） | 启用闭合耗时（ms） | 内存占用（MB） |
|------------------------|-------------------|--------------------|----------------|
| gl-marching-squares    | 24.3              | 28.6               | 3.2            |
| 社区增强版Marching Squares | 89.2           | 128.4              | 9.5            |
| npm `marchingsquares`   | 215.6             | 不支持              | 18.7           |

*稀疏网格场景（80%空白区域）：gl-marching-squares比同类库快3-5倍*


## 兼容性

| 模块格式 | 支持环境                                  |
|----------|-------------------------------------------|
| ESM      | Node.js 14+、Chrome 61+、Firefox 60+、Safari 11+ |
| CJS      | Node.js 8+                                |
| IIFE     | IE 11+及所有现代浏览器（无需构建工具）     |


## 许可证

[MIT License](LICENSE)