docs/README.md

# Using Kimodo well — guidelines

Practical guidance for getting **dynamic, accurate, aesthetic** motion out of
NVIDIA's **Kimodo** text-to-motion model (the SMPL-X variant this Space uses),
and for chaining moves into cohesive katas.

These docs combine the official Kimodo tech report and the text-to-motion /
choreography literature with **our own controlled experiments** on this Space
(quantitative analysis of the generated joint arrays — June 2026).

## Contents

1. **[Kimodo overview](kimodo-overview.md)** — what the model is, how it was
   built, what it's good and bad at, the output format.
2. **[Prompting guide](prompting-guide.md)** — the prompt format the model
   expects, with rules and example prompts. *Start here.*
3. **[Choreographing katas](choreographing-katas.md)** — turning single moves
   into a cohesive, dynamic sequence (kata structure, dynamics, the chaining rule).
4. **[Generation settings](generation-settings.md)** — denoising steps, clip
   duration vs. playback speed, guidance — with the measured trade-offs.
5. **[Pose control & constraints](pose-control-and-constraints.md)** — what can
   *control* the output beyond text (poses, paths, the pose-snap / "preview-frame"
   mechanism), the verified limits, the skeleton-verification workflow, and the
   gotchas. *Read before building pose/stance features.*
6. **[Taikyoku Shodan reference](kata-taikyoku-reference.md)** — the first full
   kata broken down: ideal front/side stance figures, the 20-move sequence +
   embusen, and the stance/move build plan using the verified constraint patterns.
7. **[Stance-based kata workflow](stance-based-kata-workflow.md)** — the plan:
   stances = recorded poses, kata = sequence of stances, moves = in-between
   transitions (0-drift). Data model + how both creators change.

## TL;DR cheat sheet

- **Write prompts as `"A person <verb>s <side> <direction>, <quality>."`** —
  third person, present tense, ~10–12 words, one period. This matches Kimodo's
  training captions (which were *all* rewritten to start with "A person…").
- **Never use bare noun phrases or imperatives.** "roundhouse kick" or "throw a
  kick" are off-distribution; we measured "roundhouse kick" producing a foot that
  *never leaves the ground*. "A person throws a roundhouse kick with the right
  leg." produces a real kick.
- **One atomic move per clip.** Chain moves for sequences; don't pack a whole
  combo into one prompt.
- **Use ~60–100 denoising steps for crisp strikes.** At 20 steps punches are
  mushy; at 60 they're ~3× snappier (this Space now defaults to 60).
- **Generate at ~1.5–2.5s, not ~1s.** Sub-1.5s clips truncate kicks (the foot
  never lands). To make a kata *feel* fast, play it back at 1.5× rather than
  generating ultra-short clips (this Space defaults playback to 1.5×).
- **Vary the dynamics and build to a climax** — don't make every move the same
  intensity. End on a balanced, held pose.
- **Phrase moves as locomotion to beat stiffness.** "A person *steps forward and*
  throws a punch" engages the whole body (+96% measured articulation) vs. a
  planted "throws a punch"; it also unlocks `root2d` floor paths. Avoid "*into a
  deep stance*" — a stance cue re-plants the feet and kills the motion.
- **To put an exact pose in a clip, pin a LATE frame, not frame 0.** A fullbody
  constraint at the **last** frame (+ `post_processing`) ends a motion exactly in a
  chosen stance (0 cm); pinning **both** ends (in-betweening) makes a clean
  transition A→B with **0 m root drift**. `generate_continue` (frame-0 pin only)
  snaps the start but the **root drifts ~3.5 m** — avoid it for stance starts.
  Verify poses with the skeleton overlay, never a scalar average. See
  [pose control](pose-control-and-constraints.md).

## Sources

- Kimodo tech report — https://research.nvidia.com/labs/sil/projects/kimodo/assets/kimodo_tech_report.pdf
- Kimodo project page / docs — https://research.nvidia.com/labs/sil/projects/kimodo/
- Model card — https://huggingface.co/nvidia/Kimodo-SMPLX-RP-v1
- HumanML3D / text-to-motion prompting and choreography sources are cited inline in each doc.