# lecar-lab/human2humanoid architecture

> Architecture diagram of the GitHub repository lecar-lab/human2humanoid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lecar-lab/human2humanoid
- Repository: https://github.com/lecar-lab/human2humanoid

## Overview

Based on our analysis of the complete file tree and the README, this project is a comprehensive research codebase for human-to-humanoid teleoperation and learning. In other words, it spans from simulation and deep reinforcement learning training (via Legged Gym, RSL RL, and PHC components) to data preparation (retargeting AMASS motions, SMPL model fitting, etc.) and finally hardware deployment (integration with Unitree H1, Inspire Hand, Damiao wrist controller, and ZED odometry). The system overall is a full-stack or end-to-end solution that covers simulation, training, data processing, policy learning, and physical robot control.

##### Main Architectural Domains and Components
- Simulation & Training Environment:
- Module “legged_gym”: Contains the simulation environment, configuration files (e.g., YAML in the cfg directory), and scripts to launch training and playing (e.g., train_hydra.py and play_hydra.py).
- Module “rsl_rl”: Contains reinforcement learning algorithms, runners, policy modules, and storage components dedicated to policy learning.
- Module “phc”: Implements data handling and additional learning components (e.g., the PHC tasks, SMPL utilities, and retargeting pipelines).
- Data Processing & Retargeting Pipeline:
- Data assets (AMASS, SMPL models) and processed data stored in folder “resources” (e.g., motions, objects, robots).
- Hardware and Deployment:
- “hardware_code”: Contains C++ and Python code for interfacing with hardware (e.g., unitree H1, Inspire Hand, wrist motor control via Damiao code, and odometry using a ZED camera).
- External integration pieces referenced in the README:
· Unitree H1 SDK for robot control.
· Inspire Hand integration (hardware_code/inspire_hand.cpp).
· Damiao wrist motor controller code (hardware_code/damiao_wrist.cpp).
· ZED camera odometry (hardware_code/zed_odometry.py).
- Visualization and Miscellaneous Utilities:
- “scripts/vis”: For visualizing motions and keypoints.
- Utility modules across the codebase (e.g., logging, data tree, transformation utilities) to support various parts of simulation and training.

##### Relationships and Interactions
- From simulation environments generating physics simulations and states.
- Into policy modules processing these states (with or without additional short-history or recurrent processing options).
- Back from the RL algorithms to adjust simulation parameters or choose actions.
- The Data Processing Pipeline takes AMASS and SMPL input data (stored in “data” folders and “resources”) and produces retargeted datasets. The processed outputs feed into training and evaluation.
- The Hardware Integration parts (hardware_code) form the deployment boundary where simulation-trained policies are transferred to the real robot. They interact with external SDKs and drivers (Unitree SDK for robot control, Inspire Hand integration, and ZED odometry) to close the loop in real time.

##### Architectural Patterns and Technologies
- Separation of concerns: Simulation/training (software simulation) is conceptually separated from data processing and the real-time hardware control modules.
- Use of configuration-driven design: Many YAML configuration files in legged_gym’s “cfg” directory allow for flexible setup of different observational modes, history lengths, motion models, and reward definitions.
- Modular structure: The project adopts modularity with dedicated packages for training (rsl_rl, phc), simulation (legged_gym), and utility/helper scripts.
- Integration of external libraries and frameworks: Dependencies include Isaac Gym for high-fidelity physics simulation, PyTorch for deep learning (requirements.txt), and third-party SDKs for hardware peripherals.

##### Final Recommendations to Engineer
- Within the simulation domain, break out Legged Gym and RSL RL (plus supporting PHC learning) as separate but interconnected modules.
- Pipeline from data acquisition (AMASS and SMPL) → Retargeting scripts → Simulation training → Policy deployment to hardware.
- Boundary interfaces where the simulation environment “talks” to the physical components (e.g., via the hardware_code, Unitree SDK, and vision components).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Simulation & Training Domain
    subgraph "Simulation & Training"
        LeggedGym["Simulation Environment - Legged Gym"]:::simulation
        RSLRL["Reinforcement Learning Module - RSL RL"]:::simulation
        PHCModule["Additional Learning & Data Handling - PHC"]:::simulation
    end

    %% Data Processing & Retargeting Domain
    subgraph "Data Processing & Retargeting"
        DataProc["Data Processing & Retargeting Pipeline"]:::dataProcessing
    end

    %% Hardware & Deployment Domain
    subgraph "Hardware & Deployment"
        Hardware["Hardware Interface - Robot Control"]:::hardware
        subgraph "External Integrations"
            Unitree["Unitree H1 SDK"]:::external
            InspireHand["Inspire Hand Integration"]:::external
            Damiao["Damiao Wrist Controller"]:::external
            ZED["ZED Odometry"]:::external
        end
    end

    %% Visualization & Utility Domain
    subgraph "Visualization & Utilities"
        VisUtil["Visualization & Utility Scripts"]:::visualization
    end

    %% Relationships among Simulation & Training components
    LeggedGym -->|"generates_sim_data"| RSLRL
    LeggedGym -->|"provides_obs"| PHCModule
    %% Data Processing feeding simulation modules
    DataProc -->|"feeds_data"| PHCModule
    DataProc -->|"feeds_data"| RSLRL
    %% Policy deployment to hardware
    RSLRL -->|"sends_policy"| Hardware
    %% Hardware controlling external devices
    Hardware -->|"controls"| Unitree
    Hardware -->|"controls"| InspireHand
    Hardware -->|"controls"| Damiao
    Hardware -->|"controls"| ZED
    %% Visualization connections from various domains
    LeggedGym -->|"visual_output"| VisUtil
    DataProc -->|"visual_data"| VisUtil
    PHCModule -->|"visual_output"| VisUtil

    %% Click Events
    click LeggedGym "https://github.com/lecar-lab/human2humanoid/tree/main/legged_gym/legged_gym"
    click RSLRL "https://github.com/lecar-lab/human2humanoid/tree/main/rsl_rl/rsl_rl"
    click PHCModule "https://github.com/lecar-lab/human2humanoid/tree/main/phc/phc"
    click DataProc "https://github.com/lecar-lab/human2humanoid/tree/main/scripts/data_process"
    click Hardware "https://github.com/lecar-lab/human2humanoid/tree/main/hardware_code"
    click VisUtil "https://github.com/lecar-lab/human2humanoid/tree/main/scripts/vis"

    %% Styling classes
    classDef simulation fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef dataProcessing fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef hardware fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef external fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef visualization fill:#FFFACD,stroke:#000,stroke-width:2px;
```
