Model card: QtMesh T2M v9 rewrite — benchmark methodology, seed failure case, per-file licences, v8 docs moved to PREVIOUS_VERSIONS.md

.gitattributes

@@ -39,3 +39,4 @@ media/compare_jump.gif filter=lfs diff=lfs merge=lfs -text
 media/compare_run.gif filter=lfs diff=lfs merge=lfs -text
 media/compare_walk.gif filter=lfs diff=lfs merge=lfs -text
 media/compare_waveR.gif filter=lfs diff=lfs merge=lfs -text
+media/compare_jump_seeds.gif filter=lfs diff=lfs merge=lfs -text

LICENSES.md

@@ -0,0 +1,50 @@
+# Licences in this repository
+
+`fernandotonon/QtMeshEditor-t2m` holds files under several licences. That is why the model card metadata says
+`license: other` (`mixed-per-file`) instead of a single licence. This page lists every file.
+
+| Path | Licence | Notes |
+|---|---|---|
+| `qtmesh_t2m/t2m-text.onnx` | CC0-1.0, with CC-BY-4.0 credits | QtMesh T2M v9 weights, trained from scratch by the QtMeshEditor project. See [Model weights](#model-weights). |
+| `qtmesh_t2m/t2m-text.json` | CC0-1.0 | The model contract (shapes, embedding instruction, canonical rest pose). |
+| `qtmesh_t2m/Qwen3-Embedding-0.6B-Q8_0.gguf` | Apache-2.0 | Qwen3-Embedding-0.6B by the Qwen team, Alibaba Cloud. Byte-identical to [Qwen/Qwen3-Embedding-0.6B-GGUF](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B-GGUF). |
+| `qtmesh_t2m/LICENSE-Qwen3-Embedding.txt` | — | The Apache-2.0 text for the file above. The upstream repository declares Apache-2.0 on its card but ships no LICENSE file, so this copy carries an attribution header. |
+| `qtmesh_t2m/ATTRIBUTION.md` | — | The credits for the CC-BY-4.0 works behind `t2m-text.onnx`. **Keep it with the model.** |
+| `t2m.onnx`, `t2m-vocab.json` | CC0-1.0, with CC-BY-4.0 credits | The previous v8.0 action-label model. Its credits are in `ATTRIBUTION-v2.md` and `ATTRIBUTION.md`. |
+| `motion-library-v2.json` | Mixed: CC0-1.0 and CC-BY-4.0, per clip | The curated template clip library and the v8 training source. Credits are in `ATTRIBUTION-v2.md`; per-asset provenance is in [QtMeshEditor-motion-corpus](https://huggingface.co/datasets/fernandotonon/QtMeshEditor-motion-corpus). |
+| `motion-library.json` | Mixed: CC0-1.0 and CC-BY-4.0, per clip | The older v1 template library. Credits are in `ATTRIBUTION.md`. |
+| `ATTRIBUTION.md`, `ATTRIBUTION-v2.md` | — | The credits for the CC-BY-4.0 works. **Keep them with the data or anything derived from it.** |
+| `media/*.gif` | CC0-1.0 | Renders made by the QtMeshEditor project of the two models' outputs on a QtMeshEditor-generated character. |
+| `README.md`, `LICENSES.md`, `PREVIOUS_VERSIONS.md` | CC0-1.0 | Documentation. |
+
+## Model weights
+
+The QtMeshEditor project dedicates its own work in the model files to the public domain under
+[CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/), as this repository has declared since it was
+created. Part of the training data is licensed CC-BY-4.0, and the project treats the trained weights as
+derived from that data. The credits in `ATTRIBUTION.md` / `ATTRIBUTION-v2.md` therefore travel with the weights.
+If you redistribute the models, include those files.
+
+## Training data that is not in this repository
+
+**Clips generated with NVIDIA Kimodo.**
+
+- About 3,400 clips generated with `Kimodo-SOMA-RP-v1.2` were used as training data.
+- They are not redistributed here.
+- Kimodo's outputs are not "Derivative Models" under the
+  [NVIDIA Open Model License](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license/)
+  (§1.1), and NVIDIA claims no ownership of outputs (§2.4).
+- No Kimodo weights, code or Llama 3 text embeddings are in this repository or in the model.
+
+**The CC0 / CC-BY-4.0 motion corpus.**
+
+- It is published separately as
+  [fernandotonon/QtMeshEditor-motion-corpus](https://huggingface.co/datasets/fernandotonon/QtMeshEditor-motion-corpus),
+  with per-asset licences and credits.
+- Non-commercial sources (AMASS, HumanML3D, KIT-ML, LAFAN1) and Mixamo were excluded.
+
+## QtMeshEditor
+
+The editor that runs these models is MIT-licensed: [github.com/fernandotonon/QtMeshEditor](https://github.com/fernandotonon/QtMeshEditor).
+Its third-party model licences are documented in
+[`THIRD_PARTY_AI_MODELS.md`](https://github.com/fernandotonon/QtMeshEditor/blob/master/THIRD_PARTY_AI_MODELS.md).

PREVIOUS_VERSIONS.md

@@ -0,0 +1,155 @@
+# Previous versions
+
+
+This page keeps the documentation of the models that preceded **QtMesh T2M (v9)**, the current model described in
+the [main model card](README.md). The v8 files are still in this repository: QtMeshEditor uses `t2m.onnx` for its
+opt-in action-label path (`qtmesh anim <rig> --generate "<prompt>" --model`) and `motion-library-v2.json` as its
+template clip library.
+
+The text below is the v8.0 model card as published on 2026-08-29, unchanged except for the file list.
+
+---
+## v8.0 action-label model
+
+Generative text→skeletal-animation model shipped with
+[QtMeshEditor](https://github.com/fernandotonon/QtMeshEditor)
+(`qtmesh anim <rig> --generate "<prompt>" --model`).
+
+**v8.0** — flow-matching DiT, 21.7M params, 30 actions.
+
+## Files
+
+- `t2m.onnx` + `t2m-vocab.json` — the generative model + its vocab/contract.
+- Earlier checkpoints (v4 and later) — in the repository's
+  [commit history](https://huggingface.co/fernandotonon/QtMeshEditor-t2m/commits/main).
+- `motion-library-v2.json` — the curated **template clip library** (150 clips).
+  It is both the fallback for prompts outside the model vocab *and* — since
+  v8.0 — the model's training data. This is the exact library v8.0 trained on.
+- `ATTRIBUTION-v2.md` — **required credits** for the CC-BY clips in that
+  library. It must ship with the data and with anything derived from it.
+
+## Dataset
+
+The published library is the full v8.0 training source: 150 clips drawn from 31
+source assets — 27 CC-BY-4.0, plus CC0 material (largely Quaternius packs) and
+17 clips the author owns outright. Every CC-BY asset is credited in
+`ATTRIBUTION-v2.md`; no clip in the library lacks a credit where one is due.
+
+The raw source assets the library was built from — plus per-asset provenance
+and the build scripts — live in the companion dataset repo
+[**fernandotonon/QtMeshEditor-motion-corpus**](https://huggingface.co/datasets/fernandotonon/QtMeshEditor-motion-corpus),
+which also carries a copy of this library under `derived/`.
+
+To rebuild the training cache from it, see **Reproducing** below. The cache
+itself is not published — it is fully regenerable from this library, and it
+stamps its own `buildArgv`/`buildFlags` so any `.npz` can state how it was
+built.
+
+## What changed in v8.0
+
+Earlier versions trained on the **CMU MoCap** corpus and inherited a facing
+problem: generated walks moved convincingly but oriented backwards. Measuring
+against a real reference walk showed why — CMU "walk" windows sit 1.73–2.07 rad
+away from it, *further than a real punch, dance or jump*, and the real-vs-real
+floor is 0.437. The corpus never carried the correct convention, so the model
+could not learn it. v6.x models scored 1.89 while their own training data
+scored 1.73: they were faithfully reproducing bad data.
+
+v8.0 trains on the **curated template clips** instead (`--library-repeat 40`),
+which measure 0.303–0.462 against the real walk. Plus two data gates and one
+new loss:
+
+- **Anatomical ankle gate** — rejects clips whose mean knee→foot angle exceeds
+  70°. Caught `march` (106°), `throw` (101°) and `hey` (90°): the foot folded
+  perpendicular to the shin in *100%* of their windows.
+- **Minimum resolved roles (16/22)** — `hey` resolved only 9, with all four
+  knee/ankle roles invalid, so the model had no leg data and invented legs.
+- **Leg-chain loss** — keeps a walk's bend in the **knee** rather than the
+  ankle. The v7.x walk bent the knee 25° and the ankle 31° (real: 38°/10°),
+  which renders as a near-straight knee with a false second joint below it.
+
+### Measured against a real reference walk
+
+| | v7.x | **v8.0** | real |
+|---|---|---|---|
+| knee/ankle split | 25°/31° | **41°/8°** | 38°/10° |
+| leg-chain penalty | 0.359 | **0.0003** | 0.014 |
+| walk refDist | 0.287 | **0.243** | 0.437 (real-vs-real floor) |
+| run refDist | 0.472 | **0.324** | — |
+
+Scored against the training distribution across 20 actions, v8.0 is closer to
+ground truth on 8, further on 3, and tied on 9. Largest gains: `wave`
+0.710→0.082 (the arm now actually goes overhead), `idle`, `climb`, `salute`,
+`punch`, `sit`.
+
+## Vocabulary (30 actions)
+
+```
+attack boxing buildloop cartgiveloop climb cough crouch cut dance death
+fall farmloop hit idle jump kick pickup punch run salute shake shoot
+sit stonegiveloop strafeleft straferight walk wave woodgiveloop working
+```
+
+`march`, `throw`, `hey` and `confession` were **removed** — their source clips
+are anatomically broken (see the ankle gate above). Those prompts fall back to
+the curated template library, which for `march`/`throw` is strictly better than
+what the model produced. `march`/`marching` resolves to `walk`.
+
+Quality is uneven across actions: `walk`, `run`, `wave`, `cough`, `death`,
+`pickup` and `attack` are the strongest; `dance` and `idle` are weak (`dance`
+averages five genuinely different dances under one label; `idle` is nearly
+static). This is a **template-quality** ceiling, not an architecture one ��� more
+curated clips is the improvement path.
+
+## Training data — permissive only
+
+The curated library is CC0/CC-BY content (Sketchfab, OpenGameArt, Quaternius
+packs) plus clips the author owns; credits are in `ATTRIBUTION-v2.md`, **which
+must ship with the library and with anything derived from it**. Earlier CMU
+MoCap windows (commercial-OK) remain in the corpus path but no longer dominate
+training. AMASS / HumanML3D / KIT-ML are **excluded** (non-commercial).
+Zombie/fruit/non-humanoid characters are filtered out, as are clips failing the
+anatomical ankle gate or resolving fewer than 16 of the 22 canonical roles.
+
+## Architecture (v8.0)
+
+- **6D-rotation** representation (Zhou et al. 2019), column-packed.
+- **Flow-matching DiT**, dim 384 × 8 layers, ~21.7M params — the model predicts
+  a velocity field; the host runs a fixed Euler schedule baked into the graph.
+- Auxiliary losses: contralateral gait phase, spine-twist penalty, travel
+  direction, limb amplitude band, jitter band, gait periodicity, and the v8.0
+  leg-chain term — each gated to the action classes where it is meaningful.
+- Exports to ONNX as a single forward pass.
+
+## I/O contract
+
+```
+input  "tokens" float32 [1, V]     one-hot over the fixed action vocab (see t2m-vocab.json)
+input  "seed"   float32 [1, Z]     latent noise (host samples ~N(0,0.5) and does best-of-N)
+output "motion" float32 [1, T, C]  C = 22*10 per-joint [tx,ty,tz, qx,qy,qz,qw, sx,sy,sz]
+```
+
+`t2m-vocab.json` ships the `{vocab, Z, T, C, J, fps, frame, restDir}` the host
+needs. `frame: "world"` marks the WORLD-frame convention (the retarget takes a
+world delta); `fps: 30`, `T: 60` (2.0 s).
+
+## Reproducing
+
+`scripts/prep-t2m-v6.py` + `scripts/train-t2m-flow-v5.py` in the QtMeshEditor
+repo (one-time, offline dev tools — the app never runs Python):
+
+`--corpus` is optional and points at the raw CMU-derived corpus, which is NOT
+published here; with `--library-repeat 40` the curated library dominates
+training either way, so omitting it reproduces the same shape of dataset from
+the published files alone:
+
+```
+python3 scripts/prep-t2m-v6.py --library motion-library-v2.json \
+    --library-repeat 40 --min-roles 16 --out t2m.npz
+python3 scripts/train-t2m-flow-v5.py --data t2m.npz --out flow --dim 384 --layers 8 \
+    --phase-weight 0.08 --twist-weight 0.5 --travel-weight 0.2 --amp-weight 0.4 \
+    --jitter-weight 0.4 --period-weight 0.5 --legchain-weight 0.35 --loco-boost 6.0
+```
+
+The cache stamps its own `buildArgv`/`buildFlags`, so any `.npz` can report how
+it was built.

README.md

@@ -1,221 +1,373 @@
 ---
-license: cc0-1.0
+license: other
+license_name: mixed-per-file
+license_link: https://huggingface.co/fernandotonon/QtMeshEditor-t2m/blob/main/LICENSES.md
+language:
+  - en
+library_name: onnx
+datasets:
+  - fernandotonon/QtMeshEditor-motion-corpus
 tags:
   - text-to-motion
+  - motion-generation
   - animation
+  - 3d-animation
+  - character-animation
+  - skeletal-animation
+  - game-development
+  - flow-matching
   - onnx
   - gguf
+  - cpu-inference
   - qtmesheditor
 ---
 
-# QtMeshEditor — text-to-motion (t2m)
-
-Text→skeletal-animation models shipped with [QtMeshEditor](https://github.com/fernandotonon/QtMeshEditor).
-
-## QtMesh T2M (v9, text-conditioned) — experimental
-
-QtMeshEditor's own text-to-motion model, offered next to NVIDIA Kimodo in the editor (Animation panel →
-**Model: QtMesh T2M**, CLI `--backend qtmesh_t2m`, MCP `generate_motion {backend: "qtmesh_t2m"}`). Kimodo stays the
-default; QtMesh T2M is **much smaller and faster, intended for lower-end machines**.
-
-It conditions on a sentence embedding of the prompt (Qwen3-Embedding-0.6B), so wording, sides ("with the right
-hand"), styles and speeds reach the model — unlike the v8 action-label model below.
-
-### Kimodo vs QtMesh T2M
-
-Same generated character, same prompt, 3 s, in place, one sample each (seed in the caption).
-
-![walk](media/compare_walk.gif)
-![run](media/compare_run.gif)
-![wave with the right hand](media/compare_waveR.gif)
-![jump](media/compare_jump.gif)
-
-Jumps vary a lot with the seed: of ten seeds, four bend the knees 70–86° (the one shown), four barely move.
-
-### Memory and speed
-
-One 3 s clip on an Apple M-series Mac; the CLI run includes importing the rig and exporting the result.
-
-| | NVIDIA Kimodo (native) | QtMesh T2M |
+# QtMesh T2M — Lightweight Text-to-3D-Motion Generation
+
+QtMesh T2M turns a sentence such as *"a person waves with the right hand"* into a skeletal animation for a
+rigged 3D character. The [QtMeshEditor](https://github.com/fernandotonon/QtMeshEditor) project trained it from
+scratch. It is **not** a quantized or distilled copy of NVIDIA Kimodo.
+
+- **Two models, loaded separately.** The motion generator is a custom **22.6 M-parameter flow-matching
+  transformer**, run with ONNX Runtime. The prompt is read by **Qwen3-Embedding-0.6B** (0.6 B parameters, Q8_0
+  GGUF), run with llama.cpp.
+- **No Python at inference.** Inside QtMeshEditor everything runs natively in C++.
+- **Small enough for modest hardware.** It is about a 740 MB download and peaks at under 1 GB of memory.
+  It runs on the CPU: ONNX Runtime's CPU provider, and llama.cpp on Apple Silicon.
+- **Integrated with the editor.** QtMeshEditor maps the output onto your character's rig, can add root travel,
+  and exports the result as glTF/GLB or FBX.
+- **Experimental.** Its motion quality is clearly below [NVIDIA Kimodo](https://github.com/nv-tlabs/kimodo), which
+  stays QtMeshEditor's default. QtMesh T2M is the option for machines that cannot run Kimodo comfortably.
+
+## Contents
+
+- [Benchmark: QtMesh T2M vs NVIDIA Kimodo](#benchmark-qtmesh-t2m-vs-nvidia-kimodo)
+- [Visual results](#visual-results--qtmesh-t2m-vs-nvidia-kimodo)
+- [How it works](#how-it-works)
+- [Training](#training)
+- [Usage](#usage)
+- [Files and tensor contract](#files-and-tensor-contract)
+- [Limitations](#limitations)
+- [License and attribution](#license-and-attribution)
+- [Previous versions](#previous-versions)
+- [Links](#links)
+
+## Benchmark: QtMesh T2M vs NVIDIA Kimodo
+
+These are the QtMeshEditor project's own measurements, not an independent benchmark. Each run generated one
+3-second clip for the same character.
+
+| | **QtMesh T2M** | NVIDIA Kimodo (native runtime) |
 |---|---|---|
-| Download | ~9.2 GB | ~740 MB |
-| Text encoding | ~1.1 s + loading an 8 GB encoder | ~0.2–0.4 s |
-| Motion sampling | ~14 s | ~2.7 s |
-| Whole CLI run | 18–21 s | ~5 s |
-| Peak resident memory | 7.6–8.2 GB | ~0.87 GB |
-
-### Files (`qtmesh_t2m/`)
-
-- `t2m-text.onnx` (98 MB) — 22.6 M-parameter flow-matching transformer with AdaLN-Zero conditioning; the 24-step
-  Euler sampler with classifier-free guidance (2.0) is unrolled in the graph. Inputs `text[1,1024]` (L2-normalised
-  embedding), `seed[1,19800]` ~ N(0, 0.5), `length[1]` frames (≤ 150, 30 fps); output `motion[1,150,220]`: per
-  canonical role (22 joints) `t, quat x y z w, s`, world frame, rotation only.
-- `t2m-text.json` — contract: shapes, fps, the embedding instruction, canonical rest directions.
-- `Qwen3-Embedding-0.6B-Q8_0.gguf` — the text encoder (Apache-2.0, `LICENSE-Qwen3-Embedding.txt`), run through
-  llama.cpp: `"Instruct: Given a description of a human body motion, retrieve motions that match it\nQuery:" +
-  prompt`, last-token pooling, L2-normalised.
-- `ATTRIBUTION.md` — required credits for the CC-BY-4.0 motion the model was trained on.
-
-### Training
-
-- **Data:** 30,488 samples — 3,400 clips we generated with NVIDIA Kimodo (each also mirrored left↔right, with
-  "left"/"right" swapped in the text), plus the v8 windows (curated template library + CC0/CC-BY corpus) captioned
-  per action; 8,028 distinct texts including paraphrases. Kimodo outputs are not Derivative Models under the NVIDIA
-  Open Model License; Kimodo's Llama 3 text embeddings were never stored or trained on.
-- **Recipe:** `scripts/prep-t2m-text.py` + `scripts/train-t2m-text.py` in the QtMeshEditor repo; 200 epochs, batch
-  128, AdamW 2e-4 cosine, 10 % text dropout for CFG, padded to 150 frames with a length mask. The export pins the
-  never-supervised canonical buttock roles (14/18) to identity.
-- **Inference details in the editor:** long clips start from rest in the Kimodo data, so the editor generates up to
-  1 s extra and trims the still start; root travel is estimated from the planted foot; the clip is retargeted with
-  the same incompatible-skeleton retargeter as Kimodo.
-
-### Limitations
-
-One prompt per clip (no multi-segment timelines), up to 5 s, no root height (jumps stay on the spot), weaker on
-rare actions; quality varies with the seed — generate a few variations.
-
----
-
-## v8.0 action-label model (previous)
-
-Generative text→skeletal-animation model shipped with
-[QtMeshEditor](https://github.com/fernandotonon/QtMeshEditor)
-(`qtmesh anim <rig> --generate "<prompt>" --model`).
-
-**v8.0** — flow-matching DiT, 21.7M params, 30 actions.
-
-## Files
-
-- `t2m.onnx` + `t2m-vocab.json` — the generative model + its vocab/contract.
-- `t2m-v61.onnx` / `t2m-v4.onnx` — previous versions, kept for rollback.
-- `motion-library-v2.json` — the curated **template clip library** (150 clips).
-  It is both the fallback for prompts outside the model vocab *and* — since
-  v8.0 — the model's training data. This is the exact library v8.0 trained on.
-- `ATTRIBUTION-v2.md` — **required credits** for the CC-BY clips in that
-  library. It must ship with the data and with anything derived from it.
-
-## Dataset
+| Download | **~740 MB** | ~9.2 GB |
+| Text encoder | Qwen3-Embedding-0.6B (Q8_0) | Llama-3-LLM2Vec-8B (Q8_0) |
+| Text encoding | **~0.2–0.4 s** | ~1.1 s, plus loading the 8 B encoder |
+| Motion sampling | **~2.7 s** (24 flow steps) | ~14 s (100 diffusion steps) |
+| Whole CLI run (import, generate, export) | **~5 s** | ~18–21 s |
+| Peak resident memory | **~0.87 GB** | ~7.6–8.2 GB |
+
+**How it was measured**
+
+- **Hardware:** Apple M5, 24 GB unified memory, macOS.
+- **Runtime:** QtMeshEditor 3.60 with ONNX Runtime 1.31.1 on the CPU execution provider. Both text encoders run as
+  Q8_0 GGUFs through the bundled llama.cpp. Kimodo used QtMeshEditor's native (Python-free) port of
+  `Kimodo-SOMA-RP-v1.2`, with its post-processing on.
+- **Method:**
+  - The command was `qtmesh anim char.fbx --generate "<prompt>" --backend <kimodo|qtmesh_t2m> --duration 3 --seed 1 --json -o out.fbx`.
+  - Each backend ran once per prompt, for four prompts: walk, run, wave with the right hand, jump.
+  - Wall time and maximum resident set size come from `/usr/bin/time -l`.
+  - The text-encoding and sampling times are the ones the CLI reports in `--json`.
+  - The "whole CLI run" covers process start, importing the character, generating, retargeting and exporting the
+    FBX.
+  - The models were already downloaded.
+- **Not controlled or not recorded:**
+  - File-cache warmth.
+  - Background load.
+  - Repeated trials. Each figure is one run per prompt; the ranges span the four prompts.
+- **Root motion differed:** Kimodo ran with `--no-root-motion`, while QtMesh T2M used its default foot-driven root
+  motion.
+
+Smaller and faster does **not** mean equivalent. Kimodo's motions are clearly more detailed and reliable; compare
+the clips below.
+
+## Visual results — QtMesh T2M vs NVIDIA Kimodo
+
+The same generated character and prompt are used on both sides. Each clip is 3 seconds, rendered in place
+(root motion off), with one sample per model. **Left: NVIDIA Kimodo. Right: QtMesh T2M.** The caption in each GIF
+gives the seed.
+
+| Prompt | Seeds (Kimodo / QtMesh T2M) | Comparison | What to look for |
+|---|---|---|---|
+| "a person walks forward" | 1 / 1 | ![walk](media/compare_walk.gif) | Both read as a walk cycle. QtMesh T2M's arms swing less. |
+| "a person runs forward" | 1 / 1 | ![run](media/compare_run.gif) | Both read as a run. Kimodo keeps the elbows bent in a running position; QtMesh T2M's arms hang straighter. |
+| "a person waves with the right hand" | 1 / 1 | ![wave with the right hand](media/compare_waveR.gif) | Both raise the character's **right** hand, the side named in the prompt; the text embedding carries left/right. QtMesh T2M waves with a large overhead arm, Kimodo with a smaller wave near the head. |
+| "a person jumps" | 1 / **2** | ![jump](media/compare_jump.gif) | **Cherry-picked:** the QtMesh T2M clip uses seed 2, not seed 1. See the failure case below. |
 
-The published library is the full v8.0 training source: 150 clips drawn from 31
-source assets — 27 CC-BY-4.0, plus CC0 material (largely Quaternius packs) and
-17 clips the author owns outright. Every CC-BY asset is credited in
-`ATTRIBUTION-v2.md`; no clip in the library lacks a credit where one is due.
+### Failure case: seed sensitivity
 
-The raw source assets the library was built from — plus per-asset provenance
-and the build scripts — live in the companion dataset repo
-[**fernandotonon/QtMeshEditor-motion-corpus**](https://huggingface.co/datasets/fernandotonon/QtMeshEditor-motion-corpus),
-which also carries a copy of this library under `derived/`.
+The two clips below come from the same model and prompt with different seeds. The left one is what you get with
+seed 1, the seed used for the other comparisons.
 
-To rebuild the training cache from it, see **Reproducing** below. The cache
-itself is not published — it is fully regenerable from this library, and it
-stamps its own `buildArgv`/`buildFlags` so any `.npz` can state how it was
-built.
+![QtMesh T2M jump, seed 1 vs seed 2](media/compare_jump_seeds.gif)
 
-## What changed in v8.0
+Across ten seeds of "a person jumps", four bent the knees 70–86° into a clear jump, and four barely moved. The
+showcased clips are therefore not a statistically representative sample. Treat them as examples of what the
+model *can* produce. In practice, generate a few variations and keep the best one.
 
-Earlier versions trained on the **CMU MoCap** corpus and inherited a facing
-problem: generated walks moved convincingly but oriented backwards. Measuring
-against a real reference walk showed why — CMU "walk" windows sit 1.73–2.07 rad
-away from it, *further than a real punch, dance or jump*, and the real-vs-real
-floor is 0.437. The corpus never carried the correct convention, so the model
-could not learn it. v6.x models scored 1.89 while their own training data
-scored 1.73: they were faithfully reproducing bad data.
+## How it works
 
-v8.0 trains on the **curated template clips** instead (`--library-repeat 40`),
-which measure 0.303–0.462 against the real walk. Plus two data gates and one
-new loss:
+```
+Text prompt
+  → Qwen3-Embedding-0.6B (llama.cpp)       1024-d, L2-normalised sentence embedding
+  → Flow-matching transformer (ONNX)        22.6 M params, 24 Euler steps, classifier-free guidance
+  → Canonical 22-joint motion               joint rotations, 30 fps, up to 150 frames (5 s)
+  → QtMeshEditor retargeting                mapped onto your character's skeleton
+  → glTF/GLB or FBX animation
+```
 
-- **Anatomical ankle gate** — rejects clips whose mean knee→foot angle exceeds
-  70°. Caught `march` (106°), `throw` (101°) and `hey` (90°): the foot folded
-  perpendicular to the shin in *100%* of their windows.
-- **Minimum resolved roles (16/22)** — `hey` resolved only 9, with all four
-  knee/ankle roles invalid, so the model had no leg data and invented legs.
-- **Leg-chain loss** — keeps a walk's bend in the **knee** rather than the
-  ankle. The v7.x walk bent the knee 25° and the ankle 31° (real: 38°/10°),
-  which renders as a near-straight knee with a false second joint below it.
+- **Text conditioning.**
+  - The prompt is prefixed with a fixed instruction:
+    `Instruct: Given a description of a human body motion, retrieve motions that match it\nQuery:`.
+  - Qwen3-Embedding then encodes it with last-token pooling, and the vector is L2-normalised.
+  - Because the model sees a sentence embedding rather than an action label, wording, body side ("with the right
+    hand"), speed and style all reach it.
+- **Motion model.**
+  - A transformer of width 384 and 8 layers, conditioned on the text and the flow time through **AdaLN-Zero**.
+  - It is trained with **rectified flow (flow matching)**: it learns a velocity field that carries random noise to
+    a motion.
+  - The ONNX graph contains the whole sampler, unrolled: **24 Euler steps with classifier-free guidance
+    (scale 2.0)**.
+  - The model generates **rotations for 22 canonical joints** (pelvis, spine, neck, head, arms and legs), in the
+    world frame, at 30 fps.
+  - Clips are up to 150 frames (5 s). The length is an input, and frames past it are padding.
+- **What the model does not generate.**
+  - It produces no root translation and no vertical root displacement. A jump therefore stays on the spot.
+  - When **Root motion** is on, QtMeshEditor *estimates* horizontal travel from the planted foot. Measured: walk
+    ~1.4 m/s, run ~1.9 m/s. The character never rises.
+- **Editor post-processing.**
+  - Long clips in the training data start from rest, so the editor generates up to 1 s of extra motion and trims a
+    still start.
+  - The canonical motion is then retargeted onto the character with QtMeshEditor's incompatible-skeleton retargeter,
+    the same one used for Kimodo output. Humanoid rigs are mapped automatically from their bone names (for
+    example Mixamo-style rigs and the characters QtMeshEditor generates).
+
+## Training
+
+The training is best described as **synthetic-data-assisted**: part of the motion data was generated by a stronger
+teacher model (Kimodo). It is not formal knowledge distillation. QtMesh T2M never sees Kimodo's weights, logits or
+text features; it only sees the finished clips.
+
+- **Data:** 30,488 training samples and 8,028 distinct text descriptions, including paraphrases. These figures were
+  checked against the training cache. The samples come from:
+  - **3,400 clips generated with NVIDIA Kimodo** from 3,470 prompts. The prompts were written with
+    `make-kimodo-t2m-prompts.py`, combining gaits, directions, styles, gestures, combat, sports, dance, reactions and
+    body-side variants.
+  - Every clip was **mirrored** left↔right, with "left" and "right" swapped in its text. That gives 6,800 samples.
+  - **23,688 windows** from QtMeshEditor's earlier v8 data, captioned per action: the curated template clip
+    library (`motion-library-v2.json`) and the **CC0 / CC-BY-4.0** [motion corpus](https://huggingface.co/datasets/fernandotonon/QtMeshEditor-motion-corpus).
+  - Every text gets paraphrases: the person word varies ("a person" / "someone" / "the character" / none), and
+    the action words are kept.
+- **Quality control.**
+  - Kimodo clips pass automatic gates (`check-kimodo-t2m-corpus.py`): finite values, foot sliding during contact,
+    feet below the floor, implausible hip height, and joint-acceleration spikes. 3,400 of the 3,470 generated clips
+    passed.
+  - Samples that resolve fewer than 16 of the 22 joints are dropped.
+  - The v8 data had already been filtered with an anatomical ankle gate and a minimum-joints gate, and non-humanoid
+    characters were excluded.
+- **Text features.**
+  - The Qwen3 embeddings were computed separately for this model with `embed-t2m-text.py`, through the same
+    llama.cpp build the editor uses. On the reference prompts, the app's embeddings match the training ones with
+    cosine 1.000000.
+  - **Kimodo's Llama 3 text embeddings were never stored or used as training inputs.**
+- **Recipe** (`train-t2m-text.py`):
+  - 200 epochs of 20,000 samples each, batch 128.
+  - AdamW at 2e-4 (weight decay 1e-4) with a cosine schedule.
+  - 70% of each batch is drawn from the Kimodo clips, balanced per base prompt.
+  - 10% of the texts are dropped (zero vector) to train classifier-free guidance.
+  - Clips are padded to 150 frames with a length mask.
+  - The final flow-matching loss is 0.0478, and the ONNX export matches PyTorch to 2.4e-6.
+  - The export pins two canonical joints the data never supervises (the left and right buttock roles) to identity.
+- **Scripts** (offline development tools; the editor never runs Python):
+  - [`make-kimodo-t2m-prompts.py`](https://github.com/fernandotonon/QtMeshEditor/blob/master/scripts/make-kimodo-t2m-prompts.py)
+    writes the prompt list.
+  - [`build-kimodo-t2m-corpus.py`](https://github.com/fernandotonon/QtMeshEditor/blob/master/scripts/build-kimodo-t2m-corpus.py)
+    generates the Kimodo clips.
+  - [`check-kimodo-t2m-corpus.py`](https://github.com/fernandotonon/QtMeshEditor/blob/master/scripts/check-kimodo-t2m-corpus.py)
+    applies the quality gates.
+  - [`prep-t2m-text.py`](https://github.com/fernandotonon/QtMeshEditor/blob/master/scripts/prep-t2m-text.py)
+    builds the training cache: mirroring, paraphrases, embeddings.
+  - [`embed-t2m-text.py`](https://github.com/fernandotonon/QtMeshEditor/blob/master/scripts/embed-t2m-text.py)
+    computes the Qwen3 embeddings.
+  - [`train-t2m-text.py`](https://github.com/fernandotonon/QtMeshEditor/blob/master/scripts/train-t2m-text.py)
+    trains the model and exports the ONNX graph (`--export-only` re-exports from a checkpoint).
+
+The Kimodo-generated training clips and the training cache are not published.
+
+## Usage
+
+### Recommended: the QtMeshEditor GUI
+
+1. **Install QtMeshEditor.**
+
+   | Platform | Command |
+   |---|---|
+   | Windows | `winget install FernandoTonon.QtMeshEditor` |
+   | macOS | `brew tap fernandotonon/qtmesheditor && brew trust fernandotonon/qtmesheditor && brew install qtmesheditor` |
+   | Linux | `sudo snap install qtmesheditor` |
+
+   Installers are also on the [GitHub releases page](https://github.com/fernandotonon/QtMeshEditor/releases).
+   QtMesh T2M needs version **3.60.0** or later.
+2. **Import a rigged humanoid character** (FBX, glTF/GLB and other formats). You can also make one with the
+   built-in character generator.
+3. **Switch to Animation mode** and find **Generate from text** in the Inspector's Animations section.
+4. **Pick a model:** set **Model** to **QtMesh T2M (experimental, small)**.
+5. **Download the model:** press **Download QtMesh T2M**. This happens once, about 740 MB. Nothing downloads
+   until you ask.
+6. **Write a prompt**, for example *"a person waves with the right hand"*. Set the duration (up to 5 s) and the
+   number of variations. Optionally turn on **Root motion** or set a **Fixed seed**.
+7. **Generate.** The clips appear as `generated_qtmesh_t2m`, `generated_qtmesh_t2m_v2`, … All variations are added
+   in one undo step. Preview them on the timeline.
+8. **Export** the character with its animations (for example to `.glb` or `.fbx`).
+
+### Advanced: the command line
+
+```bash
+qtmesh anim rigged.glb \
+  --generate "a person waves with the right hand" \
+  --backend qtmesh_t2m \
+  --duration 3 \
+  --download \
+  -o animated.glb
+```
 
-### Measured against a real reference walk
+`--download` fetches the model files the first time. Other options:
 
-| | v7.x | **v8.0** | real |
-|---|---|---|---|
-| knee/ankle split | 25°/31° | **41°/8°** | 38°/10° |
-| leg-chain penalty | 0.359 | **0.0003** | 0.014 |
-| walk refDist | 0.287 | **0.243** | 0.437 (real-vs-real floor) |
-| run refDist | 0.472 | **0.324** | — |
+| Option | What it does |
+|---|---|
+| `--variations N` | Generates N clips, 1–16. |
+| `--seed N` | Makes the result reproducible. |
+| `--no-root-motion` | Keeps the clip in place. |
+| `--name NAME` | Names the clip. |
+| `--json` | Prints a machine-readable report, including the timings. |
 
-Scored against the training distribution across 20 actions, v8.0 is closer to
-ground truth on 8, further on 3, and tied on 9. Largest gains: `wave`
-0.710→0.082 (the arm now actually goes overhead), `idle`, `climb`, `salute`,
-`punch`, `sit`.
+### MCP (AI agents)
 
-## Vocabulary (30 actions)
+QtMeshEditor's MCP server exposes the same thing through the `generate_motion` tool:
 
-```
-attack boxing buildloop cartgiveloop climb cough crouch cut dance death
-fall farmloop hit idle jump kick pickup punch run salute shake shoot
-sit stonegiveloop strafeleft straferight walk wave woodgiveloop working
+```json
+{"backend": "qtmesh_t2m", "prompt": "a person jumps", "duration": 3, "variations": 2, "seed": 2, "download": true}
 ```
 
-`march`, `throw`, `hey` and `confession` were **removed** — their source clips
-are anatomically broken (see the ankle gate above). Those prompts fall back to
-the curated template library, which for `march`/`throw` is strictly better than
-what the model produced. `march`/`marching` resolves to `walk`.
+### Using the files directly
 
-Quality is uneven across actions: `walk`, `run`, `wave`, `cough`, `death`,
-`pickup` and `attack` are the strongest; `dance` and `idle` are weak (`dance`
-averages five genuinely different dances under one label; `idle` is nearly
-static). This is a **template-quality** ceiling, not an architecture one — more
-curated clips is the improvement path.
+You can run the ONNX model in your own pipeline with ONNX Runtime and any llama.cpp build that supports Qwen3
+embeddings. See [Files and tensor contract](#files-and-tensor-contract). You then need your own retargeting from
+the 22-joint canonical skeleton, which is described in `t2m-text.json`.
 
-## Training data — permissive only
+> **About the GGUF file.** `Qwen3-Embedding-0.6B-Q8_0.gguf` is a **text-embedding model**. It is **not** a chat
+> model and **not** the animation generator. Hugging Face may show "Use this model with llama.cpp / Ollama"
+> buttons because of it. Those apply only to the embedding model, not to the text-to-motion pipeline, and chatting
+> with it will not produce anything useful.
 
-The curated library is CC0/CC-BY content (Sketchfab, OpenGameArt, Quaternius
-packs) plus clips the author owns; credits are in `ATTRIBUTION-v2.md`, **which
-must ship with the library and with anything derived from it**. Earlier CMU
-MoCap windows (commercial-OK) remain in the corpus path but no longer dominate
-training. AMASS / HumanML3D / KIT-ML are **excluded** (non-commercial).
-Zombie/fruit/non-humanoid characters are filtered out, as are clips failing the
-anatomical ankle gate or resolving fewer than 16 of the 22 canonical roles.
+## Files and tensor contract
 
-## Architecture (v8.0)
+The current model lives in [`qtmesh_t2m/`](qtmesh_t2m):
 
-- **6D-rotation** representation (Zhou et al. 2019), column-packed.
-- **Flow-matching DiT**, dim 384 × 8 layers, ~21.7M params — the model predicts
-  a velocity field; the host runs a fixed Euler schedule baked into the graph.
-- Auxiliary losses: contralateral gait phase, spine-twist penalty, travel
-  direction, limb amplitude band, jitter band, gait periodicity, and the v8.0
-  leg-chain term — each gated to the action classes where it is meaningful.
-- Exports to ONNX as a single forward pass.
-
-## I/O contract
-
-```
-input  "tokens" float32 [1, V]     one-hot over the fixed action vocab (see t2m-vocab.json)
-input  "seed"   float32 [1, Z]     latent noise (host samples ~N(0,0.5) and does best-of-N)
-output "motion" float32 [1, T, C]  C = 22*10 per-joint [tx,ty,tz, qx,qy,qz,qw, sx,sy,sz]
-```
-
-`t2m-vocab.json` ships the `{vocab, Z, T, C, J, fps, frame, restDir}` the host
-needs. `frame: "world"` marks the WORLD-frame convention (the retarget takes a
-world delta); `fps: 30`, `T: 60` (2.0 s).
+| File | Size | What it is |
+|---|---|---|
+| `t2m-text.onnx` | 98 MB | The motion model (22.6 M parameters), with the 24-step Euler + CFG sampler unrolled in the graph. |
+| `t2m-text.json` | small | The contract: shapes, fps, the embedding instruction and pooling, canonical rest directions. |
+| `Qwen3-Embedding-0.6B-Q8_0.gguf` | ~640 MB | The text encoder. It is byte-identical to Qwen's official [Q8_0 GGUF](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B-GGUF) (SHA-256 `06507c7b…e439`). |
+| `LICENSE-Qwen3-Embedding.txt` | | The Apache-2.0 licence for the encoder. |
+| `ATTRIBUTION.md` | | The required credits for the CC-BY-4.0 motion data the model was trained on. |
 
-## Reproducing
+**`t2m-text.onnx` I/O** (checked against the graph):
 
-`scripts/prep-t2m-v6.py` + `scripts/train-t2m-flow-v5.py` in the QtMeshEditor
-repo (one-time, offline dev tools — the app never runs Python):
+| Tensor | Shape / type | Meaning |
+|---|---|---|
+| input `text` | `float32 [1, 1024]` | The L2-normalised Qwen3 embedding of `instruct + prompt`. A zero vector means unconditional. |
+| input `seed` | `float32 [1, 19800]` | Starting noise, sampled from N(0, 0.5). 19800 = 150 frames × 132. |
+| input `length` | `float32 [1]` | The number of frames wanted, up to 150. |
+| output `motion` | `float32 [1, 150, 220]` | Per frame, 22 joints × 10 values `[tx, ty, tz, qx, qy, qz, qw, sx, sy, sz]`: world-frame rotation quaternions, with t = 0 and s = 1. Frames from `length` onward are padding. |
 
-`--corpus` is optional and points at the raw CMU-derived corpus, which is NOT
-published here; with `--library-repeat 40` the curated library dominates
-training either way, so omitting it reproduces the same shape of dataset from
-the published files alone:
+From `t2m-text.json`:
 
-```
-python3 scripts/prep-t2m-v6.py --library motion-library-v2.json \
-    --library-repeat 40 --min-roles 16 --out t2m.npz
-python3 scripts/train-t2m-flow-v5.py --data t2m.npz --out flow --dim 384 --layers 8 \
-    --phase-weight 0.08 --twist-weight 0.5 --travel-weight 0.2 --amp-weight 0.4 \
-    --jitter-weight 0.4 --period-weight 0.5 --legchain-weight 0.35 --loco-boost 6.0
+```text
+version v9-text   T 150   J 22   C 220   Z 19800   fps 30   frame world
+flowSteps 24   guidance 2.0   embedDim 1024   pooling last
 ```
 
-The cache stamps its own `buildArgv`/`buildFlags`, so any `.npz` can report how
-it was built.
+The joint order and the canonical rest pose (`restWorld`, `restDir`) are listed in the JSON.
+
+## Limitations
+
+- **Lower motion fidelity than Kimodo.** Motions are simpler, less expressive and less physically convincing.
+- **Occasionally wrong or too subtle.** Some prompts give a weak or only partly correct motion.
+- **Sensitive to the seed.** Quality varies a lot between seeds (see the jump example), so generate several
+  variations and pick the best one.
+- **One action prompt per clip.** There are no multi-segment timelines; QtMeshEditor rejects a multi-line prompt
+  for this model. Kimodo supports timelines.
+- **At most 5 seconds** per clip (150 frames at 30 fps).
+- **No root height or root translation.** Jumps stay on the ground plane. Horizontal travel is only an estimate
+  made by the editor.
+- **Weaker on uncommon movements.** Actions that are rare in the training data come out worse.
+- **Body only.** There are no fingers, face or props; the model drives 22 body joints. In QtMeshEditor, Kimodo
+  drives the fingers.
+- **English prompts.** The training text was English only.
+- **Experimental** and under active development. Expect the model to change.
+
+## License and attribution
+
+This repository contains files under **different licences**, so its metadata says `license: other` (mixed, per
+file) instead of claiming a single licence. The full per-file breakdown is in [`LICENSES.md`](LICENSES.md).
+In short:
+
+| Files | Licence |
+|---|---|
+| QtMesh T2M weights and contracts (`qtmesh_t2m/t2m-text.onnx`, `t2m-text.json`), the v8 model (`t2m.onnx`, `t2m-vocab.json`), the GIFs in `media/` | **CC0-1.0**, released by the QtMeshEditor project. The models were trained on CC-BY-4.0 data, so please keep the attribution files with them. |
+| `qtmesh_t2m/Qwen3-Embedding-0.6B-Q8_0.gguf` | **Apache-2.0**, © Qwen team, Alibaba Cloud ([`LICENSE-Qwen3-Embedding.txt`](qtmesh_t2m/LICENSE-Qwen3-Embedding.txt)). |
+| `motion-library.json`, `motion-library-v2.json` | **Mixed CC0-1.0 and CC-BY-4.0**, per clip. Credits are in [`ATTRIBUTION-v2.md`](ATTRIBUTION-v2.md) and [`ATTRIBUTION.md`](ATTRIBUTION.md). |
+| `ATTRIBUTION.md`, `ATTRIBUTION-v2.md`, `qtmesh_t2m/ATTRIBUTION.md` | The credits for the CC-BY-4.0 works. **Ship them with the models or the data.** |
+
+**About the Kimodo-generated training clips:**
+
+- Kimodo's outputs are not "Derivative Models" under the
+  [NVIDIA Open Model License](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license/)
+  (§1.1), and NVIDIA claims no ownership of outputs (§2.4).
+- The QtMeshEditor project therefore used Kimodo outputs as training data.
+- No Kimodo weights, code, generated clips or Llama 3 embeddings are distributed in this repository. Kimodo itself
+  is a separate download inside QtMeshEditor, under its own licences.
+
+QtMeshEditor itself is MIT-licensed.
+
+## Previous versions
+
+QtMesh T2M (v9, in `qtmesh_t2m/`) is the **current** model. The files at the repository root belong to earlier
+releases and are kept for compatibility and reproducibility:
+
+- `t2m.onnx` + `t2m-vocab.json` is the **v8.0 action-label model**: a 21.7 M-parameter flow-matching transformer
+  conditioned on one of 30 action words. It is QtMeshEditor's opt-in `--model` path.
+- `motion-library-v2.json` (150 clips) is the curated template clip library. It is also the v8 training source.
+- `motion-library.json` is the older v1 template library.
+
+The full v8 model card (dataset, measurements, architecture, I/O contract, reproduction) is in
+[`PREVIOUS_VERSIONS.md`](PREVIOUS_VERSIONS.md). Earlier checkpoints remain in this repository's
+[commit history](https://huggingface.co/fernandotonon/QtMeshEditor-t2m/commits/main).
+
+## Links
+
+- **QtMeshEditor:** [GitHub](https://github.com/fernandotonon/QtMeshEditor).
+- **Documentation:**
+  - [Kimodo and QtMesh T2M user guide](https://github.com/fernandotonon/QtMeshEditor/blob/master/docs/KIMODO.md).
+  - [Third-party model licences](https://github.com/fernandotonon/QtMeshEditor/blob/master/THIRD_PARTY_AI_MODELS.md).
+- **Inference code:** [`QtMeshT2M.cpp`](https://github.com/fernandotonon/QtMeshEditor/blob/master/src/AIMotion/QtMeshT2M.cpp)
+  and [`MotionSceneApply.cpp`](https://github.com/fernandotonon/QtMeshEditor/blob/master/src/AIMotion/MotionSceneApply.cpp)
+  (retargeting and root motion).
+- **Training and export scripts:** see [Training](#training).
+- **Model files:** this repository, plus the
+  [QtMeshEditor-models](https://huggingface.co/fernandotonon/QtMeshEditor-models/tree/main/qtmesh_t2m) mirror that
+  the app downloads from (pinned commit and SHA-256 digests).
+- **Training motion corpus:** [fernandotonon/QtMeshEditor-motion-corpus](https://huggingface.co/datasets/fernandotonon/QtMeshEditor-motion-corpus).
+- **NVIDIA Kimodo:** [github.com/nv-tlabs/kimodo](https://github.com/nv-tlabs/kimodo).
+- **Qwen3-Embedding-0.6B:** [Qwen/Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B)
+  ([GGUF](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B-GGUF)).