feat: clothing lane, character sources, and DCC bridges
Bulk import of the working lanes that were living untracked on the PC. Content: - characters/ Lena/male body lanes, bakes, texture work, run logs - clothing/ garment pipeline, configs, gates, contract docs - garments/ MD-authored garment sources (.zprj/.zpac) - UAL-Lib/ Universal Animation Library 2 source (.blend/.fbx/.glb) - tools/ blender_bridge, iclone_bridge, md_bridge, tailor, glm_agent - docs/, plans/, dev/, .agents/plans/ Repo hygiene: - .gitattributes: LFS now covers .blend, .zprj, .zpac, .obj, .npy and the Reallusion .iAvatar/.ccAvatar/.ccRestore containers. Without this the ~3.8 GB in this commit would land as raw blobs. .png/.jpg are left out on purpose — ~250 are already tracked raw and converting them would rewrite every one without shrinking history. - .gitignore: exclude /accurig/ (~1 GB AccuRig program files, redistributable from Reallusion, nothing authored here) and /dev/null/ (git-lfs hook copies dropped by a `>/dev/null` redirect on Windows). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,172 @@
|
||||
# TASK: put the approved kapa haka outfit through the clothing pipeline into the game
|
||||
|
||||
You are working in `C:/Users/Jeremy/tinqs/animation` (Git Bash, Windows). Blender is:
|
||||
|
||||
BLENDER="/c/Program Files/Blender Foundation/Blender 5.1/blender.exe"
|
||||
|
||||
## Goal
|
||||
|
||||
Two Marvelous-Designer-authored garments have been approved. Turn them into
|
||||
game-ready outfit parts on the shared 65-bone Quaternius skeleton, using the
|
||||
existing staged Blender pipeline `clothing/garment_pipeline.py`.
|
||||
|
||||
| Garment | Source file (already exported, do not re-author) | Outfit slot |
|
||||
|---|---|---|
|
||||
| Tāniko bodice ("pari") | `tools/tailor/lena_pari_v3_garment.fbx` | Body |
|
||||
| Flax skirt ("piupiu") | `tools/tailor/lena_piupiu_v2_garment.fbx` | Legs |
|
||||
|
||||
Target body / rig (the fit target and weight donor):
|
||||
`C:/Users/Jeremy/tinqs/ariki-game/assets/quaternius/derived-bodies/Ariki_Female_QuatSkin.glb`
|
||||
|
||||
Export destination:
|
||||
`C:/Users/Jeremy/tinqs/ariki-game/assets/quaternius/outfits/kapahaka/`
|
||||
Set id `Kapahaka`, gender `Female`, so the pipeline should produce
|
||||
`Female_Kapahaka_Body.gltf` and `Female_Kapahaka_Legs.gltf` (+ .bin), matching
|
||||
the naming pattern of the earlier pilot in `../outfits/mddress/`.
|
||||
|
||||
## Read these first (they are the source of truth — do not guess)
|
||||
|
||||
1. `clothing/README.md` — the pipeline's stages, design rationale, usage, and
|
||||
the config schema explanation. Read it fully before writing any config.
|
||||
2. `clothing/configs/dress.json` — a working config to model yours on.
|
||||
3. `.claude/skills/marvelous-designer/SKILL.md` — how these garments were made
|
||||
(section "Handing off downstream" is the relevant part).
|
||||
|
||||
## What is DIFFERENT about these garments (important — the pilot config misleads)
|
||||
|
||||
The pilot config (`dress.json`) was written for a *downloaded* MD dress of
|
||||
**2.49 million verts** with 12 materials, where aggressive reduction was the hard
|
||||
problem. **These garments are nothing like that:**
|
||||
|
||||
- They are tiny: pari ≈ 1.9k verts / 3.6k faces; piupiu ≈ 3.7k verts / 7.1k faces.
|
||||
They are ALREADY at game budget. Do not fight to decimate them. Set generous
|
||||
tri budgets; only reduce if something is genuinely over budget.
|
||||
- They were draped directly on this exact body in Marvelous Designer, so they
|
||||
are ALREADY fitted and correctly scaled/positioned. Expect alignment to be
|
||||
near-identity (scale 1.0, no nudge) — verify rather than assuming the pilot's
|
||||
`scale_xy: 1.18 / scale_z: 0.95` values, which were corrections for a
|
||||
foreign garment.
|
||||
- The `fit` stage is still worth running for its +4mm clearance shell
|
||||
(poke-through defence), but it should barely move anything.
|
||||
- Each garment is one simple part — no junk materials, no topstitch soup, no
|
||||
multi-island jacket. Expect a small number of islands.
|
||||
|
||||
## Already-established facts (verified — do not spend steps re-deriving)
|
||||
|
||||
- The body/rig imports clean: **65 bones**, Quaternius names, body z-range
|
||||
`-0.011 .. 1.766` m, `pelvis` z = 0.932, `neck_01` z = 1.413.
|
||||
- **The MD garment FBX exports are 10× oversized and offset in Z.** Measured
|
||||
pari z-range is `10.546 .. 14.613` against a body of `0 .. 1.77`. This is the
|
||||
mirror of how they were authored (the avatar was imported into Marvelous
|
||||
Designer at `scale=10` to work in MD's millimetre space, so garments come back
|
||||
in that same space). Expect to need roughly **0.1 uniform scale**, then a Z
|
||||
placement correction — derive the exact numbers from the measured bounds
|
||||
rather than trusting this estimate. Sanity check after aligning: the pari
|
||||
should span roughly z 1.05–1.40 m (waist to shoulder) and the piupiu roughly
|
||||
z 0.45–1.05 m (below knee to waist).
|
||||
|
||||
## CRITICAL: placement. A previous run exported a garment 10 cm too low.
|
||||
|
||||
**You cannot see the QA renders.** Confirming a PNG exists proves nothing about
|
||||
whether the garment is in the right place. Placement must be verified
|
||||
**numerically**, and it is the single most likely thing to go wrong.
|
||||
|
||||
### Why the pipeline mis-places these garments
|
||||
|
||||
`stage_prepare` auto-aligns by moving the garment so its **top** meets the
|
||||
`align.top_bone` head: `dz = (b_top - garment_top_after_scale) + z_nudge`.
|
||||
That is correct for a *foreign* garment of unknown position. It is **wrong for
|
||||
these garments**, which were draped on this exact body and are therefore already
|
||||
in the correct world position — only 10× too large. Any bone-align drags them
|
||||
off their authored placement. On the last run this applied `dz = -0.0970` and
|
||||
pushed the pari's straps below the shoulder and its hem down to the hip.
|
||||
|
||||
### The rule
|
||||
|
||||
**A garment's correct final world position is exactly its raw census z-range
|
||||
divided by 10.** Nothing else. Use `z_nudge` purely to cancel the pipeline's
|
||||
auto-align so the net placement lands there.
|
||||
|
||||
### The procedure (repeat per garment)
|
||||
|
||||
1. From the `census` log, note the raw island z-range `[z0, z1]`.
|
||||
Target world range is **`[z0/10, z1/10]`**.
|
||||
(pari measured `[10.546, 14.613]` → target **`[1.055, 1.461]`**.)
|
||||
2. Run `prepare`, then measure what you actually got — load the checkpoint and
|
||||
print the garment's world-space Z bounds, e.g.
|
||||
|
||||
```
|
||||
"$BLENDER" --background clothing/work/<name>/10_prepare.blend --python-expr "import bpy; o=[x for x in bpy.data.objects if x.name.startswith('GARM_')][0]; zs=[(o.matrix_world@v.co).z for v in o.data.vertices]; print('ZRANGE', min(zs), max(zs))"
|
||||
```
|
||||
3. If the measured top differs from the target top by more than **0.02 m**,
|
||||
adjust: `z_nudge += (target_top - measured_top)`, re-run `prepare`, measure
|
||||
again. Two iterations should converge.
|
||||
4. Only proceed to `fit` once the measured range is within 2 cm of target at
|
||||
both ends. State the final measured range in your DONE report.
|
||||
|
||||
Cross-check against the body (a gross error should be obvious): pari ≈ waist to
|
||||
just above shoulder; piupiu ≈ below-knee to waist. Body landmarks: hem/ankle
|
||||
0.11, knee 0.52, hip 0.95, waist 1.09, bust 1.26, shoulder 1.40, neck 1.41.
|
||||
|
||||
**The pari currently in the export folder is WRONG and must be redone** — delete
|
||||
`Female_Kapahaka_Body.*` and rebuild it with correct placement before moving on.
|
||||
|
||||
## Method
|
||||
|
||||
Work one garment at a time; get the pari (Body) fully through first, then the
|
||||
piupiu (Legs). Suggested sequence per garment:
|
||||
|
||||
1. `census` stage — see what islands/materials actually exist. Read the printed
|
||||
stats and `clothing/work/<name>/census.json`. Let the data drive the config.
|
||||
2. Write/adjust `clothing/configs/<name>.json` accordingly.
|
||||
3. Run `prepare` → `fit` → `reduce` → `skin` → `export`. Skip `bake` (it is
|
||||
optional, Cycles-slow, and these have no high-poly detail worth baking).
|
||||
4. After each stage, verify **numerically** (you cannot see the QA renders —
|
||||
their existence proves nothing). Print vert/tri counts and world-space
|
||||
bounds from the checkpoint .blend and check them against expectations. If a
|
||||
stage errors, read the traceback and adapt the config.
|
||||
|
||||
The pipeline is data-driven: **prefer fixing the config over editing
|
||||
`garment_pipeline.py`.** If you find a genuine bug or a missing capability in the
|
||||
pipeline, you may make a small, surgical, well-commented edit — but say so
|
||||
clearly in your DONE summary.
|
||||
|
||||
The skirt (`piupiu`, Legs slot) is the harder one: read the README's notes on
|
||||
skirt handling (`weights: dress` pelvis-gradient, cone proxy, why skirts are not
|
||||
decimated) and apply what fits. It is a straight A-line skirt, not pleated.
|
||||
|
||||
## Success criteria (all must hold)
|
||||
|
||||
1. `Female_Kapahaka_Body.gltf` and `Female_Kapahaka_Legs.gltf` exist in the
|
||||
export dir above (with their `.bin` companions).
|
||||
2. Each exported file contains a mesh skinned to a **65-bone** armature with
|
||||
Quaternius bone names (the pipeline prints verification info — capture it).
|
||||
3. Vert/tri counts are sane (roughly the input magnitudes, not zero, not
|
||||
millions).
|
||||
4. The QA renders show a garment that still looks like a garment (not shredded,
|
||||
not collapsed, not inside-out).
|
||||
|
||||
Verify claims with commands; do not assert success you have not checked.
|
||||
|
||||
## Rules
|
||||
|
||||
- **Do not** run git commit/push, do not install packages, do not touch `.env`.
|
||||
- **Do not** modify anything under `tools/tailor/` — those are approved source
|
||||
assets. Read them only.
|
||||
- Do not re-run Marvelous Designer; it is not scriptable from here and its UI is
|
||||
not available to you.
|
||||
- Work in small verifiable steps. One command per turn.
|
||||
- Blender runs are slow (a stage can take minutes). That is normal — run them
|
||||
with a single command and wait for the output.
|
||||
- If you get truly blocked, emit `DONE:` with a precise description of the
|
||||
blocker, what you tried, and what you recommend. A clear failure report is far
|
||||
more useful than silent thrashing.
|
||||
|
||||
## Report
|
||||
|
||||
When finished, emit `DONE:` with:
|
||||
- which files were produced and where,
|
||||
- the final config(s) you settled on and any notable parameter choices,
|
||||
- verification output proving the bone count / vert counts,
|
||||
- anything that looks wrong or needs a human eye,
|
||||
- any edit you made to `garment_pipeline.py`.
|
||||
Reference in New Issue
Block a user