scenario-maya-retopology-uv

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maya retopology and UVs

Maya retopology 与 UVs

Expert retopology is a loop plan with the fewest polygons that still deform: landmarks first, rings around eyes and mouth, three loops per joint, poles where nothing moves, a bend test that says whose fault a bad crease is. Expert UVs spend texels where the camera looks, at a density derived from the closest shot, with padding that survives mips. Without a mouse the agent reuses approved topology, builds from data, and measures then renders every stage. 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-maya-expert (execution channel, review loop, 2027 version traps). Toolkit:

scripts/mx_retopology_uv.py

(

import mx_retopology_uv as RU

), built on mx_audit, mx_review and mx_run.

Status (2026-09-24): every Maya call is not yet run in Maya (not installed); 99 pure and 40 fake-Maya checks pass offline. First run

tests/code/maya-retopology-uv/run_all.sh

, then fix what

job_probe_commands

reports.

专家级 retopology 是一套 loop plan：使用尽可能少、但仍能正常变形的 polygons；先确定 landmarks，再围绕眼睛和嘴部布置 rings，每个关节使用三条 loops，在不会活动的区域设置 poles，并通过 bend test 判断糟糕折痕的责任方。专家级 UVs 会把 texels 分配到镜头会看到的位置，密度由最近镜头推导，padding 还能在 mips 下保持有效。无需鼠标时，Agent 会复用已批准的 topology、基于数据构建，并对每个阶段进行测量和渲染。如果这里提到的某个 sibling skill 未包含在你的可用 skills 中，请让用户安装（

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

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

必需背景： scenario-maya-expert（执行通道、review loop、2027 版本陷阱）。工具包：

scripts/mx_retopology_uv.py

（

import mx_retopology_uv as RU

），基于 mx_audit、mx_review 和 mx_run 构建。

状态（2026-09-24）： 所有 Maya 调用尚未在 Maya 中运行（未安装）；离线状态下 99 项纯测试和 40 项 fake-Maya 检查均已通过。首先运行

tests/code/maya-retopology-uv/run_all.sh

，然后修复

job_probe_commands

报告的问题。

Stance (the expert delta)

立场（专家增量）

Landmarks first, big polygons, then fill like a puzzle. FlippedNormals: starting small is "a terrible way to work"; loose is recoverable, tight is not (9N4rG5qHWgk [00:01:05] [00:02:07]). The loop map is data before any vertex; a template fit is gated at base density before spans are added.
Reuse approved topology. FlippedNormals carry one perfect hand, ear or base mesh to every model ([00:10:11]); Jessica Dru Johnson's standard base cut face skinning from three days to 30 minutes (ZiYEO49B768 [00:58:51]). Quad Draw substitute:
```
RU.fit_template
```
.
No automatic topology on what deforms. On a face it "will look normal, but it's not" (FlippedNormals [00:23:15]); automatic is for parts that do not animate ([00:22:13]). Retopologize serves props, armor plates, static cloth; on a torso or loose coat it is a flagged start that must pass the deformation gate.
Isolate and bound deformation. Concentric rings around eyes and mouth, one control plus two support loops per joint, a flat loop from lip corner to jaw corner against shearing (Jessica [01:15:51] [01:30:10]), equal lid loop counts (FlippedNormals [00:21:41]). Poles in still areas or skin folds ([00:12:45]); triangles only in cavities; never n-gons: ZBrush triangulates them and blend shapes break ([00:05:31]).
Test the bend before handoff, blame the right artist. antCGi: loops running along a joint (wrist, ankle, hip crease) are the modeler's fix; volume lost at a correctly looped hinge is the rig's, for correctives; prove it by swapping topology under identical weights (x07USYlvu2o [00:10:27] [00:16:24]). Fit lids over the real eyeballs, with enough loops to curve over the cornea on a blink ([00:15:18]; RlNnp4qQIrU [00:08:24]). Shear (Jessica [01:13:06]) judges face hinges; on limbs a linear blend shears even perfect rings [added, measured].
Retopologize traps (Maya 2027 Help).
```
polyRetopo
```
re-runs on edits and file open: delete history; Pause the node while changing several attributes. Preprocess Mesh (default on) smooths detail: noisy 100k+ triangle input only. Hard surface 1 / 1 / 0. Never half a mesh. Edge component tags steer flow.
Texel density from the closest camera. Paulino: frame the reference piece at the closest shot, double its screen pixels, round to a power of two, Get/Set on every shell (iL2iXizf9xM [00:02:33]). Film: one density, UDIMs. Games: uniform, scale up the head, stack mirrored shells (MLC s_KLbTUdKms [00:10:57]).
Padding is a mip problem; bake prep is geometry. 4 px between shells, 2 px to the border, doubled per mip step; Room space stays 2 px (Maya 2027 Help). Hard edges on UV seams, one triangulation for bake and export, the whole mirrored model baked with mirrored UVs one tile over (Polycount), a low that hugs the high (On Mars YDu9pYMkkSM [00:17:45]).

先放 landmarks，再使用大 polygons，然后像拼图一样填充。 FlippedNormals：从很小规模开始是“糟糕的工作方式”；松弛尚可恢复，过紧则无法恢复（9N4rG5qHWgk [00:01:05] [00:02:07]）。在任何顶点之前，loop map 都必须先作为数据存在；模板拟合须先在基础密度下通过门槛，之后才能添加 spans。
复用已批准的 topology。 FlippedNormals 会把一只完美的手、一只耳朵或一个 base mesh 复用于每个模型（[00:10:11]）；Jessica Dru Johnson 的标准 base cut 面部 skinning 从 3 天缩短到 30 分钟（ZiYEO49B768 [00:58:51]）。Quad Draw 替代方案：
```
RU.fit_template
```
。
不要对会发生变形的部位自动生成 topology。 在面部，它“看起来正常，但其实并不是”（FlippedNormals [00:23:15]）；自动处理只适用于不会动画的部位（[00:22:13]）。Retopologize 适用于 props、armor plates 和 static cloth；对于 torso 或宽松外套，它只能作为带标记的起点，并且必须通过 deformation gate。
隔离并约束 deformation。 眼睛和嘴部使用同心 rings，每个关节采用一个控制 loop 加两个支撑 loop，从嘴角到下颌角使用 flat loop 以抵抗剪切（Jessica [01:15:51] [01:30:10]），眼睑 loop 数量保持相等（FlippedNormals [00:21:41]）。在静止区域或皮肤褶皱处设置 poles（[00:12:45]）；仅在 cavities 中使用 triangles；绝不使用 n-gons：ZBrush 会将它们 triangulate，而且 blend shapes 会崩坏（[00:05:31]）。
在交付前测试弯曲，并找对责任方。 antCGi：沿关节（wrist、ankle、hip crease）方向延伸的 loops 应由建模者修复；若 loop 正确但 hinge 处出现体积损失，则属于 rig 的问题，需要 corrective；可在权重完全相同的情况下替换 topology 来证明这一点（x07USYlvu2o [00:10:27] [00:16:24]）。将眼睑贴合真实 eyeballs，并提供足够的 loops，使眼睑在 blink 时能沿 cornea 弯曲（[00:15:18]；RlNnp4qQIrU [00:08:24]）。Shear 用于判断面部 hinges；在肢体上，即使 rings 完美，linear blend 也会产生剪切［新增，已测量］。
Retopologize 陷阱（Maya 2027 Help）。
```
polyRetopo
```
会在编辑或打开文件时重新运行：删除 history；修改多个 attributes 时 Pause 该 node。Preprocess Mesh（默认开启）会平滑细节：仅适用于含噪的 100k+ triangle 输入。Hard surface 1 / 1 / 0。绝不要只处理半个 mesh。Edge component 标签用于引导 flow。
根据最近的 camera 确定 texel density。 Paulino：让参考部件以最近镜头构图，将其屏幕像素数量翻倍，取接近 2 的幂，并在每个 shell 上执行 Get/Set（iL2iXizf9xM [00:02:33]）。Film：使用统一 density 和 UDIMs。Games：整体保持一致，提高 head 的 texel density，并堆叠 mirrored shells（MLC s_KLbTUdKms [00:10:57]）。
Padding 是 mip 问题；bake prep 属于几何问题。 Shells 之间保留 4 px，边界保留 2 px，并且每级 mip 翻倍；Room space 保持 2 px（Maya 2027 Help）。UV seams 上使用 hard edges；bake 和 export 使用同一份 triangulation；使用相隔一个 tile 的 mirrored UVs 烘焙完整的 mirrored model；让 low 紧贴 high（On Mars YDu9pYMkkSM [00:17:45]）。

Establish first

优先确定

Input	Why it changes the plan	Default when the brief is silent
Purpose	film cage subdivided at render vs real-time triangles plus bakes	real-time
Deformation, engine	face rig, blend shapes; one extra mouth-corner span forced a fifth influence (Jessica [00:59:24])	face and limbs deform; 4 influences, confirm with scenario-maya-rigging
Budget	triangles from the lead (Polycount); "exactly as high as needed" (FlippedNormals [00:13:46])	propose one from screen coverage, as an assumption
Closest shot	texel density	1920 x 1080, 85 mm on the head (Paulino)
Textures	map size, 0-1 or UDIM, lowest mip, strategy (optimized, technical, continuous)	games: 0-1 seen at a quarter size; film: 4K UDIMs; characters continuous
Template, eyes	base mesh; eyeballs to fit lids on	ask scenario-maya-modeling for a primitive-blocked base and eyeballs
Pose	neutral face, relaxed A-pose, eyes forward (Jessica [01:00:30]; antCGi e74KphYwMww [00:07:39])	report a posed source

Clothes fused to the body (AI meshes). Tight garments become body topology with loops on the garment lines; loose layers get their own tube or template projected onto the fused source [added]; plates may slide but the torso stays one piece (Jessica [00:44:17]); wrinkles that never animate go to Retopologize or the bake (FlippedNormals [00:22:13]).

输入	为何会改变方案	需求简报未说明时的默认值
用途	film cage 在 render 时细分；real-time 使用 triangles 加 bakes	real-time
变形、引擎	面部 rig、blend shapes；仅多出一个嘴角 span 就会迫使系统出现第五个 influence（Jessica [00:59:24]）	面部和肢体 deformation；4 个 influences，并通过 scenario-maya-rigging 确认
预算	lead 给出的 triangles 预算；“恰好只做到所需的高度”（FlippedNormals [00:13:46]）	根据 screen coverage 提出一个数值，并将其作为假设
最近镜头	texel density	1920 x 1080，头部使用 85 mm（Paulino）
贴图	map 尺寸、0-1 或 UDIM、lowest mip、策略（optimized、technical、continuous）	games：以四分之一尺寸查看 0-1；film：4K UDIMs；角色：continuous
模板、眼睛	base mesh；用于贴合眼睑的 eyeballs	要求 scenario-maya-modeling 提供基于 primitive 构型的 base mesh 和 eyeballs
Pose	中性面部、放松的 A-pose、双眼朝前（Jessica [01:00:30]；antCGi e74KphYwMww [00:07:39]）	报告存在 pose 的源模型

与身体融合的服装（AI meshes）。 紧身服装会变成带有服装线条 loops 的 body topology；宽松层应拥有独立的 tube，或使用投影到融合源模型上的 template［新增］；plates 可以滑动，但 torso 仍保持为一个整体（Jessica [00:44:17]）；不会动画的褶皱应交给 Retopologize 或 bake（FlippedNormals [00:22:13]）。

Workflow

工作流

Intake, read only.
```
mx_audit.audit(source)
```
; the source stays the bake source.
```
RU.prep_source
```
makes the working copy (weld, soften, report non-manifold); a broken source is rebuilt or used only as projection target (P2). Orient by the transform (cm, Y-up, +Z front, feet at 0). GATE: numbers written; clay sheet looked at.
Map. Landmarks, ring counts per opening, joint stations, flows (mouth corner under the cheek; neck along the sternocleidomastoid, clavicle to skull back, antCGi RlNnp4qQIrU [00:09:32] [00:37:43]), a method per part. GATE: the map is JSON before any geometry.

Build per part.

Part	Method	Call
Face, head, hands, body with a base	landmark fit	`RU.fit_template`
Limbs, fingers, sleeves, skirts, tails	plane sections, 1 + 2 loops per joint	`RU.limb_stations` , `RU.build_tube`
Props, armor plates, static cloth	Retopologize	`RU.retopologize(mesh, faces, hard_surface=...)`
Torso or face without a base	primitive base from scenario-maya-modeling, then fit	Retopologize only as a flagged start for Quad Draw (gui-paths.md)

Then cavities: mouth bag, nostrils, eye pouch (FlippedNormals [00:25:16] [00:27:22]). GATE:

mx_audit.verdict

clean per part.

Relax, center, mirror.
```
RU.relax_project
```
,
```
RU.snap_center
```
,
```
RU.mirror_half
```
(weld 0.001, antCGi QW8w15J00Ok [00:02:56]); combine symmetric parts (e74KphYwMww [00:24:32]). GATE: no center drift, symmetry 100%.
Gate the topology.
```
RU.retopo_report
```
plus wire and clay sheets in the source's views.
Deformation-ready gate, before UVs (antCGi unwraps after it).
```
RU.deform_test(mesh, chain, bends, review_dir=...)
```
per limb (elbow and knee at 90 and 130 degrees, wrist, ankle, hip; twist judged mid-limb, never at shoulder or wrist, x07USYlvu2o [00:08:40]),
```
kind="hinge"
```
for jaw open,
```
RU.lid_check(head, eyeball)
```
. Proxy weights, no skinCluster: binds are scenario-maya-deformation's. GATE: no
```
topology
```
verdict, lids ok, pose sheets looked at;
```
rig
```
verdicts travel as notes; prove a fix with
```
RU.compare_variants
```
(P19, P20).
UVs. Seams as edge loops (
```
RU.loop_keys
```
,
```
RU.cut_seams
```
): neck base, head slits, inside the mouth, sleeve line, back of the arm, wrists, waist, inner legs, boot tops, soles (MLC [00:01:37] to [00:08:05]); cloth on its real seams (Paulino [00:05:16]).
```
RU.unfold
```
,
```
RU.optimize
```
; limb shells
```
RU.orient_shell
```
then
```
RU.straighten_rows
```
(MLC [00:04:49]);
```
RU.mirror_uvs(mode="mirror")
```
. GATE: planned shells, no folds, distortion in band.

Density and packing.

RU.density_from_camera

(film) or

RU.density_for_budget

(games);

RU.set_texel_density

(head bias in games);

RU.layout(scale_mode="off")

with

RU.mip_padding

; UDIMs, or

RU.mirror_uvs(mode="stack", offset_u=1.0)

for game bakes, never where AO or a logo differs;

RU.lightmap_set

. GATE:

RU.uv_report

ok; UV and

RU.checker_review

sheets looked at.

Bake prep.
```
RU.harden_uv_borders
```
,
```
RU.bake_check
```
,
```
RU.make_cage
```
or
```
RU.project_to_surface
```
,
```
RU.bake_copy
```
,
```
RU.overlap_review(low, high, out)
```
(P21). GATE: high inside the cage, hard edges only on seams, one triangulation, silhouettes match.

AI character end to end: procedure P18.

接收输入，只读。
```
mx_audit.audit(source)
```
；源模型始终作为 bake source。
```
RU.prep_source
```
创建 working copy（weld、soften 并报告 non-manifold）；损坏的源模型应重建，或仅用作 projection target（P2）。依据 transform 校正方向（cm、Y-up、+Z front、脚位于 0）。GATE：写入数值；查看 clay sheet。
规划。 Landmarks、每个开口的 ring 数量、joint stations、flows（嘴角从面颊下方经过；颈部沿 sternocleidomastoid，锁骨延伸至 skull 后部，antCGi RlNnp4qQIrU [00:09:32] [00:37:43]），并为每个部位确定方法。GATE：任何 geometry 之前，map 都必须为 JSON。

按部位构建。

部位	方法	调用
面部、头部、手部、带 base 的身体	landmark fit	`RU.fit_template`
四肢、手指、sleeves、skirts、tails	平面截面，每个关节 1 + 2 loops	`RU.limb_stations` 、 `RU.build_tube`
Props、armor plates、static cloth	Retopologize	`RU.retopologize(mesh, faces, hard_surface=...)`
没有 base 的 torso 或面部	先从 scenario-maya-modeling 获取 primitive base，再进行 fit	仅将 Retopologize 作为 Quad Draw 的带标记起点（gui-paths.md）

随后处理 cavities：mouth bag、nostrils、eye pouch（FlippedNormals [00:25:16] [00:27:22]）。GATE：每个部位的

mx_audit.verdict

均为 clean。

Relax、居中并镜像。
```
RU.relax_project
```
、
```
RU.snap_center
```
、
```
RU.mirror_half
```
（weld 0.001，antCGi QW8w15J00Ok [00:02:56]）；合并对称部位（e74KphYwMww [00:24:32]）。GATE：无中心漂移，对称度 100%。
对 topology 执行门槛检查。
```
RU.retopo_report
```
，并在源模型视角下查看 wire 和 clay sheets。
在 UVs 之前执行 deformation-ready gate（antCGi 在此之后才 unwrap）。针对每个 limb 执行
```
RU.deform_test(mesh, chain, bends, review_dir=...)
```
（elbow 和 knee 弯曲 90 与 130 度，测试 wrist、ankle、hip；twist 在 limb 中段判断，绝不在 shoulder 或 wrist 处判断，x07USYlvu2o [00:08:40]），jaw open 使用
```
kind="hinge"
```
，并执行
```
RU.lid_check(head, eyeball)
```
。使用 Proxy weights，不使用 skinCluster：绑定由 scenario-maya-deformation 负责。GATE：不得出现
```
topology
```
verdict，眼睑检查通过，查看 pose sheets；
```
rig
```
verdicts 作为 notes 传递；使用
```
RU.compare_variants
```
证明修复（P19、P20）。
UVs。 Seams 以 edge loops 形式设置（
```
RU.loop_keys
```
、
```
RU.cut_seams
```
）：neck base、head slits、口腔内部、sleeve line、手臂背面、wrist、waist、内腿、boot tops、soles（MLC [00:01:37] 至 [00:08:05]）；布料沿其真实 seams 展开（Paulino [00:05:16]）。
```
RU.unfold
```
、
```
RU.optimize
```
；肢体 shells 先执行
```
RU.orient_shell
```
，再执行
```
RU.straighten_rows
```
（MLC [00:04:49]）；
```
RU.mirror_uvs(mode="mirror")
```
。GATE：shells 已规划，无 folds，distortion 控制在 band 内。
Density 与 packing。
```
RU.density_from_camera
```
（film）或
```
RU.density_for_budget
```
（games）；
```
RU.set_texel_density
```
（games 中为 head 设置 bias）；
```
RU.layout(scale_mode="off")
```
配合
```
RU.mip_padding
```
；使用 UDIMs，或在 game bakes 中使用
```
RU.mirror_uvs(mode="stack", offset_u=1.0)
```
，但 AO 或 logo 有差异的位置绝不能这样处理；
```
RU.lightmap_set
```
。GATE：
```
RU.uv_report
```
通过；查看 UV 和
```
RU.checker_review
```
sheets。
Bake prep。
```
RU.harden_uv_borders
```
、
```
RU.bake_check
```
、
```
RU.make_cage
```
或
```
RU.project_to_surface
```
、
```
RU.bake_copy
```
、
```
RU.overlap_review(low, high, out)
```
（P21）。GATE：high 位于 cage 内，hard edges 仅出现在 seams 上，只有一份 triangulation，silhouettes 匹配。

AI 角色端到端流程：procedure P18。

Numbers

数值

Item	Value	Relative to, source
Joint loops	1 control + 2 support; knuckles 3 each	each bend (Jessica [01:15:51] [01:17:34])
Lids, lips	upper count = lower count	FlippedNormals [00:21:41]; antCGi RlNnp4qQIrU [00:05:22]
Mirror, center	weld custom 0.001; drift band 1e-4 to 1e-2 cm, snap to 0	antCGi QW8w15J00Ok [00:02:24]; FlippedNormals [00:19:06]
Retopologize	hard surface 1 / 1 / 0; Preprocess for 100k+ tris; tolerance under 10% is slow	Maya 2027 Help
Texel density	2 x screen px at the closest shot, power of two	Paulino [00:02:33]
Maps, padding	4K tiles, odd shell at half scale on 8K; 4 / 2 px, x2 per mip (2048 seen at 512: 16 / 8)	Paulino [00:05:48]; Maya 2027 Help
Hard edges, mirror	every UV seam, bends over ~45°; mirrored UVs 1 unit over	Polycount
Deformation [added]	joint loop within 20° of the bone, no spiral over 15°, 0.8 of an ideal ring's area kept; hinge mean shear under 10°; faces under 0.3 area collapse; an ideal ring under 0.7 is a rig note	organic digest; scenario-maya-deformation
Lids [added]	nothing inside the eyeball at rest or blink, vertices and edge midpoints; gap under 0.1 eye radius	antCGi x07USYlvu2o [00:15:18]
Gates [added]	deviation under 10% of mean edge; UV area ratio 0.5 to 2, anisotropy under 2; density within 10%; packing 0.7; 3+ clean rings per opening; silhouettes differ under 2%	this skill

项目	数值	依据、来源
Joint loops	1 个控制 loop + 2 个支撑 loop；每个指节 3 个	每次弯曲（Jessica [01:15:51] [01:17:34]）
眼睑、嘴唇	upper 数量 = lower 数量	FlippedNormals [00:21:41]；antCGi RlNnp4qQIrU [00:05:22]
镜像、中心	自定义 weld 0.001；漂移区间 1e-4 至 1e-2 cm，snap 到 0	antCGi QW8w15J00Ok [00:02:24]；FlippedNormals [00:19:06]
Retopologize	hard surface 1 / 1 / 0；对 100k+ tris 使用 Preprocess；10% 以下的 tolerance 运行缓慢	Maya 2027 Help
Texel density	最近镜头中屏幕像素尺寸的 2 倍，取 2 的幂	Paulino [00:02:33]
Maps、padding	4K tiles；在 8K 上以一半尺寸显示奇数 shell；4 / 2 px，每级 mip 翻倍（2048 显示为 512 时：16 / 8）	Paulino [00:05:48]；Maya 2027 Help
Hard edges、镜像	每个 UV seam；超过约 45° 的弯曲处；mirrored UVs 间隔 1 个单位	Polycount
Deformation［新增］	joint loop 与骨骼夹角在 20° 内，无超过 15° 的 spiral，保留理想 ring 面积的 0.8；hinge 平均剪切低于 10°；faces 的面积坍塌低于 0.3；理想 ring 低于 0.7 时记为 rig note	organic digest；scenario-maya-deformation
Lids［新增］	静止或 blink 时，vertices 与 edge midpoints 均不得进入 eyeball；gap 小于 0.1 eye radius	antCGi x07USYlvu2o [00:15:18]
Gates［新增］	偏差低于 mean edge 的 10%；UV area ratio 为 0.5 至 2，anisotropy 低于 2；density 误差在 10% 内；packing 为 0.7；每个开口有 3+ clean rings；silhouettes 差异低于 2%	此 skill

Quality gates

质量门槛

In code (MAYA, not yet run in Maya):

python

rep = RU.retopo_report("body_geo", "scan_high", openings={"eye_L": {"point": (3.2, 163, 8.5)}},
                       joints={"elbow_L": {"center": (45, 140, -2), "axis": (1, 0, 0), "radius": 6}})
dt = RU.deform_test("body_geo", [shoulder, elbow, wrist, hand_tip],
                    [{"name": "elbow_130", "joint": 1, "angle": 130, "axis": (0, 1, 0)}])
lid = RU.lid_check("body_geo", "eyeL_geo")
uv = RU.uv_report("body_geo", 4096, smallest_mip=1024, target_density=20.48, images_dir="/abs/out/uv")
print(rep["fails"], dt["verdict"], lid["fails"], uv["fails"])     # full arguments: procedures.md

Topology: 0 n-gons, no

polyRetopo

history, 3+ clean rings and equal halves per opening, 3 loops per joint band, triangles only in cavities, eyes denser than the cranium, no center drift, no

topology

verdict. UVs: all faces mapped, no unintended overlap, padding at the lowest mip, density on target, hard edges only on seams (games). Visual: wire and clay sheets (rings close, even squares); pose sheets (creases where anatomy creases, no pinching); UV sheets; checker in three views plus the closest shot; overlap diff images (red: high outside the low). Score with

references/critique.md

代码中的门槛（MAYA，尚未在 Maya 中运行）：

python

rep = RU.retopo_report("body_geo", "scan_high", openings={"eye_L": {"point": (3.2, 163, 8.5)}},
                       joints={"elbow_L": {"center": (45, 140, -2), "axis": (1, 0, 0), "radius": 6}})
dt = RU.deform_test("body_geo", [shoulder, elbow, wrist, hand_tip],
                    [{"name": "elbow_130", "joint": 1, "angle": 130, "axis": (0, 1, 0)}])
lid = RU.lid_check("body_geo", "eyeL_geo")
uv = RU.uv_report("body_geo", 4096, smallest_mip=1024, target_density=20.48, images_dir="/abs/out/uv")
print(rep["fails"], dt["verdict"], lid["fails"], uv["fails"])     # full arguments: procedures.md

Topology：0 n-gons；无

polyRetopo

history；每个开口有 3+ clean rings，且左右两侧相等；每个 joint band 有 3 loops；triangles 仅用于 cavities；eyes 比 cranium 更密；无 center drift；无

topology

verdict。UVs：所有 faces 均已映射；无非预期 overlap；padding 覆盖 lowest mip；density 命中 target；hard edges 仅位于 seams 上（games）。

Visual：wire 和 clay sheets（rings 紧密、squares 均匀）；pose sheets（crease 出现在 anatomically 应有的位置，且无 pinching）；UV sheets；从三个视角及最近镜头查看 checker；overlap diff images（红色：high 超出 low）。使用

references/critique.md

评分。

Common mistakes

常见错误

Mistake	Looks like	Fix
Retopologize on a face	plausible grid, no rings	template fit; openings gate
`polyRetopo` history kept	mesh re-solves on edit or open	`RU.retopologize` deletes it
All hard edges on a scan or AI mesh	Retopologize fails or crawls	`prep_source` softens all
Cleanup and Merge on internal faces	endless non-manifold loop	select-mode Cleanup, delete by hand, or Boolean Volume (P2)
Wrist or ankle bend sent to the rigger	loops along the joint patched with correctives	`topology` verdict: reroute loops across it, A/B
Clean rings rebuilt for volume loss	same elbow collapse	`rig` verdict: corrective note for scenario-maya-deformation
Lids modeled without the eyeball	lid pops through on a blink	`lid_check` , add lid loops, refit
Center drift; relax after UVs	mirror seam; textures swim	`snap_center` first; relax before UVs or `transfer_uvs`
Straighten UVs on a whole shell	"this mess"	orient, align rows, pin, optimize the interior (MLC)
Unfold refuses a mesh that audits manifold	Unfold3D aborts	it unfolds a triangulated copy: triangulate a duplicate, select-mode Cleanup
Layout Uniform after density; stacked unique bakes	density changed; mirrored AO	`scale_mode="off"` ; stack by strategy, offset 1 tile
Half model baked, two triangulations	center seam, zig-zag shading	whole mirrored model; `bake_copy`

错误	表现	修复方式
在面部使用 Retopologize	看似合理的 grid，却没有 rings	template fit；执行 openings gate
保留 `polyRetopo` history	mesh 在编辑或打开时重新求解	`RU.retopologize` 会将其删除
对扫描或 AI mesh 的所有边设置 hard edges	Retopologize 失败或运行缓慢	`prep_source` 会 soft 全部边
对 internal faces 使用 Cleanup 和 Merge	持续出现 non-manifold loop	select-mode Cleanup、手动删除，或 Boolean Volume（P2）
将 wrist 或 ankle bend 交给 rigger	沿关节的 loops 只能通过 correctives 修补	`topology` verdict：重新规划横跨关节的 loops，并执行 A/B 比较
重建 clean rings 来解决体积损失	elbow 仍然塌陷	`rig` verdict：为 scenario-maya-deformation 记录 corrective note
未使用 eyeball 构建 lids	blink 时眼睑穿出	`lid_check` 、添加 lid loops、重新拟合
Center drift；在 UVs 之后 relax	镜像处出现 seam；贴图游移	先执行 `snap_center` ；在 UVs 前 relax，或使用 `transfer_uvs`
对整个 shell 执行 Straighten UVs	变成“这团乱麻”	orient、对齐 rows、pin、optimize 内部区域（MLC）
Unfold 拒绝了一个经 audit 判定为 manifold 的 mesh	Unfold3D 中止	对 triangulated copy 执行 unfold：复制 mesh 并 triangulate，再使用 select-mode Cleanup
在设置 density 后使用 Layout Uniform；堆叠唯一 bakes	density 被改变；mirrored AO	使用 `scale_mode="off"` ；按策略堆叠，offset 1 tile
只烘焙半个模型；使用两份 triangulations	中心 seam；锯齿状 shading	烘焙完整的 mirrored model；使用 `bake_copy`

Handoffs

交接

Receives from scenario-maya-modeling (base meshes, eyeballs,
```
mx_validate(profile="model")
```
clean), scenario-zbrush-expert (real scale, neutral; posed sources go back), scenario-3d (FBX or OBJ [verify glTF]; its remesh only for static parts); loop faults back from scenario-maya-deformation with pose and numbers.
Delivers to scenario-maya-rigging and scenario-maya-deformation: a new version,
```
<part>_geo
```
frozen without history, cm, Y-up, centered, feet on the grid, eyes separate and forward, mouth bag, symmetric parts combined;
```
retopo_report
```
,
```
deform_test
```
(rig notes: hinges needing correctives) and
```
lid_check
```
JSON, wire and pose sheets.
Delivers to scenario-maya-lookdev: UV sets, px/cm, UDIM table, the bake package (high, triangulated bake copy, cage, offsets, tangent basis: MikkTSpace for Unreal and Unity; Arnold
```
normal_map
```
has a MikkTSpace mode from MtoA 5.6.1.1, Maya 2027.1),
```
uv_report
```
JSON.

接收： scenario-maya-modeling 提供 base meshes、eyeballs，以及通过
```
mx_validate(profile="model")
```
检查的 clean 结果；scenario-zbrush-expert 提供真实比例、中性的模型，有 pose 的源模型需要退回；scenario-3d 提供 FBX 或 OBJ［验证 glTF］，其 remesh 仅用于 static parts；从 scenario-maya-deformation 接收带有 pose 和数值的 loop faults。
交付给 scenario-maya-rigging 和 scenario-maya-deformation： 一个新版本，即
```
<part>_geo
```
，已冻结且不含 history，使用 cm、Y-up、居中、双脚位于 grid 上，eyes 独立且朝前，包含 mouth bag，且已合并对称部位；提供
```
retopo_report
```
、
```
deform_test
```
（rig notes：需要 corrective 的 hinges）和
```
lid_check
```
JSON，以及 wire 和 pose sheets。
交付给 scenario-maya-lookdev： UV sets、px/cm、UDIM table、bake package（high、triangulated bake copy、cage、offsets、tangent basis：Unreal 和 Unity 使用 MikkTSpace；Arnold
```
normal_map
```
从 MtoA 5.6.1.1、Maya 2027.1 开始提供 MikkTSpace 模式），以及
```
uv_report
```
JSON。

Maya 2027 notes

Maya 2027 注意事项

Quad Draw is interactive only (Make Live first); its 2027 hotkey table is lost, so gui-paths.md's 2018 panel is [verify].
```
polyRetopo
```
flags are unsaved:
```
RU.call
```
passes only flags
```
cmds.help
```
lists. Flow Retopology (cloud, 2027.1) needs a sign-in: not headless. Reduce is decimation.
Broken source: Mesh > Booleans Volume mode with a Voxel size (2026) rebuilds watertight but needs a second input; Mesh > Remesh evens the spread before Retopologize.
Unfold3D is the default, refuses non-manifold meshes, pins unselected UVs (Legacy: selected only). Relax is Optimize > Legacy. Texel Density needs Map Size first; Measure has Pixel Distance.
```
dgaTension
```
(2026.3) measures stretch against a reference mesh for a heat map (
```
RU.tension_node
```
, attributes [verify]). A hand-made test bind leaves Skin Tools layers uninitialized (the default), so
```
skinPercent
```
floods work; on a skinned mesh delete Non-Deformer History, never History (antCGi [00:12:41]).

Quad Draw 仅支持交互操作（先执行 Make Live）；其 2027 hotkey 表已丢失，因此 gui-paths.md 中 2018 年的面板信息需要［验证］。
```
polyRetopo
```
flags 未保存：
```
RU.call
```
仅传递
```
cmds.help
```
列出的 flags。Flow Retopology（cloud，2027.1）需要登录：无法 headless 运行。Reduce 是 decimation。
损坏的源模型：Mesh > Booleans Volume mode 配合 Voxel size（2026）可重建 watertight 模型，但需要第二个输入；在 Retopologize 之前，Mesh > Remesh 可使分布更均匀。
Unfold3D 是默认选项，会拒绝 non-manifold meshes，并固定未选中的 UVs（Legacy：仅固定选中的 UVs）。Relax 是 Optimize > Legacy。Texel Density 需要先设置 Map Size；Measure 包含 Pixel Distance。
```
dgaTension
```
（2026.3）可对照 reference mesh 测量拉伸并生成 heat map（
```
RU.tension_node
```
，attributes［验证］）。手工创建的 test bind 会让 Skin Tools layers 保持未初始化状态（默认状态），因此
```
skinPercent
```
floods 可以工作；对于已 skinned 的 mesh，删除 Non-Deformer History，绝不要删除 History（antCGi [00:12:41]）。

References

参考

```
references/procedures.md
```
: full code P0 to P21 with test paths. Load before writing code.
```
references/expert-notes.md
```
: principles by expert, disagreements, deciding conditions. Load when planning a face, body, clothes, a deformation test or a mapping strategy.
```
references/critique.md
```
: the self-review rubric. Load at every review.
```
references/gui-paths.md
```
: menus, hotkeys, tool settings (Quad Draw, Retopologize, test bind, UV Toolkit).
```
references/sources.md
```
: every source with credentials, URL and timestamps.

```
references/procedures.md
```
：包含测试路径的完整代码 P0 至 P21。编写代码前先加载。
```
references/expert-notes.md
```
：专家原则、分歧和决策条件。规划 face、body、clothes、deformation test 或 mapping strategy 时加载。
```
references/critique.md
```
：self-review 评分标准。每次 review 都要加载。
```
references/gui-paths.md
```
：菜单、hotkeys 和 tool settings（Quad Draw、Retopologize、test bind、UV Toolkit）。
```
references/sources.md
```
：每个来源的凭据、URL 和时间戳。