High-performance contour extraction library based on Marching Squares algorithm, supporting ESM, CJS and IIFE formats
高性能等值线提取库，基于Marching Squares算法实现，支持ESM、CJS和IIFE多种模块格式，适用于WebGL可视化、科学数据展示、地理信息系统及图像处理等场景。
- 多模块兼容：同时提供ESM（现代前端）、CJS（Node.js）和IIFE（浏览器全局）格式，适配各种开发环境
- 极致性能：
- 稀疏网格优化（跳过空白区域，稀疏数据场景提速50%-80%）
- 预分配内存（避免动态扩容开销）
- 原生支持Float32Array（减少内存占用，提升CPU缓存命中率）
- 灵活控制：通过enableClosing参数控制等值线闭合，支持自定义精度阈值
- 图像处理支持：原生兼容ImageData格式，可直接从图像中提取轮廓
- 类型安全：完整TypeScript类型定义，提供IDE自动补全和编译时校验
- 批量处理：generateMultiContours方法高效生成多阈值等值线
适用于Node.js或前端项目（Webpack/Vite/Rollup）：
``bashnpm
npm install gl-marching-squares --save
$3
适用于无构建流程的浏览器项目，库会暴露为全局变量
：`html
`
快速使用示例
$3
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
});
`
$3
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
html
`
API 文档
$3
####
将二维数组转换为行优先的Float32Array格式。####
将Canvas图像数据转换为网格数据：
- ：从Canvas获取的图像数据对象
- channel：指定提取的通道（默认'gray'）
- 'gray'：灰度值（0.299R + 0.587G + 0.114*B）
- 'r'|'g'|'b'|'a'：分别对应RGBA通道
$3
####
generateContour(data: Float32Array, width: number, height: number, threshold: number, options?: ContourOptions): ContourResult
生成单个阈值的等值线。| 参数 | 类型 | 描述 |
|-------------|-----------------|-------------------------------|
|
| 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一致）
}
`
####
批量生成多阈值等值线，复用预处理结果提升效率。
图像处理应用场景
1. 医学影像：从CT/MRI图像提取器官轮廓
2. 遥感分析：卫星图像的地形等高线提取
3. 计算机视觉：物体边缘检测与区域分割
4. 图像编辑：智能选区与边缘高亮
处理图像时建议：
- 高分辨率图像先缩小尺寸提升性能
- 纯色背景图像启用
- 阈值选择参考图像亮度范围（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
稀疏网格场景（80%空白区域）：gl-marching-squares比同类库快3-5倍
| 模块格式 | 支持环境 |
|----------|-------------------------------------------|
| ESM | Node.js 14+、Chrome 61+、Firefox 60+、Safari 11+ |
| CJS | Node.js 8+ |
| IIFE | IE 11+及所有现代浏览器（无需构建工具） |