# bichenwuucb/squeezedet architecture

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

- Interactive diagram: https://gitdiagram.com/bichenwuucb/squeezedet
- Repository: https://github.com/bichenwuucb/squeezedet

## Overview

##### Project Type and Purpose
- This is an open-source, TensorFlow-based object-detection framework.
- It provides:
- Data ingestion (KITTI / Pascal VOC)
- Model definitions (SqueezeDet, SqueezeDet+, VGG16-ConvDet, ResNet50-ConvDet)
- Training and evaluation pipelines
- Demo and utility scripts

##### Break Down the Main Components
A. Data Layer
- Raw dataset (images + labels under data/KITTI, Pascal VOC)
- random_split_train_val.py for train/val split
- Dataset classes (src/dataset/imdb.py, kitti.py, pascal_voc.py, voc_eval.py)
- External C++ KITTI evaluation tool (src/dataset/kitti-eval/cpp)
B. Configuration Layer
- Central config module (src/config/config.py)
- Network-specific configs (kitti_res50_config.py, kitti_squeezeDet_config.py, etc.)
C. Model Layer
- Network definitions in src/nets/ (squeezeDet.py, squeezeDetPlus.py, vgg16_convDet.py, resnet50_convDet.py)
- Weight conversion utility (caffemodel2pkl.py)
D. Training Pipeline
- train.py orchestrates data loading, model instantiation, loss computation, optimizer steps, checkpointing
- scripts/train.sh wraps train.py with flags (-net, ‑train_dir, ‑gpu)
E. Evaluation Pipeline
- eval.py loads a checkpoint, runs forward pass on train/val sets, computes metrics
- scripts/eval.sh wraps eval.py (-net, ‑eval_dir, ‑image_set, ‑gpu)
- C++ kitti-eval for official metrics
F. Demo & Visualization
- demo.py for running inference on images/videos
- TensorBoard integration via log events in train_dir/eval_dir
G. Utilities & Helpers
- src/utils/util.py for common helpers (logging, file I/O)
- random_split_train_val.py, shell scripts, Makefile

##### Relationships and Data Flows
1. Data Ingestion:
Raw images/labels → Dataset classes → Batches of tensors
2. Configuration:
Experiment parameters from config/*.py → Model instantiation + Training/Eval scripts
3. Training Loop:
Batches → Network → Loss → Optimizer → Checkpoints → Logs
4. Evaluation Loop:
Checkpoints → Network → Predictions → C++ kitti-eval → AP metrics → Logs
5. Visualization & Monitoring:
Logs → TensorBoard
6. Demo Inference:
Input images → Trained Checkpoint → Network → Output detections

##### Architectural Patterns & Design Principles
- Modularity: separation of concerns among config, dataset, model, train/eval, utils
- Plugin-style networks: “-net” flag selects network and corresponding config
- Reusable dataset interface (imdb) for different sources
- Thin wrapper scripts for reproducible experiments
- External tool integration (C++ eval, TensorBoard)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DLData["data/KITTI & Pascal VOC"]:::data
        SplitScript["random_split_train_val.py"]:::script
        Imdb["imdb.py"]:::python
        KittiDS["kitti.py"]:::python
        PascalDS["pascal_voc.py"]:::python
        VocEval["voc_eval.py"]:::python
        KittiEvalCPP["C++ KITTI Eval"]:::external
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        ConfigCentral["config.py"]:::python
        ConfigSD["kitti_squeezeDet_config.py"]:::python
        ConfigSDP["kitti_squeezeDetPlus_config.py"]:::python
        ConfigVGG["kitti_vgg16_config.py"]:::python
        ConfigRes["kitti_res50_config.py"]:::python
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        SqueezeDet["squeezeDet.py"]:::python
        SqueezeDetPlus["squeezeDetPlus.py"]:::python
        VGG16["vgg16_convDet.py"]:::python
        ResNet50["resnet50_convDet.py"]:::python
        Caffe2Pkl["caffemodel2pkl.py"]:::python
    end

    %% Orchestration Layer
    subgraph "Training Pipeline"
        direction TB
        Trainer["train.py"]:::python
        TrainSH["train.sh"]:::script
        Checkpoints["Checkpoints"]:::data
    end

    subgraph "Evaluation Pipeline"
        direction TB
        Evaluator["eval.py"]:::python
        EvalSH["eval.sh"]:::script
        Metrics["AP Metrics"]:::data
    end

    %% Demo & Monitoring
    subgraph "Demo & Visualization"
        direction TB
        Demo["demo.py"]:::script
        TensorBoard["TensorBoard"]:::external
        Logs["Logs"]:::data
    end

    %% Utilities
    subgraph "Utilities & Helpers"
        direction TB
        Utils["util.py"]:::python
        Makefile["Makefile"]:::data
        Req["requirements.txt"]:::data
    end

    %% Data Flow
    DLData -->|reads images/labels| Imdb
    Imdb --> KittiDS
    Imdb --> PascalDS
    KittiDS --> VocEval
    DLData --> SplitScript
    SplitScript --> Imdb

    %% Config usage
    ConfigCentral --> Trainer
    ConfigSD --> Trainer
    ConfigSDP --> Trainer
    ConfigVGG --> Trainer
    ConfigRes --> Trainer
    ConfigCentral --> Evaluator
    ConfigCentral --> Demo

    %% Model flow
    Trainer --> SqueezeDet
    Trainer --> SqueezeDetPlus
    Trainer --> VGG16
    Trainer --> ResNet50
    Trainer --> Caffe2Pkl
    Trainer --> Checkpoints
    Trainer --> Logs

    Evaluator --> Checkpoints
    Evaluator --> SqueezeDet
    Evaluator --> SqueezeDetPlus
    Evaluator --> VGG16
    Evaluator --> ResNet50
    Evaluator --> KittiEvalCPP
    KittiEvalCPP --> Metrics
    Evaluator --> Logs

    Demo --> Checkpoints
    Demo --> SqueezeDet
    Demo --> SqueezeDetPlus
    Demo --> VGG16
    Demo --> ResNet50
    Demo --> Logs
    Logs --> TensorBoard

    %% Click Events
    click Imdb "https://github.com/bichenwuucb/squeezedet/blob/master/src/dataset/imdb.py"
    click KittiDS "https://github.com/bichenwuucb/squeezedet/blob/master/src/dataset/kitti.py"
    click PascalDS "https://github.com/bichenwuucb/squeezedet/blob/master/src/dataset/pascal_voc.py"
    click VocEval "https://github.com/bichenwuucb/squeezedet/blob/master/src/dataset/voc_eval.py"
    click KittiEvalCPP "https://github.com/bichenwuucb/squeezedet/blob/master/src/dataset/kitti-eval/cpp/evaluate_object.cpp"
    click SplitScript "https://github.com/bichenwuucb/squeezedet/blob/master/data/random_split_train_val.py"
    click ConfigCentral "https://github.com/bichenwuucb/squeezedet/blob/master/src/config/config.py"
    click ConfigSD "https://github.com/bichenwuucb/squeezedet/blob/master/src/config/kitti_squeezeDet_config.py"
    click ConfigSDP "https://github.com/bichenwuucb/squeezedet/blob/master/src/config/kitti_squeezeDetPlus_config.py"
    click ConfigVGG "https://github.com/bichenwuucb/squeezedet/blob/master/src/config/kitti_vgg16_config.py"
    click ConfigRes "https://github.com/bichenwuucb/squeezedet/blob/master/src/config/kitti_res50_config.py"
    click SqueezeDet "https://github.com/bichenwuucb/squeezedet/blob/master/src/nets/squeezeDet.py"
    click SqueezeDetPlus "https://github.com/bichenwuucb/squeezedet/blob/master/src/nets/squeezeDetPlus.py"
    click VGG16 "https://github.com/bichenwuucb/squeezedet/blob/master/src/nets/vgg16_convDet.py"
    click ResNet50 "https://github.com/bichenwuucb/squeezedet/blob/master/src/nets/resnet50_convDet.py"
    click Caffe2Pkl "https://github.com/bichenwuucb/squeezedet/blob/master/src/utils/caffemodel2pkl.py"
    click Trainer "https://github.com/bichenwuucb/squeezedet/blob/master/src/train.py"
    click TrainSH "https://github.com/bichenwuucb/squeezedet/blob/master/scripts/train.sh"
    click Evaluator "https://github.com/bichenwuucb/squeezedet/blob/master/src/eval.py"
    click EvalSH "https://github.com/bichenwuucb/squeezedet/blob/master/scripts/eval.sh"
    click Demo "https://github.com/bichenwuucb/squeezedet/blob/master/src/demo.py"
    click Utils "https://github.com/bichenwuucb/squeezedet/blob/master/src/utils/util.py"
    click Makefile "https://github.com/bichenwuucb/squeezedet/tree/master/Makefile"
    click Req "https://github.com/bichenwuucb/squeezedet/blob/master/requirements.txt"

    %% Styles
    classDef python fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef data fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef script fill:#FFE4B5,stroke:#333,stroke-dasharray:5 5
```
