scenario-blender-hard-surface

Blender 硬表面

专家处理硬表面的关键，是让边缘受控地捕捉光线：每条边都通过倒角或支撑线捕捉高光，平面看起来完全平整，并且设计定稿前切口始终可编辑。专家在方法上意见不一（N 边形与布尔 vs 四边面笼与细分），但检查项一致：操作顺序、切割器的规整度、平面，以及旋转查看时使用亮面 MatCap。Agent 使用工具包构建修改器堆栈，再通过可量化的检查项找出人类旋转视图时会发现的问题。如果此处提到的某项关联技能不在你可用的技能中，请让用户安装它 （npx skills add scenario-labs/skills --skill <name>）；若无人值守，则根据工具架构继续操作，并标记此缺失项。

必备背景： scenario-blender-expert（执行渠道、审查循环、5.2 API 变更）。 工具包：scripts/bx_hardsurface.py （import sys; sys.path.append("<skills>/scenario-blender-hard-surface/scripts"); import bx_hardsurface as HS）， 世界空间单位为米，仅使用原版 Blender。

方法立场（专家间的差异）

• 先切割，再倒角，最后处理法线。 布尔位于按角度限制的微倒角之上，加权法线位于堆栈最底部，稍后添加的镜像位于其上方（Ryuu [00:26:26]、[00:28:37]；du Mont [00:19:46]）。在 5.2 中，固定的修改器会在固定组内保持相对顺序，而新修改器会放在其上方，因此要从底部向上固定：HS.order_stack 会处理此操作，HS.add_boolean 始终将新修改器放在堆栈末尾项的上方（已验证）。
• 两个倒角，各司其职（du Mont [00:12:25] 至 [00:15:15]）：在切割前，对选定的轮廓边使用按权重限制的设计倒角（8 到 12 段）；每次切割后都使用按角度限制的微倒角（30 度、Harden Normals、Miter Outer Arc），因为现实中没有边缘是完全锋利的（Gambrell、du Mont、Ryuu）。
• 布尔运算后倒角变窄，是几何问题，不是设置问题（du Mont [00:20:18]、 [00:30:20]）。让切割器远离目标边缘，或使其与目标边缘精确重合；保持 Clamp Overlap 开启。Clamp Overlap 会限制整个对象上的倒角：一个与面边缘相差 0.7 度的槽（夹紧比 3.8）会抹掉部件另一处接口上的 3 mm 倒角［已在 5.2.1 中验证］。HS.clamp_culprits 会指出问题切口。
• 每个壁面、台阶、间隙和圆角面都必须宽于微倒角宽度的 2 倍［新增，已验证］：1 mm 的凹槽底面、1.5 mm 的壁面、带 1.5 mm 倒角的 2 mm 凹槽（3.1 mm 的凹槽没有问题），以及用 30 度面倒圆的槽，都会导致整个对象的倒角被夹紧。
• 如果 Harden Normals 或 Weighted Normal 没有任何效果，说明该面并不平整（Gambrell [00:01:06]）。将其压平；添加更多法线修改器也无济于事。
• 根据部件选择方法，而非个人偏好。 有许多切口的平面机加工部件：N 边形 + 布尔 + 倒角 + 自定义法线，大约只需四分之一的时间，且始终可编辑（Gambrell [00:18:01]）。连续曲面、非均匀圆度、雕刻或烘焙高模：四边面笼 + 细分（rileyb3d、PzThree）。用支撑线而非折痕锐化细分表面边缘：在质量相同的情况下，三角形数量为 36,800 对 3,600（Lampel [00:05:28]）。
• EXACT 是求解器。 Gambrell 在 2021 年提出的“切换到 Fast”早于 5.x：Float 在共面的切割器上产生 16 条非流形边，而 Exact 和 Manifold 均正常［已验证］。Exact 表现异常时，问题出在操作对象上（Ryuu [00:15:13]）：一个开放的切割器使 Exact 产生 19 条非流形边，而 Manifold 则静默跳过了切割［已验证］。
• 使用亮面 MatCap 检查，并逐个放大查看每个切口（Gambrell [00:00:33]、rileyb3d [00:06:32]）。 查看整个对象的平面图会掩盖污迹和变窄的倒角。

首先确定

输入	为何会改变计划	未说明时的默认值
用途	渲染：3 个以上微小分段（Gambrell）；游戏中模棱风格：1 到 2 个分段，三角化并使用自定义法线；烘焙：细分曲面或布尔高模 + 单独的低模	仍按渲染处理
实际尺寸	倒角宽度为绝对值：du Mont 在小型机器人机身上使用约 3 mm，在小零件上使用 1 mm，在套环上使用 0.1 mm	按实际尺寸建模；若未知，微小宽度取最大尺寸的 0.5% [added]
表面	主要为平面、曲面还是有机机械结构	平面零件采用 School A，曲面外壳采用 B，混合情况采用混合方案
预算和引擎	Augusto：15k 个三角形，单张 2K 贴图；仅四边形的管线会强制采用 School B（Gambrell [00:24:35]）	无预算限制：报告三角形数量
后续阶段	雕刻损伤或多分辨率细节需要四边形笼（PzThree）；绑定需要塌陷副本（du Mont）	无
对称性	零件对称时镜像目标；只有切割器对称时，围绕目标镜像切割器（Gambrell [00:14:53]）	询问参考对象

工作流

1. 按真实尺寸搭建白模。 使用基础几何体或 bmesh，然后执行 HS.apply_scale(ob)（保持子对象位置不变；负缩放时会翻转绕序）。使用长焦镜头，对照人类尺度的方盒检查比例（du Mont [00:10:01]）。验收标准：所有带有倒角、实体化或阵列的对象，其缩放均为 1；剪影评审表清晰可读（bx_review.review(..., modes=("silhouette",))）。
2. 选择流派并搭建基础堆栈。
   • A：使用 HS.find_edges(ob, min_angle=80, inside=...) 找出设计边缘，再用 HS.set_edge_attr(ob, edges, 1.0) 设置属性，然后执行 HS.hard_surface_stack(ob, micro_width=..., design_width=...)。
   • B：在 bmesh 中搭建四边面笼（控制点少、方形四边面，参考 rileyb3d / PzThree），然后执行 HS.subd_stack(ob, support_width=...)（倒角权重、均匀分段、轮廓 1.0、启用 UV Smooth Keep Corners 的细分）或显式添加 HS.support_loops。验收标准：HS.stack_problems(ob) == []；A 的求值网格上有自定义法线。
3. 切割（流派 A）。 HS.make_cutter(target, "BOX"|"CYLINDER"|"SLOT", size, location, ...) 会创建符合检查清单的切割器（缩放为 1、平滑、仅位于 Cutters 集合中、线框显示、渲染时隐藏、已设为父级、布尔运算模式为 EXACT、线框显示且位于堆栈末尾之上）。自定义形状使用 HS.as_cutter，切片使用 HS.slice_boolean。规则：切割器应延伸至被切入的每个表面之外；切割器边缘应远离目标边缘，或与其完全重合；对于分段数相同的目标，圆形切割器应偏移半个分段（相同相位会产生 10 条非流形边和条纹［已验证］；make_cutter 默认如此）；圆形切割器的倒角分段应远小于倒角角度（每 90 度至少 4 个分段）。每次切割后的验收标准：HS.cutter_report(c, target) 无问题，HS.clamp_probe(target)["ratio"] < 0.1，并查看切割处的 HS.closeup 特写。
4. 设计阶段。 将细节成组布置，留出平静区域，并与相邻特征对齐（Ryuu [00:28:37]，Gambrell [00:34:15]）；用领圈遮住完美交线（du Mont [00:39:36]）；必须共用倒角的部件应进行合并（Gambrell [00:18:57]）。验收标准：评审表体现设计意图，而非杂乱细节。
5. 着色阶段。 执行 r = HS.shading_audit(ob); HS.verdict(r)，然后运行 HS.review([ob], out, modes=("matcap","reflect","hsgrey","wire")) 并查看特写。参考 references/critique.md 进行问题分类：平面上的涂抹感、非平面面、曲面上的切口（先渲染检查：Harden + WN 已能对 24/48 分段圆柱体上的切口进行干净着色；在球体上，HS.transfer_normals 将法线误差 p95 从 2.79 度降至 0.34 度［已验证］）、镜像接缝（HS.mirror_seam_fix）。验收标准：评审结果为空，或每条剩余问题都有说明，且特写图与结论一致。
6. 流派 B 细节与尖痕检查。 使用均匀的倒角分段、轮廓 1.0 和 Keep Corners（Lampel [00:11:15]）；山脊两侧的支撑线应对称（rileyb3d [00:11:08]）；在内嵌圆形周围加设向外扩展的边框环（PzThree [00:42:25]）；关闭细分以排查笼网伪影（Gambrell [00:14:44]）。验收标准：r["subd_cage"] 中四边面占比接近 100%；将用于雕刻的笼网上没有细长矩形；光泽 Matcap 特写中没有尖痕。
7. 游戏版本或导出。 中模：g, tris = HS.game_version(ob, micro_segments=1)（在 WN 之后添加保留自定义法线的三角化；由于它与切割器共用，因此会保持原位）；glTF 保留了 100% 的自定义法线［已验证］。烘焙资产：低模和烘焙结果移至 scenario-blender-retopology 和 scenario-blender-uv-baking。绑定或导出：对副本执行 HS.collapse(ob)（du Mont [01:07:29]）。验收标准：三角形数量符合预算、仅包含三角形，并查看游戏版本副本的 Matcap 特写。
8. 交付渲染图、评审结论、每个对象的三角形数量，以及未经验证的内容。

数值

值	设置	参考来源
微倒角	角度 30 度，渲染用 3 段，游戏用 1 到 2 段，Harden Normals，Miter Outer Arc	Gambrell [00:17:20]，du Mont [00:14:40]
微倒角宽度	主体约 3 mm，小部件 1 mm，套环 0.1 mm	实际尺寸，du Mont
设计倒角	Limit Method Weight，8 到 12 段	du Mont [00:13:32]
大型滚圆曲线	46 到 50 段；切割器边缘倒角约 8 到 10 段	Ryuu [00:12:53]，[00:05:42]
最小特征	壁、台阶、凹槽、刻面宽度 > 2 x 微倒角宽度	[已添加，已验证]
夹紧探测	位移超过宽度的 10% = 夹紧	[已添加]
求解器	EXACT；对于流形操作对象，为提高速度使用 MANIFOLD；仅在诊断时使用 FLOAT	已在 5.2.1 中验证
圆形切割器	创建时设定顶点数（螺丝孔用 40）；相对于目标错开半段相位	Ryuu [00:29:43]；[已验证]
细分前倒角	2 或 4 段，轮廓 1.0，Weight，UV Smooth Keep Corners	Lampel [00:08:06]，[00:11:15]
折痕	适用于小细节，或在 1 级时圆化粗圆柱；用于主要边缘会使三角形数增加 10 倍	Lampel，du Mont [00:52:18]
SubD 笼架	圆形主体 18 个顶点，较密集部件 36 个；方形四边面	rileyb3d [00:01:34]，PzThree [00:03:15]
镜像接缝修复	bevel Face Strength Affected + WN Face Influence，权重 100	Gambrell [00:06:57]
游戏预算	15k 个三角形，一张 2K 贴图，动画部件分开	Augusto [00:11:48]
测得的成本	外壳 1,984 个三角形 (A) 对比 4,608 (B，2 级)；枪管 7,308 (A)、25,728 (B)、3,716 (A 游戏版)	test_03 [已添加]

质量门槛

代码检查（全部位于 HS.shading_audit，可通过 HS.verdict 查看）：已应用缩放； stack_problems 为空；在预期情况下存在自定义法线；非流形边为 0；平面着色面为 0； 非平面基面为 0（容差为尺寸的 1e-4）；无涂抹（平面上角点法线倾斜超过 3 度 [已添加]）；无硬边（超过 45 度）被平滑处理；夹紧比率低于 0.1；每个布尔操作都会改变网格；切割器报告干净（共面、近乎平行、薄壁、 窄间隙、差点相交、圆角刻面、凸出、卫生性）。School B：四边面百分比、四边面长宽比、折痕 长度。游戏：HS.tri_count，仅三角形。

视觉检查： HS.review 中的各行：matcap（形体）、reflect（check_reflection_horizontal：条纹在 倒角和圆角上连续）、hsgrey（倒角高光）、wire（实际布尔拓扑）；视角包括正面、四分之三、顶部、低角度。然后对 shiny （metal_carpaint）中的每个切口使用一次 HS.closeup(ob, point, radius, ...)。检查平面上的渐变涂抹、倒角高光在切口处中断或变窄、曲面切口角落处拉伸、镜像接缝上的蝴蝶形瑕疵、subD 挤压、切口壁上的刻面。正上方的 shiny 视图会导致高光过曝为白色：从顶部使用 matcap 或 hsgrey。

常见错误

错误	表现	修复方法
在微倒角下方执行布尔运算	切割边缘极为锐利，其余部分有倒角	HS.order_stack(ob)
在固定倒角后添加加权法线	WN 排在倒角上方，涂抹效果复现	自下而上固定（order_stack）
切割体靠近目标面或边缘，但未与之重合	整个对象的倒角变窄，出现细小台阶	明确移开或精确吸附；使用 cutter_report、clamp_culprits
凹槽或壁面厚度小于倒角宽度的 2 倍	到处都是被夹限的倒角	加宽特征或减小倒角宽度
圆形切割体与目标面的分段相位一致	出现条纹、黑斑、非流形边	使用半段相位（make_cutter 中的默认值）
30 度面上的切割体圆角	微倒角捕捉面边缘，导致夹限	增加分段数（beveled_narrow_facet_edges）
平面着色的切割体	切割壁面出现刻面	切割体使用平滑着色（make_cutter 会处理）
“切换到 Fast”	共面面上产生非流形结果	使用 EXACT；改为修复运算对象
未应用缩放	倒角宽度不均匀	HS.apply_scale
在非平面上叠加法线修复	出现任何修复都无法消除的拉伸	HS.flatten_faces
在 WN 前放置数据传递，或使用顶点组限定范围	没有效果／切割壁面着色与表面相同	HS.transfer_normals（放在 WN 后，并按距离限定范围）
du Mont 的支撑切口穿过圆形切口	边缘被截半，夹限值为 0 到 1.2［已验证］	仅在 sliver_report 显示布尔运算产生细长碎片时使用；前后测量
在主要细分曲面边缘上使用折痕	表面变软、收缩、厚重	使用支撑环，或在细分前进行倒角
移动游戏副本或切片	切口消失（切割体仍留在原处）	保持原位，或先执行 HS.collapse 再移动

Blender 5.2 说明

• Auto Smooth 已移除（4.1）：bpy.ops.object.shade_auto_smooth 会添加一个固定的 Smooth by Angle 节点修改器（在无头模式下使用 temp_override 也能正常工作）；WN、Harden Normals 和 Data Transfer 都不需要 Auto Smooth。
• 布尔求解器：'EXACT'（默认）、'MANIFOLD'（4.5）、'FLOAT'（旧版 Fast，已在 5.0 更名）。
• 倒角权重和折痕是属性 bevel_weight_edge / crease_edge（4.0）；Bevel 修改器通过 edge_weight 读取任何属性。
• ob.modifiers.move(i, j) 遇到固定修改器时会静默拒绝移动；modifier_move_to_index 会返回 CANCELED。先取消固定，再移动，然后从底部开始重新固定。
• bmesh.ops.bevel 的默认值是 segments=0, profile=0.0：务必同时传入这两个参数。
• 已验证，EXACT 会让切割器生成的顶点继承目标对象的顶点组权重，因此无法靠顶点组阻止 Data Transfer 影响切割壁面。
• Bool Tool、LoopTools、Extra Objects 是扩展（4.2）；LoopTools Circle/Flatten/Space 已内置（mesh.circularize、mesh.flatten、mesh.space_edge_loops_evenly）；Relax 和 Round Cube 则未内置。

参考资料

• references/procedures.md：三个部分（面板、两种流程的外壳、两种流程的枪管）的完整测试代码、所有审查案例和游戏路线。编写脚本前加载。
• references/critique.md：用于评估渲染和得出结论的评分标准与分流表。每次着色时加载。
• references/expert-notes.md：专家的原则、分歧和判断条件，并附带时间戳。遇到本文未涵盖的选择时加载。
• references/sources.md：九个视频、作者、各自最适合的用途以及最佳时间戳。