# jho-yonsei/hd-gcn architecture

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

- Interactive diagram: https://gitdiagram.com/jho-yonsei/hd-gcn
- Repository: https://github.com/jho-yonsei/hd-gcn

## Overview

HD-GCN is a research implementation for skeleton-based action recognition. The main workflow prepares NTU skeleton sequences, configures joint or bone inputs and a dataset split, then trains or tests the HD-GCN through `main.py`; testing can save class scores for a separate ensemble step. NW-UCLA has its own feeder, while graph construction and temporal convolution support the model internally. The README documents the broader workflow; links to unsampled runtime modules are limited to those supported by the tree and documented entry points.

Main entry points: [`main.py`](https://github.com/jho-yonsei/hd-gcn/blob/main/main.py) (Train and test), [`feeders/feeder_ntu.py`](https://github.com/jho-yonsei/hd-gcn/blob/main/feeders/feeder_ntu.py) (NTU feeder), [`data/ntu/get_raw_skes_data.py`](https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu/get_raw_skes_data.py) (Extract skeletons), [`ensemble.py`](https://github.com/jho-yonsei/hd-gcn/blob/main/ensemble.py) (Six-way ensemble)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_ntu_extract["Extract skeletons"]
  node_ntu_denoise["Denoise skeletons"]
  node_ntu_transform["Transform and split"]
  node_ntu120_extract["Extract 120 skeletons"]
  node_ntu120_denoise["Denoise 120 skeletons"]
  node_ntu120_transform["Transform and split 120"]
end

subgraph group_inputs["Input pipelines"]
  node_configs["Experiment configs"]
  node_ntu_feeder["NTU feeder<br/>[feeder_ntu.py]"]
  node_ucla_feeder["UCLA feeder<br/>[feeder_ucla.py]"]
  node_augment["Sequence transforms<br/>[tools.py]"]
end

subgraph group_recognition["Recognition runtime"]
  node_runner["Train and test<br/>[main.py]"]
  node_hdgcn["HD-GCN model<br/>[HDGCN.py]"]
  node_graph["Hierarchical graph"]
  node_graph_tools["Graph utilities<br/>[tools.py]"]
  node_torchlight["Runtime utilities<br/>[util.py]"]
end

subgraph group_results["Evaluation and results"]
  node_checkpoint["Model checkpoints"]
  node_scores["Test score files"]
  node_ensemble["Six-way ensemble<br/>[ensemble.py]"]
  node_prediction["Action predictions"]
end

node_researcher(("Researcher"))
node_ntu_raw["NTU skeletons"]
node_nw_data["NW-UCLA data"]

node_researcher -->|"runs preparation"| node_ntu_extract
node_ntu_raw -->|"provides skeletons"| node_ntu_extract
node_ntu_extract -->|"parsed skeletons"| node_ntu_denoise
node_ntu_denoise -->|"cleaned sequences"| node_ntu_transform
node_ntu_raw -->|"provides skeletons"| node_ntu120_extract
node_ntu120_extract -->|"parsed skeletons"| node_ntu120_denoise
node_ntu120_denoise -->|"cleaned sequences"| node_ntu120_transform
node_researcher -->|"starts experiment"| node_runner
node_configs -->|"configures run"| node_runner
node_ntu_transform -->|"supplies splits"| node_ntu_feeder
node_ntu120_transform -->|"supplies splits"| node_ntu_feeder
node_nw_data -->|"provides sequences"| node_ucla_feeder
node_runner -->|"loads NTU data"| node_ntu_feeder
node_runner -->|"loads UCLA data"| node_ucla_feeder
node_ntu_feeder -->|"uses transforms"| node_augment
node_runner -->|"trains or evaluates"| node_hdgcn
node_hdgcn -->|"constructs adjacency"| node_graph
node_graph -->|"builds graph"| node_graph_tools
node_runner -->|"uses runtime utilities"| node_torchlight
node_runner -->|"saves or loads weights"| node_checkpoint
node_runner -->|"saves test scores"| node_scores
node_researcher -->|"runs ensemble"| node_ensemble
node_scores -->|"provides modality scores"| node_ensemble
node_ensemble -->|"combines scores"| node_prediction
node_runner -->|"produces class scores"| node_prediction

click node_ntu_extract "https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu/get_raw_skes_data.py"
click node_ntu_denoise "https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu/get_raw_denoised_data.py"
click node_ntu_transform "https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu/seq_transformation.py"
click node_ntu120_extract "https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu120/get_raw_skes_data.py"
click node_ntu120_denoise "https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu120/get_raw_denoised_data.py"
click node_ntu120_transform "https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu120/seq_transformation.py"
click node_configs "https://github.com/jho-yonsei/hd-gcn/tree/main/config"
click node_ntu_feeder "https://github.com/jho-yonsei/hd-gcn/blob/main/feeders/feeder_ntu.py"
click node_ucla_feeder "https://github.com/jho-yonsei/hd-gcn/blob/main/feeders/feeder_ucla.py"
click node_augment "https://github.com/jho-yonsei/hd-gcn/blob/main/feeders/tools.py"
click node_runner "https://github.com/jho-yonsei/hd-gcn/blob/main/main.py"
click node_hdgcn "https://github.com/jho-yonsei/hd-gcn/blob/main/model/HDGCN.py"
click node_graph "https://github.com/jho-yonsei/hd-gcn/blob/main/graph/ntu_rgb_d_hierarchy.py"
click node_graph_tools "https://github.com/jho-yonsei/hd-gcn/blob/main/graph/tools.py"
click node_torchlight "https://github.com/jho-yonsei/hd-gcn/blob/main/torchlight/torchlight/util.py"
click node_ensemble "https://github.com/jho-yonsei/hd-gcn/blob/main/ensemble.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_ntu_extract,node_ntu_denoise,node_ntu_transform,node_ntu120_extract,node_ntu120_denoise,node_ntu120_transform toneBlue
class node_configs,node_ntu_feeder,node_ucla_feeder,node_augment toneAmber
class node_runner,node_hdgcn,node_graph,node_graph_tools,node_torchlight toneMint
class node_checkpoint,node_scores,node_ensemble,node_prediction toneRose
class node_researcher,node_ntu_raw,node_nw_data toneIndigo
```

## Components

### Data preparation

- [Extract skeletons](https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu/get_raw_skes_data.py): `data/ntu/get_raw_skes_data.py`
- [Denoise skeletons](https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu/get_raw_denoised_data.py): `data/ntu/get_raw_denoised_data.py`
- [Transform and split](https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu/seq_transformation.py): `data/ntu/seq_transformation.py`
- [Extract 120 skeletons](https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu120/get_raw_skes_data.py): `data/ntu120/get_raw_skes_data.py`
- [Denoise 120 skeletons](https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu120/get_raw_denoised_data.py): `data/ntu120/get_raw_denoised_data.py`
- [Transform and split 120](https://github.com/jho-yonsei/hd-gcn/blob/main/data/ntu120/seq_transformation.py): `data/ntu120/seq_transformation.py`

### Input pipelines

- [Experiment configs](https://github.com/jho-yonsei/hd-gcn/tree/main/config): `config`
- [NTU feeder](https://github.com/jho-yonsei/hd-gcn/blob/main/feeders/feeder_ntu.py): `feeders/feeder_ntu.py`
- [UCLA feeder](https://github.com/jho-yonsei/hd-gcn/blob/main/feeders/feeder_ucla.py): `feeders/feeder_ucla.py`
- [Sequence transforms](https://github.com/jho-yonsei/hd-gcn/blob/main/feeders/tools.py): `feeders/tools.py`

### Recognition runtime

- [Train and test](https://github.com/jho-yonsei/hd-gcn/blob/main/main.py): `main.py`
- [HD-GCN model](https://github.com/jho-yonsei/hd-gcn/blob/main/model/HDGCN.py): `model/HDGCN.py`
- [Hierarchical graph](https://github.com/jho-yonsei/hd-gcn/blob/main/graph/ntu_rgb_d_hierarchy.py): `graph/ntu_rgb_d_hierarchy.py`
- [Graph utilities](https://github.com/jho-yonsei/hd-gcn/blob/main/graph/tools.py): `graph/tools.py`
- [Runtime utilities](https://github.com/jho-yonsei/hd-gcn/blob/main/torchlight/torchlight/util.py): `torchlight/torchlight/util.py`

### Evaluation and results

- **Model checkpoints**
- **Test score files**
- [Six-way ensemble](https://github.com/jho-yonsei/hd-gcn/blob/main/ensemble.py): `ensemble.py`
- **Action predictions**

### Other components

- **Researcher**
- **NTU skeletons**
- **NW-UCLA data**

## Connections

- Researcher → Extract skeletons: runs preparation
- NTU skeletons → Extract skeletons: provides skeletons
- Extract skeletons → Denoise skeletons: parsed skeletons
- Denoise skeletons → Transform and split: cleaned sequences
- NTU skeletons → Extract 120 skeletons: provides skeletons
- Extract 120 skeletons → Denoise 120 skeletons: parsed skeletons
- Denoise 120 skeletons → Transform and split 120: cleaned sequences
- Researcher → Train and test: starts experiment
- Experiment configs → Train and test: configures run
- Transform and split → NTU feeder: supplies splits
- Transform and split 120 → NTU feeder: supplies splits
- NW-UCLA data → UCLA feeder: provides sequences
- Train and test → NTU feeder: loads NTU data
- Train and test → UCLA feeder: loads UCLA data
- NTU feeder → Sequence transforms: uses transforms
- Train and test → HD-GCN model: trains or evaluates
- HD-GCN model → Hierarchical graph: constructs adjacency
- Hierarchical graph → Graph utilities: builds graph
- Train and test → Runtime utilities: uses runtime utilities
- Train and test → Model checkpoints: saves or loads weights
- Train and test → Test score files: saves test scores
- Researcher → Six-way ensemble: runs ensemble
- Test score files → Six-way ensemble: provides modality scores
- Six-way ensemble → Action predictions: combines scores
- Train and test → Action predictions: produces class scores