# hongwenzhang/pymaf-x architecture

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

- Interactive diagram: https://gitdiagram.com/hongwenzhang/pymaf-x
- Repository: https://github.com/hongwenzhang/pymaf-x

## Overview

PyMAF-X reconstructs a 3D human body from monocular images or video, including body, hands, and face. Its demo workflow accepts image or video input, prepares person/pose crops, regresses pose and shape, builds a parametric mesh, and saves visual results. A separate training workflow loads annotated datasets, optimizes the regressor, evaluates predictions, and saves checkpoints. The README documents these capabilities; some demo and training wiring is inferred from documented entry points because those source excerpts are incomplete.

Main entry points: [`apps/demo_smplx.py`](https://github.com/hongwenzhang/pymaf-x/blob/smplx/apps/demo_smplx.py) (Demo Runner), [`core/trainer.py`](https://github.com/hongwenzhang/pymaf-x/blob/smplx/core/trainer.py) (Training Loop), [`models/pymaf_net.py`](https://github.com/hongwenzhang/pymaf-x/blob/smplx/models/pymaf_net.py) (PyMAF-X Regressor), [`apps/train.py`](https://github.com/hongwenzhang/pymaf-x/blob/smplx/apps/train.py) (Training Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_demo["Demo Inference"]
  node_demo["Demo Runner<br/>[demo_smplx.py]"]
  node_infdata["Inference Inputs<br/>[inference.py]"]
  node_tracker["Pose Tracking<br/>[pose_tracker.py]"]
  node_demoout["Saved Results"]
end

subgraph group_models["Reconstruction Models"]
  node_pymaf["PyMAF-X Regressor<br/>[pymaf_net.py]"]
  node_backbone["Pose Backbones<br/>[pose_resnet.py]"]
  node_transformer["Graph Transformer"]
  node_bodymodel["Body Mesh Models<br/>[smpl.py]"]
end

subgraph group_training["Model Training"]
  node_trainapp["Training Entry<br/>[train.py]"]
  node_options["Training Options<br/>[train_options.py]"]
  node_trainer["Training Loop<br/>[trainer.py]"]
  node_dataset["Dataset Loading<br/>[base_dataset.py]"]
  node_mixed["Mixed Datasets<br/>[mixed_dataset.py]"]
  node_losses["Training Objectives<br/>[trainer.py]"]
  node_checkpoint["Checkpoints<br/>[saver.py]"]
end

subgraph group_support["Geometry and Visualization"]
  node_render["Mesh Rendering<br/>[renderer.py]"]
  node_meshio["Mesh Export<br/>[mesh_io.py]"]
  node_geometry["Geometry Utilities<br/>[geometry.py]"]
end

node_user(("Image or Video User"))
node_trainuser(("Training Operator"))

node_user -->|"provides media"| node_demo
node_demo -->|"prepares frames"| node_infdata
node_demo -->|"tracks poses"| node_tracker
node_demo -->|"runs regression"| node_pymaf
node_pymaf -->|"extracts features"| node_backbone
node_pymaf -.->|"uses attention"| node_transformer
node_pymaf -->|"predicts mesh"| node_bodymodel
node_demo -->|"loads model"| node_bodymodel
node_demo -->|"renders output"| node_render
node_render -->|"produces visuals"| node_demoout
node_demo -->|"exports mesh"| node_meshio
node_meshio -->|"writes mesh"| node_demoout
node_trainuser -->|"starts training"| node_trainapp
node_trainapp -->|"parses settings"| node_options
node_trainapp -->|"starts loop"| node_trainer
node_trainer -->|"loads selections"| node_mixed
node_mixed -->|"combines samples"| node_dataset
node_trainer -->|"trains regressor"| node_pymaf
node_trainer -->|"builds targets"| node_bodymodel
node_trainer -->|"computes losses"| node_losses
node_trainer -->|"saves state"| node_checkpoint
node_pymaf -->|"uses transforms"| node_geometry

click node_demo "https://github.com/hongwenzhang/pymaf-x/blob/smplx/apps/demo_smplx.py"
click node_infdata "https://github.com/hongwenzhang/pymaf-x/blob/smplx/datasets/inference.py"
click node_tracker "https://github.com/hongwenzhang/pymaf-x/blob/smplx/utils/pose_tracker.py"
click node_pymaf "https://github.com/hongwenzhang/pymaf-x/blob/smplx/models/pymaf_net.py"
click node_backbone "https://github.com/hongwenzhang/pymaf-x/blob/smplx/models/pose_resnet.py"
click node_transformer "https://github.com/hongwenzhang/pymaf-x/blob/smplx/models/transformers/bert/modeling_graphormer.py"
click node_bodymodel "https://github.com/hongwenzhang/pymaf-x/blob/smplx/models/smpl.py"
click node_render "https://github.com/hongwenzhang/pymaf-x/blob/smplx/utils/renderer.py"
click node_meshio "https://github.com/hongwenzhang/pymaf-x/blob/smplx/utils/mesh_io.py"
click node_trainapp "https://github.com/hongwenzhang/pymaf-x/blob/smplx/apps/train.py"
click node_options "https://github.com/hongwenzhang/pymaf-x/blob/smplx/core/train_options.py"
click node_trainer "https://github.com/hongwenzhang/pymaf-x/blob/smplx/core/trainer.py"
click node_dataset "https://github.com/hongwenzhang/pymaf-x/blob/smplx/datasets/base_dataset.py"
click node_mixed "https://github.com/hongwenzhang/pymaf-x/blob/smplx/datasets/mixed_dataset.py"
click node_losses "https://github.com/hongwenzhang/pymaf-x/blob/smplx/core/trainer.py"
click node_checkpoint "https://github.com/hongwenzhang/pymaf-x/blob/smplx/utils/saver.py"
click node_geometry "https://github.com/hongwenzhang/pymaf-x/blob/smplx/utils/geometry.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,node_infdata,node_tracker,node_demoout,node_user toneBlue
class node_pymaf,node_backbone,node_transformer,node_bodymodel toneAmber
class node_trainapp,node_options,node_trainer,node_dataset,node_mixed,node_losses,node_checkpoint toneMint
class node_render,node_meshio,node_geometry toneRose
class node_trainuser toneIndigo
```

## Components

### Demo Inference

- [Demo Runner](https://github.com/hongwenzhang/pymaf-x/blob/smplx/apps/demo_smplx.py): `apps/demo_smplx.py`
- [Inference Inputs](https://github.com/hongwenzhang/pymaf-x/blob/smplx/datasets/inference.py): `datasets/inference.py`
- [Pose Tracking](https://github.com/hongwenzhang/pymaf-x/blob/smplx/utils/pose_tracker.py): `utils/pose_tracker.py`
- **Saved Results**

### Reconstruction Models

- [PyMAF-X Regressor](https://github.com/hongwenzhang/pymaf-x/blob/smplx/models/pymaf_net.py): `models/pymaf_net.py`
- [Pose Backbones](https://github.com/hongwenzhang/pymaf-x/blob/smplx/models/pose_resnet.py): `models/pose_resnet.py`
- [Graph Transformer](https://github.com/hongwenzhang/pymaf-x/blob/smplx/models/transformers/bert/modeling_graphormer.py): `models/transformers/bert/modeling_graphormer.py`
- [Body Mesh Models](https://github.com/hongwenzhang/pymaf-x/blob/smplx/models/smpl.py): `models/smpl.py`

### Model Training

- [Training Entry](https://github.com/hongwenzhang/pymaf-x/blob/smplx/apps/train.py): `apps/train.py`
- [Training Options](https://github.com/hongwenzhang/pymaf-x/blob/smplx/core/train_options.py): `core/train_options.py`
- [Training Loop](https://github.com/hongwenzhang/pymaf-x/blob/smplx/core/trainer.py): `core/trainer.py`
- [Dataset Loading](https://github.com/hongwenzhang/pymaf-x/blob/smplx/datasets/base_dataset.py): `datasets/base_dataset.py`
- [Mixed Datasets](https://github.com/hongwenzhang/pymaf-x/blob/smplx/datasets/mixed_dataset.py): `datasets/mixed_dataset.py`
- [Training Objectives](https://github.com/hongwenzhang/pymaf-x/blob/smplx/core/trainer.py): `core/trainer.py`
- [Checkpoints](https://github.com/hongwenzhang/pymaf-x/blob/smplx/utils/saver.py): `utils/saver.py`

### Geometry and Visualization

- [Mesh Rendering](https://github.com/hongwenzhang/pymaf-x/blob/smplx/utils/renderer.py): `utils/renderer.py`
- [Mesh Export](https://github.com/hongwenzhang/pymaf-x/blob/smplx/utils/mesh_io.py): `utils/mesh_io.py`
- [Geometry Utilities](https://github.com/hongwenzhang/pymaf-x/blob/smplx/utils/geometry.py): `utils/geometry.py`

### Other components

- **Image or Video User**
- **Training Operator**

## Connections

- Image or Video User → Demo Runner: provides media
- Demo Runner → Inference Inputs: prepares frames
- Demo Runner → Pose Tracking: tracks poses
- Demo Runner → PyMAF-X Regressor: runs regression
- PyMAF-X Regressor → Pose Backbones: extracts features
- PyMAF-X Regressor → Graph Transformer: uses attention
- PyMAF-X Regressor → Body Mesh Models: predicts mesh
- Demo Runner → Body Mesh Models: loads model
- Demo Runner → Mesh Rendering: renders output
- Mesh Rendering → Saved Results: produces visuals
- Demo Runner → Mesh Export: exports mesh
- Mesh Export → Saved Results: writes mesh
- Training Operator → Training Entry: starts training
- Training Entry → Training Options: parses settings
- Training Entry → Training Loop: starts loop
- Training Loop → Mixed Datasets: loads selections
- Mixed Datasets → Dataset Loading: combines samples
- Training Loop → PyMAF-X Regressor: trains regressor
- Training Loop → Body Mesh Models: builds targets
- Training Loop → Training Objectives: computes losses
- Training Loop → Checkpoints: saves state
- PyMAF-X Regressor → Geometry Utilities: uses transforms