简介：alpha-shape是计算几何方向的JavaScript工具库，用于求取任意维度点集的阿尔法形状，适合在点云轮廓提取、形状拟合与空间数据分析中快速得到清晰边界。面向有一定前端或Node.js基础的开发者，核心算法封装成调用简单的函数，可通过npm包管理器安装并直接使用，项目集成门槛较低。压缩包内共7个文件，主体为两个JS源码文件，一个负责核心计算，一个负责可视化演示，另含工程配置文件、接口说明文档、许可协议和效果预览图，整体仅39KB，结构精炼便于阅读。目前已有1515人学习下载。读者可对照接口文档理解阿尔法参数的含义与调节方法，也可运行可视化脚本查看不同参数取值下形状变化，从而加深对计算几何算法的认识；源码附带完整示例，适合作为工具库直接引入相关项目。

1. alpha-shape 是什么：给散点重建凹边界的 JavaScript 算法包

拿到几百个平面散点想画轮廓线，第一反应是凸包，可凸包永远把凹陷区域填平，真实边界出不来。alpha-shape 就是用来解决这个问题的几何算法：用一个可调参数 alpha 控制边界贴合程度，从接近凸包的粗轮廓，一路过渡到带凹陷、带孔洞的精细边界，而且不限于二维，三维、四维乃至更高维度的点集同样适用。在 JavaScript 生态里，alpha-shape 这个包把 Delaunay 剖分、外接球过滤、内部面剔除全部封装好，使用方只需要传点集和一个数值，拿回的就是边界线段或三角面的顶点索引。适合点云轮廓提取、地理围栏生成、散点聚类边界描述和图学网格重建的开发者。

2. 先跑通最小示例：alpha-shape 的安装、API 与返回结构

2.1 为什么在 JavaScript 里直接用现成实现

自己写凹包算法，至少要完成三个环节：Delaunay 三角剖分、每个单纯形的外接球半径计算、公共内部面的判定与剔除。第二和第三环节都很容易出错，尤其是公共面的去重，二维里就涉及一条边被两个三角形共用的情况，三维里则要处理一个三角面被两个四面体共用的情况，递归关系一旦理不顺，输出的边界就会有大量重复和悬空边。

alpha-shape 这个 npm 包把这些环节全部封装在内部。外部接口只有一个函数，输入就是两个参数，没有任何全局状态，也不依赖 Canvas 或 WebGL 这类浏览器环境，纯 Node.js 环境下就能跑。它依赖的底层 Delaunay 剖分实现是独立维护的，简单配置和数据处理上做得比较干净。

它的输入约定非常固定：第一个参数是 alpha 数值，第二个参数是点集。点集必须用嵌套数组表示，二维就是[[x, y], ...]，三维就是[[x, y, z], ...]。输出永远是索引数组，二维返回一组线段[[i, j], ...]，三维返回一组三角面[[i, j, k], ...]，索引值指向原始点数组里的下标。这个返回值设计很关键，后面所有几何处理，包括连线、导出、闭合环整理，都依赖这份索引数据。

2.2 安装与最小示例代码

先准备一个干净的测试目录，用 npm 安装依赖：

npm install alpha-shape

安装之后，直接写一个最小调用脚本，模拟一组建筑角点散点：

const alphaShape = require('alpha-shape'); // 一组二维散点，模拟建筑平面的角点，单位米 const points = [ [0, 0], [1, 0], [2, 0.5], [3, 1], [4, 1.5], [4, 3], [3, 3.8], [2, 4], [1, 3.5], [0, 3] ]; // alpha 取 0.5，表示对边界做中等程度的贴合 const cells = alphaShape(0.5, points); console.log('边界线段数量:', cells.length); console.log('前 5 条边:', cells.slice(0, 5));

这段代码的核心逻辑是：把点集丢给alphaShape，内部先做 Delaunay 三角剖分，然后按外接球半径过滤，最后剔除内部共享边，返回的cells就是落在边界上的线段索引。alpha值 0.5 在这个尺度下，能保留大部分贴近点集外缘的三角形边，同时把跨越凹陷区域的大三角形过滤掉。

参数选择上，points数组的每一项都必须是数组形式，元素顺序不可乱，第一个是 x，第二个是 y，三维场景再追加 z。alpha值没有单位，它和坐标尺度强相关，坐标跨度是 10 米还是 1000 米，同样的边界效果需要的 alpha 完全不同，后面第 3 章会详细展开。

2.3 把索引输出转换成实际线段

cells返回的是线段两个端点的下标，如果直接拿去绘图，还得先把下标还原成坐标。写一个简单的转换函数：

function cellsToSegments(cells, points) { return cells.map(([i, j]) => [points[i], points[j]]); } const segments = cellsToSegments(cells, points); console.log(segments[0]); // 输出类似 [[0,0],[1,0]]，表示这条边的两个端点是 points[0] 和 points[1]

这个函数的逻辑很直接：遍历cells里的每个线段索引对，用下标去points里取值，拼成[[x1,y1],[x2,y2]]的结构。三维场景下同一个函数也能用，因为points[i]自然返回三维坐标数组。

有一点需要提醒：cells里的边顺序是不保证连续的，第一条边可能和第三条边相邻，但和第二条边没有任何拓扑关系。如果你想让输出的线段首尾相接形成完整多边形，必须额外做闭合环整理，这个在最后一章专门处理。初学时直接用转换结果画短线没问题，但做面积计算或围栏判断时，绝对不能拿原始cells直接当多边形边界用。

3. alpha 参数怎么调：从凸包到带洞边界的连续渐变

3.1 先理解 alpha 与半径阈值的换算关系

alpha 不是“凹陷程度”这种模糊描述，它对应一个具体的几何量：外接球半径阈值的倒数。算法对 Delaunay 剖分生成的每个 d 维单纯形，计算其外接球半径 r，只有满足 r 小于 1/alpha 的单纯形才会进入候选集合，之后再进行内部面剔除。

这个换算关系直接决定了调参方向。alpha 非常小，比如 0.001，半径阈值就非常大，几乎所有三角形都满足条件，输出的边界接近凸包。alpha 逐渐增大，半径阈值变小，跨越凹陷区域的大三角形因为外接球太大被过滤掉，边界开始向内凹陷。alpha 继续增大到超过数据尺度时，连正常的表面三角形也被剔除，边界变得碎片化，甚至变成彼此不连的短线段或孤立小面。

所以记住一个判断方向：alpha 越大，边界越紧、越碎；alpha 越小，边界越松、越接近凸包。有的资料里会把 alpha 定义为半径而不是半径倒数，那个方向是反的，换到另一个库之前一定要先确认定义。

3.2 同一组散点在不同 alpha 下的实际表现

用第 2 章那组建筑角点散点，依次改变 alpha 值，结果差异非常明显。下表是几个典型取值下的表现特征：

这个表不是固定结论，因为 alpha 的绝对值受坐标尺度影响很大。同样的数据，如果坐标从米改成公里，点之间的间距缩小 1000 倍，外接球半径也同步缩小，alpha 就得相应放大才能等效。所以调参时必须结合自己的数据尺度判断，不能照抄别人的参数。

3.3 实用调参顺序：从凸包往回收

实际项目中我不会一上来就猜 alpha，而是用一个二分探测的思路：先给一个非常小的 alpha 拿到凸包，再逐步放大 alpha，观察边界开始出现明显凹陷的位置，再继续放大到即将碎片化的临界点，然后回退一步。

下面这个探测函数可以帮你快速找到适合当前数据集的 alpha 区间：

function probeAlpha(points, minA = 0.0001, maxA = 100) { let lower = minA; let upper = maxA; for (let i = 0; i < 12; i++) { const alpha = Math.sqrt(lower * upper); const cells = alphaShape(alpha, points); console.log('alpha:', alpha.toFixed(4), '边数:', cells.length); // 边数明显少于凸包边数时，说明已经开始凹陷 if (cells.length > points.length) lower = alpha; else upper = alpha; } }

这里的思路是：凸包状态下边界线段数通常接近点数量级，而 alpha 增大导致碎片化时，线段数量会先下降，然后又因为碎片增多而上升。用边数是否大于点数量作为分界指标，是一个简单但有效的判定方式。

实际使用中我一般会先跑一遍这个探测，把 alpha 定在边界开始收紧、但边数还没有急剧减少的位置。如果结果偏碎，就回退到上一次的输出。整个过程比手工反复猜 alpha 快得多，也不容易陷入“参数玄学”。

4. 任意维度边界重建：Delaunay 剖分与单纯形过滤的边界

4.1 为什么必须先做 Delaunay 剖分

alpha-shape 的输出质量完全建立在 Delaunay 剖分之上。Delaunay 剖分有一个重要性质：任意一个单纯形的外接球内部不包含其他输入点。这个性质决定了哪些三角形会被用于构建边界时，结果不会因为三角化方式不同而出现偏差。

如果换用普通三角剖分，同一个点集可能产生多种不同的三角形连接方式，外接球半径差异很大，同样的 alpha 过滤条件就会得到不同的边界，这是不可接受的。alpha-shape 选择 Delaunay 作为前置步骤，保证了过滤结果的唯一性，也保证了随着 alpha 增大，边界变化是连续的。

从维度角度看，二维的剖分生成三角形，三维生成四面体，四维生成五胞体。alpha-shape 内部对每个 d 维单纯形计算外接球半径，再按半径阈值过滤，然后把被保留单纯形的所有低维面提取出来。例如二维里保留三角形后提取三条边，三维里保留四面体后提取四个三角面，四维里保留五胞体后提取五个四面体。这就是“任何维度”在实现层面的含义。

4.2 三维点云重建的完整示例

三维场景的调用方式与二维完全一致，只是点集变成[x, y, z]结构，返回的cells也从线段变成三角面索引。下面用一组模拟球面点云做演示：

const alphaShape = require('alpha-shape'); // 在单位球面上按经纬度采样，生成 300 个点 const points = []; for (let i = 0; i < 50; i++) { for (let j = 0; j < 6; j++) { const u = (i / 50) * Math.PI; const v = (j / 6) * Math.PI * 2; points.push([ Math.sin(u) * Math.cos(v), Math.sin(u) * Math.sin(v), Math.cos(u) ]); } } // 三维场景下 alpha 选 0.15，保证球面三角面完整贴合 const cells = alphaShape(0.15, points); console.log('三角面数量:', cells.length); console.log('第一个面:', cells[0]); // 输出类似 [12, 13, 29]，三个数字是顶点下标

这段代码里，采样密度是 50 乘 6，点间距在球面上比较均匀，alpha 0.15 对应的半径阈值大约是 6.67，足够保留球面上的大部分小三角形，同时过滤掉跨越球体内部的大三角形。如果 point cloud 的密度不均匀，同一个 alpha 会导致稀疏区域碎片化，这是三维重建里最常见的问题。

拿到三角面索引后，如果要导出到三维软件查看，最简单的格式是 OBJ。写一个轻量导出函数：

function exportOBJ(cells, points) { const lines = []; // 先输出所有顶点 points.forEach(p => { lines.push(`v ${p[0]} ${p[1]} ${p[2]}`); }); // 再输出三角面，OBJ 的索引从 1 开始 cells.forEach(([a, b, c]) => { lines.push(`f ${a + 1} ${b + 1} ${c + 1}`); }); return lines.join('\n'); } console.log(exportOBJ(cells, points).split('\n').slice(0, 5).join('\n'));

导出逻辑要注意两个关键点：OBJ 是 1-based 索引，必须把cells里的下标加 1；三角面的顶点顺序需要保证逆时针，否则部分软件显示时法线方向是反的。alpha-shape 返回的面索引顺序不保证一致，简单查看时可以忽略，但做大面积网格渲染前必须检查法线。

4.3 高维场景与复杂度边界

四维及以上维度的调用方式和二维三维没有任何区别，传入[[x1,x2,x3,x4], ...]即可。但高维场景有两个现实约束。

第一个约束是数据量。Delaunay 剖分的时间复杂度随维度增长非常快，二维处理上万点尚可，三维处理几千点开始吃力，四维处理几百点就可能卡顿。实际项目中，高维 alpha-shape 更多用于特征分析，而不是追求大规模重建。

第二个约束是输出难以直接可视化。四维返回的是由五个顶点组成的四维单纯形面，人类无法直观观察，通常需要降维投影或者只提取统计特征。如果你只是需要高维点集中某一簇的边界描述，可以考虑先做主成分分析降维到二维或三维，再用 alpha-shape 重建，会比直接在高维空间运行高效得多。

5. alpha-shape 避坑清单：重复点、退化输入与性能翻车

5.1 重复点导致剖分直接报错

现象：输入点集里有两个完全相同的坐标，调用alphaShape时直接抛出异常，或者返回结果明显错乱。

原因：Delaunay 剖分要求输入点集中不能有退化情况，重复点会让剖分算法在构建初始三角形时无法确定邻接关系。

解决：在调用前做一次去重。注意不要只比较数组对象引用，要去重坐标值：

function dedupePoints(points) { const seen = new Set(); return points.filter(p => { const key = p.map(v => Number(v).toFixed(6)).join(','); if (seen.has(key)) return false; seen.add(key); return true; }); } // 使用前去重 const cleanPoints = dedupePoints(points); const cells = alphaShape(0.5, cleanPoints);

这里的去重逻辑把每个点坐标格式化为固定精度的字符串，然后放进 Set 判断。toFixed(6)表示保留 6 位小数，如果你的数据本身是毫米级精度且坐标值很大，可以把位数改成 3 或 2，避免过度去重。实际工程中，测量数据经常出现连点，这一步建议固定放到预处理阶段，而不是等到崩溃再查。

5.2 共线或共面点输出空数组

现象：所有散点排在同一条直线上，或者三维点云所有点落在同一个平面上，alphaShape返回空数组[]，不报错，但也没有任何输出。

原因：alpha-shape 需要 d 维单纯形才能构建边界。所有点共线时，二维三角剖分无法生成任何三角形，候选集合为空；三维点共面时，虽然点有 z 坐标，但实际维度只有 2，四面体也无法生成。

解决：先检查数据的实际维度。最直接的办法是看点集的协方差矩阵特征值，有几个非零特征值，数据就在几维空间里：

function checkRank(points) { const mean = points[0].map((_, i) => points.reduce((sum, p) => sum + p[i], 0) / points.length ); const cov = points[0].map((_, i) => points[0].map((__, j) => points.reduce((sum, p) => sum + (p[i] - mean[i]) * (p[j] - mean[j]), 0) / points.length ) ); const trace = cov.reduce((s, row, i) => s + row[i], 0); return trace > 1e-8 ? 2 : 1; }

如果检测出数据退化，就不要继续用 alpha-shape，而是降维处理。二维点共线时，直接对 x 坐标排序取首尾即可；三维点共面时，先做平面拟合把坐标投影到二维，再用二维 alpha-shape 重建边界。

5.3 碎片化边缘和悬空边

现象：alpha 调大后，输出里出现大量彼此不连通的短线段，或者单个三角形孤零零地存在，无法组成连续边界。

原因：局部点密度不均匀导致外接球半径差异巨大。密集区域的三角形外接球半径小，稀疏区域的三角形外接球半径大，同一个 alpha 阈值下，密集区域保留了大量小三角形，稀疏区域则全部被过滤，边界自然断裂。

解决：先归一化坐标，再调参。把点的坐标范围缩放到 0 到 1 之间，让密度差异不那么大，然后再跑探测函数：

function normalizePoints(points) { const mins = points[0].slice(); const maxs = points[0].slice(); points.forEach(p => { p.forEach((v, i) => { mins[i] = Math.min(mins[i], v); maxs[i] = Math.max(maxs[i], v); }); }); return points.map(p => p.map((v, i) => (v - mins[i]) / (maxs[i] - mins[i] + 1e-8)) ); }

归一化之后，alpha 的取值稳定在 0.01 到 1 之间，可预测性高得多。如果你需要原始坐标的输出，归一化重建后再把边界点映射回原始坐标即可。碎片化还有一个常见来源是 alpha 选得过大，遇到这个情况优先回退 alpha，而不是继续在后处理里强行修补。

5.4 上万点输入直接卡死

现象：点数量在几千时运行流畅，超过一万就开始明显卡顿，两万以上可能持续十几秒甚至更久。

原因：Delaunay 剖分的复杂度在二维接近线性，但三维会明显上升，且 alpha-shape 还需要对所有单纯形计算外接球半径。点数量翻倍，剖分和过滤的总耗时可能翻三倍以上。

解决：先降采样再重建。常用做法是把点投射到网格，每个网格只保留一个代表点：

function gridSample(points, cellSize) { const map = new Map(); points.forEach(p => { const key = p.map(v => Math.floor(v / cellSize)).join(','); if (!map.has(key)) map.set(key, p); }); return Array.from(map.values()); }

cellSize决定采样密度，取值越大，保留的点越少。建议从数据整体尺度的 1/100 开始试，重建完边界后，如果边界明显偏离原始点云，再逐步减小 cellSize 提高精度。采样后的补点操作也要控制幅度，不要让 alpha-shape 直接处理全量数据。

6. 把 cells 串成闭环：边界整理与自相交检查

alpha-shape 输出的边没有拓扑顺序，直接连线会出现“折返”和“缺口”。我一般会先把边图整理成环，再做面积计算或栅格化。下面这个函数用邻接表把线段串成闭合环：

function buildRings(edges) { const adj = new Map(); edges.forEach(([a, b]) => { if (!adj.has(a)) adj.set(a, []); if (!adj.has(b)) adj.set(b, []); adj.get(a).push(b); adj.get(b).push(a); }); const visited = new Set(); const rings = []; for (const [start] of adj) { if (visited.has(start)) continue; const ring = []; let cur = start; let prev = -1; while (!visited.has(cur)) { visited.add(cur); ring.push(cur); const neighbors = adj.get(cur).filter(n => n !== prev); if (neighbors.length === 0) break; prev = cur; cur = neighbors[0]; } if (ring.length > 2) rings.push(ring); } return rings; }

这个算法从任意顶点出发，沿着邻接边一直走，遇到分叉时取第一个可用方向，最终回到起点就完成一个环。它不处理复杂拓扑，比如一个带洞的形状会有内外两个环，此时需要额外判断环的包含关系，把面积较小的环作为孔洞扣除。

环整理完之后，用鞋带公式算面积，同时检查是否有重复点或非常短的边。如果相邻两点距离小于点集典型间距的 1%，说明边界上存在“毛刺”，可以选择过滤掉该点重新连接两侧邻居。

我最早在这个环节偷过懒，直接拿 alpha-shape 的原始输出画 Polyline，结果同样的边界在不同库里有完全不同的显示效果，后来才发现是内部存在重复边没有清理。从那以后我每次做 alpha-shape 结果验证，都强制走一遍闭环整理与自相交检查，确保每个环里的顶点序号和坐标都能一一对应，边界才真正可用。希望帮到你。

本文还有配套的精品资源，点击获取