# owen-liuyuxuan/visualdet3d architecture

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

- Interactive diagram: https://gitdiagram.com/owen-liuyuxuan/visualdet3d
- Repository: https://github.com/owen-liuyuxuan/visualdet3d

## Overview

##### Project type and purpose
- This is a research‐oriented, full‐pipeline Python toolkit for 3D object detection and depth estimation on the KITTI dataset.

##### File structure
- Top‐level:
- `config/` – user‐editable `.py` configurations (data paths, hyperparameters)
- `scripts/` & `launchers/` – CLI entrypoints for preprocessing, training, evaluation
- `make.sh` – builds custom ops under `visualDet3D/networks/lib/ops/`
- `demos/`, `docs/` – notebooks and documentation
- Core library: `visualDet3D/` subdivided into:
- `data/` – dataset loaders, samplers, augmentation pipelines
- `networks/` – backbones, detectors, heads, loss modules, optimizers, training/evaluation pipelines
- `evaluator/` – KITTI‐style metric calculators
- `utils/` – common utilities (paths, timers, registry)

##### README
- The registry pattern allows plugging new datasets, models, transforms.
- Modular design supports mono and stereo 3D detection, depth prediction, multi‐GPU.
- Custom operations (deformable conv, IoU3D) built via `make.sh`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Config Layer
    subgraph "Control & Config Layer"
        direction TB
        ConfigLoader["Configuration Manager"]:::control
        subgraph "CLI Scripts" 
            direction TB
            TrainScript["train.py"]:::control
            EvalScript["eval.py"]:::control
            DepthPrecompute["depth_precompute.py"]:::control
            DisparityCompute["disparity_compute.py"]:::control
            ImdbPrecompute["imdb_precompute_3d.py"]:::control
            LauncherTrain["train.sh"]:::control
            LauncherEval["eval.sh"]:::control
            LauncherDetPre["det_precompute.sh"]:::control
            LauncherDispPre["disparity_precompute.sh"]:::control
        end
    end

    %% Data Layer
    subgraph "Data Subsystem" 
        direction TB
        DataloaderBuilder["dataloader_builder"]:::data
        Sampler["distributed_sampler"]:::data
        AugBuilder["augmentation_builder"]:::data
        StereoAug["stereo_augmentator"]:::data
        MonoDS["mono_dataset"]:::data
        StereoDS["stereo_dataset"]:::data
        DepthMonoDS["depth_mono_dataset"]:::data
        KM3DDS["KM3D_dataset"]:::data
    end

    %% Model Layer
    subgraph "Model Subsystem"
        direction TB
        BackboneRes["resnet"]:::model
        BackboneDLA["dla"]:::model
        YOLOMono["yolomono3d_detector"]:::model
        YOLOStereo["yolostereo3d_detector"]:::model
        DetectorKM3D["KM3D"]:::model
        Head3D["detection_3d_head"]:::model
        HeadKM3D["km3d_head"]:::model
        MonoFlex["monoflex_head"]:::model
        DepthLoss["monodepth_loss"]:::model
        RetinaHead["retinanet_head"]:::model
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        Trainer["trainers"]:::model
        Optimizer["optimizers"]:::model
        Scheduler["schedulers"]:::model
    end

    %% Evaluation Subsystem
    subgraph "Evaluation Subsystem"
        direction TB
        Tester["testers"]:::model
        Evaluator["evaluators"]:::model
        KITTIeval["evaluate.py"]:::model
        DepthEval["evaluate_depth.py"]:::model
    end

    %% Utilities & Registry
    subgraph "Utilities & Registry"
        direction TB
        Registry["registry"]:::utils
        Utils["utils"]:::utils
        Timer["timer"]:::utils
    end

    %% Custom Ops
    subgraph "Custom CUDA Ops"
        direction TB
        DeformOps["deform_conv_cuda_kernel"]:::ops
        IoU3DOps["iou3d_kernel"]:::ops
        RootMake["make.sh"]:::ops
    end

    %% External Services
    DataFS["KITTI Dataset"]:::external
    Checkpoints["Model Checkpoints"]:::external
    TensorBoard["TensorBoard"]:::external

    %% Relationships
    ConfigLoader -->|loads configs| Registry
    ConfigLoader -->|reads| TrainScript
    ConfigLoader -->|reads| EvalScript

    TrainScript -->|instantiates| DataloaderBuilder
    TrainScript -->|uses| Registry
    EvalScript -->|instantiates| Tester

    DataloaderBuilder -->|builds| Sampler
    Sampler -->|samples| MonoDS
    Sampler -->|samples| StereoDS
    Sampler -->|samples| DepthMonoDS
    Sampler -->|samples| KM3DDS
    DataloaderBuilder -->|uses| AugBuilder
    AugBuilder -->|uses| StereoAug

    DataloaderBuilder -->|reads from| DataFS

    Registry -->|provides| BackboneRes
    Registry -->|provides| BackboneDLA
    Registry -->|provides| YOLOMono
    Registry -->|provides| YOLOStereo
    Registry -->|provides| DetectorKM3D
    Registry -->|provides| Head3D
    Registry -->|provides| HeadKM3D
    Registry -->|provides| MonoFlex
    Registry -->|provides| DepthLoss
    Registry -->|provides| RetinaHead

    Trainer -->|runs forward/backward| BackboneRes
    Trainer -->|runs forward/backward| BackboneDLA
    Trainer -->|runs| YOLOMono
    Trainer -->|runs| YOLOStereo
    Trainer -->|runs| DetectorKM3D
    Trainer -->|runs| Head3D
    Trainer -->|runs| HeadKM3D
    Trainer -->|runs| MonoFlex
    Trainer -->|runs| DepthLoss
    Trainer -->|runs| RetinaHead

    Trainer -->|updates| Optimizer
    Optimizer -->|steps| Scheduler
    Trainer -->|logs to| TensorBoard
    Trainer -->|saves| Checkpoints

    EvalScript -->|loads| Checkpoints
    Tester -->|uses| BackboneRes
    Tester -->|uses| BackboneDLA
    Tester -->|runs| YOLOMono
    Tester -->|runs| YOLOStereo
    Tester -->|runs| DetectorKM3D
    Tester -->|runs| Head3D
    Tester -->|runs| HeadKM3D
    Tester -->|runs| MonoFlex
    Tester -->|runs| DepthLoss
    Tester -->|runs| RetinaHead

    Tester -->|passes outputs| Evaluator
    Evaluator -->|calls| KITTIeval
    Evaluator -->|calls| DepthEval
    Evaluator -->|writes metrics| Checkpoints

    RootMake -->|builds| DeformOps
    RootMake -->|builds| IoU3DOps
    DeformOps -->|used by| BackboneRes
    IoU3DOps -->|used by| Head3D

    %% Click Events
    click ConfigLoader "https://github.com/owen-liuyuxuan/visualdet3d/tree/master/config/"
    click TrainScript "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/scripts/train.py"
    click EvalScript "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/scripts/eval.py"
    click DepthPrecompute "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/scripts/depth_precompute.py"
    click DisparityCompute "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/scripts/disparity_compute.py"
    click ImdbPrecompute "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/scripts/imdb_precompute_3d.py"
    click LauncherTrain "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/launchers/train.sh"
    click LauncherEval "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/launchers/eval.sh"
    click LauncherDetPre "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/launchers/det_precompute.sh"
    click LauncherDispPre "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/launchers/disparity_precompute.sh"

    click DataloaderBuilder "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/data/dataloader/dataloader_builder.py"
    click Sampler "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/data/dataloader/distributed_sampler.py"
    click AugBuilder "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/data/pipeline/augmentation_builder.py"
    click StereoAug "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/data/pipeline/stereo_augmentator.py"
    click MonoDS "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/data/kitti/dataset/mono_dataset.py"
    click StereoDS "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/data/kitti/dataset/stereo_dataset.py"
    click DepthMonoDS "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/data/kitti/dataset/depth_mono_dataset.py"
    click KM3DDS "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/data/kitti/dataset/KM3D_dataset.py"

    click BackboneRes "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/backbones/resnet.py"
    click BackboneDLA "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/backbones/dla.py"
    click YOLOMono "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/detectors/yolomono3d_detector.py"
    click YOLOStereo "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/detectors/yolostereo3d_detector.py"
    click DetectorKM3D "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/detectors/KM3D.py"
    click Head3D "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/heads/detection_3d_head.py"
    click HeadKM3D "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/heads/km3d_head.py"
    click MonoFlex "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/heads/monoflex_head.py"
    click DepthLoss "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/heads/monodepth_loss.py"
    click RetinaHead "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/heads/retinanet_head.py"

    click Trainer "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/pipelines/trainers.py"
    click Optimizer "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/optimizers/optimizers.py"
    click Scheduler "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/optimizers/schedulers.py"

    click Tester "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/pipelines/testers.py"
    click Evaluator "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/pipelines/evaluators.py"
    click KITTIeval "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/evaluator/kitti/evaluate.py"
    click DepthEval "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/evaluator/kitti_depth_prediction/evaluate_depth.py"

    click DeformOps "https://github.com/owen-liuyuxuan/visualdet3d/tree/master/visualDet3D/networks/lib/ops/dcn/"
    click IoU3DOps "https://github.com/owen-liuyuxuan/visualdet3d/tree/master/visualDet3D/networks/lib/ops/iou3d/"
    click RootMake "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/make.sh"

    click Registry "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/networks/utils/registry.py"
    click Utils "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/utils/utils.py"
    click Timer "https://github.com/owen-liuyuxuan/visualdet3d/blob/master/visualDet3D/utils/timer.py"

    %% Styles
    classDef control fill:#ADD8E6,stroke:#000
    classDef data fill:#90EE90,stroke:#000
    classDef model fill:#FFA500,stroke:#000
    classDef utils fill:#DDA0DD,stroke:#000
    classDef ops fill:#FF6347,stroke:#000
    classDef external fill:#CCCCCC,stroke:#000
```
