# Project Structure

```text
kimodo/
├── kimodo/                       # Main Python package
│   ├── model/                    # Model architecture and loading
│   │   ├── kimodo_model.py       # Kimodo diffusion model wrapper
│   │   ├── twostage_denoiser.py  # Two-stage denoising architecture
│   │   ├── backbone.py           # Transformer encoder backbone
│   │   ├── diffusion.py          # Diffusion process
│   │   ├── cfg.py                # Classifier-free guidance
│   │   ├── common.py             # Shared model utilities
│   │   ├── load_model.py         # Model loading and registry lookup
│   │   ├── loading.py            # Checkpoint loading utilities
│   │   ├── registry.py           # Model registry (skeleton, checkpoint URLs)
│   │   ├── text_encoder_api.py   # Text encoder API client
│   │   ├── tmr.py                # TMR compatibility
│   │   └── llm2vec/              # LLM-based text encoder
│   ├── motion_rep/               # Motion representation
│   │   ├── reps/                 # Skeleton-specific motion reps
│   │   │   ├── base.py           # Base motion rep types
│   │   │   ├── kimodo_motionrep.py
│   │   │   └── tmr_motionrep.py
│   │   ├── conditioning.py       # Conditioning (text, constraints)
│   │   ├── feature_utils.py      # Feature extraction
│   │   ├── feet.py               # Foot contact / smoothing
│   │   ├── smooth_root.py        # Smooth root representation
│   │   └── stats.py              # Normalization statistics
│   ├── skeleton/                 # Skeleton definitions and kinematics
│   │   ├── definitions.py        # Skeleton topology (joints, chains)
│   │   ├── registry.py           # Skeleton registry
│   │   ├── base.py               # Base skeleton types
│   │   ├── kinematics.py         # Forward kinematics
│   │   ├── transforms.py         # Rotation/transform utilities
│   │   └── bvh.py                # BVH I/O
│   ├── viz/                      # Visualization
│   │   ├── scene.py              # 3D scene setup
│   │   ├── playback.py           # Timeline / motion playback
│   │   ├── viser_utils.py        # Viser 3D helpers
│   │   ├── gui.py                # Demo GUI components
│   │   ├── constraint_ui.py      # Constraint editing UI
│   │   ├── coords.py             # Coordinate frames
│   │   ├── soma_skin.py          # SOMA character skinning
│   │   ├── soma_layer_skin.py    # SOMA layer-based skinning
│   │   ├── smplx_skin.py         # SMPL-X skinning
│   │   └── g1_rig.py             # G1 robot rig
│   ├── demo/                     # Interactive web demo
│   │   ├── app.py                # Demo entry (Gradio / Viser)
│   │   ├── config.py             # Demo configuration
│   │   ├── state.py              # Application state
│   │   ├── ui.py                 # UI layout and callbacks
│   │   ├── generation.py         # Generation pipeline for demo
│   │   ├── embedding_cache.py    # Cached text embeddings
│   │   ├── queue_manager.py      # Request queue for demo
│   │   └── __main__.py           # Demo run as module
│   ├── exports/                  # Motion I/O and format conversion
│   │   ├── motion_io.py          # Kimodo motion dict helpers (load, save, resample)
│   │   ├── motion_convert_lib.py # Library API for format conversion
│   │   ├── motion_formats.py     # Format detection and FPS resolution
│   │   ├── bvh.py                # SOMA BVH read/write
│   │   ├── mujoco.py             # G1 MuJoCo qpos conversion
│   │   └── smplx.py              # AMASS / SMPL-X conversion
│   ├── metrics/                  # Evaluation metrics
│   │   ├── base.py               # Metric base classes
│   │   ├── foot_skate.py         # Foot skate metrics
│   │   ├── constraints.py        # Constraint metrics
│   │   └── tmr.py                # TMR-based metrics
│   ├── scripts/                  # CLI and helper scripts
│   │   ├── generate.py           # CLI for motion synthesis (kimodo_gen)
│   │   ├── motion_convert.py     # CLI for format conversion (kimodo_convert)
│   │   ├── run_text_encoder_server.py  # Text encoder server (kimodo_textencoder)
│   │   ├── gradio_theme.py       # Gradio theme for demo
│   │   ├── lock_requirements.py  # Dependency locking
│   │   └── mujoco_load.py        # MuJoCo g1 csv loading
│   ├── assets/                   # Package data (shipped with package)
│   │   ├── demo/                 # Demo examples and config
│   │   └── skeletons/            # Skeleton assets
│   ├── constraints.py            # Constraint definitions and handling
│   ├── geometry.py               # Geometric utilities
│   ├── postprocess.py            # Post-processing (e.g. MotionCorrection)
│   ├── meta.py                   # Motion metadata
│   ├── sanitize.py               # Input sanitization
│   ├── assets.py                 # Asset path resolution
│   └── tools.py                  # General utilities
├── benchmark/                    # Evaluation pipeline scripts
│   ├── create_benchmark.py       # Step 1: Build test suite from SEED + metadata
│   ├── generate_eval.py          # Step 2: Generate motions for test suite
│   ├── embed_folder.py           # Step 3: Embed motions and text with TMR
│   ├── evaluate_folder.py        # Step 4: Compute metrics for test cases
│   └── parse_folder.py           # Step 5: Aggregate and display results
├── MotionCorrection/             # Optional C++/Python post-processing
│   ├── python/motion_correction/ # Python bindings
│   └── src/cpp/                  # C++ implementation
├── docs/                         # Documentation (Sphinx)
│   └── source/                   # RST/MD sources
├── assets/                       # Repo-level assets (banner, screenshots)
├── pyproject.toml                # Package config and entry points
├── setup.py                      # Setuptools entry (if needed)
├── Dockerfile                    # Container image for demo
├── docker-compose.yaml           # Docker Compose for demo + text encoder
└── README.md
```

Entry points (from `pyproject.toml`):

- **`kimodo_gen`** — command-line motion synthesis (`kimodo.scripts.generate:main`)
- **`kimodo_demo`** — interactive web demo (`kimodo.demo:main`)
- **`kimodo_convert`** — motion format conversion (`kimodo.scripts.motion_convert:main`)
- **`kimodo_textencoder`** — text encoder server (`kimodo.scripts.run_text_encoder_server:main`)