# rdxrf/fastpoly architecture

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

- Interactive diagram: https://gitdiagram.com/rdxrf/fastpoly
- Repository: https://github.com/rdxrf/fastpoly

## Overview

Fast-Poly is a nuScenes-focused 3D multi-object tracker. The documented workflow loads ordered detector results and scene tokens, tracks each scene, saves results, and evaluates them; its internals associate detections with predicted tracks and estimate object motion. The README also documents configurable parameter search and detector suppression. Some implementation details, including the evaluation and finetuning paths, were not sampled, so those relationships are shown only where documented; uncertain internal calls are omitted.

Main entry points: [`test.py`](https://github.com/rdxrf/fastpoly/blob/main/test.py) (Inference entry), [`tracking/nusc_tracker.py`](https://github.com/rdxrf/fastpoly/blob/main/tracking/nusc_tracker.py) (Tracker orchestration), [`tracking/nusc_trajectory.py`](https://github.com/rdxrf/fastpoly/blob/main/tracking/nusc_trajectory.py) (Trajectory lifecycle), [`dataloader/nusc_loader.py`](https://github.com/rdxrf/fastpoly/blob/main/dataloader/nusc_loader.py) (nuScenes loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input and preparation"]
  node_loader["nuScenes loader<br/>[nusc_loader.py]"]
  node_conversion["Detection conversion"]
  node_nms["Detection NMS<br/>[nusc_nms.py]"]
  node_constants["Dataset constants<br/>[NUSC_CONSTANT.py]"]
end

subgraph group_tracking["Tracking lifecycle"]
  node_tracker["Tracker orchestration<br/>[nusc_tracker.py]"]
  node_trajectory["Trajectory lifecycle<br/>[nusc_trajectory.py]"]
  node_life["Track life management"]
  node_score["Track score management"]
  node_geometrymanage["Track geometry management"]
end

subgraph group_geometry["Geometry and motion"]
  node_matching["Association helpers<br/>[matching.py]"]
  node_similarity["Box similarity<br/>[nusc_distance.py]"]
  node_box["3D box geometry<br/>[nusc_box.py]"]
  node_geomutils["Geometry utilities<br/>[nusc_utils.py]"]
  node_kalman["Kalman estimation<br/>[kalman_filter.py]"]
  node_motion["Motion models<br/>[motion_model.py]"]
  node_frameobject["Frame state<br/>[nusc_object.py]"]
end

subgraph group_runtime["Runtime and evaluation"]
  node_entry["Inference entry<br/>[test.py]"]
  node_config["Tracker config<br/>[nusc_config.yaml]"]
  node_output["Results and evaluation<br/>[test.py]"]
  node_finetune["Parameter search<br/>[test.py]"]
end

node_user(("User"))
node_detections["Detector results"]
node_tokens["Scene tokens"]
node_evaldb[("Evaluation database")]

node_user -->|"runs inference"| node_entry
node_detections -->|"provides detections"| node_loader
node_tokens -->|"initializes scenes"| node_loader
node_evaldb -->|"supports evaluation"| node_entry
node_config -->|"configures tracker"| node_entry
node_entry -.->|"loads scenes"| node_loader
node_loader -.->|"converts detections"| node_conversion
node_tracker -.->|"applies suppression"| node_nms
node_tracker -.->|"updates tracks"| node_trajectory
node_trajectory -->|"manages track life"| node_life
node_trajectory -.->|"uses score management"| node_score
node_trajectory -.->|"uses geometry management"| node_geometrymanage
node_tracker -.->|"constructs associations"| node_matching
node_tracker -.->|"computes costs"| node_similarity
node_conversion -->|"creates boxes"| node_box
node_nms -->|"scores overlap"| node_similarity
node_kalman -->|"uses motion models"| node_motion
node_kalman -->|"stores frame state"| node_frameobject
node_entry -->|"runs evaluation"| node_output
node_user -->|"enables search"| node_finetune

click node_entry "https://github.com/rdxrf/fastpoly/blob/main/test.py"
click node_config "https://github.com/rdxrf/fastpoly/blob/main/config/nusc_config.yaml"
click node_loader "https://github.com/rdxrf/fastpoly/blob/main/dataloader/nusc_loader.py"
click node_conversion "https://github.com/rdxrf/fastpoly/blob/main/pre_processing/nusc_data_conversion.py"
click node_nms "https://github.com/rdxrf/fastpoly/blob/main/pre_processing/nusc_nms.py"
click node_constants "https://github.com/rdxrf/fastpoly/blob/main/data/script/NUSC_CONSTANT.py"
click node_tracker "https://github.com/rdxrf/fastpoly/blob/main/tracking/nusc_tracker.py"
click node_trajectory "https://github.com/rdxrf/fastpoly/blob/main/tracking/nusc_trajectory.py"
click node_life "https://github.com/rdxrf/fastpoly/blob/main/tracking/nusc_life_manage.py"
click node_score "https://github.com/rdxrf/fastpoly/blob/main/tracking/nusc_score_manage.py"
click node_geometrymanage "https://github.com/rdxrf/fastpoly/blob/main/tracking/nusc_geometry_manage.py"
click node_matching "https://github.com/rdxrf/fastpoly/blob/main/utils/matching.py"
click node_similarity "https://github.com/rdxrf/fastpoly/blob/main/geometry/nusc_distance.py"
click node_box "https://github.com/rdxrf/fastpoly/blob/main/geometry/nusc_box.py"
click node_geomutils "https://github.com/rdxrf/fastpoly/blob/main/geometry/nusc_utils.py"
click node_kalman "https://github.com/rdxrf/fastpoly/blob/main/motion_module/kalman_filter.py"
click node_motion "https://github.com/rdxrf/fastpoly/blob/main/motion_module/motion_model.py"
click node_frameobject "https://github.com/rdxrf/fastpoly/blob/main/motion_module/nusc_object.py"
click node_output "https://github.com/rdxrf/fastpoly/blob/main/test.py"
click node_finetune "https://github.com/rdxrf/fastpoly/blob/main/test.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_loader,node_conversion,node_nms,node_constants,node_user toneBlue
class node_tracker,node_trajectory,node_life,node_score,node_geometrymanage,node_evaldb toneAmber
class node_matching,node_similarity,node_box,node_geomutils,node_kalman,node_motion,node_frameobject toneMint
class node_entry,node_config,node_output,node_finetune toneRose
class node_detections,node_tokens toneIndigo
```

## Components

### Input and preparation

- [nuScenes loader](https://github.com/rdxrf/fastpoly/blob/main/dataloader/nusc_loader.py): `dataloader/nusc_loader.py`
- [Detection conversion](https://github.com/rdxrf/fastpoly/blob/main/pre_processing/nusc_data_conversion.py): `pre_processing/nusc_data_conversion.py`
- [Detection NMS](https://github.com/rdxrf/fastpoly/blob/main/pre_processing/nusc_nms.py): `pre_processing/nusc_nms.py`
- [Dataset constants](https://github.com/rdxrf/fastpoly/blob/main/data/script/NUSC_CONSTANT.py): `data/script/NUSC_CONSTANT.py`

### Tracking lifecycle

- [Tracker orchestration](https://github.com/rdxrf/fastpoly/blob/main/tracking/nusc_tracker.py): `tracking/nusc_tracker.py`
- [Trajectory lifecycle](https://github.com/rdxrf/fastpoly/blob/main/tracking/nusc_trajectory.py): `tracking/nusc_trajectory.py`
- [Track life management](https://github.com/rdxrf/fastpoly/blob/main/tracking/nusc_life_manage.py): `tracking/nusc_life_manage.py`
- [Track score management](https://github.com/rdxrf/fastpoly/blob/main/tracking/nusc_score_manage.py): `tracking/nusc_score_manage.py`
- [Track geometry management](https://github.com/rdxrf/fastpoly/blob/main/tracking/nusc_geometry_manage.py): `tracking/nusc_geometry_manage.py`

### Geometry and motion

- [Association helpers](https://github.com/rdxrf/fastpoly/blob/main/utils/matching.py): `utils/matching.py`
- [Box similarity](https://github.com/rdxrf/fastpoly/blob/main/geometry/nusc_distance.py): `geometry/nusc_distance.py`
- [3D box geometry](https://github.com/rdxrf/fastpoly/blob/main/geometry/nusc_box.py): `geometry/nusc_box.py`
- [Geometry utilities](https://github.com/rdxrf/fastpoly/blob/main/geometry/nusc_utils.py): `geometry/nusc_utils.py`
- [Kalman estimation](https://github.com/rdxrf/fastpoly/blob/main/motion_module/kalman_filter.py): `motion_module/kalman_filter.py`
- [Motion models](https://github.com/rdxrf/fastpoly/blob/main/motion_module/motion_model.py): `motion_module/motion_model.py`
- [Frame state](https://github.com/rdxrf/fastpoly/blob/main/motion_module/nusc_object.py): `motion_module/nusc_object.py`

### Runtime and evaluation

- [Inference entry](https://github.com/rdxrf/fastpoly/blob/main/test.py): `test.py`
- [Tracker config](https://github.com/rdxrf/fastpoly/blob/main/config/nusc_config.yaml): `config/nusc_config.yaml`
- [Results and evaluation](https://github.com/rdxrf/fastpoly/blob/main/test.py): `test.py`
- [Parameter search](https://github.com/rdxrf/fastpoly/blob/main/test.py): `test.py`

### Other components

- **User**
- **Detector results**
- **Scene tokens**
- **Evaluation database**

## Connections

- User → Inference entry: runs inference (evidence: `README.md`)
- Detector results → nuScenes loader: provides detections (evidence: `README.md`)
- Scene tokens → nuScenes loader: initializes scenes (evidence: `README.md`)
- Evaluation database → Inference entry: supports evaluation (evidence: `README.md`)
- Tracker config → Inference entry: configures tracker (evidence: `README.md`)
- Inference entry → nuScenes loader: loads scenes
- nuScenes loader → Detection conversion: converts detections
- Tracker orchestration → Detection NMS: applies suppression
- Tracker orchestration → Trajectory lifecycle: updates tracks (evidence: `tracking/nusc_tracker.py`)
- Trajectory lifecycle → Track life management: manages track life (evidence: `tracking/nusc_life_manage.py`)
- Trajectory lifecycle → Track score management: uses score management (evidence: `tracking/nusc_trajectory.py`)
- Trajectory lifecycle → Track geometry management: uses geometry management (evidence: `tracking/nusc_trajectory.py`)
- Tracker orchestration → Association helpers: constructs associations (evidence: `tracking/nusc_tracker.py`)
- Tracker orchestration → Box similarity: computes costs (evidence: `tracking/nusc_tracker.py`)
- Detection conversion → 3D box geometry: creates boxes (evidence: `pre_processing/nusc_data_conversion.py`)
- Detection NMS → Box similarity: scores overlap (evidence: `pre_processing/nusc_nms.py`)
- Kalman estimation → Motion models: uses motion models (evidence: `motion_module/kalman_filter.py`)
- Kalman estimation → Frame state: stores frame state (evidence: `motion_module/kalman_filter.py`)
- Inference entry → Results and evaluation: runs evaluation (evidence: `README.md`)
- User → Parameter search: enables search (evidence: `README.md`)