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
适用于无构建流程的浏览器项目,库会暴露为全局变量
glmarchingsquares:`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
####
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通道
$3
####
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
批量生成多阈值等值线,复用预处理结果提升效率。
图像处理应用场景
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+及所有现代浏览器(无需构建工具) |