# pjlab-adg/detzero architecture

> Architecture diagram of the GitHub repository pjlab-adg/detzero, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pjlab-adg/detzero
- Repository: https://github.com/pjlab-adg/detzero

## Overview

##### Main Components
- Detection Module – This core component contains the “detzero_det” submodule. It handles all aspects of 3D object detection. Its inner structure includes:
- Dataset management (with subdirectories like “datasets”, “augmentor”, “processor”, and specific dataset handling for Waymo).
- Model definitions (e.g., centerpoint, PDV head, backbone modules, etc.).
- Utility functions and loss functions specific to 3D detection.
- Tool scripts and configuration files (located in the “tools” directory under detection).
- Tracking Module – Found under the “tracking” folder, this module is responsible for tracking objects over time. It involves:
- Dataset preparation and processing specific to tracking.
- Tracker models (including Kalman filters, data association modules, etc.).
- Dedicated tracking scripts and configurations.
- Refining Module – Located in the “refining” directory, this module refines the detection results via geometry and confidence models. It likewise contains:
- Dataset classes for various refinement aspects (confidence, geometry, position).
- Model definitions for different refinement strategies.
- Tools and configuration files for training and evaluation.
- Evaluator – The “evaluator” directory contains the offline evaluation tools, including scripts for both detection and tracking metrics.
- Daemon – The “daemon” folder has supplementary tools (e.g., combining outputs, generating ground truth, visualizers) that prepare object data for refinement or additional post-processing.
- Shared Utilities – The “utils” directory gathers common libraries and functions (e.g., operations for non-maximum suppression, point cloud processing, visualization) that are used across all modules.

##### Relationships and Interactions
- Data Flow:
- Input Data from sensors/datasets is stored in the “data” folder and is processed by the detection and tracking modules.
- The detection module pre-processes the raw point cloud data (using its “datasets/processor” and “augmentor”) and forwards detection results to both the tracking and refining modules.
- The tracking module uses these detections to establish temporal object associations, relying on modules like Kalman filtering and data association.
- The refining module further processes outputs from detection (and possibly tracking) to enhance spatial accuracy, using its own dataset processors and transformer-based modules.
- Evaluation: Offline evaluation tools in the “evaluator” folder analyze the performance of detection and tracking models, referencing log files and metrics documentation in “docs”.

##### Architectural Patterns and Design Principles
- Modular Architecture: Each primary function—detection, tracking, and refining—is isolated in its dedicated module to promote maintainability and scalability.
- Data Processing Pipelines: The separation between data augmentation, voxel/point processing, and model inference highlights a pipeline-based approach.
- Config-driven Execution: The presence of extensive configuration directories (e.g., YAML files under “tools/cfgs” across modules) indicates an emphasis on flexibility and ease of experimentation.
- Utility Abstraction: A shared “utils” directory provides commonly used operations (including optimized ops written in C++/CUDA), enabling efficient reuse across modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Input
    Input["Input Data (Sensors/Datasets)"]:::input

    %% Detection Module Subgraph
    subgraph "Detection Module"
        det_dataset["Dataset Management"]:::module
        det_models["Model Definitions"]:::module
        det_utils["Utility & Loss Functions"]:::module
        det_tools["Tools & Configurations"]:::module
    end

    %% Tracking Module Subgraph
    subgraph "Tracking Module"
        track_datasets["Dataset Processing"]:::module
        track_models["Tracker Models"]:::module
        track_tools["Tracking Scripts & Configurations"]:::module
    end

    %% Refining Module Subgraph
    subgraph "Refining Module"
        ref_datasets["Dataset Classes"]:::module
        ref_models["Refinement Model Definitions"]:::module
        ref_tools["Tools & Configurations"]:::module
    end

    %% Other Modules
    evaluator["Evaluator"]:::eval
    daemon["Daemon"]:::daemon
    utils["Shared Utilities"]:::utils

    %% Data Flow Connections
    Input -->|"raw_pointcloud"| det_dataset

    %% Detection internal flow
    det_dataset -->|"processed_data"| det_models
    det_models -->|"utilizes"| det_utils
    det_models -->|"config_control"| det_tools

    %% Flow from Detection to Tracking and Refining
    det_models -->|"detection_output"| track_datasets
    det_models -->|"detection_output"| ref_models

    %% Tracking Module flow
    track_datasets -->|"prepared_dataset"| track_models
    track_models -->|"tracking_results"| track_tools
    track_tools -->|"tracking_metrics"| evaluator

    %% Refining Module flow
    ref_datasets -->|"prepared_datasets"| ref_models
    ref_models -->|"refined_detection"| ref_tools
    ref_tools -->|"refinement_metrics"| evaluator

    %% Additional detection metrics flow
    det_tools -->|"detection_metrics"| evaluator

    %% Flow to Daemon for supplementary tasks
    det_models -->|"prepare_outputs"| daemon
    track_models -->|"prepare_outputs"| daemon
    ref_models -->|"prepare_outputs"| daemon

    %% Shared Utilities used by multiple modules
    utils --> det_utils
    utils --> track_models
    utils --> ref_models

    %% Click Events for Detection Module
    click det_dataset "https://github.com/pjlab-adg/detzero/tree/main/detection/detzero_det/datasets"
    click det_models "https://github.com/pjlab-adg/detzero/tree/main/detection/detzero_det/models"
    click det_utils "https://github.com/pjlab-adg/detzero/tree/main/detection/detzero_det/utils"
    click det_tools "https://github.com/pjlab-adg/detzero/tree/main/detection/tools"

    %% Click Events for Tracking Module
    click track_datasets "https://github.com/pjlab-adg/detzero/tree/main/tracking/detzero_track/datasets"
    click track_models "https://github.com/pjlab-adg/detzero/tree/main/tracking/detzero_track/models"
    click track_tools "https://github.com/pjlab-adg/detzero/tree/main/tracking/tools"

    %% Click Events for Refining Module
    click ref_datasets "https://github.com/pjlab-adg/detzero/tree/main/refining/detzero_refine/datasets"
    click ref_models "https://github.com/pjlab-adg/detzero/tree/main/refining/detzero_refine/models"
    click ref_tools "https://github.com/pjlab-adg/detzero/tree/main/refining/tools"

    %% Click Events for Evaluator, Daemon, and Shared Utilities
    click evaluator "https://github.com/pjlab-adg/detzero/tree/main/evaluator"
    click daemon "https://github.com/pjlab-adg/detzero/tree/main/daemon"
    click utils "https://github.com/pjlab-adg/detzero/tree/main/utils/detzero_utils"

    %% Styles
    classDef input fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef module fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef eval fill:#a2d149,stroke:#333,stroke-width:2px;
    classDef daemon fill:#ff9966,stroke:#333,stroke-width:2px;
    classDef utils fill:#66cccc,stroke:#333,stroke-width:2px;
```
