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）：

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

# yarn
yarn add gl-marching-squares

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

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

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

快速使用示例

1. 基础网格等值线提取

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）提取轮廓

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）

<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.299R + 0.587G + 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| 可选配置参数 |

配置参数：

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