### Install FFmpeg using apt

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Install ffmpeg for visualizing stick figures if you have sudo permissions. Verify the installation with `ffmpeg -version`.

```bash
sudo apt update
sudo apt install ffmpeg
ffmpeg -version  # check!
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Install all required Python packages listed in the requirements.txt file using pip.

```bash
pip install -r requirements.txt
```

--------------------------------

### Text-to-Motion Demo with Example Prompts

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Generate motions from provided text prompts and lengths specified in 'demo/example.txt'. Two configuration options are available: MLD and MotionLCM.

```python
python demo.py --cfg configs/mld_t2m.yaml --example assets/example.txt
```

```python
python demo.py --cfg configs/motionlcm_t2m.yaml --example assets/example.txt
```

--------------------------------

### Install Environment and Dependencies

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Sets up the conda environment and installs all necessary dependencies, including system libraries and pretrained model checkpoints. This is a prerequisite for running any scripts.

```bash
conda create python=3.10.12 --name motionlcm
conda activate motionlcm
pip install -r requirements.txt

sudo apt install ffmpeg         # or: conda install conda-forge::ffmpeg
conda install conda-forge::git-lfs

bash prepare/download_glove.sh
bash prepare/download_t5.sh
bash prepare/prepare_t5.sh
bash prepare/download_smpl_models.sh

bash prepare/download_pretrained_models.sh

bash prepare/prepare_tiny_humanml3d.sh

# Full dataset: clone HumanML3D and copy results
# cp -r ../HumanML3D/HumanML3D ./datasets/humanml3d
```

--------------------------------

### MotionLCM Text-to-Motion Configuration Example

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Example YAML configuration for MotionLCM text-to-motion training. Specifies output directories, run names, training parameters, and dataset settings.

```yaml
# configs/motionlcm_t2m.yaml — MotionLCM text-to-motion config example

FOLDER: './experiments_t2m'          # output directory for training runs
TEST_FOLDER: './experiments_t2m_test'
NAME: 'motionlcm_humanml'            # run name; combined with timestamp for output path

TRAIN:
  PRETRAINED: 'experiments_t2m/mld_humanml/mld_humanml.ckpt'  # MLD teacher for distillation
  max_train_epochs: 1000
  learning_rate: 2e-4
  # LCM-specific:
  w_min: 5.0
  w_max: 15.0
  num_ddim_timesteps: 10
  loss_type: 'huber'
  ema_decay: 0.95
  unet_time_cond_proj_dim: 256

TEST:
  CHECKPOINTS: 'experiments_t2m/motionlcm_humanml/motionlcm_humanml.ckpt'
  REPLICATION_TIMES: 20
  DO_MM_TEST: true

DATASET:
  NAME: 'humanml3d'
  HUMANML3D:
    FRAME_RATE: 20.0
    ROOT: './datasets/humanml3d'
    CONTROL_ARGS:
      CONTROL: false           # set true for ControlNet configs
      TRAIN_JOINTS: [0]        # joint indices for spatial control
      TEST_DENSITY: 100        # % of GT trajectory as hints

model:
  target: ['motion_vae', 'text_encoder', 'denoiser', 'scheduler_lcm', 'noise_optimizer']
  latent_dim: [16, 32]
  guidance_scale: 'dynamic'   # auto-selects from scheduler's cfg_step_map
  is_controlnet: false        # set true + add traj_encoder target for ControlNet
```

--------------------------------

### Run Motion Generation Demo Script

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Command-line arguments for the `demo.py` script, covering various motion generation tasks like reconstruction, text-to-motion, and spatial control. Options include specifying config files, example text prompts, and output suppression.

```bash
# Motion reconstruction (VAE round-trip on HumanML3D test set)
python demo.py --cfg configs/vae.yaml

# Text-to-motion with MLD (multi-step DDIM)
python demo.py --cfg configs/mld_t2m.yaml --example assets/example.txt

# Text-to-motion with MotionLCM (1-step LCM, real-time)
python demo.py --cfg configs/motionlcm_t2m.yaml --example assets/example.txt

# Spatial motion control with ControlNet (trajectory on Pelvis joint)
python demo.py --cfg configs/motionlcm_control_s.yaml

# Motion control via Consistency Latent Tuning (CLT, optimization-based)
python demo.py --cfg configs/motionlcm_t2m_clt.yaml --optimize

# Suppress skeleton animation, generate multiple samples
python demo.py --cfg configs/motionlcm_t2m.yaml --example assets/example.txt \
               --no-plot --replication 3
```

--------------------------------

### Install FFmpeg using Conda

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Install ffmpeg via conda if you do not have sudo permissions. Verify the installation with `ffmpeg -version`.

```bash
conda install conda-forge::ffmpeg
ffmpeg -version  # check!
```

--------------------------------

### Install Git LFS

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Install git-lfs using conda, which is required for handling large files.

```bash
conda install conda-forge::git-lfs
```

--------------------------------

### Copy HumanML3D Dataset

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Copy the prepared HumanML3D dataset to the MotionLCM repository's datasets folder. Refer to the HumanML3D GitHub repository for dataset setup instructions.

```bash
cp -r ../HumanML3D/HumanML3D ./datasets/humanml3d
```

--------------------------------

### Download Pretrained Models

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Execute this script to download the pre-trained models for motion reconstruction, text-to-motion, and motion control.

```bash
bash prepare/download_pretrained_models.sh
```

--------------------------------

### Initialize and Run VAE for Motion Reconstruction

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Loads a pre-trained VAE model and performs motion reconstruction using a dataset batch. Ensure the VAE configuration file and checkpoint are specified.

```python
import torch
from mld.config import parse_args
from mld.data.get_data import get_dataset
from mld.models.modeltype.vae import VAE

cfg = parse_args()   # --cfg configs/vae.yaml
device = torch.device('cuda')

dataset = get_dataset(cfg)
state_dict = torch.load(cfg.TEST.CHECKPOINTS, map_location="cpu")["state_dict"]

model = VAE(cfg, dataset)
model.load_state_dict(state_dict)
model.to(device).eval()

# Reconstruction demo via dataset batch
test_dataloader = dataset.test_dataloader()
batch = next(iter(test_dataloader))
batch = {k: v.to(device) if hasattr(v, 'to') else v for k, v in batch.items()}

with torch.no_grad():
    joints_rst, joints_ref = model(batch)
# joints_rst[i]: reconstructed motion, joints_ref[i]: ground-truth motion
```

--------------------------------

### Download Dependencies Materials

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Run these bash scripts to download necessary dependency materials like GloVe, T2M evaluators, T5, and SMPL models.

```bash
bash prepare/download_glove.sh
```

```bash
bash prepare/download_t2m_evaluators.sh
```

```bash
bash prepare/prepare_t5.sh
```

```bash
bash prepare/download_smpl_models.sh
```

--------------------------------

### Fit All Pickle Files in a Directory

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Process all .pkl files within a specified directory to create SMPL meshes. The script automatically filters out already fitted files.

```python
python fit.py --dir assets/
```

--------------------------------

### Train Motion VAE

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Trains a motion VAE from scratch. Configure training parameters like epochs, learning rate, and batch size in `configs/vae.yaml`. Supports TensorBoard and SwanLab logging.

```bash
# Edit configs/vae.yaml to set FOLDER, NAME, TRAIN.PRETRAINED, etc.
python -m train_vae --cfg configs/vae.yaml --vis tb        # TensorBoard logging
```

```bash
python -m train_vae --cfg configs/vae.yaml --vis swanlab   # SwanLab logging
```

--------------------------------

### Download Tiny HumanML3D Dataset

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Use this command to download a small dataset if data preparation is not yet complete. This is a prerequisite for some demo functionalities.

```bash
bash prepare/prepare_tiny_humanml3d.sh
```

--------------------------------

### demo.py — Motion Generation Demo Script

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

A script to run the full motion generation pipeline. It accepts configuration files and custom text prompts to generate motion, saving results as .pkl files and .mp4 animations.

```APIDOC
## demo.py — Motion Generation Demo Script

Runs the full generation pipeline given a config and optional custom text prompts, saving `.pkl` files (joint positions, text, length, hint) and `.mp4` stick-figure animations per sample.

```bash
# Motion reconstruction (VAE round-trip on HumanML3D test set)
python demo.py --cfg configs/vae.yaml

# Text-to-motion with MLD (multi-step DDIM)
python demo.py --cfg configs/mld_t2m.yaml --example assets/example.txt

# Text-to-motion with MotionLCM (1-step LCM, real-time)
python demo.py --cfg configs/motionlcm_t2m.yaml --example assets/example.txt

# Spatial motion control with ControlNet (trajectory on Pelvis joint)
python demo.py --cfg configs/motionlcm_control_s.yaml

# Motion control via Consistency Latent Tuning (CLT, optimization-based)
python demo.py --cfg configs/motionlcm_t2m_clt.yaml --optimize

# Suppress skeleton animation, generate multiple samples
python demo.py --cfg configs/motionlcm_t2m.yaml --example assets/example.txt \
               --no-plot --replication 3
```

Output is written to `${TEST_FOLDER}/${NAME}/demo_<timestamp>/samples/`:
- `sample_id_0_length_196_rep_0.pkl` — dict with keys `joints`, `text`, `length`, `hint`
- `sample_id_0_length_196_rep_0.mp4` — stick-figure animation
```

--------------------------------

### Run Quantitative Evaluation Script

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Command-line arguments for the `test.py` script to evaluate model performance using standard metrics for text-to-motion and control tasks. Metrics are saved to `metrics.json`.

```bash
# Evaluate VAE reconstruction (PosMetrics: MPJPE, FID)
python -m test --cfg configs/vae.yaml

# Evaluate MLD text-to-motion (TM2TMetrics: FID, R-Precision, MM-Dist)
python -m test --cfg configs/mld_t2m.yaml

# Evaluate MotionLCM text-to-motion
python -m test --cfg configs/motionlcm_t2m.yaml
```

--------------------------------

### Run Motion Reconstruction Demo

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Execute this command to perform motion reconstruction using Ground Truth motions from the HumanML3D test set. Requires the VAE configuration.

```python
python demo.py --cfg configs/vae.yaml
```

--------------------------------

### Dynamic Class Instantiation from Config

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Instantiates model components like VAE, denoiser, text encoder, scheduler, or ControlNet using a DictConfig. The config must specify a `target` class path and optional `params`. This is used internally during MLD initialization.

```python
from mld.config import instantiate_from_config
from omegaconf import OmegaConf

# Example: manually instantiate a denoiser from its config section
cfg = OmegaConf.load('configs/motionlcm_t2m.yaml')
# cfg.model.denoiser has keys: target, params
denoiser = instantiate_from_config(cfg.model.denoiser)
# Returns the constructed nn.Module ready to load weights

# Used internally during MLD.__init__:
# self.text_encoder = instantiate_from_config(cfg.model.text_encoder)
# self.vae          = instantiate_from_config(cfg.model.motion_vae)
# self.denoiser     = instantiate_from_config(cfg.model.denoiser)
# self.scheduler    = instantiate_from_config(cfg.model.scheduler)
```

--------------------------------

### Initialize and Run MLD for Text-to-Motion Inference

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Loads a pre-trained MLD or MotionLCM model and performs text-to-motion inference. Ensure the correct configuration file and checkpoint are specified.

```python
import torch
from mld.config import parse_args
from mld.data.get_data import get_dataset
from mld.models.modeltype.mld import MLD

cfg = parse_args()   # requires --cfg flag; shown here conceptually
device = torch.device('cuda') if torch.cuda.is_available() else torch.device('cpu')

dataset = get_dataset(cfg)
state_dict = torch.load(cfg.TEST.CHECKPOINTS, map_location="cpu")["state_dict"]

model = MLD(cfg, dataset)
model.load_state_dict(state_dict)
model.to(device).eval()

# Text-to-motion inference
batch = {
    "text": ["a person walks forward slowly", "someone does a cartwheel"],
    "length": [80, 120]
}
with torch.no_grad():
    joints, joints_ref = model(batch)
# joints: list of numpy arrays, each shaped (nframes, 22, 3) — XYZ joint positions
# joints_ref: None when no ground-truth motion is in the batch
```

--------------------------------

### Train VAE and MLD Models

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Run these commands after updating parameters in `configs/vae.yaml` and `configs/mld_t2m.yaml` to train the VAE and MLD components.

```bash
python -m train_vae --cfg configs/vae.yaml
```

```bash
python -m train_mld --cfg configs/mld_t2m.yaml
```

--------------------------------

### Text-to-Motion Demo with HumanML3D Prompts

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Generate motions using prompts sourced directly from the HumanML3D test set. Two configuration options are available: MLD and MotionLCM.

```python
python demo.py --cfg configs/mld_t2m.yaml
```

```python
python demo.py --cfg configs/motionlcm_t2m.yaml
```

--------------------------------

### Motion Control Demo with Motion ControlNet

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Utilize MotionLCM with Motion ControlNet for motion control tasks, using prompts and trajectory from the HumanML3D test set.

```python
python demo.py --cfg configs/motionlcm_control_s.yaml
```

--------------------------------

### Fit Pickle File to Create SMPL Meshes

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Convert a generated motion's pickle file into SMPL meshes. The output is saved as a numpy array.

```python
python fit.py --pkl assets/example.pkl
```

--------------------------------

### Evaluate Motion Reconstruction

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Run this command to evaluate the motion reconstruction model using the specified VAE configuration.

```bash
python -m test --cfg configs/vae.yaml
```

--------------------------------

### Render SMPL Meshes as Video

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Render SMPL meshes into a video sequence using Blender. Specify the path to your Blender executable, the pickle file, and the desired frames per second (fps).

```bash
YOUR_BLENDER_PATH/blender --background --python render.py -- --pkl assets/example_mesh.pkl --mode video --fps 20
```

--------------------------------

### Load Text-to-Motion Input File

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Reads a plain-text file where each line is formatted as `<length> <text description>`. It returns parallel lists of motion lengths and text strings suitable for batch inference. The `batch` dictionary can be passed directly to the model for generation.

```python
# demo.py
from demo import load_example_input

# assets/example.txt contents:
# 196 the man walks in a counterclockwise circle.
# 100 a person walks backward slowly.
# 56 a person does a jump.

texts, lens = load_example_input("assets/example.txt")
# texts -> ["the man walks in a counterclockwise circle.", "a person walks backward slowly.", "a person does a jump."]
# lens  -> [196, 100, 56]

batch = {"length": lens, "text": texts}
# Pass batch directly to model(batch) for generation
```

--------------------------------

### Evaluate Text-to-Motion Models

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Evaluate both the MLD and MotionLCM models for text-to-motion tasks using their respective configuration files.

```bash
python -m test --cfg configs/mld_t2m.yaml
```

```bash
python -m test --cfg configs/motionlcm_t2m.yaml
```

--------------------------------

### Train MotionLCM Model

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Execute this command after verifying parameters in `configs/motionlcm_t2m.yaml` to train the MotionLCM model.

```bash
python -m train_motionlcm --cfg configs/motionlcm_t2m.yaml
```

--------------------------------

### Render SMPL Meshes as Sequence

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Render SMPL meshes into a sequence of keyframes using Blender. Specify the path to your Blender executable, the pickle file, and the number of keyframes.

```bash
YOUR_BLENDER_PATH/blender --background --python render.py -- --pkl assets/example_mesh.pkl --mode sequence --num 8
```

--------------------------------

### test.py — Quantitative Evaluation

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

A script for quantitative evaluation of motion generation models. It computes standard metrics across multiple replication runs and saves aggregated results.

```APIDOC
## test.py — Quantitative Evaluation

Evaluates a checkpoint across multiple replication runs, computing standard metrics (FID, R-Precision, MultiModality for text-to-motion; KPS Mean Error, Trajectory Failure Rate for control), then saves aggregated results to `metrics.json`.

```bash
# Evaluate VAE reconstruction (PosMetrics: MPJPE, FID)
python -m test --cfg configs/vae.yaml

# Evaluate MLD text-to-motion (TM2TMetrics: FID, R-Precision, MM-Dist)
python -m test --cfg configs/mld_t2m.yaml

# Evaluate MotionLCM text-to-motion
python -m test --cfg configs/motionlcm_t2m.yaml
```
```

--------------------------------

### Render SMPL Meshes with Blender

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Renders .pkl mesh files into images or videos using Blender's Python API. Supports rendering sequences, full videos, single frames, or entire directories of mesh files.

```bash
# Render 8-keyframe sequence image (darker = later in time)
YOUR_BLENDER_PATH/blender --background --python render.py -- \
  --pkl assets/example_mesh.pkl --mode sequence --num 8
```

```bash
# Render full video at 20 FPS
YOUR_BLENDER_PATH/blender --background --python render.py -- \
  --pkl assets/example_mesh.pkl --mode video --fps 20
```

```bash
# Render single frame at temporal midpoint
YOUR_BLENDER_PATH/blender --background --python render.py -- \
  --pkl assets/example_mesh.pkl --mode frame --exact_frame 0.5
```

```bash
# Render entire directory of _mesh.pkl files as videos
YOUR_BLENDER_PATH/blender --background --python render.py -- \
  --dir assets/ --mode video --fps 20 --res high
```

--------------------------------

### Fit SMPL Meshes to Generated Joint Positions

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Fits SMPL body model parameters to joint positions from a .pkl file using SMPLify-3D optimization. Outputs a _mesh.pkl file containing vertex arrays. Can process single files or entire directories.

```bash
# Fit a single pkl file
python fit.py --pkl assets/example.pkl
# Output: assets/example_mesh.pkl
```

```bash
# Fit all unfitted pkl files in a directory (skips already-fitted files)
python fit.py --dir assets/
```

```bash
# Full options
python fit.py --pkl assets/example.pkl \
              --num_smplify_iters 150 \
              --joint_category AMASS \
              --fix_foot True \
              --gpu_ids 0
```

--------------------------------

### Motion Control Demo with CLT

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Perform motion control using MotionLCM with consistency latent tuning (CLT). This command includes an optimization flag.

```python
python demo.py --cfg configs/motionlcm_t2m_clt.yaml --optimize
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Use this command to create a new conda environment with Python 3.10.12 and activate it for MotionLCM.

```bash
conda create python=3.10.12 --name motionlcm
conda activate motionlcm
```

--------------------------------

### Train Motion ControlNet

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Trains a ControlNet for spatial/temporal trajectory-conditioned generation by freezing a pretrained MotionLCM backbone. Supports TensorBoard logging. Customize joint usage and test density via configuration.

```bash
# Requires MotionLCM checkpoint at TRAIN.PRETRAINED
python -m train_motion_control --cfg configs/motionlcm_control_s.yaml --vis tb
```

--------------------------------

### Parse and Merge YAML Configuration

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Parses command-line arguments and loads OmegaConf configuration from a YAML file. It merges sub-configurations from the `modules/` directory into a unified config object. This function is called internally by demo, train, and test scripts.

```python
# mld/config.py
from mld.config import parse_args

# Called internally by demo.py, train_*.py, test.py
# Equivalent CLI: python demo.py --cfg configs/motionlcm_t2m.yaml --example assets/example.txt
cfg = parse_args()
# cfg.NAME            -> 'motionlcm_humanml'
# cfg.TEST.CHECKPOINTS -> 'experiments_t2m/motionlcm_humanml/motionlcm_humanml.ckpt'
# cfg.model.latent_dim -> [16, 32]
# cfg.DATASET.NAME    -> 'humanml3d'
```

--------------------------------

### Configure Inference Steps

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Modify `num_inference_steps` in these configuration files to adjust the number of inference steps for MLD and MotionLCM.

```text
configs/modules/scheduler_ddim.yaml  # MLD
```

```text
configs/modules/scheduler_lcm.yaml   # MotionLCM
```

--------------------------------

### Render Specific SMPL Mesh Frame

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Render a single keyframe from SMPL meshes using Blender. Specify the path to your Blender executable, the pickle file, and the exact frame to render.

```bash
YOUR_BLENDER_PATH/blender --background --python render.py -- --pkl assets/example_mesh.pkl --mode frame --exact_frame 0.5
```

--------------------------------

### Dataset Density Logic

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

This Python code snippet illustrates how `TEST_DENSITY` is used to determine the number of control points selected from the ground truth trajectory.

```python
# MotionLCM/mld/data/humanml/dataset.py (Text2MotionDataset)
length = joints.shape[0]
density = self.testing_density
if density in [1, 2, 5]:
    choose_seq_num = density
else:
    choose_seq_num = int(length * density / 100)
```

--------------------------------

### Train MotionLCM via Consistency Distillation

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Distills a pretrained MLD model into a latent consistency model using the LCM training algorithm. Requires a pretrained MLD checkpoint specified in `configs/motionlcm_t2m.yaml`. Supports TensorBoard logging.

```bash
# Requires a pretrained MLD checkpoint at configs/motionlcm_t2m.yaml -> TRAIN.PRETRAINED
python -m train_motionlcm --cfg configs/motionlcm_t2m.yaml --vis tb
```

--------------------------------

### Motion Control Checkpoints

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

These are the available checkpoints for motion control training, one trained on 'Pelvis' and the other on 'All' joints.

```text
CHECKPOINTS: 'experiments_control/spatial/motionlcm_humanml/motionlcm_humanml_s_pelvis.ckpt'  # Trained on Pelvis
```

```text
CHECKPOINTS: 'experiments_control/spatial/motionlcm_humanml/motionlcm_humanml_s_all.ckpt'  #  Trained on All
```

--------------------------------

### MLD.forward(batch) — Generate Joint Positions from Text

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Runs the full inference pipeline for text-to-motion synthesis. This method handles text encoding, optional ControlNet trajectory encoding, the diffusion reverse process, VAE decoding, and joint position extraction.

```APIDOC
## MLD.forward(batch) — Generate Joint Positions from Text (and Optional Hints)

Runs the full inference pipeline: text encoding → (optional ControlNet trajectory encoding) → diffusion reverse process → VAE decoding → joint position extraction.

```python
import torch
from mld.utils.temos_utils import remove_padding

# Minimal inference with a trained MLD/MotionLCM checkpoint
batch = {
    "text": ["the person sits down on a chair"],
    "length": [60]
}

with torch.no_grad():
    joints, _ = model(batch)

# joints[0].shape -> (60, 22, 3)  — 60 frames, 22 joints, XYZ coords
print(f"Generated motion: {joints[0].shape} frames×joints×3")

# With spatial control hint (requires ControlNet checkpoint):
# batch["hint"]      -> Tensor (B, T, num_joints, 3) — target positions (normalized)
# batch["hint_mask"] -> Tensor (B, T, num_joints, 3) — binary mask for active frames
```
```

--------------------------------

### Train Motion ControlNet Model

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Run this command after updating parameters in `configs/motionlcm_control_s.yaml` to train the motion ControlNet. By default, it uses the 'Pelvis' joint.

```bash
python -m train_motion_control --cfg configs/motionlcm_control_s.yaml
```

--------------------------------

### MLD.forward - Generate Joint Positions from Text

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Executes the inference pipeline for generating motion from text. Can optionally include spatial control hints if a ControlNet checkpoint is used.

```python
import torch
from mld.utils.temos_utils import remove_padding

# Minimal inference with a trained MLD/MotionLCM checkpoint
batch = {
    "text": ["the person sits down on a chair"],
    "length": [60]
}

with torch.no_grad():
    joints, _ = model(batch)

# joints[0].shape -> (60, 22, 3)  — 60 frames, 22 joints, XYZ coords
print(f"Generated motion: {joints[0].shape} frames×joints×3")

# With spatial control hint (requires ControlNet checkpoint):
# batch["hint"]      -> Tensor (B, T, num_joints, 3) — target positions (normalized)
# batch["hint_mask"] -> Tensor (B, T, num_joints, 3) — binary mask for active frames
```

--------------------------------

### Evaluate MotionLCM Models

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Scripts to evaluate spatial ControlNet and CLT motion control models. ControlNet evaluation uses TM2TMetrics and ControlMetrics, while CLT motion control enforces specific inference parameters.

```bash
python -m test --cfg configs/motionlcm_control_s.yaml
```

```bash
python -m test --cfg configs/motionlcm_t2m_clt.yaml --optimize
```

--------------------------------

### Generate 3D Motion Stick-Figure Animation

Source: https://context7.com/dai-wenxun/motionlcm/llms.txt

Generates an animated MP4 stick-figure visualization of joint positions. Pass `None` for `hint` to omit trajectory visualization. Saves the animation to the specified path.

```python
import numpy as np
from mld.data.humanml.utils.plot_script import plot_3d_motion

# joints: np.ndarray of shape (nframes, 22, 3)
joints = np.load("my_motion_joints.npy")   # (60, 22, 3)

# Optional: trajectory hint for controlled joints (sparse, zeros for uncontrolled frames)
hint = np.zeros((60, 22, 3))
hint[0, 0] = [0.1, 0.9, 0.0]   # pelvis position at frame 0
hint[30, 0] = [0.5, 0.9, 0.0]  # pelvis position at frame 30

plot_3d_motion(
    save_path="output/walk_demo.mp4",
    joints=joints,
    title="a person walks forward",
    fps=20,
    hint=hint        # pass None to omit hint visualization
)
# Saves animated MP4 with skeleton limbs color-coded by body segment
```

--------------------------------

### Configure Training Joints for ControlNet

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Modify the `TRAIN_JOINTS` parameter in `configs/motionlcm_control_s.yaml` to use all available joints instead of just 'Pelvis'.

```yaml
TRAIN_JOINTS: [0] -> [0, 10, 11, 15, 20, 21]
```

--------------------------------

### Motion Control Testing Parameters

Source: https://github.com/dai-wenxun/motionlcm/blob/main/README.md

Default testing joint is 'Pelvis' with density 100. Adjust `TEST_JOINTS` and `TEST_DENSITY` for comprehensive results.

```text
TEST_JOINTS: [0]  # choice -> [0], [10], [11], [15], [20], [21] (ONLY when trained on all)
```

```text
TEST_DENSITY: 100  # choice -> [100, 25, 5, 2, 1]
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.