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 — what the model is, how it was built, what it's good and bad at, the output format.
2. Prompting guide — the prompt format the model expects, with rules and example prompts. Start here.
3. Choreographing katas — turning single moves into a cohesive, dynamic sequence (kata structure, dynamics, the chaining rule).
4. Generation settings — denoising steps, clip duration vs. playback speed, guidance — with the measured trade-offs.
5. Pose control & constraints — 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 — 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 — 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.

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.