# hanyang9/umr architecture

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

- Interactive diagram: https://gitdiagram.com/hanyang9/umr
- Repository: https://github.com/hanyang9/umr

## Overview

UMR retargets human or character motion to a humanoid robot through two documented stages: learning point-cloud correspondence for a source-template/robot pair, then optimizing motion from those correspondences and constraints. The primary pipeline orchestrates correspondence building, training, retargeting, and viewing; specialized entry points adapt this workflow for interaction, character, NR, AdaPT, and batch data. The README documents these capabilities, while sampled source excerpts are partial, so uncertain internal calls are omitted.

Main entry points: [`scripts/humanoid_retarget_pipeline.py`](https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline.py) (Standard Pipeline), [`scripts/train_correspondence_template_residual_ae.py`](https://github.com/hanyang9/umr/blob/main/scripts/train_correspondence_template_residual_ae.py) (Correspondence Training), [`scripts/humanoid_retarget_pipeline_adapt.py`](https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline_adapt.py) (AdaPT Pipeline), [`scripts/humanoid_retarget_pipeline_batch.py`](https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline_batch.py) (Batch Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Pipeline Orchestration"]
  node_main_pipeline["Standard Pipeline"]
  node_batch_pipeline["Batch Pipeline"]
  node_hsi_pipeline["HSI / HOI Pipeline"]
  node_character_pipeline["Character Pipeline"]
  node_nr_pipeline["NR Pipeline"]
  node_adapt_pipeline["AdaPT Pipeline"]
end

subgraph group_inputs["Motion Sources"]
  node_source_adapters["Source Adapters<br/>[soma_source.py]"]
  node_nr_adapter["NR Motion Adapter<br/>[nr_source.py]"]
  node_surface_sampling["Surface Sampling"]
end

subgraph group_learning["Correspondence Learning"]
  node_correspondence_data["Correspondence Dataset"]
  node_adapt_dataset["AdaPT Dataset"]
  node_correspondence_training["Correspondence Training"]
end

subgraph group_retarget["Retargeting And Results"]
  node_retarget_solver["Surface Retarget Solver"]
  node_interaction_solver["Interaction Solver"]
  node_batch_solver["Batch Retargeting"]
  node_retarget_results["Retargeted Motion"]
  node_result_viewer["Result Viewer"]
  node_adapt_viewer["AdaPT Correspondence Viewer<br/>[app.js]"]
end

node_user(("Researcher"))
node_motion_data["Motion Data"]
node_robot_asset["Robot MJCF"]

node_user -->|"runs"| node_main_pipeline
node_user -->|"runs"| node_batch_pipeline
node_user -->|"runs"| node_hsi_pipeline
node_user -->|"runs"| node_character_pipeline
node_user -->|"runs"| node_nr_pipeline
node_user -->|"runs"| node_adapt_pipeline
node_motion_data -->|"provides motion"| node_main_pipeline
node_robot_asset -->|"configures robot"| node_main_pipeline
node_main_pipeline -->|"builds point clouds"| node_surface_sampling
node_main_pipeline -->|"builds dataset"| node_correspondence_data
node_main_pipeline -->|"trains slots"| node_correspondence_training
node_main_pipeline -->|"runs retargeting"| node_retarget_solver
node_main_pipeline -->|"opens results"| node_result_viewer
node_motion_data -->|"supplies source data"| node_source_adapters
node_source_adapters -->|"prepares motion"| node_main_pipeline
node_batch_pipeline -->|"prepares batch inputs"| node_source_adapters
node_batch_pipeline -->|"dispatches clips"| node_batch_solver
node_batch_pipeline -->|"writes outputs"| node_retarget_results
node_hsi_pipeline -->|"runs interaction retargeting"| node_interaction_solver
node_hsi_pipeline -->|"trains correspondence"| node_correspondence_training
node_character_pipeline -->|"builds samples"| node_surface_sampling
node_character_pipeline -->|"trains correspondence"| node_correspondence_training
node_character_pipeline -->|"runs retargeting"| node_retarget_solver
node_nr_pipeline -->|"loads motion"| node_nr_adapter
node_nr_pipeline -->|"trains correspondence"| node_correspondence_training
node_nr_pipeline -->|"runs retargeting"| node_interaction_solver
node_adapt_pipeline -->|"builds correspondence data"| node_adapt_dataset
node_adapt_pipeline -->|"trains correspondence"| node_correspondence_training
node_adapt_pipeline -->|"runs retargeting"| node_retarget_solver
node_adapt_pipeline -->|"opens correspondence view"| node_adapt_viewer
node_retarget_solver -->|"writes motion"| node_retarget_results
node_interaction_solver -->|"writes motion"| node_retarget_results
node_retarget_results -->|"loads for playback"| node_result_viewer
node_correspondence_data -->|"trains from"| node_correspondence_training

click node_main_pipeline "https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline.py"
click node_batch_pipeline "https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline_batch.py"
click node_hsi_pipeline "https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline_hsi_hoi.py"
click node_character_pipeline "https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline_character.py"
click node_nr_pipeline "https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline_nr.py"
click node_adapt_pipeline "https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline_adapt.py"
click node_source_adapters "https://github.com/hanyang9/umr/blob/main/scripts/soma_source.py"
click node_nr_adapter "https://github.com/hanyang9/umr/blob/main/scripts/nr_source.py"
click node_surface_sampling "https://github.com/hanyang9/umr/blob/main/scripts/surface_sampling.py"
click node_correspondence_data "https://github.com/hanyang9/umr/blob/main/scripts/build_correspondence_ae_dataset.py"
click node_adapt_dataset "https://github.com/hanyang9/umr/blob/main/scripts/build_adapt_correspondence_dataset.py"
click node_correspondence_training "https://github.com/hanyang9/umr/blob/main/scripts/train_correspondence_template_residual_ae.py"
click node_retarget_solver "https://github.com/hanyang9/umr/blob/main/scripts/retarget_body_segment_surface.py"
click node_interaction_solver "https://github.com/hanyang9/umr/blob/main/scripts/retarget_body_segment_surface_hoi_hsi.py"
click node_batch_solver "https://github.com/hanyang9/umr/blob/main/scripts/retarget_smpl_to_humanoid_surface_vector_batch.py"
click node_result_viewer "https://github.com/hanyang9/umr/blob/main/scripts/visualize_robot_retarget_result.py"
click node_adapt_viewer "https://github.com/hanyang9/umr/blob/main/static/adapt_correspondence_viewer/app.js"

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_main_pipeline,node_batch_pipeline,node_hsi_pipeline,node_character_pipeline,node_nr_pipeline,node_adapt_pipeline toneBlue
class node_source_adapters,node_nr_adapter,node_surface_sampling toneAmber
class node_correspondence_data,node_adapt_dataset,node_correspondence_training toneMint
class node_retarget_solver,node_interaction_solver,node_batch_solver,node_retarget_results,node_result_viewer,node_adapt_viewer toneRose
class node_user,node_motion_data,node_robot_asset toneIndigo
```

## Components

### Pipeline Orchestration

- [Standard Pipeline](https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline.py): `scripts/humanoid_retarget_pipeline.py`
- [Batch Pipeline](https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline_batch.py): `scripts/humanoid_retarget_pipeline_batch.py`
- [HSI / HOI Pipeline](https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline_hsi_hoi.py): `scripts/humanoid_retarget_pipeline_hsi_hoi.py`
- [Character Pipeline](https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline_character.py): `scripts/humanoid_retarget_pipeline_character.py`
- [NR Pipeline](https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline_nr.py): `scripts/humanoid_retarget_pipeline_nr.py`
- [AdaPT Pipeline](https://github.com/hanyang9/umr/blob/main/scripts/humanoid_retarget_pipeline_adapt.py): `scripts/humanoid_retarget_pipeline_adapt.py`

### Motion Sources

- [Source Adapters](https://github.com/hanyang9/umr/blob/main/scripts/soma_source.py): `scripts/soma_source.py`
- [NR Motion Adapter](https://github.com/hanyang9/umr/blob/main/scripts/nr_source.py): `scripts/nr_source.py`
- [Surface Sampling](https://github.com/hanyang9/umr/blob/main/scripts/surface_sampling.py): `scripts/surface_sampling.py`

### Correspondence Learning

- [Correspondence Dataset](https://github.com/hanyang9/umr/blob/main/scripts/build_correspondence_ae_dataset.py): `scripts/build_correspondence_ae_dataset.py`
- [AdaPT Dataset](https://github.com/hanyang9/umr/blob/main/scripts/build_adapt_correspondence_dataset.py): `scripts/build_adapt_correspondence_dataset.py`
- [Correspondence Training](https://github.com/hanyang9/umr/blob/main/scripts/train_correspondence_template_residual_ae.py): `scripts/train_correspondence_template_residual_ae.py`

### Retargeting And Results

- [Surface Retarget Solver](https://github.com/hanyang9/umr/blob/main/scripts/retarget_body_segment_surface.py): `scripts/retarget_body_segment_surface.py`
- [Interaction Solver](https://github.com/hanyang9/umr/blob/main/scripts/retarget_body_segment_surface_hoi_hsi.py): `scripts/retarget_body_segment_surface_hoi_hsi.py`
- [Batch Retargeting](https://github.com/hanyang9/umr/blob/main/scripts/retarget_smpl_to_humanoid_surface_vector_batch.py): `scripts/retarget_smpl_to_humanoid_surface_vector_batch.py`
- **Retargeted Motion**
- [Result Viewer](https://github.com/hanyang9/umr/blob/main/scripts/visualize_robot_retarget_result.py): `scripts/visualize_robot_retarget_result.py`
- [AdaPT Correspondence Viewer](https://github.com/hanyang9/umr/blob/main/static/adapt_correspondence_viewer/app.js): `static/adapt_correspondence_viewer/app.js`

### Other components

- **Researcher**
- **Motion Data**
- **Robot MJCF**

## Connections

- Researcher → Standard Pipeline: runs
- Researcher → Batch Pipeline: runs
- Researcher → HSI / HOI Pipeline: runs
- Researcher → Character Pipeline: runs
- Researcher → NR Pipeline: runs
- Researcher → AdaPT Pipeline: runs
- Motion Data → Standard Pipeline: provides motion
- Robot MJCF → Standard Pipeline: configures robot
- Standard Pipeline → Surface Sampling: builds point clouds
- Standard Pipeline → Correspondence Dataset: builds dataset
- Standard Pipeline → Correspondence Training: trains slots
- Standard Pipeline → Surface Retarget Solver: runs retargeting
- Standard Pipeline → Result Viewer: opens results
- Motion Data → Source Adapters: supplies source data
- Source Adapters → Standard Pipeline: prepares motion
- Batch Pipeline → Source Adapters: prepares batch inputs
- Batch Pipeline → Batch Retargeting: dispatches clips
- Batch Pipeline → Retargeted Motion: writes outputs
- HSI / HOI Pipeline → Interaction Solver: runs interaction retargeting
- HSI / HOI Pipeline → Correspondence Training: trains correspondence
- Character Pipeline → Surface Sampling: builds samples
- Character Pipeline → Correspondence Training: trains correspondence
- Character Pipeline → Surface Retarget Solver: runs retargeting
- NR Pipeline → NR Motion Adapter: loads motion
- NR Pipeline → Correspondence Training: trains correspondence
- NR Pipeline → Interaction Solver: runs retargeting
- AdaPT Pipeline → AdaPT Dataset: builds correspondence data
- AdaPT Pipeline → Correspondence Training: trains correspondence
- AdaPT Pipeline → Surface Retarget Solver: runs retargeting
- AdaPT Pipeline → AdaPT Correspondence Viewer: opens correspondence view
- Surface Retarget Solver → Retargeted Motion: writes motion
- Interaction Solver → Retargeted Motion: writes motion
- Retargeted Motion → Result Viewer: loads for playback
- Correspondence Dataset → Correspondence Training: trains from