# zju3dv/gvhmr architecture

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

- Interactive diagram: https://gitdiagram.com/zju3dv/gvhmr
- Repository: https://github.com/zju3dv/gvhmr

## Overview

GVHMR is a human-motion recovery system that estimates 3D body motion in gravity-aligned world coordinates from video-derived observations. The documented workflow is video input, optional camera-motion estimation, motion recovery, then evaluation or visualization; training and dataset testing are also supported. The graph includes the model’s conditioning, decoding, and post-processing layers, plus documented training-data and metric branches. Some demo and preprocessing wiring is unsampled, so uncertain links are omitted or marked unverified rather than inferred from module names.

Main entry points: [`hmr4d/model/gvhmr/pipeline/gvhmr_pipeline.py`](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/model/gvhmr/pipeline/gvhmr_pipeline.py) (Recovery pipeline), [`hmr4d/configs/store_gvhmr.py`](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/configs/store_gvhmr.py) (GVHMR config), [`hmr4d/build_gvhmr.py`](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/build_gvhmr.py) (Demo builder), [`hmr4d/model/gvhmr/gvhmr_pl.py`](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/model/gvhmr/gvhmr_pl.py) (Training model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Inputs and preprocessing"]
  node_demo_builder["Demo builder<br/>[build_gvhmr.py]"]
  node_video_io["Video I/O<br/>[video_io_utils.py]"]
  node_pose_features["Pose features<br/>[vitpose.py]"]
  node_camera_motion["Camera motion<br/>[simple_vo.py]"]
end

subgraph group_model["Motion recovery"]
  node_lightning_model["Training model<br/>[gvhmr_pl.py]"]
  node_pipeline["Recovery pipeline<br/>[gvhmr_pipeline.py]"]
  node_transformer["Motion transformer"]
  node_endecoder["Motion decoder<br/>[endecoder.py]"]
  node_postprocess["Motion postprocess<br/>[postprocess.py]"]
  node_stats["Motion statistics<br/>[stats_compose.py]"]
end

subgraph group_training["Training and evaluation"]
  node_img_dataset["Image-motion data<br/>[base_dataset.py]"]
  node_bedlam["BEDLAM dataset<br/>[bedlam.py]"]
  node_motion_dataset["Motion datasets"]
  node_datamodule["Data module"]
  node_train_entry["Train and test<br/>[train.py]"]
  node_config_store["GVHMR config<br/>[store_gvhmr.py]"]
  node_metrics["Dataset metrics"]
end

subgraph group_support["Geometry and visualization"]
  node_body_model["SMPL body models<br/>[smplx_utils.py]"]
  node_global_geometry["World coordinates<br/>[hmr_global.py]"]
  node_visualization["Motion visualization<br/>[renderer.py]"]
end

node_video_user(("Video user"))

node_video_user -->|"runs demo"| node_demo_builder
node_demo_builder -.->|"uses video tools"| node_video_io
node_demo_builder -.->|"extracts pose"| node_pose_features
node_demo_builder -.->|"estimates camera"| node_camera_motion
node_train_entry -->|"loads configuration"| node_config_store
node_config_store -->|"registers dataset"| node_bedlam
node_config_store -->|"registers datasets"| node_motion_dataset
node_config_store -->|"registers model"| node_lightning_model
node_config_store -->|"registers decoder"| node_endecoder
node_config_store -->|"registers metrics"| node_metrics
node_bedlam -->|"inherits dataset"| node_img_dataset
node_datamodule -.->|"loads samples"| node_bedlam
node_datamodule -.->|"loads samples"| node_motion_dataset
node_lightning_model -.->|"runs pipeline"| node_pipeline
node_pipeline -->|"decodes predictions"| node_endecoder
node_pipeline -->|"normalizes features"| node_stats
node_pipeline -.->|"invokes denoiser"| node_transformer
node_lightning_model -->|"post-processes output"| node_postprocess
node_postprocess -->|"uses decoder"| node_endecoder
node_pipeline -->|"computes body joints"| node_body_model
node_pipeline -->|"uses world transforms"| node_global_geometry
node_metrics -.->|"evaluates body output"| node_body_model
node_metrics -.->|"visualizes results"| node_visualization

click node_demo_builder "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/build_gvhmr.py"
click node_video_io "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/utils/video_io_utils.py"
click node_pose_features "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/utils/preproc/vitpose.py"
click node_camera_motion "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/utils/preproc/relpose/simple_vo.py"
click node_img_dataset "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/dataset/imgfeat_motion/base_dataset.py"
click node_bedlam "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/dataset/bedlam/bedlam.py"
click node_motion_dataset "https://github.com/zju3dv/gvhmr/tree/main/hmr4d/dataset/pure_motion"
click node_datamodule "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/datamodule/mocap_trainX_testY.py"
click node_train_entry "https://github.com/zju3dv/gvhmr/blob/main/tools/train.py"
click node_config_store "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/configs/store_gvhmr.py"
click node_lightning_model "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/model/gvhmr/gvhmr_pl.py"
click node_pipeline "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/model/gvhmr/pipeline/gvhmr_pipeline.py"
click node_transformer "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/network/gvhmr/relative_transformer.py"
click node_endecoder "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/model/gvhmr/utils/endecoder.py"
click node_postprocess "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/model/gvhmr/utils/postprocess.py"
click node_stats "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/model/gvhmr/utils/stats_compose.py"
click node_body_model "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/utils/smplx_utils.py"
click node_global_geometry "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/utils/geo/hmr_global.py"
click node_metrics "https://github.com/zju3dv/gvhmr/tree/main/hmr4d/model/gvhmr/callbacks"
click node_visualization "https://github.com/zju3dv/gvhmr/blob/main/hmr4d/utils/vis/renderer.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_demo_builder,node_video_io,node_pose_features,node_camera_motion,node_video_user toneBlue
class node_lightning_model,node_pipeline,node_transformer,node_endecoder,node_postprocess,node_stats toneAmber
class node_img_dataset,node_bedlam,node_motion_dataset,node_datamodule,node_train_entry,node_config_store,node_metrics toneMint
class node_body_model,node_global_geometry,node_visualization toneRose
```

## Components

### Inputs and preprocessing

- [Demo builder](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/build_gvhmr.py): `hmr4d/build_gvhmr.py`
- [Video I/O](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/utils/video_io_utils.py): `hmr4d/utils/video_io_utils.py`
- [Pose features](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/utils/preproc/vitpose.py): `hmr4d/utils/preproc/vitpose.py`
- [Camera motion](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/utils/preproc/relpose/simple_vo.py): `hmr4d/utils/preproc/relpose/simple_vo.py`

### Motion recovery

- [Training model](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/model/gvhmr/gvhmr_pl.py): `hmr4d/model/gvhmr/gvhmr_pl.py`
- [Recovery pipeline](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/model/gvhmr/pipeline/gvhmr_pipeline.py): `hmr4d/model/gvhmr/pipeline/gvhmr_pipeline.py`
- [Motion transformer](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/network/gvhmr/relative_transformer.py): `hmr4d/network/gvhmr/relative_transformer.py`
- [Motion decoder](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/model/gvhmr/utils/endecoder.py): `hmr4d/model/gvhmr/utils/endecoder.py`
- [Motion postprocess](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/model/gvhmr/utils/postprocess.py): `hmr4d/model/gvhmr/utils/postprocess.py`
- [Motion statistics](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/model/gvhmr/utils/stats_compose.py): `hmr4d/model/gvhmr/utils/stats_compose.py`

### Training and evaluation

- [Image-motion data](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/dataset/imgfeat_motion/base_dataset.py): `hmr4d/dataset/imgfeat_motion/base_dataset.py`
- [BEDLAM dataset](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/dataset/bedlam/bedlam.py): `hmr4d/dataset/bedlam/bedlam.py`
- [Motion datasets](https://github.com/zju3dv/gvhmr/tree/main/hmr4d/dataset/pure_motion): `hmr4d/dataset/pure_motion`
- [Data module](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/datamodule/mocap_trainX_testY.py): `hmr4d/datamodule/mocap_trainX_testY.py`
- [Train and test](https://github.com/zju3dv/gvhmr/blob/main/tools/train.py): `tools/train.py`
- [GVHMR config](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/configs/store_gvhmr.py): `hmr4d/configs/store_gvhmr.py`
- [Dataset metrics](https://github.com/zju3dv/gvhmr/tree/main/hmr4d/model/gvhmr/callbacks): `hmr4d/model/gvhmr/callbacks`

### Geometry and visualization

- [SMPL body models](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/utils/smplx_utils.py): `hmr4d/utils/smplx_utils.py`
- [World coordinates](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/utils/geo/hmr_global.py): `hmr4d/utils/geo/hmr_global.py`
- [Motion visualization](https://github.com/zju3dv/gvhmr/blob/main/hmr4d/utils/vis/renderer.py): `hmr4d/utils/vis/renderer.py`

### Other components

- **Video user**

## Connections

- Video user → Demo builder: runs demo
- Demo builder → Video I/O: uses video tools
- Demo builder → Pose features: extracts pose
- Demo builder → Camera motion: estimates camera
- Train and test → GVHMR config: loads configuration (evidence: `tools/train.py`)
- GVHMR config → BEDLAM dataset: registers dataset (evidence: `hmr4d/configs/store_gvhmr.py`)
- GVHMR config → Motion datasets: registers datasets (evidence: `hmr4d/configs/store_gvhmr.py`)
- GVHMR config → Training model: registers model (evidence: `hmr4d/configs/store_gvhmr.py`)
- GVHMR config → Motion decoder: registers decoder (evidence: `hmr4d/configs/store_gvhmr.py`)
- GVHMR config → Dataset metrics: registers metrics (evidence: `hmr4d/configs/store_gvhmr.py`)
- BEDLAM dataset → Image-motion data: inherits dataset (evidence: `hmr4d/dataset/bedlam/bedlam.py`)
- Data module → BEDLAM dataset: loads samples
- Data module → Motion datasets: loads samples
- Training model → Recovery pipeline: runs pipeline
- Recovery pipeline → Motion decoder: decodes predictions (evidence: `hmr4d/model/gvhmr/pipeline/gvhmr_pipeline.py`)
- Recovery pipeline → Motion statistics: normalizes features (evidence: `hmr4d/model/gvhmr/pipeline/gvhmr_pipeline.py`)
- Recovery pipeline → Motion transformer: invokes denoiser
- Training model → Motion postprocess: post-processes output (evidence: `hmr4d/model/gvhmr/gvhmr_pl.py`)
- Motion postprocess → Motion decoder: uses decoder (evidence: `hmr4d/model/gvhmr/utils/postprocess.py`)
- Recovery pipeline → SMPL body models: computes body joints (evidence: `hmr4d/model/gvhmr/pipeline/gvhmr_pipeline.py`)
- Recovery pipeline → World coordinates: uses world transforms (evidence: `hmr4d/model/gvhmr/pipeline/gvhmr_pipeline.py`)
- Dataset metrics → SMPL body models: evaluates body output (evidence: `hmr4d/model/gvhmr/callbacks/metric_rich.py`)
- Dataset metrics → Motion visualization: visualizes results (evidence: `hmr4d/model/gvhmr/callbacks/metric_rich.py`)
