# supermhp/gupnet architecture

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

- Interactive diagram: https://gitdiagram.com/supermhp/gupnet
- Repository: https://github.com/supermhp/gupnet

## Overview

GUPNet is a research implementation for monocular 3D object detection on KITTI. The main workflow loads KITTI images, calibration and labels; trains a network to predict 2D and 3D object properties with detection and uncertainty-aware losses; then decodes predictions into KITTI detection files for validation or submission. The entry point also supports evaluating a checkpoint, with KITTI’s offline evaluator as a separate step. The graph follows the documented workflow and sampled call sites; several helper implementations and the tester were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`code/tools/train_val.py`](https://github.com/supermhp/gupnet/blob/main/code/tools/train_val.py) (Train/eval entry), [`code/lib/helpers/trainer_helper.py`](https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/trainer_helper.py) (Trainer), [`code/lib/models/gupnet.py`](https://github.com/supermhp/gupnet/blob/main/code/lib/models/gupnet.py) (GUPNet), [`code/lib/helpers/tester_helper.py`](https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/tester_helper.py) (Tester)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["KITTI data"]
  node_loader_builder["Loader builder"]
  node_dataset["KITTI dataset reader<br/>[kitti.py]"]
  node_dataset_utils["Dataset utilities<br/>[utils.py]"]
end

subgraph group_model["Detection model"]
  node_model_builder["Model builder<br/>[model_helper.py]"]
  node_gupnet["GUPNet<br/>[gupnet.py]"]
  node_backbones["Feature backbones"]
  node_neck["Feature fusion<br/>[dlaup.py]"]
  node_operators["Network operators"]
end

subgraph group_training["Training"]
  node_entry["Train/eval entry<br/>[train_val.py]"]
  node_config["Experiment config<br/>[config.yaml]"]
  node_trainer["Trainer<br/>[trainer_helper.py]"]
  node_loss["Detection losses<br/>[loss_function.py]"]
  node_optimizer["Optimizer builder"]
  node_scheduler["LR scheduler"]
  node_checkpoint["Checkpoint helpers<br/>[save_helper.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_tester["Tester<br/>[tester_helper.py]"]
  node_decoder["Prediction decoder<br/>[decode_helper.py]"]
  node_detections["KITTI detection files"]
  node_evaluator["KITTI offline evaluator"]
end

node_researcher(("Researcher"))
node_kitti[("KITTI dataset")]
node_labels[("KITTI ground truth")]

node_researcher -->|"runs"| node_entry
node_researcher -->|"provides data"| node_kitti
node_entry -->|"loads"| node_config
node_entry -->|"builds loaders"| node_loader_builder
node_loader_builder -->|"creates"| node_dataset
node_dataset -->|"reads images and labels"| node_kitti
node_dataset -->|"uses"| node_dataset_utils
node_entry -->|"builds model"| node_model_builder
node_model_builder -->|"constructs"| node_gupnet
node_gupnet -->|"extracts features"| node_backbones
node_gupnet -->|"fuses features"| node_neck
node_gupnet -.->|"uses"| node_operators
node_entry -->|"builds optimizer"| node_optimizer
node_entry -->|"builds schedulers"| node_scheduler
node_entry -->|"starts training"| node_trainer
node_trainer -->|"consumes batches"| node_loader_builder
node_trainer -->|"runs batches"| node_gupnet
node_trainer -->|"computes losses"| node_loss
node_trainer -->|"updates weights"| node_optimizer
node_trainer -->|"steps schedule"| node_scheduler
node_trainer -->|"saves and resumes"| node_checkpoint
node_entry -->|"starts evaluation"| node_tester
node_tester -->|"runs inference"| node_gupnet
node_tester -->|"decodes predictions"| node_decoder
node_decoder -->|"decodes angles"| node_dataset_utils
node_tester -->|"writes results"| node_detections
node_researcher -->|"runs evaluation"| node_evaluator
node_evaluator -->|"scores results"| node_detections
node_evaluator -->|"compares with"| node_labels

click node_entry "https://github.com/supermhp/gupnet/blob/main/code/tools/train_val.py"
click node_config "https://github.com/supermhp/gupnet/blob/main/code/experiments/config.yaml"
click node_loader_builder "https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/dataloader_helper.py"
click node_dataset "https://github.com/supermhp/gupnet/blob/main/code/lib/datasets/kitti.py"
click node_dataset_utils "https://github.com/supermhp/gupnet/blob/main/code/lib/datasets/utils.py"
click node_model_builder "https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/model_helper.py"
click node_gupnet "https://github.com/supermhp/gupnet/blob/main/code/lib/models/gupnet.py"
click node_backbones "https://github.com/supermhp/gupnet/tree/main/code/lib/backbones"
click node_neck "https://github.com/supermhp/gupnet/blob/main/code/lib/backbones/dlaup.py"
click node_operators "https://github.com/supermhp/gupnet/tree/main/code/lib/operators"
click node_trainer "https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/trainer_helper.py"
click node_loss "https://github.com/supermhp/gupnet/blob/main/code/lib/losses/loss_function.py"
click node_optimizer "https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/optimizer_helper.py"
click node_scheduler "https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/scheduler_helper.py"
click node_checkpoint "https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/save_helper.py"
click node_tester "https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/tester_helper.py"
click node_decoder "https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/decode_helper.py"
click node_evaluator "https://github.com/supermhp/gupnet/blob/main/code/tools/kitti_eval/evaluate_object_3d_offline_ap40.cpp"

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_loader_builder,node_dataset,node_dataset_utils toneBlue
class node_model_builder,node_gupnet,node_backbones,node_neck,node_operators,node_kitti,node_labels toneAmber
class node_entry,node_config,node_trainer,node_loss,node_optimizer,node_scheduler,node_checkpoint toneMint
class node_tester,node_decoder,node_detections,node_evaluator toneRose
class node_researcher toneIndigo
```

## Components

### KITTI data

- [Loader builder](https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/dataloader_helper.py): `code/lib/helpers/dataloader_helper.py`
- [KITTI dataset reader](https://github.com/supermhp/gupnet/blob/main/code/lib/datasets/kitti.py): `code/lib/datasets/kitti.py`
- [Dataset utilities](https://github.com/supermhp/gupnet/blob/main/code/lib/datasets/utils.py): `code/lib/datasets/utils.py`

### Detection model

- [Model builder](https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/model_helper.py): `code/lib/helpers/model_helper.py`
- [GUPNet](https://github.com/supermhp/gupnet/blob/main/code/lib/models/gupnet.py): `code/lib/models/gupnet.py`
- [Feature backbones](https://github.com/supermhp/gupnet/tree/main/code/lib/backbones): `code/lib/backbones`
- [Feature fusion](https://github.com/supermhp/gupnet/blob/main/code/lib/backbones/dlaup.py): `code/lib/backbones/dlaup.py`
- [Network operators](https://github.com/supermhp/gupnet/tree/main/code/lib/operators): `code/lib/operators`

### Training

- [Train/eval entry](https://github.com/supermhp/gupnet/blob/main/code/tools/train_val.py): `code/tools/train_val.py`
- [Experiment config](https://github.com/supermhp/gupnet/blob/main/code/experiments/config.yaml): `code/experiments/config.yaml`
- [Trainer](https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/trainer_helper.py): `code/lib/helpers/trainer_helper.py`
- [Detection losses](https://github.com/supermhp/gupnet/blob/main/code/lib/losses/loss_function.py): `code/lib/losses/loss_function.py`
- [Optimizer builder](https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/optimizer_helper.py): `code/lib/helpers/optimizer_helper.py`
- [LR scheduler](https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/scheduler_helper.py): `code/lib/helpers/scheduler_helper.py`
- [Checkpoint helpers](https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/save_helper.py): `code/lib/helpers/save_helper.py`

### Evaluation

- [Tester](https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/tester_helper.py): `code/lib/helpers/tester_helper.py`
- [Prediction decoder](https://github.com/supermhp/gupnet/blob/main/code/lib/helpers/decode_helper.py): `code/lib/helpers/decode_helper.py`
- **KITTI detection files**
- [KITTI offline evaluator](https://github.com/supermhp/gupnet/blob/main/code/tools/kitti_eval/evaluate_object_3d_offline_ap40.cpp): `code/tools/kitti_eval/evaluate_object_3d_offline_ap40.cpp`

### Other components

- **Researcher**
- **KITTI dataset**
- **KITTI ground truth**

## Connections

- Researcher → Train/eval entry: runs
- Researcher → KITTI dataset: provides data
- Train/eval entry → Experiment config: loads
- Train/eval entry → Loader builder: builds loaders
- Loader builder → KITTI dataset reader: creates
- KITTI dataset reader → KITTI dataset: reads images and labels
- KITTI dataset reader → Dataset utilities: uses
- Train/eval entry → Model builder: builds model
- Model builder → GUPNet: constructs
- GUPNet → Feature backbones: extracts features
- GUPNet → Feature fusion: fuses features
- GUPNet → Network operators: uses
- Train/eval entry → Optimizer builder: builds optimizer
- Train/eval entry → LR scheduler: builds schedulers
- Train/eval entry → Trainer: starts training
- Trainer → Loader builder: consumes batches
- Trainer → GUPNet: runs batches
- Trainer → Detection losses: computes losses
- Trainer → Optimizer builder: updates weights
- Trainer → LR scheduler: steps schedule
- Trainer → Checkpoint helpers: saves and resumes
- Train/eval entry → Tester: starts evaluation
- Tester → GUPNet: runs inference
- Tester → Prediction decoder: decodes predictions
- Prediction decoder → Dataset utilities: decodes angles
- Tester → KITTI detection files: writes results
- Researcher → KITTI offline evaluator: runs evaluation
- KITTI offline evaluator → KITTI detection files: scores results
- KITTI offline evaluator → KITTI ground truth: compares with