# horizonrobotics/holomotion architecture

> Architecture diagram of the GitHub repository horizonrobotics/holomotion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/horizonrobotics/holomotion
- Repository: https://github.com/horizonrobotics/holomotion

## Overview

HoloMotion is a humanoid-motion control system spanning motion-data preparation, policy learning, simulation evaluation, and robot deployment. The documented custom-policy workflow begins with HoloSMPL conversion, proceeds through robot retargeting and training, then evaluation; deployment also supports offline clips and live teleoperation without retraining. HoloSMPL provides a shared canonical motion representation and conversion, validation, packing, and visualization capabilities. The graph preserves these major branches. Several training and deployment links are documented rather than verified from source excerpts, so those edges cite the README; unsampled implementation details are not inferred.

Main entry points: [`holosmpl/cli.py`](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/cli.py) (HoloSMPL CLI), [`holosmpl/workflows/pack_formal_h5.py`](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/workflows/pack_formal_h5.py) (H5 packing), [`holosmpl/workflows/convert_dataset.py`](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/workflows/convert_dataset.py) (Canonical conversion), [`holomotion/src/motion_retargeting/holomotion_preprocess.py`](https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/motion_retargeting/holomotion_preprocess.py) (Robot retargeting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_motion_data["Motion data"]
  node_holosmpl_cli["HoloSMPL CLI<br/>[cli.py]"]
  node_source_registry["Source registry<br/>[sources.py]"]
  node_source_converters["Source converters"]
  node_canonical_conversion["Canonical conversion<br/>[convert_dataset.py]"]
  node_formal_conversion["Formal conversion<br/>[convert_formal.py]"]
  node_distributed_h5["Distributed H5 production"]
  node_h5_packing["H5 packing<br/>[pack_formal_h5.py]"]
end

subgraph group_retargeting["Retargeting"]
  node_robot_retargeting["Robot retargeting"]
  node_retarget_engine["HoloRetarget engine<br/>[_engine_impl.py]"]
end

subgraph group_learning_eval["Learning and evaluation"]
  node_training_data["Robot H5 data<br/>[robot_h5.py]"]
  node_training_loader["H5 data loader<br/>[h5_dataloader.py]"]
  node_policy_training["Policy training<br/>[train.py]"]
  node_ppo_algorithm["PPO algorithm<br/>[ppo.py]"]
  node_network_modules["Policy networks<br/>[network_modules.py]"]
  node_simulation_evaluation["Simulation evaluation"]
  node_motion_env["Motion tracking environment<br/>[motion_tracking.py]"]
end

subgraph group_robot_runtime["Robot runtime"]
  node_offline_deployment["Offline deployment"]
  node_policy_runtime["Policy runtime<br/>[policy_runtime.py]"]
  node_ros2_policy_node["ROS 2 policy node"]
  node_teleoperation["Live teleoperation"]
end

subgraph group_shared_formats["Shared data formats"]
  node_data_validation["Data validation"]
  node_canonical_schema["Canonical schema<br/>[canonical.py]"]
  node_motion_resampling["Motion resampling<br/>[resample.py]"]
  node_formal_h5_writer["Formal H5 writer<br/>[formal_h5.py]"]
  node_motion_visualization["Motion visualization<br/>[video_render.py]"]
end

node_user(("Motion user"))
node_humanoid_robot["Unitree G1"]
node_live_motion_source(("Live motion source"))

node_user -->|"converts motion"| node_holosmpl_cli
node_holosmpl_cli -->|"selects source"| node_source_registry
node_source_registry -->|"dispatches to"| node_source_converters
node_holosmpl_cli -->|"runs conversion"| node_canonical_conversion
node_canonical_conversion -->|"writes canonical data"| node_canonical_schema
node_canonical_conversion -->|"validates output"| node_data_validation
node_holosmpl_cli -->|"runs conversion"| node_formal_conversion
node_formal_conversion -->|"validates formal data"| node_data_validation
node_holosmpl_cli -->|"packs formal data"| node_h5_packing
node_h5_packing -->|"checks H5 data"| node_data_validation
node_h5_packing -->|"writes H5"| node_formal_h5_writer
node_holosmpl_cli -->|"runs distributed production"| node_distributed_h5
node_distributed_h5 -->|"combines H5 shards"| node_h5_packing
node_holosmpl_cli -->|"renders previews"| node_motion_visualization
node_user -->|"retargets motion"| node_robot_retargeting
node_robot_retargeting -->|"uses engine"| node_retarget_engine
node_robot_retargeting -->|"produces robot data"| node_training_data
node_training_data -->|"provides training data"| node_training_loader
node_user -->|"trains policy"| node_policy_training
node_training_loader -->|"supplies batches"| node_policy_training
node_policy_training -->|"optimizes with PPO"| node_ppo_algorithm
node_ppo_algorithm -->|"uses networks"| node_network_modules
node_user -->|"evaluates policy"| node_simulation_evaluation
node_simulation_evaluation -.->|"evaluates tracking"| node_motion_env
node_user -->|"replays clips"| node_offline_deployment
node_offline_deployment -.->|"provides reference motion"| node_policy_runtime
node_live_motion_source -->|"streams motion"| node_teleoperation
node_teleoperation -->|"feeds live references"| node_policy_runtime
node_policy_runtime -.->|"runs policy"| node_ros2_policy_node
node_ros2_policy_node -->|"controls robot"| node_humanoid_robot
node_teleoperation -->|"supports teleoperation"| node_humanoid_robot

click node_holosmpl_cli "https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/cli.py"
click node_source_registry "https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/sources.py"
click node_source_converters "https://github.com/horizonrobotics/holomotion/tree/master/holosmpl/converters"
click node_canonical_conversion "https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/workflows/convert_dataset.py"
click node_formal_conversion "https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/workflows/convert_formal.py"
click node_distributed_h5 "https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/distributed_holosmpl_h5.py"
click node_h5_packing "https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/workflows/pack_formal_h5.py"
click node_data_validation "https://github.com/horizonrobotics/holomotion/tree/master/holosmpl/core/validation"
click node_canonical_schema "https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/core/schema/canonical.py"
click node_motion_resampling "https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/core/processing/resample.py"
click node_formal_h5_writer "https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/core/writers/formal_h5.py"
click node_motion_visualization "https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/visualization/video_render.py"
click node_robot_retargeting "https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/motion_retargeting/holomotion_preprocess.py"
click node_retarget_engine "https://github.com/horizonrobotics/holomotion/blob/master/holoretarget/_engine_impl.py"
click node_training_data "https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/training/data_production/robot_h5.py"
click node_training_loader "https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/training/h5_dataloader.py"
click node_policy_training "https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/training/train.py"
click node_ppo_algorithm "https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/algo/ppo.py"
click node_network_modules "https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/modules/network_modules.py"
click node_simulation_evaluation "https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/evaluation/eval_mujoco_sim2sim.py"
click node_motion_env "https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/env/motion_tracking.py"
click node_offline_deployment "https://github.com/horizonrobotics/holomotion/blob/master/deployment/unitree_g1_ros2_29dof/src/humanoid_policy/motion_clip_library.py"
click node_policy_runtime "https://github.com/horizonrobotics/holomotion/blob/master/deployment/unitree_g1_ros2_29dof/src/humanoid_policy/policy_runtime.py"
click node_ros2_policy_node "https://github.com/horizonrobotics/holomotion/blob/master/deployment/unitree_g1_ros2_29dof/src/humanoid_policy/policy_node_29dof.py"
click node_teleoperation "https://github.com/horizonrobotics/holomotion/blob/master/deployment/holomotion_teleop/holomotion_teleop_node.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_holosmpl_cli,node_source_registry,node_source_converters,node_canonical_conversion,node_formal_conversion,node_distributed_h5,node_h5_packing,node_user toneBlue
class node_robot_retargeting,node_retarget_engine toneAmber
class node_training_data,node_training_loader,node_policy_training,node_ppo_algorithm,node_network_modules,node_simulation_evaluation,node_motion_env toneMint
class node_offline_deployment,node_policy_runtime,node_ros2_policy_node,node_teleoperation toneRose
class node_data_validation,node_canonical_schema,node_motion_resampling,node_formal_h5_writer,node_motion_visualization,node_humanoid_robot,node_live_motion_source toneIndigo
```

## Components

### Motion data

- [HoloSMPL CLI](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/cli.py): `holosmpl/cli.py`
- [Source registry](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/sources.py): `holosmpl/sources.py`
- [Source converters](https://github.com/horizonrobotics/holomotion/tree/master/holosmpl/converters): `holosmpl/converters`
- [Canonical conversion](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/workflows/convert_dataset.py): `holosmpl/workflows/convert_dataset.py`
- [Formal conversion](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/workflows/convert_formal.py): `holosmpl/workflows/convert_formal.py`
- [Distributed H5 production](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/distributed_holosmpl_h5.py): `holosmpl/distributed_holosmpl_h5.py`
- [H5 packing](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/workflows/pack_formal_h5.py): `holosmpl/workflows/pack_formal_h5.py`

### Retargeting

- [Robot retargeting](https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/motion_retargeting/holomotion_preprocess.py): `holomotion/src/motion_retargeting/holomotion_preprocess.py`
- [HoloRetarget engine](https://github.com/horizonrobotics/holomotion/blob/master/holoretarget/_engine_impl.py): `holoretarget/_engine_impl.py`

### Learning and evaluation

- [Robot H5 data](https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/training/data_production/robot_h5.py): `holomotion/src/training/data_production/robot_h5.py`
- [H5 data loader](https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/training/h5_dataloader.py): `holomotion/src/training/h5_dataloader.py`
- [Policy training](https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/training/train.py): `holomotion/src/training/train.py`
- [PPO algorithm](https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/algo/ppo.py): `holomotion/src/algo/ppo.py`
- [Policy networks](https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/modules/network_modules.py): `holomotion/src/modules/network_modules.py`
- [Simulation evaluation](https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/evaluation/eval_mujoco_sim2sim.py): `holomotion/src/evaluation/eval_mujoco_sim2sim.py`
- [Motion tracking environment](https://github.com/horizonrobotics/holomotion/blob/master/holomotion/src/env/motion_tracking.py): `holomotion/src/env/motion_tracking.py`

### Robot runtime

- [Offline deployment](https://github.com/horizonrobotics/holomotion/blob/master/deployment/unitree_g1_ros2_29dof/src/humanoid_policy/motion_clip_library.py): `deployment/unitree_g1_ros2_29dof/src/humanoid_policy/motion_clip_library.py`
- [Policy runtime](https://github.com/horizonrobotics/holomotion/blob/master/deployment/unitree_g1_ros2_29dof/src/humanoid_policy/policy_runtime.py): `deployment/unitree_g1_ros2_29dof/src/humanoid_policy/policy_runtime.py`
- [ROS 2 policy node](https://github.com/horizonrobotics/holomotion/blob/master/deployment/unitree_g1_ros2_29dof/src/humanoid_policy/policy_node_29dof.py): `deployment/unitree_g1_ros2_29dof/src/humanoid_policy/policy_node_29dof.py`
- [Live teleoperation](https://github.com/horizonrobotics/holomotion/blob/master/deployment/holomotion_teleop/holomotion_teleop_node.py): `deployment/holomotion_teleop/holomotion_teleop_node.py`

### Shared data formats

- [Data validation](https://github.com/horizonrobotics/holomotion/tree/master/holosmpl/core/validation): `holosmpl/core/validation`
- [Canonical schema](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/core/schema/canonical.py): `holosmpl/core/schema/canonical.py`
- [Motion resampling](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/core/processing/resample.py): `holosmpl/core/processing/resample.py`
- [Formal H5 writer](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/core/writers/formal_h5.py): `holosmpl/core/writers/formal_h5.py`
- [Motion visualization](https://github.com/horizonrobotics/holomotion/blob/master/holosmpl/visualization/video_render.py): `holosmpl/visualization/video_render.py`

### Other components

- **Motion user**
- **Unitree G1**
- **Live motion source**

## Connections

- Motion user → HoloSMPL CLI: converts motion (evidence: `README.md`)
- HoloSMPL CLI → Source registry: selects source (evidence: `holosmpl/cli.py`)
- Source registry → Source converters: dispatches to (evidence: `holosmpl/sources.py`)
- HoloSMPL CLI → Canonical conversion: runs conversion (evidence: `holosmpl/cli.py`)
- Canonical conversion → Canonical schema: writes canonical data (evidence: `holosmpl/workflows/convert_dataset.py`)
- Canonical conversion → Data validation: validates output (evidence: `holosmpl/workflows/convert_dataset.py`)
- HoloSMPL CLI → Formal conversion: runs conversion (evidence: `holosmpl/cli.py`)
- Formal conversion → Data validation: validates formal data (evidence: `holosmpl/workflows/convert_formal.py`)
- HoloSMPL CLI → H5 packing: packs formal data (evidence: `holosmpl/cli.py`)
- H5 packing → Data validation: checks H5 data (evidence: `holosmpl/workflows/pack_formal_h5.py`)
- H5 packing → Formal H5 writer: writes H5 (evidence: `holosmpl/workflows/pack_formal_h5.py`)
- HoloSMPL CLI → Distributed H5 production: runs distributed production (evidence: `README.md`)
- Distributed H5 production → H5 packing: combines H5 shards (evidence: `holosmpl/distributed_holosmpl_h5.py`)
- HoloSMPL CLI → Motion visualization: renders previews (evidence: `holosmpl/cli.py`)
- Motion user → Robot retargeting: retargets motion (evidence: `README.md`)
- Robot retargeting → HoloRetarget engine: uses engine
- Robot retargeting → Robot H5 data: produces robot data (evidence: `README.md`)
- Robot H5 data → H5 data loader: provides training data (evidence: `holomotion/src/training/h5_dataloader.py`)
- Motion user → Policy training: trains policy (evidence: `README.md`)
- H5 data loader → Policy training: supplies batches (evidence: `README.md`)
- Policy training → PPO algorithm: optimizes with PPO
- PPO algorithm → Policy networks: uses networks (evidence: `holomotion/src/algo/ppo_tf.py`)
- Motion user → Simulation evaluation: evaluates policy (evidence: `README.md`)
- Simulation evaluation → Motion tracking environment: evaluates tracking
- Motion user → Offline deployment: replays clips (evidence: `README.md`)
- Offline deployment → Policy runtime: provides reference motion
- Live motion source → Live teleoperation: streams motion (evidence: `README.md`)
- Live teleoperation → Policy runtime: feeds live references (evidence: `deployment/holomotion_teleop/holomotion_teleop_node.py`)
- Policy runtime → ROS 2 policy node: runs policy
- ROS 2 policy node → Unitree G1: controls robot (evidence: `README.md`)
- Live teleoperation → Unitree G1: supports teleoperation (evidence: `README.md`)
