# naturalpad-studio/instanthmr architecture

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

- Interactive diagram: https://gitdiagram.com/naturalpad-studio/instanthmr
- Repository: https://github.com/naturalpad-studio/instanthmr

## Overview

InstantHMR is a human-mesh-recovery product: images or video frames become per-person 2D keypoints, 3D joints, pose/shape parameters, and body meshes. The demo and Python pipeline detect people, run model inference, optionally filter poses over time, and present results. Separate branches support dataset acquisition/preparation, model training, and benchmark validation. Runtime links follow the sampled pipeline and README; several dataset and training internals were not sampled, so their undocumented connections are omitted.

Main entry points: [`training/train.py`](https://github.com/naturalpad-studio/instanthmr/blob/main/training/train.py) (Model training), [`instanthmr/pipeline.py`](https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/pipeline.py) (Pose pipeline), [`instanthmr/inference.py`](https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/inference.py) (HMR inference), [`demo.py`](https://github.com/naturalpad-studio/instanthmr/blob/main/demo.py) (Demo input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Inference runtime"]
  node_pipeline["Pose pipeline<br/>[pipeline.py]"]
  node_detector["Person detector<br/>[detector.py]"]
  node_inference["HMR inference<br/>[inference.py]"]
  node_models["Model resolution<br/>[models.py]"]
  node_skeleton["MHR skeleton<br/>[skeleton.py]"]
  node_posefilter["Pose filtering<br/>[smoothing.py]"]
end

subgraph group_presentation["Demo presentation"]
  node_demo["Demo input<br/>[demo.py]"]
  node_temporal["Output smoothing<br/>[smoothing.py]"]
  node_visualizer["Rerun visualization<br/>[visualizer.py]"]
end

subgraph group_data["Dataset preparation"]
  node_registry["Dataset registry<br/>[registry.py]"]
  node_acquisition["Dataset acquisition"]
  node_diskplan["Disk planning<br/>[plan_disk.py]"]
  node_splitbuild["Split construction<br/>[build_split.py]"]
  node_annotations["Annotation conversion<br/>[parquet_to_npz.py]"]
end

subgraph group_learning["Training and evaluation"]
  node_trainer["Model training<br/>[train.py]"]
  node_ddptrainer["Distributed training<br/>[train_ddp.py]"]
  node_cont["Continuous MHR<br/>[mhr_cont.py]"]
  node_kinematic["Kinematic fit<br/>[kinematic_fit.py]"]
  node_validation["3DPW validation<br/>[val3dpw.py]"]
  node_benchmark["Benchmark evaluation"]
end

node_user(("User / video source"))
node_datasetfiles[("Source datasets")]
node_modeloutput["Pose and mesh"]

node_user -->|"provides frames"| node_demo
node_demo -->|"runs"| node_pipeline
node_pipeline -->|"detects people"| node_detector
node_pipeline -->|"predicts poses"| node_inference
node_pipeline -->|"configures filter"| node_posefilter
node_inference -->|"resolves body"| node_models
node_inference -->|"uses rig"| node_skeleton
node_inference -->|"produces"| node_modeloutput
node_demo -->|"optionally smooths"| node_temporal
node_demo -->|"renders results"| node_visualizer
node_datasetfiles -.->|"supplies data"| node_acquisition
node_registry -->|"specifies sources"| node_acquisition
node_acquisition -.->|"plans storage"| node_diskplan
node_diskplan -.->|"guides build"| node_splitbuild
node_registry -->|"resolves split"| node_splitbuild
node_splitbuild -->|"converts annotations"| node_annotations
node_annotations -->|"creates training data"| node_trainer
node_trainer -.->|"uses parameterization"| node_cont
node_ddptrainer -->|"reuses training code"| node_trainer
node_trainer -->|"validates on 3DPW"| node_validation
node_trainer -.->|"exports fit capability"| node_kinematic
node_validation -->|"uses metrics"| node_benchmark

click node_demo "https://github.com/naturalpad-studio/instanthmr/blob/main/demo.py"
click node_pipeline "https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/pipeline.py"
click node_detector "https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/detector.py"
click node_inference "https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/inference.py"
click node_models "https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/models.py"
click node_skeleton "https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/skeleton.py"
click node_posefilter "https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/smoothing.py"
click node_temporal "https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/smoothing.py"
click node_visualizer "https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/visualizer.py"
click node_registry "https://github.com/naturalpad-studio/instanthmr/blob/main/datasets_pipeline/registry.py"
click node_acquisition "https://github.com/naturalpad-studio/instanthmr/tree/main/datasets_pipeline"
click node_diskplan "https://github.com/naturalpad-studio/instanthmr/blob/main/datasets_pipeline/plan_disk.py"
click node_splitbuild "https://github.com/naturalpad-studio/instanthmr/blob/main/datasets_pipeline/build_split.py"
click node_annotations "https://github.com/naturalpad-studio/instanthmr/blob/main/tools/parquet_to_npz.py"
click node_trainer "https://github.com/naturalpad-studio/instanthmr/blob/main/training/train.py"
click node_ddptrainer "https://github.com/naturalpad-studio/instanthmr/blob/main/training/train_ddp.py"
click node_cont "https://github.com/naturalpad-studio/instanthmr/blob/main/training/mhr_cont.py"
click node_kinematic "https://github.com/naturalpad-studio/instanthmr/blob/main/training/kinematic_fit.py"
click node_validation "https://github.com/naturalpad-studio/instanthmr/blob/main/training/val3dpw.py"
click node_benchmark "https://github.com/naturalpad-studio/instanthmr/tree/main/benchmark"

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_pipeline,node_detector,node_inference,node_models,node_skeleton,node_posefilter,node_user toneBlue
class node_demo,node_temporal,node_visualizer,node_datasetfiles toneAmber
class node_registry,node_acquisition,node_diskplan,node_splitbuild,node_annotations toneMint
class node_trainer,node_ddptrainer,node_cont,node_kinematic,node_validation,node_benchmark toneRose
class node_modeloutput toneIndigo
```

## Components

### Inference runtime

- [Pose pipeline](https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/pipeline.py): `instanthmr/pipeline.py`
- [Person detector](https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/detector.py): `instanthmr/detector.py`
- [HMR inference](https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/inference.py): `instanthmr/inference.py`
- [Model resolution](https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/models.py): `instanthmr/models.py`
- [MHR skeleton](https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/skeleton.py): `instanthmr/skeleton.py`
- [Pose filtering](https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/smoothing.py): `instanthmr/smoothing.py`

### Demo presentation

- [Demo input](https://github.com/naturalpad-studio/instanthmr/blob/main/demo.py): `demo.py`
- [Output smoothing](https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/smoothing.py): `instanthmr/smoothing.py`
- [Rerun visualization](https://github.com/naturalpad-studio/instanthmr/blob/main/instanthmr/visualizer.py): `instanthmr/visualizer.py`

### Dataset preparation

- [Dataset registry](https://github.com/naturalpad-studio/instanthmr/blob/main/datasets_pipeline/registry.py): `datasets_pipeline/registry.py`
- [Dataset acquisition](https://github.com/naturalpad-studio/instanthmr/tree/main/datasets_pipeline): `datasets_pipeline`
- [Disk planning](https://github.com/naturalpad-studio/instanthmr/blob/main/datasets_pipeline/plan_disk.py): `datasets_pipeline/plan_disk.py`
- [Split construction](https://github.com/naturalpad-studio/instanthmr/blob/main/datasets_pipeline/build_split.py): `datasets_pipeline/build_split.py`
- [Annotation conversion](https://github.com/naturalpad-studio/instanthmr/blob/main/tools/parquet_to_npz.py): `tools/parquet_to_npz.py`

### Training and evaluation

- [Model training](https://github.com/naturalpad-studio/instanthmr/blob/main/training/train.py): `training/train.py`
- [Distributed training](https://github.com/naturalpad-studio/instanthmr/blob/main/training/train_ddp.py): `training/train_ddp.py`
- [Continuous MHR](https://github.com/naturalpad-studio/instanthmr/blob/main/training/mhr_cont.py): `training/mhr_cont.py`
- [Kinematic fit](https://github.com/naturalpad-studio/instanthmr/blob/main/training/kinematic_fit.py): `training/kinematic_fit.py`
- [3DPW validation](https://github.com/naturalpad-studio/instanthmr/blob/main/training/val3dpw.py): `training/val3dpw.py`
- [Benchmark evaluation](https://github.com/naturalpad-studio/instanthmr/tree/main/benchmark): `benchmark`

### Other components

- **User / video source**
- **Source datasets**
- **Pose and mesh**

## Connections

- User / video source → Demo input: provides frames (evidence: `README.md`)
- Demo input → Pose pipeline: runs (evidence: `demo.py`)
- Pose pipeline → Person detector: detects people (evidence: `instanthmr/pipeline.py`)
- Pose pipeline → HMR inference: predicts poses (evidence: `instanthmr/pipeline.py`)
- Pose pipeline → Pose filtering: configures filter (evidence: `instanthmr/pipeline.py`)
- HMR inference → Model resolution: resolves body (evidence: `instanthmr/inference.py`)
- HMR inference → MHR skeleton: uses rig (evidence: `README.md`)
- HMR inference → Pose and mesh: produces (evidence: `README.md`)
- Demo input → Output smoothing: optionally smooths (evidence: `demo.py`)
- Demo input → Rerun visualization: renders results (evidence: `demo.py`)
- Source datasets → Dataset acquisition: supplies data
- Dataset registry → Dataset acquisition: specifies sources (evidence: `datasets_pipeline/registry.py`)
- Dataset acquisition → Disk planning: plans storage (evidence: `datasets_pipeline/probe_split.py`)
- Disk planning → Split construction: guides build
- Dataset registry → Split construction: resolves split (evidence: `datasets_pipeline/build_split.py`)
- Split construction → Annotation conversion: converts annotations (evidence: `datasets_pipeline/build_split.py`)
- Annotation conversion → Model training: creates training data (evidence: `README.md`)
- Model training → Continuous MHR: uses parameterization
- Distributed training → Model training: reuses training code (evidence: `training/train_ddp.py`)
- Model training → 3DPW validation: validates on 3DPW (evidence: `training/train_ddp.py`)
- Model training → Kinematic fit: exports fit capability
- 3DPW validation → Benchmark evaluation: uses metrics (evidence: `training/val3dpw.py`)