# telehuman/pbhc architecture

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

- Interactive diagram: https://gitdiagram.com/telehuman/pbhc
- Repository: https://github.com/telehuman/pbhc

## Overview

##### Project Type and Purpose
- This is a research-grade, full-stack robotics and RL framework (“KungfuBot”) for physics-based humanoid control.
- It integrates a multi-stage motion-processing pipeline, an RL training/deployment engine, and visualization/tools modules.

##### High-Level Architecture
The system can be viewed as a linear pipeline of stages with cross-cutting configuration and external dependencies:
┌───────────────┐     ┌─────────────────┐     ┌────────────────────┐     ┌───────────────────┐     ┌───────────────────┐
│ Motion Source │ →   │ Retargeting     │ →   │ Motion Processing  │ →   │ RL Training       │ →   │ Deployment & Eval │
└───────────────┘     └─────────────────┘     └────────────────────┘     └───────────────────┘     └───────────────────┘
(motion_source/)      (smpl_retarget/)         (robot_motion_process/,   (humanoidverse/)        (humanoidverse/)
smpl_vis/)

##### Main Components and Their Interactions
a. Motion Collection (“motion_source/”)
- Input: raw human motion (video, LAFAN, AMASS, custom).
- Output: unified SMPL-format files (*.pkl).
- Key modules: `convert_lafan_pkl.py`, `demo.py`, rotation-utils, batch utilities.

b. Retargeting (“smpl_retarget/”)
- Pipelines: Mink-based (`mink_retarget/`) and PHC-based (`phc_retarget/`).
- Input: SMPL motions.
- Output: robot-specific motion trajectories.
- Tools: motion_filter (denoise/normalize), poselib for skeleton abstractions.

c. Motion Processing & Visualization
- “robot_motion_process/”: interpolation, trajectory analysis, MJViewer scripts.
- “smpl_vis/”: SMPL mesh rendering, Blender import, custom renderer tools.
- Purpose: QC and analysis before RL training.

d. RL Training Framework (“humanoidverse/”)
- Core: Hydra-driven config, ASAP + RSL_RL libraries, modular agents, callbacks.
- Agents: base_algo, mh_ppo, ppo.
- Simulators: IsaacGym, MuJoCo, Genesis, IsaacSim.
- Envs: motion_tracking, legged_base, base_task.
- Deploy: single vs multiple robot setups, external modules for real-world.

e. Examples & Data (“example/”)
- Sample SMPL motions, pretrained policy checkpoints (PyTorch + ONNX).

f. Configuration & Utilities
- “humanoidverse/config/”: Hydra config hierarchy (algo, env, sim, robot, terrain, domain randomization, logging, deploy).
- “humanoidverse/utils/”: logging, math, config helpers, motion libraries, real-robot helpers.

##### External Dependencies & Data Stores
- External libraries: ASAP, RSL_RL, Maskedmimic (Mink), PHC, GVHMR, IPMAN.
- Simulators: NVIDIA IsaacGym, MuJoCo, IsaacSim, Genesis.
- Data: SMPL datasets, Unitree G1 URDF & meshes (under description/robots/g1), pretrained models (.pt, .onnx).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Motion Collection
    subgraph "Motion Collection (motion_source/)" 
        style MotionCollection fill:#CFE2F3,stroke:#000,stroke-width:1px
        Convert["convert_lafan_pkl.py"]:::dataBlue
        Demo["demo.py"]:::dataBlue
        RotUtils["rotation_conversions.py"]:::dataBlue
        BatchUtils["torch_humanoid_batch.py"]:::dataBlue
    end

    %% Retargeting
    subgraph "Retargeting (smpl_retarget/)" 
        style Retargeting fill:#CFE2F3,stroke:#000,stroke-width:1px
        subgraph "Mink-based (mink_retarget/)"
            style Mink fill:#CFE2F3,stroke:#000
            MinkImpl["mink_retarget.py"]:::dataBlue
            ConvertFit["convert_fit_motion.py"]:::dataBlue
            MBatch["torch_humanoid_batch.py"]:::dataBlue
            SMPLXBatch["torch_smplx_humanoid_batch.py"]:::dataBlue
            MRConfig["config.py"]:::dataBlue
        end
        subgraph "PHC-based (phc_retarget/)"
            style PHC fill:#CFE2F3,stroke:#000
            FitMotion["fit_smpl_motion.py"]:::dataBlue
            FitShape["fit_smpl_shape.py"]:::dataBlue
        end
        subgraph "Motion Filter (motion_filter/)"
            style Filter fill:#CFE2F3,stroke:#000
            MFCore["motion_filter.py"]:::dataBlue
            MeshUtils["mesh_utils.py"]:::dataBlue
            Parser["smpl_paraser.py"]:::dataBlue
            PartVol["part_volumes.py"]:::dataBlue
            MFConst["constants.py"]:::dataBlue
            MFModel["smpl.py"]:::dataBlue
        end
        subgraph "PoseLib (poselib/poselib/)"
            style PoseLib fill:#CFE2F3,stroke:#000
            CoreUtils["core utils"]:::dataBlue
            Skeleton["skeleton core"]:::dataBlue
            VisTools["visualization"]:::dataBlue
            Setup["setup.py"]:::dataBlue
        end
    end

    %% Processing & Visualization
    subgraph "Processing & Visualization"
        style ProcViz fill:#D9EAD3,stroke:#000,stroke-width:1px
        subgraph "Robot Motion (robot_motion_process/)"
            style RobotProc fill:#D9EAD3,stroke:#000
            Interp["motion_interpolation_pkl.py"]:::green
            Reader["motion_readpkl.py"]:::green
            MJ1["vis_q_mj.py"]:::green
            MJ2["vis_rr.py"]:::green
            NB["traj_vis.ipynb"]:::green
        end
        subgraph "SMPL Visualization (smpl_vis/)"
            style SMPLVis fill:#D9EAD3,stroke:#000
            Render["smpl_render.py"]:::green
            BlenderImport["import_motion_blender.py"]:::green
            RTools["renderer_tools.py"]:::green
            Renderer["renderer.py"]:::green
            BodyModel["body_model_smpl.py"]:::green
            GeoTrans["geo_transform.py"]:::green
            SMPLUtils["smpl_utils.py"]:::green
        end
    end

    %% RL Training Framework
    subgraph "RL Engine (humanoidverse/)"
        style RLEngine fill:#FCE5CD,stroke:#000,stroke-width:1px
        subgraph "Config (config/)"
            Hydra["Hydra config hierarchy"]:::orange
        end
        subgraph "Agents"
            BaseAlgo["base_algo.py"]:::orange
            PPO["ppo.py"]:::orange
            MHPPO["mh_ppo.py"]:::orange
            Callbacks["callbacks"]:::orange
            Modules["modules"]:::orange
        end
        subgraph "Environments"
            BaseTask["base_task.py"]:::orange
            Legged["legged_robot_base.py"]:::orange
            MotionTrack["motion_tracking.py"]:::orange
            EnvUtils["env_utils"]:::orange
        end
        subgraph "Simulators"
            BaseSim["base_simulator.py"]:::orange
            IsaacGym["isaacgym.py"]:::orange
            MuJoCoSim["genesis"]:::orange
            IsaacSim["isaacsim"]:::orange
        end
        subgraph "Deploy"
            DeployCode["deploy code"]:::orange
            DeployConfigs["deploy configs"]:::orange
        end
        Utils["utils & helpers"]:::orange
    end

    %% Example Data
    subgraph "Example & Data (example/)"
        style Example fill:#EDEDED,stroke:#000,stroke-width:1px
        SampleMotions["motion_data/*.pkl"]:::gray
        Pretrained["pretrained models"]:::gray
    end

    %% Robot Assets
    Assets["description/robots assets"]:::ext

    %% Flows
    Convert -->|".pkl SMPL"| MinkImpl
    Convert -->|".pkl SMPL"| FitMotion
    MinkImpl -->|"robot traj"| MFCore
    FitMotion -->|"robot traj"| MFCore
    MFCore -->|".pkl robot"| Interp
    Interp -->|".pkl"| Reader
    Reader -->|".pkl"| MJ1
    Reader -->|".pkl"| MJ2
    MJ1 -->|QC artifacts| Hydra
    Render -->|mesh| MJ1
    Hydra -->|"config"| BaseAlgo
    BaseAlgo -->|"agent"| PPO
    BaseAlgo -->|"agent"| MHPPO
    PPO -->|callback| Callbacks
    MHPPO -->|callback| Callbacks
    PPO -->|"trained policy"| Pretrained
    SampleMotions -->|input| Convert
    Assets -->|URDF & meshes| MinkImpl
    Assets -->|URDF & meshes| BaseSim

    %% Cross-cutting
    Hydra -->|feeds| IsaacGym
    Hydra -->|feeds| MuJoCoSim

    %% Click Events
    click Convert "https://github.com/telehuman/pbhc/blob/main/motion_source/convert_lafan_pkl.py"
    click Demo "https://github.com/telehuman/pbhc/blob/main/motion_source/demo.py"
    click RotUtils "https://github.com/telehuman/pbhc/blob/main/motion_source/utils/rotation_conversions.py"
    click BatchUtils "https://github.com/telehuman/pbhc/blob/main/motion_source/utils/torch_humanoid_batch.py"
    click MinkImpl "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/mink_retarget/retargeting/mink_retarget.py"
    click ConvertFit "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/mink_retarget/convert_fit_motion.py"
    click MBatch "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/mink_retarget/retargeting/torch_humanoid_batch.py"
    click SMPLXBatch "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/mink_retarget/retargeting/torch_smplx_humanoid_batch.py"
    click MRConfig "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/mink_retarget/retargeting/config.py"
    click FitMotion "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/phc_retarget/fit_smpl_motion.py"
    click FitShape "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/phc_retarget/fit_smpl_shape.py"
    click MFCore "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/motion_filter/utils/motion_filter.py"
    click MeshUtils "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/motion_filter/utils/mesh_utils.py"
    click Parser "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/motion_filter/utils/smpl_paraser.py"
    click PartVol "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/motion_filter/utils/part_volumes.py"
    click MFConst "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/motion_filter/constants.py"
    click MFModel "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/motion_filter/model/smpl.py"
    click Setup "https://github.com/telehuman/pbhc/blob/main/smpl_retarget/poselib/setup.py"
    click Interp "https://github.com/telehuman/pbhc/blob/main/robot_motion_process/motion_interpolation_pkl.py"
    click Reader "https://github.com/telehuman/pbhc/blob/main/robot_motion_process/motion_readpkl.py"
    click MJ1 "https://github.com/telehuman/pbhc/blob/main/robot_motion_process/vis_q_mj.py"
    click MJ2 "https://github.com/telehuman/pbhc/blob/main/robot_motion_process/vis_rr.py"
    click NB "https://github.com/telehuman/pbhc/blob/main/robot_motion_process/traj_vis.ipynb"
    click Render "https://github.com/telehuman/pbhc/blob/main/smpl_vis/smpl_render.py"
    click BlenderImport "https://github.com/telehuman/pbhc/blob/main/smpl_vis/import_motion_blender.py"
    click RTools "https://github.com/telehuman/pbhc/blob/main/smpl_vis/utils/renderer_tools.py"
    click Renderer "https://github.com/telehuman/pbhc/blob/main/smpl_vis/utils/renderer.py"
    click BodyModel "https://github.com/telehuman/pbhc/blob/main/smpl_vis/utils/body_model_smpl.py"
    click GeoTrans "https://github.com/telehuman/pbhc/blob/main/smpl_vis/utils/geo_transform.py"
    click SMPLUtils "https://github.com/telehuman/pbhc/blob/main/smpl_vis/utils/smpl_utils.py"
    click BaseAlgo "https://github.com/telehuman/pbhc/blob/main/humanoidverse/agents/base_algo/base_algo.py"
    click PPO "https://github.com/telehuman/pbhc/blob/main/humanoidverse/agents/ppo/ppo.py"
    click MHPPO "https://github.com/telehuman/pbhc/blob/main/humanoidverse/agents/mh_ppo/mh_ppo.py"
    click BaseTask "https://github.com/telehuman/pbhc/blob/main/humanoidverse/envs/base_task/base_task.py"
    click Legged "https://github.com/telehuman/pbhc/blob/main/humanoidverse/envs/legged_base_task/legged_robot_base.py"
    click MotionTrack "https://github.com/telehuman/pbhc/blob/main/humanoidverse/envs/motion_tracking/motion_tracking.py"
    click BaseSim "https://github.com/telehuman/pbhc/blob/main/humanoidverse/simulator/base_simulator/base_simulator.py"
    click IsaacGym "https://github.com/telehuman/pbhc/blob/main/humanoidverse/simulator/isaacgym/isaacgym.py"
    click Assets "https://github.com/telehuman/pbhc/tree/main/description/robots/g1/"
    click DeployCode "https://github.com/telehuman/pbhc/blob/main/humanoidverse/deploy/mujoco.py"
    click Pretrained "https://github.com/telehuman/pbhc/blob/main/example/pretrained_/config.yaml"

    %% Styles
    classDef dataBlue fill:#CFE2F3,stroke:#036;color:#000
    classDef green fill:#D9EAD3,stroke:#073;color:#000
    classDef orange fill:#FCE5CD,stroke:#C60;color:#000
    classDef gray fill:#EDEDED,stroke:#666;color:#000
    classDef ext fill:#F4CCCC,stroke:#900,color:#000
```
