scenario-blender-retopology

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Blender retopology

Expert retopology is a plan executed with the fewest loops that capture the forms and let the mesh deform: loops close around eyes, mouth and joints, poles sit where nothing moves, and the subdivided surface, not the cage, matches the sculpt. An agent without a mouse can build every piece of this from data, but it reaches expert quality only on the parts it plans explicitly. Automatic remeshing is a finish for static assets and a start for everything else. If a sibling skill named here is missing from your available skills, ask the user to install it (

npx skills add scenario-labs/skills --skill <name>

); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-blender-expert (execution channel, review loop, 5.2 API changes). Toolkit:

scripts/bx_retopo.py

(

import sys; sys.path.append("<skills>/scenario-blender-retopology/scripts"); import bx_retopo as R

), all coordinates in the sculpt's local space.

专家级 retopology 是一份用最少 loop 捕捉形体并让 mesh 能够变形的计划：loop 在眼睛、嘴部和关节周围闭合，pole 位于不会发生运动的位置，而且与 sculpt 匹配的是细分后的 surface，而不是 cage。没有鼠标的 Agent 也能根据数据构建其中的每个部分，但只有对明确规划过的部分才能达到专家质量。对于静态 asset，自动 remesh 是终点；对于其他所有用途，它都只是起点。如果此处提到的某个同级 skill 不在可用 skill 中，请让用户安装它（

npx skills add scenario-labs/skills --skill <name>

）；在无人值守的情况下，根据 tool schema 继续执行，并标记该缺口。

必需背景： scenario-blender-expert（执行通道、review loop、5.2 API 变更）。Toolkit：

scripts/bx_retopo.py

（

import sys; sys.path.append("<skills>/scenario-blender-retopology/scripts"); import bx_retopo as R

），所有坐标均位于 sculpt 的 local space。

Stance (the expert delta)

立场（专家级差距）

Map first, as data. Kaspar draws six layers on the sculpt before any vertex: edge flow, primary creases, secondary (expression-only) creases, articulation, expression bounds, landmarks (BCON22 [00:07:55], shown in frames 00:07:53 to 00:14:38). The agent writes the same map as coordinates and loop counts (landmarks from renders plus
```
R.surface_point
```
), then builds.
Loops are the budget, not vertices. Articulation minimum (Kaspar after Brian Tindall): lids, lips and brows as curves with 3 controls and 2 handle loops each, plus 2 corner loops on eyes; upper count = lower count (Dikko, Kaspar, Kenny); 3 loops per joint; a crease is 1 loop on it plus 2 hugging it. Elsewhere "as much as it needs to be" (Kaspar Live #3 [01:56:33]).
Poles: valence 3 or 5, where nothing moves, never on a crease loop, a shell rim or the face center line (Kaspar Live #7 [00:11:41], Live #3 [00:36:54]; Dikko [00:04:49]). Lampel's reason: pinching is a density jump in the subdivided result, harmless on flat still areas (BCON24 [00:21:18]). [added] An agent's poles come from ring-count reductions (4 per unit) and from cut borders that staircase across an auto base (about half their vertices): budget both.
Loops close on themselves. A spiral around eyes or lips means rebuild (Dikko); a spiral that terminates in a still area is tolerated (Dikko body [00:09:34], Kaspar nose).
Judge the subdivided surface. A snapped cage shrinks inside when subdivided; a Shrinkwrap offset fixes convex areas and worsens cavities. Fit the cage so its subdivided surface matches (Duha BCON23 [00:08:58]):
```
R.fit_subdiv
```
. Kaspar's Multires Apply Base does the same job but overshoots (measured below).
Game low poly = silhouette plus animation loops (SpeedChar): face about 3x body density, triangles wherever nothing bends, twisted quads cut by hand so baker and engine agree, low poly slightly proud of the high; every hard edge is a UV seam (On Mars 3D).
Auto-remesh fits static, scanned, background or bake-only assets (Lampel [00:09:05], Grant Abbitt, Duha, Jamie Dunbar). For deforming characters it lacks the judgment calls: on the sheep, QuadriFlow at expert density gave no rings around eyes or mouth and tore a thin ear.

先以数据形式绘制 Map。 Kaspar 在创建任何 vertex 前，会先在 sculpt 上画出六层：edge flow、primary crease、secondary crease（仅用于表情）、articulation、expression bounds 和 landmark（BCON22 [00:07:55]，展示于 00:07:53 至 00:14:38）。Agent 会将同一张 Map 写为坐标和 loop 数量（landmark 来自 render 与
```
R.surface_point
```
），然后再进行构建。
Loop 是预算，而不是 vertex。 Articulation 的最低配置（Kaspar 在 Brian Tindall 之后的方法）：眼睑、嘴唇和眉毛用曲线表示，每条包含 3 个 control 和 2 个 handle loop，眼睛另外加 2 个 corner loop；上侧数量 = 下侧数量（Dikko、Kaspar、Kenny）；每个 joint 使用 3 个 loop；一条 crease 上有 1 个 loop，另有 2 个 loop 紧贴它。其他位置则“需要多少就放多少”（Kaspar Live #3 [01:56:33]）。
Pole：valence 为 3 或 5，放在不会运动的位置；绝不能位于 crease loop、shell rim 或 face center line 上（Kaspar Live #7 [00:11:41]、Live #3 [00:36:54]；Dikko [00:04:49]）。Lampel 的解释是：pinching 是细分结果中的 density jump，在平坦且静止的区域无害（BCON24 [00:21:18]）。[新增] Agent 的 pole 来自 ring 数量的缩减（每缩减一个 unit 会产生 4 个 pole），以及切边在 auto base 上呈阶梯状分布的情况（约占其 vertex 的一半）：这两类都要计入预算。
Loop 必须自行闭合。 眼睛或嘴唇周围出现 spiral 就必须重建；在静止区域终止的 spiral 则可以接受（Dikko body [00:09:34]、Kaspar nose）。
以细分后的 surface 为准。 snapped cage 在细分后会收缩到内部；Shrinkwrap offset 能修正凸起区域，却会加重 cavity。调整 cage，使其细分后的 surface 与 sculpt 匹配（Duha BCON23 [00:08:58]）：
```
R.fit_subdiv
```
。Kaspar 的 Multires Apply Base 也能完成同样的工作，但会产生过冲（见下方测量值）。
游戏 low poly = silhouette + 动画 loop（SpeedChar）：面部 density 约为身体的 3 倍；不会弯曲的位置使用 triangle；扭曲的 quad 必须手动切割，让 baker 和 engine 得到一致结果；low poly 应略微位于 high poly 外侧；每条 hard edge 都是 UV seam（On Mars 3D）。
Auto-remesh 适合静态、扫描、背景或仅用于 bake 的 asset（Lampel [00:09:05]、Grant Abbitt、Duha、Jamie Dunbar）。对于会变形的 character，它缺少必要的判断：在 sheep 上，QuadriFlow 按专家 density 重网格后，眼睛和嘴部周围没有 ring，还撕裂了一片薄耳朵。

Establish first

先确定条件

Input	Why it changes the plan	Default when silent
Purpose	film cage renders at subdivision 2 (Kaspar); game ships triangles and bakes	deforming character: film-style all-quad cage
Budget	film: no vertex budget, minimum loops (Kaspar); game: triangle budget	film stylized head 1,650 to 4,100 faces, body 9,400 to 16,500 (Blender Studio meshes); game character < 10,000 tris
Deformation	face rig, joints, how far the mouth travels (expression bounds)	face + limbs deform
Camera	detail and density follow the closest view (SpeedChar)	close-up face
Style	stylized: creases in topology; realistic: generic base + displacement (Kaspar)	stylized
Symmetry	`R.topology_report(sculpt)["sym_local_pct"]` , local space	Mirror only above ~98 % (the sheep is 21 %, posed)
Separate parts	eyes, teeth, hair clumps, clothing (from the body duplicate)	separate objects

输入	为什么会改变计划	未说明时的默认值
用途	film cage 在 subdivision 2 下进行 render（Kaspar）；game 输出 triangle 并进行 bake	会变形的 character：采用 film 风格的全 quad cage
预算	film：没有 vertex budget，以最少 loop 为原则（Kaspar）；game：采用 triangle budget	film 风格化头部 1,650 至 4,100 个 face，身体 9,400 至 16,500 个（Blender Studio mesh）；game character < 10,000 tris
变形	面部 rig、joint、嘴部的运动幅度（expression bounds）	面部和四肢均会变形
Camera	细节和 density 跟随最近的视角	特写面部
风格	风格化：在 topology 中表现 crease；写实：通用 base + displacement（Kaspar）	风格化
对称性	`R.topology_report(sculpt)["sym_local_pct"]` ，local space	仅在约 98% 以上时使用 Mirror（sheep 为 21%，且处于 pose 状态）
独立部件	眼睛、牙齿、发束、衣物（从身体 duplicate 得出）	独立 object

Workflow

工作流

Inspect (procedures P1): holes, manifoldness, scale, rotation, symmetry. GATE: all four written down.
Map: read the sculptor's face sets first (
```
R.face_set_map
```
,
```
R.face_set_review
```
, P1b: lip line, eye masks, ears, hooves); landmarks with coordinates, loop counts per feature from the Numbers table, crease list (check expression shape keys), per-part density. GATE: map exists before any geometry.

Choose a method per part:

Part	Method	Evidence
Eyes, mouth, brows (deforming)	`carve_rings(corners=, count=(lo, hi))` : upper = lower by construction, geodesic rings, the border's count kept when inside the range; pair odd boundaries first ( `parity_strip` )	v2: eyes 24 (12/12), mouth 30 (15/15) on every clean ring; forcing Kaspar's 18/24 cost 40 more poles
Nasolabial, face frame, neck (map lines)	`carve_band` along `enclosing_contour` of face sets (P7): one clean loop, poles pushed onto the base	v2: nasolabial +18 poles; face frame opt-in, +64 poles on the sheep
Limbs, ears, tail, fingers, horns	`limb_profile` (geodesic contours, root and joints found) + `socket_tube(count=)` (P3b, P8); straight parts: `tube` from sections	v2: all 7 parts incl. the 1 m curled tail, 3 rings per joint
Skull, torso, smooth masses	QuadriFlow start acceptable, else grid patches	little deformation
Static prop, scan, bake-only	QuadriFlow whole object ( `R.quadriflow` )	Lampel, Grant Abbitt
Realistic human head	shrinkwrap a clean generic base mesh, then fit (Kaspar BCON22 [00:20:16])	not scripted here

Build islands separately and roughly (Kaspar: "don't focus on tweaking all the points"). Stack via
```
R.setup_cage
```
(Mirror clip > Shrinkwrap Target Normal Project > Subsurf hidden in edit mode). GATE: topology gate below passes per island.
Relax and freeze hand-built layouts:
```
R.relax
```
,
```
R.freeze
```
. Not after QuadriFlow (worsened coverage 0.44 % to 0.55 %).
Connect by counts:
```
R.boundary_loops
```
, then
```
R.bridge
```
/
```
R.weld_loops
```
on equal counts; reduce the larger side first (Kaspar: wrist 10 vs hand 16 was "six too many"). GATE: no triangles created.
Volume: film
```
R.fit_subdiv
```
(gentle defaults); game
```
R.push_outside
```
then
```
R.triangulate_twisted
```
and a Triangulate modifier on export.
Review and hand off: gates, two render sheets, handoff hygiene (P13). Report what the agent did not plan.

检查（流程 P1）：孔洞、manifold 性、scale、rotation、symmetry。GATE：四项都必须记录下来。
绘制 Map：先读取 sculpt 中的 face set（
```
R.face_set_map
```
、
```
R.face_set_review
```
、P1b：lip line、eye mask、ear、hoof）；记录 landmark 及坐标、Numbers 表中各特征的 loop 数量、crease 列表（检查 expression shape key）、各部件 density。GATE：创建任何 geometry 之前，Map 必须存在。

为每个部件选择方法：

部件	方法	依据
眼睛、嘴部、眉毛（会变形）	`carve_rings(corners=, count=(lo, hi))` ：通过构造保证上侧 = 下侧，使用 geodesic ring；当边界数量处于范围内时保持该数量；优先成对处理 odd boundary（ `parity_strip` ）	v2：每个干净 ring 上眼睛为 24（12/12），嘴部为 30（15/15）；强制采用 Kaspar 的 18/24 会额外产生 40 个 pole
Nasolabial、面部框架、颈部（Map line）	沿 face set 的 `enclosing_contour` 使用 `carve_band` （P7）：得到一个干净 loop，并将 pole 推至 base 上	v2：nasolabial 增加 18 个 pole；face frame 为可选启用，在 sheep 上增加 64 个 pole
四肢、耳朵、尾巴、手指、角	`limb_profile` （geodesic contour，自动寻找 root 和 joint）+ `socket_tube(count=)` （P3b、P8）；笔直部分：用 section 生成 `tube`	v2：全部 7 个部件，包括 1 米长的卷曲尾巴，每个 joint 使用 3 个 ring
头骨、躯干、光滑体块	QuadriFlow 起点可接受，否则使用 grid patch	变形很少
静态 prop、扫描模型、仅用于 bake 的 asset	对整个 object 使用 QuadriFlow（ `R.quadriflow` ）	Lampel、Grant Abbitt
写实人类头部	用 Shrinkwrap 包裹一个干净的通用 base mesh，然后执行 fit（Kaspar BCON22 [00:20:16]）	此处未编写 script

分别且粗略地构建各个 island（Kaspar：“不要把注意力都放在微调所有点上”）。通过
```
R.setup_cage
```
进行 stack（Mirror clip > Shrinkwrap Target Normal Project > 在 edit mode 中隐藏 Subsurf）。GATE：下方 topology gate 必须在每个 island 上通过。
Relax 并冻结手工构建的 layout：
```
R.relax
```
、
```
R.freeze
```
。不要在 QuadriFlow 之后执行（coverage 会从 0.44% 恶化到 0.55%）。
按数量连接：先使用
```
R.boundary_loops
```
，然后对数量相等的 loop 使用
```
R.bridge
```
/
```
R.weld_loops
```
；先减少较大的一侧（Kaspar：手腕 10 对手掌 16，“多了六个”）。GATE：不得产生 triangle。
Volume：film 使用
```
R.fit_subdiv
```
（轻度默认值）；game 使用
```
R.push_outside
```
，然后执行
```
R.triangulate_twisted
```
，并在导出时添加 Triangulate modifier。
Review 与 handoff：执行 gate、生成两张 render sheet、遵守 handoff 规范（P13）。报告 Agent 未规划的部分。

What an agent reaches (measured on the sheep;

tests/code/blender-retopology/sheep_results.json

and

compare/metrics.json

)

Agent 能达到的效果（在 sheep 上测量；

tests/code/blender-retopology/sheep_results.json

和

compare/metrics.json

）

Strategy	Faces	Subdiv-2 mean error	Inside	Eye / mouth rings	Closed-loop edges	Looks
Kaspar's own retopo	2,596	0.24 %	47 %	5,5 / 2	29.9 %	clean, reads unsubdivided
QuadriFlow, area-matched budget	4,372	0.14 %	87 %	0 / 0	1.6 %	faceted, torn ear, uniform density
+ gentle `fit_subdiv`	4,372	0.045 %	53 %	0 / 0	1.6 %	smooth masses, lumpy hooves
+ Multires Apply Base instead	4,372	0.11 %	15 %	0 / 0	1.6 %	overshoot
Hybrid: eye rings + ear tubes + gentle fit	4,544	0.042 %	52 %	3,3 / 0	5.9 %	first skill version
E1 run with the skill (fresh agent: face sets, warp, 4 eye rings, 5 lip rings, limb tubes)	5,778	0.040 %	51 %	4,4 / 5 (46 to 48 verts)	19.4 %	planned face, rippled lids, lumps at leg joins
v2 tools, final ( `test_sheep_v2.py` : face sets, counts as ranges, corner split, geodesic rings and tubes, nasolabial loop)	4,980	0.028 %	52 %	4,4 clean 24-vert rings, 12/12 / 5 x 30, 15/15	33.9 %	best agent result: poles 5.7 % (Kaspar 5.2 %), none on clean rings, no 6-poles; nose and upper-lip patch irregular (human pass)

Numbers flatter the agent: an aggressive fit scored 0.043 % and looked lumpier than Kaspar's cage. What stays human-level only: articulation counts with handle loops, crease loops placed from expression shapes, pole routing and loop budgets out of the face. Say so in the report.

策略	Faces	Subdiv-2 mean error	Inside	Eye / mouth rings	Closed-loop edges	外观
Kaspar 自己的 retopo	2,596	0.24%	47%	5,5 / 2	29.9%	干净，即使不 subdivision 也能清楚表达形体
QuadriFlow，按 area 匹配的 budget	4,372	0.14%	87%	0 / 0	1.6%	有 facet、耳朵撕裂、density 均匀
+ 轻度 `fit_subdiv`	4,372	0.045%	53%	0 / 0	1.6%	体块平滑，但 hoof 凹凸不平
+ 改用 Multires Apply Base	4,372	0.11%	15%	0 / 0	1.6%	过冲
混合方案：eye ring + ear tube + 轻度 fit	4,544	0.042%	52%	3,3 / 0	5.9%	首个 skill 版本
使用该 skill 的 E1 run（全新 Agent：face set、warp、4 个 eye ring、5 个 lip ring、limb tube）	5,778	0.040%	51%	4,4 / 5（46 至 48 个 vert）	19.4%	面部有规划，眼睑起伏，腿部连接处有块状凸起
v2 tools，最终版（ `test_sheep_v2.py` ：face set、范围形式的 count、corner split、geodesic ring 和 tube、nasolabial loop）	4,980	0.028%	52%	4、4 个干净的 24-vert ring，12/12 / 5 x 30，15/15	33.9%	最佳 Agent 结果：pole 占 5.7%（Kaspar 为 5.2%），干净 ring 上没有 pole，也没有 6-pole；nose 和 upper-lip patch 不规则（经人工处理）

这些数字会让 Agent 的表现显得更好：激进 fit 的误差得分为 0.043%，但看起来比 Kaspar 的 cage 更加凹凸不平。仍然只有人类专家水平的部分是：带 handle loop 的 articulation 数量、根据 expression shape 放置 crease loop、pole routing，以及脸部之外的 loop 预算。必须在报告中说明这一点。

Numbers

数字指标

Item	Value	Source
Render subdivision (film)	2 levels; viewport 1	Kaspar Live #6 [00:21:53]; BCON22 frame 00:26:38
Joint	3 loops over the bending part	Kaspar Live #5 [01:37:48]
Limb start ring	8 verts (legs 8 then 12); Dikko arms 8 min, 10 to 12 typical, legs 18	Kaspar Live #4 [00:06:54]; Dikko [00:13:47]
Eyelid	2 loops per lid crease + ~4 across; 10/10 spans example	Kaspar Live #1 [02:11:22]; Dikko [00:04:16]
Studio mesh	99.9 %+ quads, 0 to 4 valence 6+ (report and justify each), poles ~1.8 % head, ~5 % body, edge CV 0.33 to 0.8	calibration (bx_audit on Blender Studio files)
Auto-remesh hint (not a gate)	edge CV ~0.17 to 0.27 on an unedited uniform remesh, near 0 % closed loops	calibration, sheep
Game	head 2,000 to 3,000 tris, hands ~1,000 both, body 5,000 to 6,000	SpeedChar ep23 [00:09:58], ep24 [00:50:34]
Apply Base levels	2 body, 3 head, hair, clothes	Kaspar Live #5 [02:15:03]

项目	数值	来源
渲染细分（film）	2 个级别；viewport 为 1	Kaspar Live #6 [00:21:53]；BCON22 frame 00:26:38
Joint	弯曲部分上方使用 3 个 loop	Kaspar Live #5 [01:37:48]
Limb 起始 ring	8 个 vert（腿先 8 后 12）；Dikko 手臂最少 8 个，通常为 10 至 12 个，腿为 18 个	Kaspar Live #4 [00:06:54]；Dikko [00:13:47]
Eyelid	每个眼睑 crease 使用 2 个 loop，横向约 4 个；10/10 span 示例	Kaspar Live #1 [02:11:22]；Dikko [00:04:16]
Studio mesh	99.9% 以上为 quad，valence 6+ 为 0 至 4 个（逐个报告并说明理由），头部 pole 约 1.8%，身体约 5%，edge CV 为 0.33 至 0.8	校准数据（对 Blender Studio 文件执行 bx_audit）
Auto-remesh 提示（不是 gate）	未编辑的均匀 remesh，其 edge CV 约为 0.17 至 0.27，closed loop 接近 0%	校准数据，sheep
Game	头部 2,000 至 3,000 tris，双手合计约 1,000 tris，身体 5,000 至 6,000 tris	SpeedChar ep23 [00:09:58]、ep24 [00:50:34]
Apply Base 级别	身体 2 级，头部、头发、衣物 3 级	Kaspar Live #5 [02:15:03]

Quality gates

Quality gate

Code (thresholds [added], calibrated on Kaspar's sheep: 0.24 % mean, 47 % inside, coverage p95 0.82 %):

python

retopo_gate = R.topology_report(retopo)
fit_gate = R.fidelity(retopo, sculpt, levels=2)
gate = {"six_poles_to_justify": retopo_gate["valence_6plus"], "no_rim_poles": retopo_gate["rim_poles"] == 0,
        "quads": retopo_gate["non_quads_visible"] == 0 or retopo_gate["quads_pct"] >= 99.0,
        "subd_fit": fit_gate["mean_pct"] <= 0.3 and 40 <= fit_gate["inside_pct"] <= 60,
        "coverage": fit_gate["cov_p95_pct"] <= 1.0, "loops": R.loop_stats(retopo)}
print(gate)

Edge-length CV is never pass/fail (studio meshes read 0.33 to 0.8); 6-poles are reported and justified, not banned (studio 0 to 4). Also:

crease_poles == 0

center_poles == 0

on mirrored faces,

R.loops_around(retopo, eye, normal, max_radius)

returns at least 3 closed rings per eye and mouth, ring counts equal before every merge, triangles only in hidden or rigid areas, budget met (

R.tri_count

). Visual (

bx_review

, same views as the sculpt): cage in wire (rings close, no wandering loops, poles in still areas) and subdivided matcap (lumps, pinching at poles, creases held), then the cage alone: it must read without subdivision (Kaspar Finale [01:58:41]). Score with

references/critique.md

代码（阈值 [新增]，以 Kaspar 的 sheep 校准：0.24% mean、47% inside、coverage p95 0.82%）：

python

retopo_gate = R.topology_report(retopo)
fit_gate = R.fidelity(retopo, sculpt, levels=2)
gate = {"six_poles_to_justify": retopo_gate["valence_6plus"], "no_rim_poles": retopo_gate["rim_poles"] == 0,
        "quads": retopo_gate["non_quads_visible"] == 0 or retopo_gate["quads_pct"] >= 99.0,
        "subd_fit": fit_gate["mean_pct"] <= 0.3 and 40 <= fit_gate["inside_pct"] <= 60,
        "coverage": fit_gate["cov_p95_pct"] <= 1.0, "loops": R.loop_stats(retopo)}
print(gate)

Edge-length CV 从不作为 pass/fail（studio mesh 的读数为 0.33 至 0.8）；6-pole 需要报告并给出理由，而不是一律禁止（studio 为 0 至 4 个）。另外：镜像 face 上的

crease_poles == 0

、

center_poles == 0

；

R.loops_around(retopo, eye, normal, max_radius)

对每只眼睛和嘴部至少返回 3 个 closed ring；每次 merge 前 ring 数量必须相等；triangle 只允许出现在隐藏或刚性区域；必须满足 budget（

R.tri_count

）。视觉检查（

bx_review

，使用与 sculpt 相同的视角）：以 wire 显示 cage（ring 闭合、没有游走的 loop、pole 位于静止区域），再显示 subdivision 后的 matcap（检查凸块、pole 处的夹点、crease 是否保持），最后只显示 cage：它必须在不 subdivision 的情况下也能清楚表达形体（Kaspar Finale [01:58:41]）。按照

references/critique.md

评分。

Common mistakes

常见错误

Mistake	Looks like	Fix
Carving around QuadriFlow's closed eye slits	every eye ring odd (47, 45), no all-quad fix	`R.parity_strip` between the two odd boundaries BEFORE carving
Counts inherited from a dense cut, or forced far below it	eye rings 46 to 48; or pole density 9.5 %	`count=(lo, hi)` : each reduction unit costs 4 poles; ranges took the sheep from 9.5 to 5.7 %
3D-nearest lookups where surfaces touch	a band or socket cut bites an ear lying on the cheek	geodesic fields, `curve_verts` , oriented `nearest_vertex` (built into bands and tubes)
Tight rings for an edge-flow loop	a ridge after subdivision	band `spacing` = edge length; tight only for creases
Shipping a snapped cage	subdivided surface inside the sculpt (87 %)	`R.fit_subdiv`
Shrinkwrap offset for volume	cavities worse	fit, offset 0
Raw `quadriflow_remesh` on a small dense mesh	CANCELED, "needs to be manifold"	`R.quadriflow` (scale trick, voxel fallback)
QuadriFlow symmetry left at its default True	wrong half on a posed mesh	`symmetry=False` unless symmetric
Relaxing an auto-remesh	tips and ears shrink	relax hand-built layouts only
Mark Sharp / Seam as reminders	shading breaks (4.1+), unwrap cuts	`retopo_crease` attribute (P5)
Grid fill on an odd loop	FINISHED, 0 faces	count first; `R.grid_fill` raises
Connecting parts early	every new loop runs everywhere	islands, count, merge last
Trusting mean error	lumpy fit passes	matcap review, gentle fit
Re-shrinkwrap after Apply Base	volume lost again	never (Kaspar Live #6 [00:20:08])
Game quads left non-planar	lines in the normal map	`R.triangulate_twisted` , Triangulate on export

错误	表现	修复方法
围绕 QuadriFlow 的 closed eye slit 进行 carving	每个 eye ring 都是 odd 数量（47、45），无法得到全 quad	在 carving 之前，对两个 odd boundary 之间运行 `R.parity_strip`
沿用从密集 cut 继承的数量，或将数量强制压得过低	eye ring 为 46 至 48 个；pole density 为 9.5%	使用 `count=(lo, hi)` ：每缩减一个 unit 会消耗 4 个 pole；range 将 sheep 的 pole 比例从 9.5% 降至 5.7%
表面相接处使用 3D nearest lookup	band 或 socket cut 会切入贴在脸颊上的耳朵	使用 geodesic field、 `curve_verts` 、有朝向的 `nearest_vertex` （band 和 tube 已内置）
为 edge-flow loop 使用过紧的 ring	subdivision 后出现 ridge	band 的 `spacing` = edge length；仅对 crease 使用紧 ring
交付 snapped cage	subdivision 后的 surface 位于 sculpt 内部（87%）	`R.fit_subdiv`
使用 Shrinkwrap offset 修正 volume	cavity 变得更糟	使用 fit，offset 设为 0
在小型密集 mesh 上直接使用 `quadriflow_remesh`	CANCELED，“needs to be manifold”	`R.quadriflow` （scale trick、voxel fallback）
QuadriFlow symmetry 保持默认 True	在 posed mesh 上得到错误的一半	除非 mesh 对称，否则设置 `symmetry=False`
Relax auto-remesh	tip 和 ear 收缩	仅 relax 手工构建的 layout
将 Mark Sharp / Seam 仅作为提醒标记	shading 中断（4.1+），unwrap 出现切口	使用 `retopo_crease` attribute（P5）
在 odd loop 上使用 Grid fill	FINISHED，0 faces	先执行 count； `R.grid_fill` 会抛出异常
过早连接部件	每个新 loop 都贯穿所有位置	先构建 island，再 count，最后 merge
过度信任 mean error	凹凸不平的 fit 也能通过	使用 matcap review 和轻度 fit
Apply Base 后重新执行 shrinkwrap	volume 再次丢失	绝不能这样做（Kaspar Live #6 [00:20:08]）
游戏 quad 保持非平面状态	normal map 中出现线条	`R.triangulate_twisted` ，并在导出时启用 Triangulate

Blender 5.2 notes

Blender 5.2 注意事项

Hidden Wire is the Retopology overlay (
```
overlay.show_retopology
```
, offset 0.01 m since 4.5); "Project Individual Elements" is
```
snap_elements_individual = {'FACE_PROJECT'}
```
. GUI only.
Slide Relax is the Relax Slide brush asset (strokes need a window,
```
bx_gui
```
); headless use
```
R.relax
```
. F2, LoopTools, BSurfaces are extensions;
```
mesh.circularize
```
,
```
space_edge_loops_evenly
```
,
```
flatten
```
are built in;
```
mesh.select_by_pole_count
```
exists (4.4).
The BCON22 build's Shrinkwrap showed Smooth Factor 0.05 / Repeat 1 (frame 00:22:53); 5.2.1's Shrinkwrap has no such option.
```
sharp_edge
```
is always honored since 4.1; Auto Smooth is gone (Smooth by Angle modifier).
Apply Base =
```
object.multires_base_apply(apply_heuristic=True)
```
; QuadriFlow lost its shortcut and has the traps above.

Hidden Wire 现在是 Retopology overlay（
```
overlay.show_retopology
```
，自 4.5 起 offset 为 0.01 m）；“Project Individual Elements”对应
```
snap_elements_individual = {'FACE_PROJECT'}
```
。仅限 GUI。
Slide Relax 是 Relax Slide brush asset（stroke 需要在窗口中执行，使用
```
bx_gui
```
）；headless 场景使用
```
R.relax
```
。F2、LoopTools、BSurfaces 是 extension；
```
mesh.circularize
```
、
```
space_edge_loops_evenly
```
、
```
flatten
```
是内置功能；
```
mesh.select_by_pole_count
```
已存在（4.4）。
BCON22 版本中的 Shrinkwrap 显示 Smooth Factor 0.05 / Repeat 1（frame 00:22:53）；5.2.1 的 Shrinkwrap 没有此选项。
```
sharp_edge
```
自 4.1 起始终会生效；Auto Smooth 已被移除（改用 Smooth by Angle modifier）。
Apply Base =
```
object.multires_base_apply(apply_heuristic=True)
```
；QuadriFlow 失去了快捷方式，并且存在上述陷阱。

References

参考资料

```
references/procedures.md
```
: tested code, P0 to P14 (inspect, face sets P1b, stack, tubes, geodesic limbs P3b, freeze/relax, annotations, QuadriFlow, map-line loops and rings, sockets, volume, checks, game, expression test, handoff, AI-mesh finishing). Load before writing any code.
```
references/expert-notes.md
```
: principles by expert with timestamps, face and body loop maps, clothing, game rules, the sheep experiment in full. Load when planning a face, body, clothing or game mesh.
```
references/critique.md
```
: the rubric to judge your own retopo. Load at every review.
```
references/sources.md
```
: all 24 source videos with best timestamps.

```
references/procedures.md
```
：经过测试的代码，P0 至 P14（检查、face set P1b、stack、tube、geodesic limb P3b、freeze/relax、标注、QuadriFlow、map-line loop 和 ring、socket、volume、检查、game、expression test、handoff、AI mesh 收尾）。编写任何代码前先加载。
```
references/expert-notes.md
```
：各位专家的原则及时间戳、face 和 body loop map、服装、game 规则，以及完整的 sheep 实验。规划 face、body、clothing 或 game mesh 时加载。
```
references/critique.md
```
：用于评审自身 retopo 的 rubric。每次 review 时都应加载。
```
references/sources.md
```
：全部 24 个来源视频及其最佳时间戳。

scenario-blender-retopology

Original

Translation

Blender retopology

Blender retopology

Stance (the expert delta)

立场（专家级差距）

Establish first

先确定条件

Workflow

工作流

What an agent reaches (measured on the sheep;
`tests/code/blender-retopology/sheep_results.json`
and
`compare/metrics.json`
)

Agent 能达到的效果（在 sheep 上测量；
`tests/code/blender-retopology/sheep_results.json`
和
`compare/metrics.json`
）

Numbers

数字指标

Quality gates

Quality gate

Common mistakes

常见错误

Blender 5.2 notes

Blender 5.2 注意事项

References

参考资料

scenario-blender-retopology

Original

Translation

Blender retopology

Blender retopology

Stance (the expert delta)

立场（专家级差距）

Establish first

先确定条件

Workflow

工作流

What an agent reaches (measured on the sheep; tests/code/blender-retopology/sheep_results.json and compare/metrics.json)

Agent 能达到的效果（在 sheep 上测量；tests/code/blender-retopology/sheep_results.json 和 compare/metrics.json）

Numbers

数字指标

Quality gates

Quality gate

Common mistakes

常见错误

Blender 5.2 notes

Blender 5.2 注意事项

References

参考资料

What an agent reaches (measured on the sheep;
`tests/code/blender-retopology/sheep_results.json`
and
`compare/metrics.json`
)

Agent 能达到的效果（在 sheep 上测量；
`tests/code/blender-retopology/sheep_results.json`
和
`compare/metrics.json`
）