# lufficc/ssd architecture

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

- Interactive diagram: https://gitdiagram.com/lufficc/ssd
- Repository: https://github.com/lufficc/ssd

## Overview

##### Project type and purpose
- This is a research-oriented, modular PyTorch implementation of SSD (Single Shot MultiBox Detector) for object detection.
- It provides training, evaluation, inference and demo scripts, supports multi-GPU, configurable backbones (VGG, MobileNet, EfficientNet), and abstracted modules for easy extension.

##### File structure
- Top-level:
- scripts: train.py, test.py, demo.py, test.py
- configs/: YAML files defining model/data/solver settings
- setup.py, requirements.txt, DEVELOP_GUIDE.md, TROUBLESHOOTING.md
- Core package “ssd/” subdivided into:
- config: default CfgNode definitions, path catalog
- data: datasets (VOC, COCO), samplers, transforms, build logic
- engine: trainer.py (training loop), inference.py
- modeling: backbone, anchors, box_head (predictor, loss, inference), detector (SSD detector), registry
- solver: optimizer & lr_scheduler builders
- layers: custom conv layers
- structures: container utilities
- utils: checkpointing, distributed training, logging, metrics, NMS, model zoo

##### Insights from README
- The system relies on PyTorch 1.0+, uses yacs for config, supports DistributedDataParallel, auto-downloads pretrained weights, tensorboard logging.
- No single monolithic file: users configure and launch via CLI scripts that pull everything together.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Config Manager
    subgraph "Config Manager"
        direction TB
        CFG_YAML["configs/*.yaml"]:::config
        DEFAULTS["ssd/config/defaults.py"]:::config
        PATHCAT["ssd/config/path_catlog.py"]:::config
    end

    %% Data Pipeline
    subgraph "Data Pipeline"
        direction TB
        BUILD_DATA["ssd/data/build.py"]:::data
        VOC_DATA["ssd/data/datasets/voc.py"]:::data
        COCO_DATA["ssd/data/datasets/coco.py"]:::data
        VOC_EVAL["ssd/data/datasets/evaluation/voc/eval_detection_voc.py"]:::data
        COCO_EVAL["ssd/data/datasets/evaluation/coco/__init__.py"]:::data
        SAMPLER_DIST["ssd/data/samplers/distributed.py"]:::data
        SAMPLER_ITER["ssd/data/samplers/iteration_based_batch_sampler.py"]:::data
        TRANSFORMS["ssd/data/transforms/transforms.py"]:::data
        TARGET_TRANS["ssd/data/transforms/target_transform.py"]:::data
    end

    %% Model Construction
    subgraph "Model Construction"
        direction TB
        REGISTRY["ssd/modeling/registry.py"]:::model
        VGG["ssd/modeling/backbone/vgg.py"]:::model
        MOB["ssd/modeling/backbone/mobilenet.py"]:::model
        MOBV3["ssd/modeling/backbone/mobilenetv3.py"]:::model
        EFFICIENT["ssd/modeling/backbone/efficient_net/efficient_net.py"]:::model
        PRIOR["ssd/modeling/anchors/prior_box.py"]:::model
        BOX_HEAD["ssd/modeling/box_head/box_head.py"]:::model
        BOX_PRED["ssd/modeling/box_head/box_predictor.py"]:::model
        BOX_INF["ssd/modeling/box_head/inference.py"]:::model
        BOX_LOSS["ssd/modeling/box_head/loss.py"]:::model
        SSD_DET["ssd/modeling/detector/ssd_detector.py"]:::model
    end

    %% Solver
    subgraph "Solver"
        direction TB
        SOLVER_BUILD["ssd/solver/build.py"]:::solver
        LR_SCHED["ssd/solver/lr_scheduler.py"]:::solver
    end

    %% Engine
    subgraph "Engine"
        direction TB
        TRAINER["ssd/engine/trainer.py"]:::engine
        INFERENCE_MOD["ssd/engine/inference.py"]:::engine
    end

    %% Utility Modules
    subgraph "Utilities"
        direction TB
        CKPT["ssd/utils/checkpoint.py"]:::utils
        DIST["ssd/utils/dist_util.py"]:::utils
        LOGGER["ssd/utils/logger.py"]:::utils
        METRIC_LOG["ssd/utils/metric_logger.py"]:::utils
        MODEL_ZOO["ssd/utils/model_zoo.py"]:::utils
        NMS["ssd/utils/nms.py"]:::utils
        BOX_UTILS["ssd/utils/box_utils.py"]:::utils
        REG_UTIL["ssd/utils/registry.py"]:::utils
        MISC["ssd/utils/misc.py"]:::utils
    end

    %% Scripts
    subgraph "Entry Points"
        direction TB
        TRAIN["train.py"]:::script
        TEST["test.py"]:::script
        DEMO["demo.py"]:::script
    end

    %% External Resources
    subgraph "External Resources"
        direction TB
        VOC_ROOT["VOC_ROOT (Folder)"]:::external
        COCO_ROOT["COCO_ROOT (Folder)"]:::external
        MODEL_ZOO_URL["Pretrained Weights URLs"]:::external
    end

    %% Data Flow and Dependencies
    CFG_YAML -->|loads| BUILD_DATA
    DEFAULTS -->|defines| CFG_YAML
    PATHCAT -->|defines| CFG_YAML

    BUILD_DATA -->|constructs| VOC_DATA
    BUILD_DATA --> COCO_DATA
    BUILD_DATA --> TRANSFORMS
    TRANSFORMS --> TARGET_TRANS
    VOC_DATA --> VOC_ROOT
    COCO_DATA --> COCO_ROOT
    VOC_EVAL -->|evaluation| VOC_DATA
    COCO_EVAL --> COCO_DATA
    SAMPLER_DIST --> BUILD_DATA
    SAMPLER_ITER --> BUILD_DATA

    REGISTRY --> VGG
    REGISTRY --> MOB
    REGISTRY --> MOBV3
    REGISTRY --> EFFICIENT
    REGISTRY --> PRIOR
    REGISTRY --> BOX_HEAD
    BOX_HEAD --> BOX_PRED
    BOX_HEAD --> BOX_INF
    BOX_HEAD --> BOX_LOSS
    SSD_DET -->|uses| REGISTRY

    SOLVER_BUILD --> LR_SCHED
    SOLVER_BUILD --> TRAINER

    TRAINER -->|uses| SOLVER_BUILD
    TRAINER -->|uses| INFERENCE_MOD
    TRAINER -->|logs to| LOGGER
    TRAINER -->|saves| CKPT
    TRAINER -->|metrics| METRIC_LOG
    TRAINER -->|distributed| DIST

    INFERENCE_MOD -->|uses| SSD_DET
    INFERENCE_MOD -->|outputs| MODEL_ZOO_URL
    INFERENCE_MOD -->|uses| NMS

    TRAIN -->|orchestrates| CFG_YAML
    TRAIN -->|calls| TRAINER
    TEST -->|orchestrates| CFG_YAML
    TEST -->|calls| INFERENCE_MOD
    DEMO -->|orchestrates| CFG_YAML
    DEMO -->|calls| INFERENCE_MOD

    %% Click Events
    click CFG_YAML "https://github.com/lufficc/ssd/blob/master/configs/vgg_ssd300_voc0712.yaml"
    click DEFAULTS "https://github.com/lufficc/ssd/blob/master/ssd/config/defaults.py"
    click PATHCAT "https://github.com/lufficc/ssd/blob/master/ssd/config/path_catlog.py"
    click BUILD_DATA "https://github.com/lufficc/ssd/blob/master/ssd/data/build.py"
    click VOC_DATA "https://github.com/lufficc/ssd/blob/master/ssd/data/datasets/voc.py"
    click COCO_DATA "https://github.com/lufficc/ssd/blob/master/ssd/data/datasets/coco.py"
    click VOC_EVAL "https://github.com/lufficc/ssd/blob/master/ssd/data/datasets/evaluation/voc/eval_detection_voc.py"
    click COCO_EVAL "https://github.com/lufficc/ssd/blob/master/ssd/data/datasets/evaluation/coco/__init__.py"
    click SAMPLER_DIST "https://github.com/lufficc/ssd/blob/master/ssd/data/samplers/distributed.py"
    click SAMPLER_ITER "https://github.com/lufficc/ssd/blob/master/ssd/data/samplers/iteration_based_batch_sampler.py"
    click TRANSFORMS "https://github.com/lufficc/ssd/blob/master/ssd/data/transforms/transforms.py"
    click TARGET_TRANS "https://github.com/lufficc/ssd/blob/master/ssd/data/transforms/target_transform.py"
    click REGISTRY "https://github.com/lufficc/ssd/blob/master/ssd/modeling/registry.py"
    click VGG "https://github.com/lufficc/ssd/blob/master/ssd/modeling/backbone/vgg.py"
    click MOB "https://github.com/lufficc/ssd/blob/master/ssd/modeling/backbone/mobilenet.py"
    click MOBV3 "https://github.com/lufficc/ssd/blob/master/ssd/modeling/backbone/mobilenetv3.py"
    click EFFICIENT "https://github.com/lufficc/ssd/blob/master/ssd/modeling/backbone/efficient_net/efficient_net.py"
    click PRIOR "https://github.com/lufficc/ssd/blob/master/ssd/modeling/anchors/prior_box.py"
    click BOX_HEAD "https://github.com/lufficc/ssd/blob/master/ssd/modeling/box_head/box_head.py"
    click BOX_PRED "https://github.com/lufficc/ssd/blob/master/ssd/modeling/box_head/box_predictor.py"
    click BOX_INF "https://github.com/lufficc/ssd/blob/master/ssd/modeling/box_head/inference.py"
    click BOX_LOSS "https://github.com/lufficc/ssd/blob/master/ssd/modeling/box_head/loss.py"
    click SSD_DET "https://github.com/lufficc/ssd/blob/master/ssd/modeling/detector/ssd_detector.py"
    click SOLVER_BUILD "https://github.com/lufficc/ssd/blob/master/ssd/solver/build.py"
    click LR_SCHED "https://github.com/lufficc/ssd/blob/master/ssd/solver/lr_scheduler.py"
    click TRAINER "https://github.com/lufficc/ssd/blob/master/ssd/engine/trainer.py"
    click INFERENCE_MOD "https://github.com/lufficc/ssd/blob/master/ssd/engine/inference.py"
    click CKPT "https://github.com/lufficc/ssd/blob/master/ssd/utils/checkpoint.py"
    click DIST "https://github.com/lufficc/ssd/blob/master/ssd/utils/dist_util.py"
    click LOGGER "https://github.com/lufficc/ssd/blob/master/ssd/utils/logger.py"
    click METRIC_LOG "https://github.com/lufficc/ssd/blob/master/ssd/utils/metric_logger.py"
    click MODEL_ZOO "https://github.com/lufficc/ssd/blob/master/ssd/utils/model_zoo.py"
    click NMS "https://github.com/lufficc/ssd/blob/master/ssd/utils/nms.py"
    click BOX_UTILS "https://github.com/lufficc/ssd/blob/master/ssd/utils/box_utils.py"
    click REG_UTIL "https://github.com/lufficc/ssd/blob/master/ssd/utils/registry.py"
    click MISC "https://github.com/lufficc/ssd/blob/master/ssd/utils/misc.py"
    click TRAIN "https://github.com/lufficc/ssd/blob/master/train.py"
    click TEST "https://github.com/lufficc/ssd/blob/master/test.py"
    click DEMO "https://github.com/lufficc/ssd/blob/master/demo.py"

    %% Styles
    classDef config fill:#D0E6F6,stroke:#0366D6,color:#03396C
    classDef data fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10
    classDef model fill:#FFE4B5,stroke:#FF8C00,color:#CD6600
    classDef solver fill:#FFEFD5,stroke:#FF7F50,color:#E56800
    classDef engine fill:#F4CCCC,stroke:#D8000C,color:#A80000
    classDef utils fill:#E3E4FA,stroke:#6A5ACD,color:#483D8B
    classDef script fill:#D0E6F6,stroke:#0366D6,color:#03396C
    classDef external fill:#F0F0F0,stroke:#999999,color:#666666
```
