tinqs/animation
5
0
Fork 0
Code Pull Requests Actions Packages Projects Releases Wiki Activity Issues

docs+tools: working-file policy, lane pruner, and a human MD explainer

Browse Source 
Two pieces of work.

1. Keep milestones, not steps. Staged NN_*.py lanes were saving a full
   ~80 MB .blend per attempt, so Lena's lane reached 3.0 GB of which 2.2 GB
   was 30 .blend files -- five snapshots to land one crotch fix, five more
   for the bra. The .py recipes are the real history; the blends are cache.

   - .agents/rules/working-files.md: four-tier policy (KEEP / MASTER /
     SCRATCH / UNKNOWN) + how to work a lane.
   - tools/prune_lane.py: classifies a lane and prunes the scratch tier.
     Dry-run by default. Reads a per-lane .lanekeep manifest, flags
     binaries byte-identical to a registered original (canonical name
     always survives a duplicate pair), and never auto-deletes a .blend
     with no step script beside it -- those cannot be rebuilt.
   - .gitignore: scratch patterns can never be committed.

   Dry run on characters/female/lena_nude reports 2.3 GB reclaimable.
   Not applied -- that lane had a live Blender session at the time.

2. .humans/marvelous-designer.html: how we author garments in Marvelous
   Designer, written for people rather than agents -- the six-step process,
   what has been made, the traps that cost hours, and what is still
   unsolved. Matches the .humans/ HTML convention in ariki-game.

Also committing the docs the AGENTS.md knowledge map and the new page
reference, so they are not dangling: the clothing-lane architecture page,
the marvelous-designer skill, and the two screenshots the page embeds.

characters/ is deliberately untracked and stays that way -- it holds GBs of
blends and GLBs, and .gitattributes does not LFS-track .blend.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Jeremy
2026-08-06 12:05:46 -07:00
parent 854dbb5ce4
commit d1030def4e
13 changed files with 1729 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/marvelous-designer/SKILL.md
+274
View File
@@ -0,0 +1,274 @@
---
name: marvelous-designer
description: Authoring garments in Marvelous Designer agentically — driving MD's Python API over the TinqsMDBridge socket plugin, drafting patterns from a reference image and Lena's measurements, draping/QC-ing them on the game body, and exporting meshes for the clothing pipeline. Use for any "make/adjust a garment", "match this clothing photo", or "drive Marvelous Designer" task, and read before touching tools/md_bridge* or tools/tailor/.
---
# Marvelous Designer — agentic garment authoring
The **upstream half** of the clothing lane: reference image (or a description) →
sewn, draped, textured garment mesh fitted to the game body. The downstream half
(garment mesh → game-ready skinned GLB) is `clothing/` — see
`.agents/wiki/architecture/clothing-lane.md` for how they meet.
Everything here was learned by doing it on 2026-07-30 (tee, skirt, kapa haka
pari + piupiu). The API facts are **verified against MD 2026 Personal**, not
docs — Reallusion/CLO's published API docs are thin and several signatures in
them are wrong.
## The 60-second model
- MD is driven through **`tools/md_bridge.py`** → a socket plugin running inside
MD (`tools/md_bridge/TinqsMDBridge.py`). Full protocol: `docs/md-bridge.md`.
- A garment = **flat 2D panels** (`CreatePatternWithPoints`) + **seams**
(`AddSeamlinePairGroup`) + **arrangement points** on the avatar
(`SetArrangement`), then **simulate** (`utility_api.Simulate(frames)`) to drape
cloth onto the body.
- You see results by rendering the viewport to PNG (`ExportSnapshot3D`) and
reading the image back. **This vision loop is the whole method** — draft,
drape, look, measure, adjust, repeat.
- **Which call for which job, and why:** `references/tooling.md`. Read it before any
QC or diagnostic work — it carries the verified signatures, the render/measure
toolkit, the seam-pairing decision table, and the harness patterns.
- Garment identity for traditional wear is mostly **textiles, not tailoring**.
Kapa haka / Mexica / Pacific garments are rectangles + blocks; the design lives
in generated texture maps. Model the shape simply, spend effort on the pattern.
## Session protocol (read first — MD's UI freezes)
MD's embedded Python **does not run background threads**, so the bridge owns the
main thread while it serves. Consequences:
1. **A human must click** Plugin → TinqsMDBridge to start a session. You cannot
start one yourself. Ask, then wait.
2. **MD's UI is frozen** for the whole session ("Not Responding" is normal).
3. End with `python tools/md_bridge.py --stop` — works from the terminal even
though the UI is dead. Idle timeout is 4 h (was 300 s; raised so one click
lasts a work session).
4. **Pause the session whenever Jeremy wants to look at the model.** He inspects
in MD's viewport; he can't while you hold the thread. Default to stopping when
you hand back a result, unless he said to stay in.
```bash
python tools/md_bridge.py --ping # verify + see mode/api modules
python tools/md_bridge.py --exec "result = pattern_api.GetPatternCount()"
python tools/md_bridge.py --file tools/tailor/md_pari.py --timeout 500
python tools/md_bridge.py --stop # give the UI back
```
Long `Simulate()` calls need a raised client `--timeout` (~1 min per 300 frames).
The exec namespace persists **within** a session, not across; MD api modules
(`pattern_api`, `import_api`, `export_api`, `fabric_api`, `utility_api`,
`ApiTypes`) plus a `BRIDGE` info dict are pre-seeded.
**Introspect, don't trust docs.** Full surface dump lives at
`tools/md_bridge/api_surface.json` (688 functions) and harvested docstrings at
`tools/md_bridge/api_docs.json`. Overloaded pybind11 functions break
`inspect.signature()` — read `__doc__` instead.
## API facts that cost hours to find
| Fact | Consequence |
|---|---|
| **2D pattern y+ maps to UP in 3D** | Panels drafted y-down drape **upside-down over the head** and tangle. Symptom looks like a seam bug; it isn't. Hem at y=0, neckline at high y. |
| Units are **mm**; gravity −9800 | A "500" square is 50 cm. |
| Blender-exported FBX avatars import **10× small** | Import with `op.scale = 10.0`. |
| `ImportAvatar()` is **.avt only** — returns `False` on FBX | Use **`import_api.ImportFBX(path, op)`** for the game body. |
| `op.bAddArrangementPoints = True` | Auto-generates ~98 named arrangement points on a custom avatar. Without it you have nowhere to hang cloth. |
| `SetArrangement()` only *assigns*; **`utility_api.ResetClothArrangement()` applies** it | Skipping the apply = nothing moves. (`ReDrape3DArrangement` only materializes not-yet-draped cloth.) |
| Arrangement **indices regenerate** per avatar import | Always look up by name from `GetArrangementList()`; never hardcode an index. Offsets aren't stable either — verify with a 0-frame snapshot. |
| Avatar getters live in **`export_api`** (`GetAvatarCount`, `GetAvatarNameList`) | Not `utility_api`, where you'd look. |
| `utility_api.NewProject()` **deletes the avatar** | Re-import after. |
| `SetBaseTextureMapImageGivenFilePath(path, fabricIdx)` — **path is arg0** | Reversed args throw a TypeError that reads like a missing overload. |
| **PNG DPI sets a texture's physical size in MD** | 1024 px at 54.2 dpi = 480 mm of cloth. Control tiling by setting dpi in PIL, not by scaling the image. |
| `fabric_api.AddFabric()` needs a **`.zfab` file path** | A name string silently fails. Stock presets: `C:\Users\Public\Documents\MarvelousDesigner\New Assets\Fabric\`. |
| Fabric **index 0 is the shared default** | Coloring it dyes every garment in the scene. Always `AddFabric` a new one. |
| `AssignFabricToPattern()` returns False for every arg order tried | Use **`pattern_api.SetPatternPieceFabricIndex(pattern, fabric)`**. |
| `SetViewPoint()` does nothing; **`SetCamViewPoint(2)` = front view** | Call before every QC snapshot so shots are comparable. |
| **`SetCamViewPoint` has NO REAR VIEW** (0 bottom, 1/3 front ¾, 2 front, 4/6/7 sides, 5 top) | `ExportSnapshot3D` cannot show the back of a garment at all. Use `export_api.ExportTurntableImages(4)` — index 2 is the back. It ignores its path arg and writes into MD's own output folder, so the return value is the only way to find the files. This blind spot shipped four separate defects. |
| `SetArrangementPosition` takes **4 ints** | A float raises `TypeError`. The correct **x** depends on the arrangement family: `Body_*_Center_1` needs the two panels to **match** (a 50/0 split folds one shoulder); `Leg_Skirt_*` needs them to **differ** (50/50 drops the skirt on the floor). Sweep with a control before changing it. See `references/tooling.md` §5. |
| `ExportOBJ` writes **mm**; the FBX→census path reads **decimetres** | The two exporters disagree. Metres = OBJ × 0.001, FBX census × 0.1 (that's what `align.scale_z` is for). |
| `GetClothPositions()` is an out-param that stays empty from Python | No mesh introspection. Export a throwaway OBJ and parse its `v ` lines — exact, and the only option for gappy/strand garments, where `qc_placement.py`'s pixel classifier fails outright. |
| No `SaveProjectFile`; no glTF export; no EveryWear in the API | Save = `export_api.ExportZPrj`. Exits: `ExportFBX` / `ExportOBJ` / `ExportZPac`. EveryWear is GUI-only. |
## Construction doctrine
**Take the reference apart before drafting anything.** The tailor's method —
image → slot split → anchoring → placement targets → ease table → piece plan —
is `references/deconstruction.md`. Its output is a worksheet of numbers, and
every downstream value (panel dims, `expect.bands`, sim recipe) traces to a row
of it. Skipping this step is how garments shipped 4–14 cm off target.
**Draft from measurements, not guesses.** Lena's card:
`tools/tailor/lena_measurements.json` (regenerate for any body with
`tools/tailor/measure_body.py`, a headless-Blender mesh slicer). She is
stylized — 108-67-109 cm with 72 cm thighs on 178 cm — so real-world size charts
produce clothes that don't fit.
**Build from blocks, not freehand.** The blocks are parametric now —
`tools/tailor/blocks.py` turns worksheet numbers into a runnable config skeleton
(`python tools/tailor/blocks.py fitted_top --name x --band-top-z 1.31 --hem-z 1.05 --ease 17`),
with the seam parity, arrangement-x rules, bodice taper, and tension waists
baked in (`--selftest` proves it regenerates the shipped garments). Prefer
generate-then-edit over hand-typing point lists. The original per-garment
recipes remain as provenance:
| Block | Generator | Legacy recipe | Notes |
|---|---|---|---|
| Fitted top / tank / bodice | `blocks.fitted_top` | `md_tee_v1.py`, `md_pari.py` | Front+back panels, shoulder+side seams, neck gap and armholes cut into the outline. Straps hold height reliably. Legacy recipes predate the §3.3 seam-parity and §5 arrangement-x discoveries — the generator has the fixes. |
| A-line skirt | `blocks.aline_skirt` | `md_skirt_v1.py`, `md_piupiu.py` | 2 panels, side seams only. The most forgiving garment; start here. |
| Strand/fringe skirt | `blocks.strand_skirt` | — | Comb outline (teeth, never partial seams), symmetric half-gaps, elastic mid-settle. |
| Trousers/shorts | **unsolved** — see failure catalogue | | |
**Seams:** whole-edge only. Pair the **same line index** on **mirrored** front/back
panels with `(False, False)` — *mirrored* is load-bearing. Most recipes here draft both
panels from the **identical** point list offset by `dx`, which is NOT mirrored, and
those need **`(True, True)`** on the side seams or the panel twists and turns partly
inside out. Full decision table in `references/tooling.md` §3.3; cross-pairing every
seam makes the garment slide off the shoulders. Build
neck gaps and armholes as extra points in the outline, not as partial seams.
Fingerprint line indices by length via `GetLineLength(pattern, line)`.
**Straps beat tubes.** A strapless tube slides down to the narrowest catch
(underbust). If a reference garment is strapless, add straps anyway when the
target body has baked-in underwear to cover — it fixes placement and coverage at
once. It's also what made the pari read correctly.
**Bottoms stay up by tension, not elastic.** Cut the waist *smaller* than the
hips and let fabric stretch hold it.
## Drape recipe (the sequence that works)
```python
pattern_api.SetPatternStrengthen(p, True) # stiffen so cloth wraps, not crumples
utility_api.ResetClothArrangement() # apply arrangement
utility_api.Simulate(250) # main settle, still stiff
# skirts: enable waist elastic HERE, mid-settle, then Simulate(80) more
pattern_api.SetPatternStrengthen(p, False)
utility_api.Simulate(50) # relax into natural folds
```
- **Strengthen through the whole settle**, relax only at the end. Soft fabric
from frame 0 rolls into a bunch at the waist. This is the anti-bunching fix —
**but only for garments whose sides are fully sewn.** On a bodice sewn only over
its lower half with 90 mm straps, strengthening flattens the back and **rotates the
whole garment**, giving an uneven hem and exposed skin. Where it can't be used,
remove the surplus cloth instead.
- **Elastic mid-settle, never from the start.** Elastic applied before the cloth
has wrapped cinches the garment off one hip. Drape first, cinch second — that
is what finally locked the piupiu waistband at the waist.
- **Skirts arrange on `Leg_Skirt_Front` / `Leg_Skirt_Back`**, not the body-waist
points, with `SetArrangementPosition(p, x, 92, 50)`.
- **One garment per scene.** A second garment — even frozen — grabs and inverts
the new one. Game exports are per-garment anyway. Assemble outfits only at the
end, by reloading finished pieces (below).
- **Outfit assembly:** `ImportZprj(base)` + `ImportZpac(other, op.bAdd=True)`.
Textures survive **only if you don't re-fabric or re-simulate after merging** —
a merge renumbers patterns and fabrics unpredictably. Assemble, shoot, done.
## QC — the part that was missing and matters most
Early drapes were accepted because they "looked like clothing". They were
bunched around the middle. Fit is judged by **numbers against the reference**:
1. **Extract placement targets** from the reference photo — where each edge sits
relative to body landmarks, as a table with tolerances. Example (kapa haka):
pari top 1.31 m ±3 cm (above bust), pari hem / piupiu waist 1.05 m ±3 cm,
piupiu hem 0.45 m ±4 cm (below knee).
2. **Measure every drape**: `python tools/tailor/qc_placement.py <snapshot.png>`
classifies background/skin/garment pixels, calibrates px→m off Lena's known
1.777 m height, and reports each garment band's top/bottom in metres against
the nearest landmark. Iterate until inside tolerance.
3. **Snapshot with `SetCamViewPoint(2)`** so every shot is comparable.
4. **Save a screenshot into the repo** for every shipped garment —
`tools/tailor/screenshots/<garment>.png`. Required, not optional: it's how
Jeremy reviews without opening MD.
**The diagnostic that unsticks everything:** snapshot *after*
`ResetClothArrangement()` with **zero simulation frames**. That shows where the
panels actually start, before physics muddies it. Seven "seam bug" iterations
were really an upside-down garment; one pre-sim snapshot would have caught it
immediately. Reach for it the moment a drape misbehaves.
`qc_placement.py` is honest but crude: it counts the body's baked-in underwear
and floor shadow as garment. Tighten it with per-garment colour masks when
precision matters.
## Textures
Generate procedurally with PIL and set physical scale via DPI —
`tools/tailor/textures/` holds `taniko.png` (concentric woven diamonds) and
`piupiu.png` (flax strands with geometric banding), both derived from a reference
photo. Pattern-generation scripts are worth keeping when a motif will recur.
Workflow: `AddFabric(<.zfab>)` → `SetBaseTextureMapImageGivenFilePath(png, fab)`
→ `SetPatternPieceFabricIndex(pattern, fab)`. Set the PNG's dpi so the design
spans the garment exactly once (dpi = px / (mm/25.4)).
## Handing off downstream
Export three ways per garment, into `tools/tailor/`:
```python
export_api.ExportZPrj(".../lena_<garment>_v<N>.zprj") # editable source of truth
op = ApiTypes.ImportExportOption(); op.bExportGarment = True; op.bExportAvatar = False
export_api.ExportFBX(".../lena_<garment>_v<N>_garment.fbx", op) # for clothing/
export_api.ExportOBJ(".../lena_<garment>_v<N>_garment.obj", op)
export_api.ExportZPac(".../lena_<garment>_v<N>.zpac") # for outfit assembly
```
Then the garment goes through `clothing/garment_pipeline.py` (fit → reduce →
skin → export) to become a game outfit part. **Two advantages MD-authored
garments have over downloaded ones**, worth exploiting in the config:
- **They're already game budget.** These export at 1.2k–3.7k verts; the
downloaded MD dress the clothing pipeline was piloted on is 2.49 M verts /
110 MB. The brutal `reduce` stage is mostly unnecessary — start with a high
tri budget and only decimate if the test bed complains.
- **They're already fitted**, having been draped on the actual game body, so
`align`/`fit` needs little more than the clearance shell.
Keep the `.zprj` — regenerating a variant beats re-authoring, and the clothing
README explicitly prefers re-exporting from MD over fighting reduction.
## Failure catalogue (don't rediscover these)
- **Shorts / trousers are unsolved.** Two-panel crotch-notch construction twists
every time — fabric can't thread between Lena's touching thighs, and all seam
parities were tried. Next approach: **4 panels arranged on the per-leg points**
(`Leg_Front_L/R`, `Leg_Back_L/R`) so cloth starts wrapped around each thigh.
- **Upside-down panels** (y-down drafting) — see the y+ = UP rule.
- **Elastic-first drapes** slide off a hip; **soft-from-frame-0** drapes bunch.
- **Co-draping** two garments inverts one.
- **A textured render hides folds and winding.** Judge shape with the texture OFF:
cloth is white on its front face, grey on its back, so a panel showing grey from
outside is inside out and a white streak is a fold. A busy motif conceals both.
- **A sweep without a control case teaches you something false.** If the control
(known-good settings) also fails, the harness is broken, not the geometry.
- **A light garment does not slide into place.** MD materialises cloth at the
arrangement point and does not simulate donning, so for anything light the
arrangement height *is* the placement.
- **Retexturing after a scene merge** silently repaints the wrong garment.
- **Threaded/background socket servers inside MD never answer** — the bridge must
own the main thread. Don't "fix" the frozen UI by re-threading it; that was
tried and the design is deliberate.
- MD 2026's **AI Image Generator / EveryWear are GUI-only** — not scriptable.
## File map
| Path | What |
|---|---|
| `tools/md_bridge.py` | Terminal client (`--ping/--exec/--file/--stop`) |
| `tools/md_bridge/TinqsMDBridge.py` | The plugin (register once via Plug-in Manager; referenced in place, so edits go live on next click) |
| `tools/md_bridge/api_surface.json`, `api_docs.json` | Introspected API truth |
| `docs/md-bridge.md` | Protocol, install, threading rationale |
| `tools/tailor/measure_body.py`, `lena_measurements.json` | Body measurement tool + Lena's card |
| `tools/tailor/blocks.py` | Parametric blocks: worksheet numbers → config skeleton (`--selftest`) |
| `tools/tailor/draft_garment.py` | Config `md` block → bridge script (the four recipes, templated) |
| `tools/tailor/md_*.py` | Per-garment recipes (each header carries its own lessons) |
| `references/deconstruction.md` | The tailor's method: taking a reference image apart into pieces |
| `tools/tailor/qc_placement.py` | Placement QC measurement |
| `tools/tailor/textures/` | Generated fabric maps |
| `tools/tailor/screenshots/` | Required per-garment review renders (front **and back** — see tooling.md §0) |
| `references/tooling.md` | Which API call for which job, verified signatures, decision tables |
| `tools/tailor/avatar/Lena_QuatSkin_Avatar.fbx` | Game body as an MD avatar (from the GLB, leaf bones stripped) |
| `tools/tailor/lena_*_v*.{zprj,fbx,obj,zpac}` | Shipped garments |
.claude/skills/marvelous-designer/references/deconstruction.md
+214
View File
@@ -0,0 +1,214 @@
# Deconstruction — taking a reference apart like a tailor
Companion to `../SKILL.md`. That file is drafting/draping doctrine; **this file is
the step before it**: how to read a clothing image (or description) and take the
garment apart into pieces our MD lane can actually build. Skipping this step is
how garments shipped 4–14 cm off their own targets — the drafting was fine, the
*analysis* had never been written down.
The output is a **worksheet of numbers**, not geometry. Panel point lists come
last, and mostly from `tools/tailor/blocks.py`, not by hand.
---
## 0. The worksheet (output contract)
Fill this in full **before** asking for a bridge session. Every number the drape
and QC stages use traces back to a row here.
| # | Item | Feeds |
|---|---|---|
| 1 | Slot split — which separate garments is this outfit? | one config per garment |
| 2 | Per garment: class + block choice | `blocks.py` function |
| 3 | Anchoring — what holds it up | construction + arrangement |
| 4 | Placement targets — each edge's z ± tol vs landmarks | `expect.bands` (gate G1) |
| 5 | Edge circumference + ease table | panel widths, taper |
| 6 | Piece list + seam plan | `md.panels` / `md.seams` |
| 7 | Textile plan — what is texture, not geometry | texture generation |
| 8 | Fabric read — weight/stiffness | `.zfab` choice + sim recipe |
| 9 | Risks — unsolved/untested features | scope call before starting |
`blocks.py` turns rows 2–5 into a config skeleton (`md` block + `expect.bands`)
in one call. If no block fits, hand-draft under `tooling.md` §3 rules (named
landmarks, computed line indices) — never freehand a point list.
## 1. Split the outfit into garments by slot
The game wears **per-slot parts** (Body, Legs, …) and MD drapes **one garment per
scene** — a second garment, even frozen, grabs and inverts the new one. So a
"dress over leggings with a belt" reference is *three* worksheets, three configs,
three drape sessions. Decide the split first:
- One garment per clothing slot it occupies. A dress is one garment (Body slot,
or whatever slot spans it) even though it covers both regions.
- Belts, sashes, armbands: texture if flat against the host garment; separate
garment only if they hang or swing.
- Outfit photos are assembled at the end from finished `.zpac`s (SKILL.md
"Outfit assembly") — never co-draped.
## 2. Anchoring — decide what holds it up before what it looks like
Anchoring determines construction more than silhouette does. MD materialises
cloth at the arrangement point and does **not** simulate donning, so nothing
"slides into place".
| What the image shows | Anchor | Construction consequence |
|---|---|---|
| Straps, sleeves, or a shoulder line | shoulder-hung | bodice block; straps reach `shoulder_z` or the garment settles at the underbust |
| Strapless top | (unreliable) | **add straps anyway** — a tube slides to the narrowest catch; straps also cover the body's baked-in bra straps |
| Skirt/trousers at waist or hip | waist tension | cut the waist **smaller** than the hips (0.90–0.92 × hip circ) and let stretch hold it; elastic only mid-settle, never frame 0 |
| Light/gappy garment (strands, fringe, open weave) | arrangement itself | arrangement height **is** the placement — a light band stays exactly where arranged |
Always check what the anchor must *cover*: the target body has baked-in
underwear, and any neckline or scoop that drops below it reads as the garment
failing. Check the **back** neckline explicitly — the reference photo almost
never shows it, `ExportSnapshot3D` cannot show it (`tooling.md` §1.1), and that
blind spot has shipped defects. If the image doesn't show the back, *decide* the
back (scoop depth, coverage) and write it on the worksheet rather than letting it
default.
## 3. Read the seams, then discard most of them
A real tailor's deconstruction finds every seam. Ours finds them and then
**collapses almost all of them**, because the MD lane sews whole edges only, has
no darts, and garment identity for our targets is mostly textiles (SKILL.md).
Translation table:
| Feature in the image | Our move |
|---|---|
| Side seams, shoulder seams | keep — these are the block's real seams |
| Darts (bust, waist) | **no darts.** Taper the panel side edges + stretch ease carries the shaping |
| Princess seams, yokes | collapse into the panel; if visible, draw them in the texture |
| Waistband | merge into the panel top; separate band only for strand/fringe skirts |
| Set-in sleeves | **untested** — no sleeve block yet; treat as scope risk (row 9) |
| Collars, hoods | **untested/unsolved** — same |
| Trousers/shorts crotch | **unsolved** (failure catalogue); next approach is 4 panels on the per-leg points |
| Plackets, buttons, zips, pockets, topstitching | texture, always |
| Gathers, pleats, ruffles | texture unless the *silhouette* depends on them |
| Fringe / strands / fur edge | teeth cut into the panel outline (comb panel), never partial seams |
| Belt/sash flat against the garment | texture |
The test for "geometry or texture?": does it change the **silhouette** or the
**edge positions**? If not, it's texture.
## 4. Placement targets — numbers before points
Extract where every garment edge sits **before drafting anything**. This is the
step that was skipped when shipped garments landed 3.9–14 cm off targets that
existed only as prose.
Landmark card for the current body (`tools/tailor/lena_measurements.json`,
regenerate per body with `measure_body.py`; metres, floor = 0):
| Landmark | z | Landmark | z |
|---|---|---|---|
| top of head | 1.777 | hip (widest) / crotch | 0.946 |
| neck base | 1.457 | thigh | 0.865 |
| shoulder | 1.397 | knee | 0.517 |
| chest (bust) | 1.264 | ankle | 0.106 |
| waist | 1.089 | | |
Method, per garment edge (top of band, hem, waistline…):
1. Find the edge in the image relative to the two nearest **visible** landmarks
(e.g. "hem lands mid-thigh, about ⅓ of the knee→hip span above the knee").
2. Interpolate a z from the card. The body is stylized — always place against
*these* landmarks, never against real-world garment-length conventions.
3. Assign a tolerance: ±3 cm for fitted edges, ±4 cm for free-hanging hems.
4. Write the rows into `expect.bands` — gate G1 measures every drape against
them from then on.
Sanity anchor (proven): a pari band 1.31→1.05 m and piupiu 1.05→0.45 m came from
exactly this read of the kapa haka reference.
## 5. Ease — how much bigger than the body
For each **horizontal** edge, the panel width comes from the body circumference
at that z plus ease. Interpolate circumference linearly between the card's
(z, circ) pairs — neck 0.392, chest 1.083, waist 0.675, hip 1.095 — and **never
interpolate below the hip** (the legs bifurcate; a slice there measures nonsense).
| Fit read from the image | Total ease | Proven case |
|---|---|---|
| Snug / bandeau / activewear | +15–20 mm | pari: 1100 vs 1083 bust |
| Regular fitted top | +90–100 mm | tee: 1180 vs 1083 bust |
| Loose / drapey | +150 mm and up | (untested above ~150) |
| Bottoms waist edge | **negative**: 0.90–0.92 × hip circ | piupiu: 1000 vs 1095 hip |
Bottoms are the inversion to internalise: the waist edge is cut *smaller* than
the hips it must pass over, because tension is the anchor (§2).
## 6. Vertical spans are 1:1
Pattern millimetres map 1:1 to world metres — drape shrinkage is negligible for
our fabrics. So:
- panel cloth height = `(top_z − hem_z) × 1000`
- a shoulder-hung garment's straps must reach the shoulder: total panel height
= `(shoulder_z − hem_z) × 1000`, and the front scoop depth is what's left
between strap top and the visible band top: `scoop = panel_h − (band_top_z −
hem_z) × 1000`.
Proof this math is the real one: it reproduces all three shipped garments —
tee 480 (shoulder 1.397 → hip-ish hem 0.917), pari 350/scoop 105 (shoulder →
waist 1.05, band top 1.30), piupiu 600 (1.05 → 0.45).
## 7. Blocks — what we can build today
| Garment class | Block | Status |
|---|---|---|
| Tank / tee / fitted bodice / bandeau-with-straps | `blocks.fitted_top` | **proven** (tee, pari) |
| A-line / straight skirt | `blocks.aline_skirt` | **proven** (skirt, piupiu v2) |
| Strand / fringe skirt (piupiu, hula, fur trim) | `blocks.strand_skirt` | proven construction (comb outline), parameters per garment |
| Dress | `fitted_top` + skirt geometry in one panel pair | **untested** — try taper-through-waist first |
| Trousers / shorts | — | **unsolved**; next: 4 panels on `Leg_Front_L/R`, `Leg_Back_L/R` |
| Sleeves, collars, hoods | — | untested; scope risk |
| Capes / cloaks / rectangles (traditional wear) | plain panels | rectangles + blocks; identity is the textile |
Every block bakes in the expensive discoveries — seam parity for
identical-offset panels, the arrangement-x rules per point family, bodice taper,
tension waists, strengthen/relax sim recipes — so **prefer a block over a
hand-typed point list even when the block needs post-editing**. Generate, then
edit the config, not the other way round.
## 8. Textiles carry the identity
For traditional wear especially (kapa haka, Mexica, Pacific), the garment reads
as *itself* because of the textile, not the cut. Spend the effort there:
generate the pattern procedurally (PIL), set physical size via DPI
(`dpi = px / (mm / 25.4)`), and keep the generator script — motifs recur.
Model the shape as simply as the silhouette allows.
## 9. Fabric read → sim plan
From the image, judge weight and stiffness, then pick levers (`tooling.md` §4):
- **Stiffness ladder** (`.zfab` presets): `V2_Woven_Canvas_1` <
`V2_Woven_Denim_1` < `V2_Non-Fabric_Tyvek_1`. `fabric_api` has no physics
setters — the `.zfab` *is* the stiffness choice.
- Fully-sewn sides → strengthen through the whole settle, relax at the end.
Under-constrained (half-sewn sides, thin straps) → **don't** strengthen
(it rotates the garment); remove surplus cloth instead.
- Light/gappy → `SetParticleDistanceOfPattern` ~20 mm and remember §2:
arrangement height is placement.
- Skin-tight → `SetAddlThicknessCollision` a few mm before the settle.
## 10. Worked example — the kapa haka reference, as this method
What was done by trial and error in 2026-07-30/31, restated as the worksheet:
| Row | Pari (bodice) | Piupiu (skirt) |
|---|---|---|
| Slot | Body | Legs |
| Class/block | bandeau → `fitted_top` | strand skirt → `strand_skirt` (v2 shipped as `aline_skirt`) |
| Anchoring | photo shows strapless → **straps anyway** (covers bra straps, fixes height) | waist tension, 1000 vs 1095 hip; light strands → arrangement = placement |
| Targets | band top 1.31 ±0.03, hem 1.05 ±0.03 | waist 1.05 ±0.03, hem 0.45 ±0.04 (below knee) |
| Ease | snug: +17 mm over bust | waist 0.91 × hip |
| Seam plan | shoulders + sides; scoop/armholes in outline | band side edges only; strands are outline teeth |
| Textile | tāniko band → generated `taniko.png`, DPI-sized to span once | flax strands + geometric banding → `piupiu.png` |
| Fabric | default sim fabric, strengthen full settle | default, strengthen + (v3) elastic mid-settle |
| Risks | back neckline never visible in photo — decided, then verified via turntable | hem vs leg-swing envelope (skirt bones downstream) |
The lesson the example carries: **nothing in the finished configs is a guess.**
Every number is a worksheet row, and every worksheet row is checkable — by G1
against the render, or by `GetLineLength` against the drafted panel.
.claude/skills/marvelous-designer/references/tooling.md
+310
View File
@@ -0,0 +1,310 @@
# MD tooling — which call to reach for, when, and why
Companion to `../SKILL.md`. That file is **doctrine** (how to author a garment).
This file is **tool selection**: for a given question, which API answers it, why that
one rather than the obvious alternative, and what it costs you when you guess.
Everything here is verified against **MD 2026 Personal** by running it. Where a
belief was disproved by experiment, the disproof is kept — those are the expensive
entries. Published Reallusion/CLO docs are thin and several signatures in them are
wrong; `tools/md_bridge/api_surface.json` (688 functions) is the name truth,
`api_docs.json` holds only ~48 harvested docstrings, so **read `__doc__` live** for
anything not listed below.
---
## 0. The diagnostic loop — the part that actually determines whether you succeed
The vision loop in SKILL.md is right but incomplete. Four passes, in this order,
because each one can only see what the previous one can't hide:
| Pass | Call | Catches |
|---|---|---|
| 1. **Pre-sim, zero frames** | `ExportSnapshot3D` right after `ResetClothArrangement()` | Upside-down panels, tangles, self-intersecting outlines, wrong start height. Physics hasn't muddied anything yet. |
| 2. **Untextured** | skip `SetBaseTextureMapImageGivenFilePath` | Folds and **winding**. See §1.3 — this is non-negotiable for shape work. |
| 3. **The back** | `ExportTurntableImages(4)`, index 2 | Anything on the rear. `ExportSnapshot3D` **cannot** show the back at all (§1.1). |
| 4. **Numbers** | export a throwaway OBJ, parse it (§2) | Placement, span, coverage. Eyeballing placement is how garments shipped 8–14 cm off their own written targets. |
A defect that survives to production is almost always one that pass 2 or 3 would
have caught. Every screenshot in this repo before 2026-07-31 was a **textured front
view** — pass 1 only — and a twisted seam, an inside-out panel, an asymmetric
shoulder fold and an exposed back neckline all shipped underneath that blind spot.
---
## 1. Looking at the garment
### 1.1 `SetCamViewPoint` HAS NO REAR VIEW
Verified by shooting all eight:
| n | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|---|---|---|---|---|---|---|---|---|
| view | bottom | front ¾ | **front** | front ¾ | side | **top** | side | side |
There is no back. So `ExportSnapshot3D` is structurally incapable of showing the
rear of a garment, no matter how you drive it. Use:
```python
paths = export_api.ExportTurntableImages(4) # 0 front, 1 side, 2 BACK, 3 side
```
- The `(int)` overload **ignores any path you pass** and writes into MD's own output
folder (`%LOCALAPPDATA%\CLO Virtual Fashion\Marvelous Designer Personal\<n>\output*.png`).
The **return value is the only way to find the files**.
- The documented `(path, count, w, h, startIndex)` overload returned `[]` — didn't work.
- `ExportCustomViewSnapshot(folder, w, h, prefix)` also returned `[]`.
- Turntable **reuses the same `output*.png` names every call**, so if you are
sweeping variants, `shutil.copyfile` each frame out immediately or you lose it.
- `SetCamViewPoint(5)` (top-down) is the clearest angle on a **shoulder join** —
nothing else shows whether front and back actually meet over the shoulder.
- `SetViewPoint()` does nothing. Don't confuse the two.
- Always set the viewpoint before a snapshot so shots are comparable.
### 1.2 Zoom in, and build contact sheets
The turntable renders 2500×2500. Crop to the region of interest and upscale with
PIL before looking, or you will miss centimetre-scale defects. When comparing
variants, tile them into **one** image with labels — one look at four labelled
tiles beats four separate looks, and it makes the winner obvious.
### 1.3 Untextured renders show face orientation — the single best shape diagnostic
With the default sim fabric and no texture map, cloth renders **WHITE on its front
face and GREY on its back face**.
- A panel showing **grey from outside is inside out**.
- A **white streak on an otherwise grey panel** is a fold exposing the true front face.
- A busy motif hides both **completely**. A tāniko print concealed a twisted side
seam through several rounds of wrong diagnosis; the untextured pass identified it
in one look.
Judge shape untextured, then re-enable the texture only for the shipping render.
---
## 2. Measuring — you cannot introspect the mesh, so export and parse
`GetClothPositions()` is an out-param that **stays empty from Python**. There is no
mesh access. So:
```python
op = ApiTypes.ImportExportOption(); op.bExportGarment = True; op.bExportAvatar = False
export_api.ExportOBJ(throwaway_path, op) # then parse the 'v ' lines yourself
```
**Units are a trap.** The two exporters disagree:
| Path | Units | Conversion to metres |
|---|---|---|
| `ExportOBJ` | **millimetres** | `× 0.001` |
| `ExportFBX` → clothing pipeline census | **decimetres** | `× 0.1` (this is what `align.scale_z: 0.1` is doing) |
Verified: an OBJ y of 1086.9 is 1.0869 m, checked against the known 1.777 m body.
Getting this wrong wastes a full sim round-trip.
**`tools/tailor/qc_placement.py` only works on solid silhouettes.** Its pixel
classifier needs a filled shape; on a strand skirt (mostly gaps) it reported a
1.71 m span, which is nonsense. For anything gappy, layered, or strand-based,
measure the exported geometry instead. Useful derived numbers: z-span (band top,
hem), fraction of verts above a bone-ring height, and per-height radius
percentiles for ease.
**`GetLineLength(pattern, line)`** is the cheap way to confirm you are about to sew
the edges you think you are. Fingerprint by expected length before every seam call
— see §3.2.
---
## 3. Constructing patterns
### 3.1 Outlines, not partial seams
`CreatePatternWithPoints` with **y+ = UP in 3D**. Drafting y-down drapes the garment
upside-down over the head; the symptom reads like a seam bug and isn't.
Cut features **into the outline** — neck gaps, armholes, and the teeth of a strand
skirt. Partial seams twist unpredictably. A 32-strand piupiu was built as two
comb-shaped panels with the strands cut into the outline and only the two band side
edges sewn; the alternative (32 partial seams) is in the failure catalogue for a
reason.
### 3.2 Line indices shift — compute them, never hardcode
Line `i` runs `pts[i] → pts[i+1]`. **Inserting a point shifts every index after it.**
Hardcoded `0/5/7/9` broke this repo's bodice recipe twice. Build the point list with
named landmarks and derive the indices:
```python
n_arm = 1 if arm else 0
side_r = 6 + n_arm + 1
idx = {"shoulder_l": 0, "shoulder_r": 5,
"side_r": side_r, "hem": side_r + 1, "side_l": side_r + 2}
```
Then verify against known lengths (`shoulders ≈ 93 mm`, `sides ≈ 208 mm`). If those
drift, your index maths is wrong — not the cloth. This check turns a silent
mis-sew into an immediate, obvious failure.
**Paired edges must be EQUAL, not close.** A strand skirt fingerprinted as
`[60.0, 60.075, 60.0, 60.075]` and that 0.075 mm was dismissed as rounding. It wasn't:
one band side edge was a true vertical and the other was **slanted**, because the
outline gave a half-gap to the leftmost tooth but not the rightmost (the loop skipped
the band-bottom step point on its first iteration, leaving that tooth flush with the
panel edge and half a gap wider than every other). Sewing a flush tooth to a
half-gapped one across a slanted seam notched the waistband and exposed the reverse
face. **Treat any inequality between paired edges as a construction bug.**
### 3.3 Seam pairing — a decision table, because the naive rule is incomplete
`AddSeamlinePairGroup(pf, lineF, pb, lineB, flagA, flagB)`. The two booleans reverse
edge traversal. SKILL.md's rule — "same line index on **mirrored** front/back panels
with `(False, False)`" — is correct but the word *mirrored* is load-bearing, and
most recipes here draft both panels from the **identical** point list offset by `dx`,
which is **not** mirrored.
| Panels | Pairing | Flags | Result |
|---|---|---|---|
| Mirrored | same index | `(False, False)` | correct (the documented case) |
| **Identical, not mirrored** | same index | **`(True, True)`** | correct — both edges reversed |
| Identical, not mirrored | same index | `(False,False)` / `(0,1)` / `(1,0)` | **twists the panel**; part turns inside out and rucks up |
| Mirrored coords, list order kept | same index | any | **garment falls off** — mirroring permutes the indices |
| Mirrored coords + **remapped** indices (`shoulder_l`↔`shoulder_r`, `side_r`↔`side_l`) | crossed | `(False, False)` | correct, and the only thing that fixes an inside-out back panel |
| Cross every pair (sides **and** shoulders) | crossed | any | **slides to the hips** — cross-wired straps cancel and it falls off the shoulders |
Proven by sweeping all four flag combinations at fixed geometry. Two lessons worth
internalising: **a twisted seam and surplus cloth look identical when textured**, and
mirroring is only correct if you remap the pair indices with it.
### 3.4 Shape rules that are geometry, not physics
- **Bodices must taper.** A rectangular panel cut for the bust carries its full bust
width down to a hem sitting on a much smaller waist (1083 mm bust vs 675 mm waist
here — ~400 mm of surplus) and the excess can only fold. Take it off each side
edge at the hem. Use the **same** taper on both panels: side-seam length is
`sqrt(taper² + side_y²)`, so equal tapers keep whole-edge pairing matched and
unequal ones skew it.
- **A pelvis-parented skirt must contain the whole leg-swing envelope.** At a hem
0.5 m below the hip pivot, 30° of hip flexion sweeps the leg ~25 cm forward — more
than any believable silhouette clears. Clearance alone cannot fix a knee-length
skirt; discrete strands or a runtime bone rig has to do the rest.
- **Straps exist to cover the target body's baked-in underwear.** If a neckline or
scoop drops below the body's painted-on tank, the tank shows and reads as the
garment failing to connect. Check the back neckline specifically — nothing was
looking at it.
---
## 4. Fit and physics levers
| Goal | Call | Why this one |
|---|---|---|
| Stand cloth off the skin | `pattern_api.SetAddlThicknessCollision(p, mm)` | The sim **resolves** the clearance, so it holds everywhere. Better than the downstream Blender normal-push, which self-intersects in concave regions — exactly between touching thighs. Set it **before** the settle. |
| Mesh / sim resolution | `SetParticleDistanceOfPattern(p, mm)` | Drives vert count and how many rows sit between skeleton joints. 20 mm gave ~29 rows on a 530 mm strand; 15 mm blew the vert budget. |
| Stop crumpling during the settle | `SetPatternStrengthen(p, True)` → relax at the end | **Conditional — see §6.** |
| Hold a waistband up | `SetPatternPieceElastic(p, line, bool)` + `SetPatternPieceElasticTotalLength(p, line, mm)` | Apply **mid-settle**, never from frame 0. Not needed if the band is cut smaller than the hips — the hip blocks it. |
| Fabric stiffness | **a different `.zfab`** | `fabric_api` has **no physics setters at all** — it is textures and metadata only. Stiffness ladder: `V2_Woven_Canvas_1` < `V2_Woven_Denim_1` < `V2_Non-Fabric_Tyvek_1`. Stock presets in `C:\Users\Public\Documents\MarvelousDesigner\New Assets\Fabric\`. |
Signatures verified live (all `(patternIdx, …)`, and the elastic family takes a
**line index** as its second arg):
```
SetAddlThicknessCollision(int, float) -> None GetAddlThicknessCollisionValue(int) -> float
SetParticleDistanceOfPattern(int, float) -> None SetPatternPieceSolidifyStrengthen(int, float) -> None
SetPatternPieceElastic(int, int, bool) -> None SetPatternPieceElasticTotalLength(int, int, float) -> None
SetPatternPieceElasticStrength(int, int, float) SetPatternPieceElasticSegmentLength(int, int, float)
SetSimulationSelfCollisionAvoidanceStiffness(float) SetAvatarSoftBodyStiffness(int, float)
GetLineLength(int, int) -> float ImportZprj(str, ApiTypes.ImportZPRJOption) -> bool
```
---
## 5. Arrangement — placement is a separate system from physics
| Fact | Consequence |
|---|---|
| `SetArrangement()` only **assigns**; `utility_api.ResetClothArrangement()` **applies** | Skipping the apply = nothing moves. |
| Arrangement **indices regenerate** per avatar import | Always look up by name from `GetArrangementList()`. Never hardcode. |
| `SetArrangementPosition` takes **4 ints** | A float raises `TypeError`. |
| **The x argument's correct value DEPENDS ON THE ARRANGEMENT POINT FAMILY — verified both ways by sweep** | `Body_*_Center_1` (bodice): the two panels must use the **SAME** x. Front `50` / back `0` folds one shoulder only and exposes the reverse face. `Leg_Skirt_Front`/`Back` (skirt): the two panels must use **DIFFERENT** x. `50/0` and `0/50` both drape correctly (band top 1.093 / 1.095) while `50/50` and `0/0` drop the skirt **on the floor** (0.10 / 0.14). So the split is load-bearing for skirts and a bug for bodices. **Never harmonise the two recipes** — and sweep with a control before changing this value on a new garment. |
| Skirts belong on `Leg_Skirt_Front` / `Leg_Skirt_Back`, y=92 | Using `Body_*_Waist` instead put a skirt **8–14 cm high**. Switching fixed placement to within 9 mm. |
| **A light garment does not slide into place** | MD materialises cloth at the arrangement point; it does not simulate donning. A heavy solid panel settles onto the hips, but a 60 mm waistband with light strands **stays exactly where it is arranged** — the first strand-skirt drape sat at the chest. For light garments, **arrangement height IS the placement**. |
| `utility_api.NewProject()` **deletes the avatar** | Re-import after. |
---
## 6. Rules in SKILL.md that need a condition attached
- **"Soft-from-frame-0 drapes bunch"** → true, and strengthening does flatten a
bunched back. But `SetPatternStrengthen` **rotates an under-constrained garment**:
a bodice whose sides are sewn only over the lower half and whose straps are 90 mm
wide came out flat *and twisted*, with an uneven hem and skin showing. Pre-sim was
clean, so it develops during the settle. **The rule applies to garments whose sides
are fully sewn.** Where it doesn't, remove the surplus instead of stiffening.
- **"Pair the same line index with `(False, False)`"** → only for **mirrored**
panels. See the table in §3.3.
---
## 7. Harness patterns for iterating
**Sweep variants in ONE bridge call.** Each `--file` round trip costs a session
turn; a loop with `NewProject()` per iteration costs one. Four 250-frame sims ≈ 4
minutes and answers a question that four guesses would not.
```python
for value in SWEEP:
utility_api.NewProject(); import_api.ImportFBX(AVATAR_FBX, op) # avatar first
...build, sew, arrange, Simulate(250)...
shots = export_api.ExportTurntableImages(4)
shutil.copyfile(shots[2], f"...{value}_back.png") # names are reused — copy now
```
**Read pass/fail from GEOMETRY, not images, where you can.** A garment on the floor
measures `band_top < 0.3 m`. Have the sweep parse its own probe OBJ and self-report
which cells even stayed on the body — then you only open images for the survivors.
**Always include a control case that reproduces the known-good result.** A sweep
whose control also fails tells you the *harness* is broken, not the geometry —
`tools/tailor/md_pari_armsweep.py` dropped the garment on the floor in all four
cells including its control, so every one of its results was void.
`md_pari_seamsweep.py` had a valid control and produced a decisive answer. Without a
control you cannot tell those two situations apart, and you will "learn" something
false.
**Guard the export.** Keep `EXPORT = False` until a snapshot looks right, so a
look-first run cannot overwrite shipped files.
**Timeouts:** roughly 1 minute per 300 simulated frames; pass `--timeout 880` for
anything with several sims.
**Session mechanics:** a human must click Plugin → TinqsMDBridge; MD's UI is frozen
for the whole session ("Not Responding" is normal); `python tools/md_bridge.py --stop`
hands it back and works even though the UI is dead. Stop when you hand back a
result — Jeremy inspects in the viewport and can't while the bridge owns the thread.
**Writing recipe files from Python:** these files contain box-drawing and em-dash
characters. Always `io.open(path, encoding='utf-8')`. A default-codec round trip
(cp1252) corrupted a recipe and the bridge then failed to read it at all.
---
## 8. Exits
`ExportZPrj` (editable source of truth), `ExportFBX`, `ExportOBJ`, `ExportZPac`
(outfit assembly), `ExportAlembic` / `ExportUSD`, `ExportAnimationVideo`.
No glTF export. No `SaveProjectFile` — saving *is* `ExportZPrj`. **EveryWear and the
AI Image Generator are GUI-only**, absent from the API, so the downstream
Blender half of the lane cannot be replaced by them.
Avatar getters live in **`export_api`** (`GetAvatarCount`, `GetAvatarNameList`), not
`utility_api` where you would look for them.
There is an **animation surface worth knowing about but unverified**:
`SetStartAnimationFrame` / `SetEndAnimationFrame` / `SetCurrentAnimationFrame` /
`RunAnimationRecording` / `GetAnimationLayerFrameRange`, plus `ExportAlembic`. If a
game clip's motion can be driven onto the avatar, this yields a per-frame cloth cache
with zero penetration by construction — the reference a skinned garment should be
scored against. **Not yet tested**: whether `ImportFBX`'s options can bring animation
in with the avatar is unknown.