简介一套面向3D图形开发者和算法学习者的三角形网格模型补洞源码工程解决模型导入导出时出现的孔洞、拓扑不连续等问题。包内含完整C11工程与第三方Eigen数学库覆盖边环检测、新面生成、拓扑更新、平滑处理等补洞步骤工程基于Visual Studio源码层次清晰适合研究网格修复算法或改造集成到自研管线。压缩包共1627个文件以883个h头文件、557个cpp源文件为主另含工程配置、模型样例off文件与说明文档整体约26.19MB便于离线搭建编译环境。已有4592人学习下载。通过阅读代码可掌握C11右值引用、lambda等特性在图形程序中的实际应用学习邻接表/邻接矩阵等拓扑结构以及法线计算、插值和平滑等几何操作的工程实现方式。1. 3D三角形网格模型补洞源代码先想清楚它解决的是哪一类残缺3D三角形网格模型补洞源代码通常解决的是这类场景扫描仪或重建流程出来的三角形网格在遮挡、高光、薄壁区域留下一个个边界敞开的口子导致模型不能水密3D 打印会生成废件CAE 前处理也会直接报错。补洞要做的事很明确检测出所有开口的边界环用新三角形把口子填平再让补丁的法向和曲率跟周边一致。适合谁读手上有残缺网格要修复的工程师想在渲染或仿真前把模型做成水密的开发者以及打算自己实现而非调用现成库的算法学习者。下面按检测、三角剖分、平滑、验收的顺序把一套可落地的做法拆开讲。2. 补洞原理拆解边界环检测与耳切三角剖分怎么配合补洞不是拿到网格就画三角形而是先回答两个问题洞在哪洞在平面上的轮廓长什么样。前者靠边邻接统计后者靠投影和三角剖分。这一步没做对后面所有平滑都是白搭因为填进去的三角形根本不在正确的位置上。2.1 用一条边被多少个三角形共用判定什么是洞水密网格里每条边恰好被两个三角形共用这是流形网格的基本性质。一旦某条边只被一个三角形共用它就裸露在表面边缘成为边界边把边界边按首尾顺序串起来得到的就是边界环每个边界环对应一个洞。与它相对的是非流形边即一条边被三个或更多三角形共用这类模型通常要先修复不能直接进补洞流程。实现上不需要真的构建半边结构用一个字典统计边出现次数就够了几百万面的网格也能跑from collections import defaultdict def collect_boundary_loops(faces): # faces: (F, 3)每个三角形按逆时针给出顶点索引 edge_cnt defaultdict(int) for f in faces: for i in range(3): a, b int(f[i]), int(f[(i 1) % 3]) edge_cnt[(min(a, b), max(a, b))] 1 # 边界边要带上方向方向取自所属三角形的绕序 nxt {} for f in faces: for i in range(3): a, b int(f[i]), int(f[(i 1) % 3]) if edge_cnt[(min(a, b), max(a, b))] 1: nxt[a] b loops [] visited set() for s in list(nxt.keys()): if s in visited: continue loop, cur [], s while cur not in visited and cur in nxt: visited.add(cur) loop.append(cur) cur nxt[cur] if cur s: # 只有准确回到起点才算闭合环 loops.append(loop) return loops逻辑说明第一遍遍历把所有无向边计数count 1的就是边界边第二遍遍历时如果某条无向边是边界边就把它在三角形绕序里的有向方向记下来这样每个起点只对应一个后继。最后从任意起点沿着后继指针走走回起点就是一个完整边界环。visited集合保证每条环只被提取一次。两个容易忽略的点一是(min(a,b), max(a,b))作为字典 key天然屏蔽了方向统计的是无向边不会把正反两个方向算成两条边二是cur s的判断会把不闭合的环丢掉——开放网格的外轮廓就是这种环不丢掉的话会把整个模型外边界当成一个巨型洞填掉那是灾难性的。2.2 把洞多边形投影到平面再做耳切为什么是最稳妥的第一步耳切法本质是 2D 多边形三角剖分算法而洞的边界顶点在三维空间里分布在一个近似平面上所以第一步要把边界环投影到它的最佳拟合平面剖分完成后再把三角形顶点的索引映射回三维坐标。平面法向用 Newell 方法估算最稳它本质上是对所有边叉积求和对顶点顺序敏感恰好能利用边界环自带的方向信息比最小二乘拟合对噪声更鲁棒。选型上为什么不直接上scipy.spatial.Delaunay因为 Delaunay 对凸多边形没问题一旦洞是凹的无约束 Delaunay 生成的三角形可能越过边界线补丁直接穿出模型表面。耳切法的约束是所有三角形顶点都来自原边界环天然不会越界代价是复杂度 O(n²)但单个洞一般只有几十到几百条边完全够用。2.3 什么情况下该判定这个洞不能简单填有三类情况属于简单补洞只是浪费算力洞边界边数超过几百条耳切法会切出大量细长三角形洞里带独立面片也就是非单连通区域单环提取根本拿不到完整边界洞落在曲率剧烈变化的区域平面补丁补完后会明显塌。这三类会在第 5 章给出具体处理日常模型先不用管能跑通基础流程更重要。3. 跑通最小补洞程序读入 STL 到写出补丁的核心代码这一章给一套可以直接落地的最小程序依赖只有 numpy 和 trimesh 两个库trimesh 只负责读模型和写模型检测和剖分逻辑全部手写这样你能看清每一步在做什么出问题也好定位。3.1 读入模型并构建边邻接import numpy as np import trimesh mesh trimesh.load(broken.stl) mesh.merge_vertices(digits_vertex6) # 焊接重复顶点去重精度 1e-6 vertices np.asarray(mesh.vertices, dtypenp.float64) faces np.asarray(mesh.faces, dtypenp.int64) loops collect_boundary_loops(faces) # 上一章的函数直接复用 print(检测到边界环数量:, len(loops)) for loop in loops: print(环长度:, len(loop))参数说明digits_vertex6表示坐标保留 6 位小数后按值去重顶点坐标差小于 1e-6 的会被当成同一点。这一步必须在边邻接统计之前做否则扫描件里常见的重复顶点会让边界边的判定失真。trimesh 的merge_vertices会自动更新faces和vertices所以先合并再取数组。注意如果模型本身存在非流形边一条边被三个或更多三角形共用这一步不会帮你修复需要单独处理第 4 章会讲。3.2 耳切法三角剖分与补丁生成的实现投影和耳切的完整实现如下选耳策略用的是最小内角优先比无脑切第一个凸耳能明显减少细长三角形def project_loop(pts): # 输入边界环三维点 (n, 3)输出二维坐标和平面基向量 n len(pts) normal np.zeros(3) for i in range(n): v0, v1 pts[i], pts[(i 1) % n] normal np.cross(v0, v1) # Newell 法向 normal / np.linalg.norm(normal) u np.cross(normal, [0, 1, 0]) # 构造平面内正交基 if np.linalg.norm(u) 1e-8: u np.cross(normal, [1, 0, 0]) u / np.linalg.norm(u) v np.cross(normal, u) return np.stack([pts u, pts v], axis1), u, v def point_in_triangle(p, a, b, c): # 判断点 p 是否落在三角形 abc 内部含边界 def sign(p1, p2, p3): return (p1[0] - p3[0]) * (p2[1] - p3[1]) \ - (p1[1] - p3[1]) * (p2[0] - p3[0]) d1, d2, d3 sign(p, a, b), sign(p, b, c), sign(p, c, a) has_neg (d1 0) or (d2 0) or (d3 0) has_pos (d1 0) or (d2 0) or (d3 0) return not (has_neg and has_pos) def ear_clip(pts2d): # 最小内角优先的耳切返回三角形索引三元组列表 idx list(range(len(pts2d))) tris [] while len(idx) 3: best_i, best_ang None, np.inf for i in range(len(idx)): p, c, q idx[i - 1], idx[i], idx[(i 1) % len(idx)] cp np.cross(pts2d[c] - pts2d[p], pts2d[q] - pts2d[c]) if cp 1e-10: # 凹点或共线不能当耳 continue inside False for o in idx: if o in (p, c, q): continue if point_in_triangle(pts2d[o], pts2d[p], pts2d[c], pts2d[q]): inside True break if inside: continue v1 pts2d[p] - pts2d[c] v2 pts2d[q] - pts2d[c] ang np.arctan2(abs(np.cross(v1, v2)), np.dot(v1, v2)) if ang best_ang: best_ang, best_i ang, i if best_i is None: # 退化保护避免死循环 break p, c, q idx[best_i - 1], idx[best_i], idx[(best_i 1) % len(idx)] tris.append((p, c, q)) idx.pop(best_i) if len(idx) 3: tris.append(tuple(idx)) return idx, tris逻辑说明project_loop里pts u是把三维点投影到基向量 u 上得到一维分量两个基向量各投一次就得到二维坐标。耳切部分每轮从所有候选耳里挑内角最小的切掉——内角越小越接近退化三角形越早处理越能避免最后剩下极端形状。point_in_triangle用叉积符号判断点是否在三角形内部保证切掉的耳不含其他边界顶点。参数说明1e-10是凸性判断阈值把共线和近共线点排除np.arctan2计算的是顶点 c 处的内角单位是弧度。如果ear_clip提前退出且剩余顶点多于 3 个说明多边形退化常见做法是最外层调用方打印警告然后用扇形剖分兜底避免静默失败。剖分结果接回到网格上完整调用入口如下def fill_mesh_holes(vertices, faces, max_hole_edges100): loops collect_boundary_loops(faces) patch_faces [] for loop in loops: if len(loop) 3 or len(loop) max_hole_edges: continue pts vertices[loop] pts2d, _, _ project_loop(pts) remain, tris ear_clip(pts2d) for a, b, c in tris: patch_faces.append([loop[a], loop[b], loop[c]]) return np.asarray(patch_faces, dtypenp.int64) patch_faces fill_mesh_holes(vertices, faces) new_mesh trimesh.Trimesh(verticesvertices, facesnp.vstack([faces, patch_faces])) new_mesh.export(repaired.stl)这里loop[a]取回的是原始网格的顶点索引不是投影后的坐标所以补丁三角形和原网格共享顶点不用额外做顶点合并。max_hole_edges100是硬阈值超过的洞先跳过保证程序不会在一个超大的坏洞上耗尽时间。3.3 补洞关键参数表与默认值建议参数怎么调直接看这张表参数作用建议值调参方向max_hole_edges超过该边数的洞跳过100扫描件大洞多调到 200~300但要接受质量下降凸性阈值判定凹点/共线的叉积下限1e-10模型坐标单位很大毫米级时可放大到 1e-6投影退化阈值Newell 法向长度下限1e-8环不共面时改用 PCA 投影平滑迭代 iters补丁打磨轮数20高曲率区域减到 5~10平面洞可以到 50平滑权重 lam每轮移动步长0.3超过 0.8 容易震荡低于 0.1 收敛太慢坐标单位对阈值影响很大。如果模型是毫米级顶点坐标动辄上百叉积结果天然很大如果是归一化到单位立方体阈值就得缩小几个数量级。最稳妥的做法是把模型先归一化到包围盒对角线为 1再跑补洞所有阈值都用相对值省得每次换数据都重新调。4. 补洞常见问题排查五个高频翻车现场与对策补洞算法本身不复杂真正耗时间的是各种边界情况。下面这五条是我反复踩过的坑每条都是现象、原因、解决三段照着定位就行。4.1 洞检测阶段的两类翻车边计数出现 3 与嵌套洞现象一统计边邻接时出现大量count 3的边提取出的洞异常大或形状怪异补洞后模型更乱了。原因顶点坐标重复导致网格没被正确焊接同一个几何点存在多个顶点索引边计数被稀释或者模型本身就带非流形结构。解决先做重复顶点合并trimesh 里就是merge_vertices(digits_vertex6)自己实现就用哈希把坐标量化到 1e-6 再映射去重。合并后重新统计理想情况下只有count 1和count 2两种边。如果count 3仍然存在这块区域属于真非流形需要手工修网格不要让补洞算法硬填。现象二补完外环后新三角形和洞里的孤立面片交叉重叠渲染出现闪烁。原因洞不是单连通区域里面还漂着一个岛——比如扫描时遗落在洞内的一小片网格简单单环提取只能拿到外边界。解决先把所有边界环都提取出来按环顶点坐标求最近点对在距离最近的两个边界顶点之间加两条桥接边把内环并到外环上合成一条边界后再统一做耳切。桥接边的位置决定了补丁会不会自交所以桥接前一定要确认最近点对没有穿过其他三角形。4.2 剖分与平滑阶段的三类翻车细长三角形、法向翻转与体积收缩现象三补丁大面积出现细长三角形渲染时黑条纹明显光照下像裂纹。原因耳切法没有最小内角优先或者洞边界顶点分布极不均匀导致切出来的三角形受顶点分布支配凹洞尤其容易出 sliver。解决用第 3 章的最小内角优先版本剖分后对补丁内部做 5~10 代均匀拉普拉斯平滑。如果洞边数超过 150直接进入第 5 章的加密流程靠平滑救不回来。现象四补丁看起来凹进去和周围表面朝向相反光照下特别扎眼。原因边界环方向反了三角形绕序随之翻转。网格整体法向朝外时边界环提取方向应该和面绕序一致但部分 STL 模型的面绕序本身就不一致环方向就会被带错。解决取补丁边界外圈邻域面的法向均值和补丁面法向均值做点积结果为负就把补丁三角形索引按[0, 2, 1]交换后写回。现象五平滑迭代次数调大后补丁中间塌陷体积明显收缩。原因把边界环上的原网格顶点也放进平滑集合了边界被拉动后外圈内缩补丁整体跟着塌。解决平滑时只更新新增顶点原网格顶点全部固定。注意拉普拉斯平滑的 λ 不宜超过 0.5。超过 0.8 后高频分量不降反升补丁表面会出现波浪状起伏这是血泪经验换来的教训。5. 进阶处理约束平滑、法向对齐与大型洞的加密预处理第 3 章的最小程序能处理七成常规洞。剩下的两成集中在两类洞太大洞落在曲率变化剧烈的区域。这两类问题指望耳切本身解决不现实得在剖分前后各加一道工序。5.1 只动补丁上的新顶点带约束的拉普拉斯平滑实现受约束的拉普拉斯平滑是补洞质量的关键核心是区分新增顶点和原网格顶点。实现上先构建顶点邻接表每轮迭代只更新新顶点且每轮用上一轮的结果计算均值也就是 Jacobi 迭代避免 Gauss-Seidel 式的前后依赖带来方向性漂移from collections import defaultdict def build_vertex_adj(faces): adj defaultdict(set) for f in faces: for i in range(3): a, b int(f[i]), int(f[(i 1) % 3]) adj[a].add(b) adj[b].add(a) return {k: list(v) for k, v in adj.items()} def constrained_smooth(vertices, faces, new_mask, fixed_verts, iters30, lam0.4): # new_mask: 布尔数组标记哪些顶点是补丁新增的 # fixed_verts: 原网格边界环顶点集合这些顶点打死不动 adj build_vertex_adj(faces) v vertices.copy() for _ in range(iters): old v.copy() # 用上一轮快照Jacobi 迭代 for i in range(len(v)): if not new_mask[i] or i in fixed_verts: continue nb adj.get(i, []) if not nb: continue v[i] lam * (np.mean(old[np.array(nb)], axis0) - v[i]) return v参数说明lam是每轮向邻域重心移动的比例0.4 意味着每轮最多移动差距的 40%20~30 轮后基本收敛。fixed_verts必须包含补丁边界一圈的所有原网格顶点否则平滑会把边界拉变形这也是补丁和原网格之间出现台阶最常见的来源。这里用的是均匀权重对补丁足够如果想做更精细的曲面贴合可以把均匀权重换成 cotangent 权重代价是每次迭代要多算一遍角余切处理百万面网格时才需要考虑。5.2 大洞先加密再补中点细分救回细长三角形洞边数超过 150 后耳切的输出质量会明显下滑因为边界顶点之间的距离差异太大。常见做法是先对边界环做中点细分在每条边界边上插一个中顶点让耳切的输入更均匀def refine_hole_polygon(vertices, loop, rounds1): # 在边界环每条边中点插入新顶点返回更新后的顶点表和环索引 new_verts [list(v) for v in vertices] new_loop list(loop) for _ in range(rounds): finer [] m len(new_loop) for i in range(m): a new_loop[i] b new_loop[(i 1) % m] mid (np.asarray(new_verts[a]) np.asarray(new_verts[b])) * 0.5 new_verts.append(mid.tolist()) finer [a, len(new_verts) - 1] new_loop finer return np.asarray(new_verts, dtypenp.float64), new_loop注意这里的顶点表是复制出来的新数组和原网格顶点不共享所以后续要把新顶点合并回原顶点表或者干脆把补丁和原网格分开存储最后导出再合并。另一种方案是先做稀疏耳切再把每个三角形做 1 到 4 细分并投影到切平面效果类似但实现要处理共享顶点稍麻烦。还有一个选型上的边界如果洞是凸的可以用scipy.spatial.Delaunay直接对投影点做三角剖分质量和速度都更好一旦洞是凹的无约束 Delaunay 会产生越过边界的三角形必须用第 3 章的耳切。判断凹凸性的办法是看环上所有点的叉积符号是否一致不一致就是凹洞。5.3 法向对齐检查用外圈邻域判断绕序并修正绕序修正是最后一道工序放在平滑之后。原理是用补丁外圈邻域面的平均法向做参照补丁平均法向与它点积为负就翻转def face_normal(v, f): return np.cross(v[f[1]] - v[f[0]], v[f[2]] - v[f[0]]) def fix_patch_winding(vertices, patch_faces, neighbor_faces): n_patch np.mean( [face_normal(vertices, f) for f in patch_faces], axis0) n_nb np.mean( [face_normal(vertices, f) for f in neighbor_faces], axis0) if np.dot(n_patch, n_nb) 0: patch_faces patch_faces[:, [0, 2, 1]] # 交换绕序 return patch_facesneighbor_faces的取法遍历补丁边界边找出所有和边界边共边的原网格三角形构成外圈一环邻域。这里有个细节外圈邻域面如果本身绕序就是乱的需要先统计邻域法向的总体朝向多数一致的方向才算数否则点积判断会被少数反向面带偏。6. 补完怎么验收流形性检查与法向偏差的量化验证补洞完成后别急着交付先把三个检查跑一遍全部通过再谈效果。第一个是流形性检查本质是第 2 章边计数的反向使用要求每条边恰好被两个三角形共用def verify_manifold(faces): cnt defaultdict(int) for f in faces: for i in range(3): a, b int(f[i]), int(f[(i 1) % 3]) cnt[(min(a, b), max(a, b))] 1 bad {k: v for k, v in cnt.items() if v ! 2} return len(bad) 0, bad返回的字典里value 1说明还有边界边没补干净value 2说明新增补丁造成了非流形。第二个检查是法向偏差统计补丁边界三角形与外圈邻域三角形的法向夹角平面洞应该接近 0 度允许到 30 度超过 45 度的比例大于 5% 就说明补丁和邻域衔接生硬需要加强平滑或重新剖分。第三个检查是面积比补丁总面积和网格平均面面积对比如果补丁面积异常大多半是选错了洞或者剖分自交看一眼渲染结果就能确认。这三个检查不花多少算力我习惯把它们写成一个verify函数放进补洞管线每次导出修复模型的同时输出一份 JSON 报告。这个习惯帮我挡掉过好几回漏检内环的尴尬——表面看不出问题流形检查一跑发现还有两百多条边界边其实是内环压根没进剖分流程。补洞这件事算法只占一半另一半是验证希望帮到你。本文还有配套的精品资源点击获取
简介一套面向3D图形开发者和算法学习者的三角形网格模型补洞源码工程解决模型导入导出时出现的孔洞、拓扑不连续等问题。包内含完整C11工程与第三方Eigen数学库覆盖边环检测、新面生成、拓扑更新、平滑处理等补洞步骤工程基于Visual Studio源码层次清晰适合研究网格修复算法或改造集成到自研管线。压缩包共1627个文件以883个h头文件、557个cpp源文件为主另含工程配置、模型样例off文件与说明文档整体约26.19MB便于离线搭建编译环境。已有4592人学习下载。通过阅读代码可掌握C11右值引用、lambda等特性在图形程序中的实际应用学习邻接表/邻接矩阵等拓扑结构以及法线计算、插值和平滑等几何操作的工程实现方式。1. 3D三角形网格模型补洞源代码先想清楚它解决的是哪一类残缺3D三角形网格模型补洞源代码通常解决的是这类场景扫描仪或重建流程出来的三角形网格在遮挡、高光、薄壁区域留下一个个边界敞开的口子导致模型不能水密3D 打印会生成废件CAE 前处理也会直接报错。补洞要做的事很明确检测出所有开口的边界环用新三角形把口子填平再让补丁的法向和曲率跟周边一致。适合谁读手上有残缺网格要修复的工程师想在渲染或仿真前把模型做成水密的开发者以及打算自己实现而非调用现成库的算法学习者。下面按检测、三角剖分、平滑、验收的顺序把一套可落地的做法拆开讲。2. 补洞原理拆解边界环检测与耳切三角剖分怎么配合补洞不是拿到网格就画三角形而是先回答两个问题洞在哪洞在平面上的轮廓长什么样。前者靠边邻接统计后者靠投影和三角剖分。这一步没做对后面所有平滑都是白搭因为填进去的三角形根本不在正确的位置上。2.1 用一条边被多少个三角形共用判定什么是洞水密网格里每条边恰好被两个三角形共用这是流形网格的基本性质。一旦某条边只被一个三角形共用它就裸露在表面边缘成为边界边把边界边按首尾顺序串起来得到的就是边界环每个边界环对应一个洞。与它相对的是非流形边即一条边被三个或更多三角形共用这类模型通常要先修复不能直接进补洞流程。实现上不需要真的构建半边结构用一个字典统计边出现次数就够了几百万面的网格也能跑from collections import defaultdict def collect_boundary_loops(faces): # faces: (F, 3)每个三角形按逆时针给出顶点索引 edge_cnt defaultdict(int) for f in faces: for i in range(3): a, b int(f[i]), int(f[(i 1) % 3]) edge_cnt[(min(a, b), max(a, b))] 1 # 边界边要带上方向方向取自所属三角形的绕序 nxt {} for f in faces: for i in range(3): a, b int(f[i]), int(f[(i 1) % 3]) if edge_cnt[(min(a, b), max(a, b))] 1: nxt[a] b loops [] visited set() for s in list(nxt.keys()): if s in visited: continue loop, cur [], s while cur not in visited and cur in nxt: visited.add(cur) loop.append(cur) cur nxt[cur] if cur s: # 只有准确回到起点才算闭合环 loops.append(loop) return loops逻辑说明第一遍遍历把所有无向边计数count 1的就是边界边第二遍遍历时如果某条无向边是边界边就把它在三角形绕序里的有向方向记下来这样每个起点只对应一个后继。最后从任意起点沿着后继指针走走回起点就是一个完整边界环。visited集合保证每条环只被提取一次。两个容易忽略的点一是(min(a,b), max(a,b))作为字典 key天然屏蔽了方向统计的是无向边不会把正反两个方向算成两条边二是cur s的判断会把不闭合的环丢掉——开放网格的外轮廓就是这种环不丢掉的话会把整个模型外边界当成一个巨型洞填掉那是灾难性的。2.2 把洞多边形投影到平面再做耳切为什么是最稳妥的第一步耳切法本质是 2D 多边形三角剖分算法而洞的边界顶点在三维空间里分布在一个近似平面上所以第一步要把边界环投影到它的最佳拟合平面剖分完成后再把三角形顶点的索引映射回三维坐标。平面法向用 Newell 方法估算最稳它本质上是对所有边叉积求和对顶点顺序敏感恰好能利用边界环自带的方向信息比最小二乘拟合对噪声更鲁棒。选型上为什么不直接上scipy.spatial.Delaunay因为 Delaunay 对凸多边形没问题一旦洞是凹的无约束 Delaunay 生成的三角形可能越过边界线补丁直接穿出模型表面。耳切法的约束是所有三角形顶点都来自原边界环天然不会越界代价是复杂度 O(n²)但单个洞一般只有几十到几百条边完全够用。2.3 什么情况下该判定这个洞不能简单填有三类情况属于简单补洞只是浪费算力洞边界边数超过几百条耳切法会切出大量细长三角形洞里带独立面片也就是非单连通区域单环提取根本拿不到完整边界洞落在曲率剧烈变化的区域平面补丁补完后会明显塌。这三类会在第 5 章给出具体处理日常模型先不用管能跑通基础流程更重要。3. 跑通最小补洞程序读入 STL 到写出补丁的核心代码这一章给一套可以直接落地的最小程序依赖只有 numpy 和 trimesh 两个库trimesh 只负责读模型和写模型检测和剖分逻辑全部手写这样你能看清每一步在做什么出问题也好定位。3.1 读入模型并构建边邻接import numpy as np import trimesh mesh trimesh.load(broken.stl) mesh.merge_vertices(digits_vertex6) # 焊接重复顶点去重精度 1e-6 vertices np.asarray(mesh.vertices, dtypenp.float64) faces np.asarray(mesh.faces, dtypenp.int64) loops collect_boundary_loops(faces) # 上一章的函数直接复用 print(检测到边界环数量:, len(loops)) for loop in loops: print(环长度:, len(loop))参数说明digits_vertex6表示坐标保留 6 位小数后按值去重顶点坐标差小于 1e-6 的会被当成同一点。这一步必须在边邻接统计之前做否则扫描件里常见的重复顶点会让边界边的判定失真。trimesh 的merge_vertices会自动更新faces和vertices所以先合并再取数组。注意如果模型本身存在非流形边一条边被三个或更多三角形共用这一步不会帮你修复需要单独处理第 4 章会讲。3.2 耳切法三角剖分与补丁生成的实现投影和耳切的完整实现如下选耳策略用的是最小内角优先比无脑切第一个凸耳能明显减少细长三角形def project_loop(pts): # 输入边界环三维点 (n, 3)输出二维坐标和平面基向量 n len(pts) normal np.zeros(3) for i in range(n): v0, v1 pts[i], pts[(i 1) % n] normal np.cross(v0, v1) # Newell 法向 normal / np.linalg.norm(normal) u np.cross(normal, [0, 1, 0]) # 构造平面内正交基 if np.linalg.norm(u) 1e-8: u np.cross(normal, [1, 0, 0]) u / np.linalg.norm(u) v np.cross(normal, u) return np.stack([pts u, pts v], axis1), u, v def point_in_triangle(p, a, b, c): # 判断点 p 是否落在三角形 abc 内部含边界 def sign(p1, p2, p3): return (p1[0] - p3[0]) * (p2[1] - p3[1]) \ - (p1[1] - p3[1]) * (p2[0] - p3[0]) d1, d2, d3 sign(p, a, b), sign(p, b, c), sign(p, c, a) has_neg (d1 0) or (d2 0) or (d3 0) has_pos (d1 0) or (d2 0) or (d3 0) return not (has_neg and has_pos) def ear_clip(pts2d): # 最小内角优先的耳切返回三角形索引三元组列表 idx list(range(len(pts2d))) tris [] while len(idx) 3: best_i, best_ang None, np.inf for i in range(len(idx)): p, c, q idx[i - 1], idx[i], idx[(i 1) % len(idx)] cp np.cross(pts2d[c] - pts2d[p], pts2d[q] - pts2d[c]) if cp 1e-10: # 凹点或共线不能当耳 continue inside False for o in idx: if o in (p, c, q): continue if point_in_triangle(pts2d[o], pts2d[p], pts2d[c], pts2d[q]): inside True break if inside: continue v1 pts2d[p] - pts2d[c] v2 pts2d[q] - pts2d[c] ang np.arctan2(abs(np.cross(v1, v2)), np.dot(v1, v2)) if ang best_ang: best_ang, best_i ang, i if best_i is None: # 退化保护避免死循环 break p, c, q idx[best_i - 1], idx[best_i], idx[(best_i 1) % len(idx)] tris.append((p, c, q)) idx.pop(best_i) if len(idx) 3: tris.append(tuple(idx)) return idx, tris逻辑说明project_loop里pts u是把三维点投影到基向量 u 上得到一维分量两个基向量各投一次就得到二维坐标。耳切部分每轮从所有候选耳里挑内角最小的切掉——内角越小越接近退化三角形越早处理越能避免最后剩下极端形状。point_in_triangle用叉积符号判断点是否在三角形内部保证切掉的耳不含其他边界顶点。参数说明1e-10是凸性判断阈值把共线和近共线点排除np.arctan2计算的是顶点 c 处的内角单位是弧度。如果ear_clip提前退出且剩余顶点多于 3 个说明多边形退化常见做法是最外层调用方打印警告然后用扇形剖分兜底避免静默失败。剖分结果接回到网格上完整调用入口如下def fill_mesh_holes(vertices, faces, max_hole_edges100): loops collect_boundary_loops(faces) patch_faces [] for loop in loops: if len(loop) 3 or len(loop) max_hole_edges: continue pts vertices[loop] pts2d, _, _ project_loop(pts) remain, tris ear_clip(pts2d) for a, b, c in tris: patch_faces.append([loop[a], loop[b], loop[c]]) return np.asarray(patch_faces, dtypenp.int64) patch_faces fill_mesh_holes(vertices, faces) new_mesh trimesh.Trimesh(verticesvertices, facesnp.vstack([faces, patch_faces])) new_mesh.export(repaired.stl)这里loop[a]取回的是原始网格的顶点索引不是投影后的坐标所以补丁三角形和原网格共享顶点不用额外做顶点合并。max_hole_edges100是硬阈值超过的洞先跳过保证程序不会在一个超大的坏洞上耗尽时间。3.3 补洞关键参数表与默认值建议参数怎么调直接看这张表参数作用建议值调参方向max_hole_edges超过该边数的洞跳过100扫描件大洞多调到 200~300但要接受质量下降凸性阈值判定凹点/共线的叉积下限1e-10模型坐标单位很大毫米级时可放大到 1e-6投影退化阈值Newell 法向长度下限1e-8环不共面时改用 PCA 投影平滑迭代 iters补丁打磨轮数20高曲率区域减到 5~10平面洞可以到 50平滑权重 lam每轮移动步长0.3超过 0.8 容易震荡低于 0.1 收敛太慢坐标单位对阈值影响很大。如果模型是毫米级顶点坐标动辄上百叉积结果天然很大如果是归一化到单位立方体阈值就得缩小几个数量级。最稳妥的做法是把模型先归一化到包围盒对角线为 1再跑补洞所有阈值都用相对值省得每次换数据都重新调。4. 补洞常见问题排查五个高频翻车现场与对策补洞算法本身不复杂真正耗时间的是各种边界情况。下面这五条是我反复踩过的坑每条都是现象、原因、解决三段照着定位就行。4.1 洞检测阶段的两类翻车边计数出现 3 与嵌套洞现象一统计边邻接时出现大量count 3的边提取出的洞异常大或形状怪异补洞后模型更乱了。原因顶点坐标重复导致网格没被正确焊接同一个几何点存在多个顶点索引边计数被稀释或者模型本身就带非流形结构。解决先做重复顶点合并trimesh 里就是merge_vertices(digits_vertex6)自己实现就用哈希把坐标量化到 1e-6 再映射去重。合并后重新统计理想情况下只有count 1和count 2两种边。如果count 3仍然存在这块区域属于真非流形需要手工修网格不要让补洞算法硬填。现象二补完外环后新三角形和洞里的孤立面片交叉重叠渲染出现闪烁。原因洞不是单连通区域里面还漂着一个岛——比如扫描时遗落在洞内的一小片网格简单单环提取只能拿到外边界。解决先把所有边界环都提取出来按环顶点坐标求最近点对在距离最近的两个边界顶点之间加两条桥接边把内环并到外环上合成一条边界后再统一做耳切。桥接边的位置决定了补丁会不会自交所以桥接前一定要确认最近点对没有穿过其他三角形。4.2 剖分与平滑阶段的三类翻车细长三角形、法向翻转与体积收缩现象三补丁大面积出现细长三角形渲染时黑条纹明显光照下像裂纹。原因耳切法没有最小内角优先或者洞边界顶点分布极不均匀导致切出来的三角形受顶点分布支配凹洞尤其容易出 sliver。解决用第 3 章的最小内角优先版本剖分后对补丁内部做 5~10 代均匀拉普拉斯平滑。如果洞边数超过 150直接进入第 5 章的加密流程靠平滑救不回来。现象四补丁看起来凹进去和周围表面朝向相反光照下特别扎眼。原因边界环方向反了三角形绕序随之翻转。网格整体法向朝外时边界环提取方向应该和面绕序一致但部分 STL 模型的面绕序本身就不一致环方向就会被带错。解决取补丁边界外圈邻域面的法向均值和补丁面法向均值做点积结果为负就把补丁三角形索引按[0, 2, 1]交换后写回。现象五平滑迭代次数调大后补丁中间塌陷体积明显收缩。原因把边界环上的原网格顶点也放进平滑集合了边界被拉动后外圈内缩补丁整体跟着塌。解决平滑时只更新新增顶点原网格顶点全部固定。注意拉普拉斯平滑的 λ 不宜超过 0.5。超过 0.8 后高频分量不降反升补丁表面会出现波浪状起伏这是血泪经验换来的教训。5. 进阶处理约束平滑、法向对齐与大型洞的加密预处理第 3 章的最小程序能处理七成常规洞。剩下的两成集中在两类洞太大洞落在曲率变化剧烈的区域。这两类问题指望耳切本身解决不现实得在剖分前后各加一道工序。5.1 只动补丁上的新顶点带约束的拉普拉斯平滑实现受约束的拉普拉斯平滑是补洞质量的关键核心是区分新增顶点和原网格顶点。实现上先构建顶点邻接表每轮迭代只更新新顶点且每轮用上一轮的结果计算均值也就是 Jacobi 迭代避免 Gauss-Seidel 式的前后依赖带来方向性漂移from collections import defaultdict def build_vertex_adj(faces): adj defaultdict(set) for f in faces: for i in range(3): a, b int(f[i]), int(f[(i 1) % 3]) adj[a].add(b) adj[b].add(a) return {k: list(v) for k, v in adj.items()} def constrained_smooth(vertices, faces, new_mask, fixed_verts, iters30, lam0.4): # new_mask: 布尔数组标记哪些顶点是补丁新增的 # fixed_verts: 原网格边界环顶点集合这些顶点打死不动 adj build_vertex_adj(faces) v vertices.copy() for _ in range(iters): old v.copy() # 用上一轮快照Jacobi 迭代 for i in range(len(v)): if not new_mask[i] or i in fixed_verts: continue nb adj.get(i, []) if not nb: continue v[i] lam * (np.mean(old[np.array(nb)], axis0) - v[i]) return v参数说明lam是每轮向邻域重心移动的比例0.4 意味着每轮最多移动差距的 40%20~30 轮后基本收敛。fixed_verts必须包含补丁边界一圈的所有原网格顶点否则平滑会把边界拉变形这也是补丁和原网格之间出现台阶最常见的来源。这里用的是均匀权重对补丁足够如果想做更精细的曲面贴合可以把均匀权重换成 cotangent 权重代价是每次迭代要多算一遍角余切处理百万面网格时才需要考虑。5.2 大洞先加密再补中点细分救回细长三角形洞边数超过 150 后耳切的输出质量会明显下滑因为边界顶点之间的距离差异太大。常见做法是先对边界环做中点细分在每条边界边上插一个中顶点让耳切的输入更均匀def refine_hole_polygon(vertices, loop, rounds1): # 在边界环每条边中点插入新顶点返回更新后的顶点表和环索引 new_verts [list(v) for v in vertices] new_loop list(loop) for _ in range(rounds): finer [] m len(new_loop) for i in range(m): a new_loop[i] b new_loop[(i 1) % m] mid (np.asarray(new_verts[a]) np.asarray(new_verts[b])) * 0.5 new_verts.append(mid.tolist()) finer [a, len(new_verts) - 1] new_loop finer return np.asarray(new_verts, dtypenp.float64), new_loop注意这里的顶点表是复制出来的新数组和原网格顶点不共享所以后续要把新顶点合并回原顶点表或者干脆把补丁和原网格分开存储最后导出再合并。另一种方案是先做稀疏耳切再把每个三角形做 1 到 4 细分并投影到切平面效果类似但实现要处理共享顶点稍麻烦。还有一个选型上的边界如果洞是凸的可以用scipy.spatial.Delaunay直接对投影点做三角剖分质量和速度都更好一旦洞是凹的无约束 Delaunay 会产生越过边界的三角形必须用第 3 章的耳切。判断凹凸性的办法是看环上所有点的叉积符号是否一致不一致就是凹洞。5.3 法向对齐检查用外圈邻域判断绕序并修正绕序修正是最后一道工序放在平滑之后。原理是用补丁外圈邻域面的平均法向做参照补丁平均法向与它点积为负就翻转def face_normal(v, f): return np.cross(v[f[1]] - v[f[0]], v[f[2]] - v[f[0]]) def fix_patch_winding(vertices, patch_faces, neighbor_faces): n_patch np.mean( [face_normal(vertices, f) for f in patch_faces], axis0) n_nb np.mean( [face_normal(vertices, f) for f in neighbor_faces], axis0) if np.dot(n_patch, n_nb) 0: patch_faces patch_faces[:, [0, 2, 1]] # 交换绕序 return patch_facesneighbor_faces的取法遍历补丁边界边找出所有和边界边共边的原网格三角形构成外圈一环邻域。这里有个细节外圈邻域面如果本身绕序就是乱的需要先统计邻域法向的总体朝向多数一致的方向才算数否则点积判断会被少数反向面带偏。6. 补完怎么验收流形性检查与法向偏差的量化验证补洞完成后别急着交付先把三个检查跑一遍全部通过再谈效果。第一个是流形性检查本质是第 2 章边计数的反向使用要求每条边恰好被两个三角形共用def verify_manifold(faces): cnt defaultdict(int) for f in faces: for i in range(3): a, b int(f[i]), int(f[(i 1) % 3]) cnt[(min(a, b), max(a, b))] 1 bad {k: v for k, v in cnt.items() if v ! 2} return len(bad) 0, bad返回的字典里value 1说明还有边界边没补干净value 2说明新增补丁造成了非流形。第二个检查是法向偏差统计补丁边界三角形与外圈邻域三角形的法向夹角平面洞应该接近 0 度允许到 30 度超过 45 度的比例大于 5% 就说明补丁和邻域衔接生硬需要加强平滑或重新剖分。第三个检查是面积比补丁总面积和网格平均面面积对比如果补丁面积异常大多半是选错了洞或者剖分自交看一眼渲染结果就能确认。这三个检查不花多少算力我习惯把它们写成一个verify函数放进补洞管线每次导出修复模型的同时输出一份 JSON 报告。这个习惯帮我挡掉过好几回漏检内环的尴尬——表面看不出问题流形检查一跑发现还有两百多条边界边其实是内环压根没进剖分流程。补洞这件事算法只占一半另一半是验证希望帮到你。本文还有配套的精品资源点击获取
