# lutao2021/pidray architecture

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

- Interactive diagram: https://gitdiagram.com/lutao2021/pidray
- Repository: https://github.com/lutao2021/pidray

## Overview

##### Project Type and Purpose
- PIDray is an open‐source research codebase built as an extension of the mmdetection framework. Its goal is to train, evaluate, and benchmark object detection/segmentation models on the PIDray X-ray prohibited items dataset.

##### High‐Level Components
- CLI Layer (entrypoints):
- shell scripts (tools/dist_train.sh, tools/dist_test.sh)
- Python entrypoints (tools/train.py, tools/test.py)
- Configuration Manager:
- configs/… (custom cascade_mask_rcnn_r101_with_R0R1.py, etc.)
- mmdet/.mim/configs/_base_ (dataset, model, schedule, runtime defaults)
- Dataset & Pipeline:
- mmdet/datasets (dataset builders, wrappers, pipelines for loading + augmentations)
- Custom PIDray dataset integration via config overrides
- Model Builder:
- mmdet/models (backbones, necks, heads, detectors, ROI‐heads, seg‐heads)
- mmdet/models/utils for building blocks
- Core Engine & Utilities:
- mmdet/apis/train.py & inference.py (training/testing loops)
- mmdet/core (anchor generation, bbox coder, sampling, losses, evaluation hooks)
- mmdet/core/hook (logging, checkpointing, EMA, lr schedulers)
- mmdet/utils & mmcv (logging, config parsing, dist utilities)
- Evaluation & Export:
- mmdet/apis/test.py
- mmdet/core/evaluation (mean AP, IoU, panoptic utils)
- model export tools (onnx, TorchServe, TensorRT) in mmdet/tools/deployment
- External Services & Storage:
- GPU cluster / distributed training via PyTorch DDP & Slurm scripts
- Dataset storage (local disk or network drives)
- Model weights & logs (file system or remote buckets)

##### Relationships & Data Flow
1. User invokes shell script → Python entrypoint
2. Entrypoint loads experiment config via Config Manager
3. Config Manager builds: Dataset objects + DataLoader + Model + Optimizer + Hooks
4. Training loop (Engine) pulls batches from DataLoader → forward pass through Model → losses computed via Core modules → backward pass → parameter update
5. Hooks handle logging, checkpoint save, lr scheduling
6. After training or on‐the‐fly, Evaluation module computes metrics on validation/test splits
7. Results (model weights, metrics, inference outputs) written to disk

##### Architectural Patterns & Design Principles
- Modular separation: CLI, Configs, Data, Model, Core, Hooks, Deployment
- Factory/Builder pattern: “build_dataset”, “build_detector”, “build_optimizer” in mmdet/models/builder.py
- Hook system: decouples training loop from logging, checkpointing, EMA, lr schedule
- Layered directory structure: clear demarcation between configs, code, demos, tests

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer" 
        direction TB
        DTSh["dist_train.sh"]:::cli
        DTSt["dist_test.sh"]:::cli
        TrainPy["train.py"]:::cli
        TestPy["test.py"]:::cli
    end

    %% Config Manager
    subgraph "Config Manager"
        direction TB
        PID1["cascade_mask_rcnn_r101_with_R0R1.py"]:::config
        PID2["ddod_r101_with_R0R1.py"]:::config
        BaseRun["default_runtime.py"]:::config
        BaseData["_base_/datasets"]:::config
        BaseModel["_base_/models"]:::config
        BaseSched["_base_/schedules"]:::config
    end

    %% Dataset & Pipeline
    subgraph "Dataset & Pipeline"
        direction TB
        Builder["builder.py"]:::data
        CustomDS["custom.py"]:::data
        CoreDS["coco.py / voc.py / xml_style.py"]:::data
        Pipelines["loading.py / transforms.py / test_time_aug.py"]:::data
    end

    %% Model Builder
    subgraph "Model Builder"
        direction TB
        MBInit["__init__.py"]:::model
        MBBuilder["builder.py"]:::model
        UtilsBuild["utils/builder.py"]:::model
        BrickWrap["utils/brick_wrappers.py"]:::model
    end

    %% Core Engine & Utilities
    subgraph "Core Engine & Utilities"
        direction TB
        TrainAPI["train.py"]:::core
        InferenceAPI["inference.py"]:::core
        HooksDir["core/hook/"]:::core
        AnchorMod["core/anchor/"]:::core
        BBoxMod["core/bbox/"]:::core
        MaskMod["core/mask/"]:::core
        OptMod["core/optimizers/"]:::core
        PostProc["core/post_processing/"]:::core
        UtilsLog["utils/logger.py"]:::core
        UtilsCfg["utils/compat_config.py"]:::core
        UtilsDist["utils/util_distribution.py"]:::core
    end

    %% Evaluation & Export
    subgraph "Evaluation & Export"
        direction TB
        TestAPI["test.py"]:::eval
        EvalTools["mean_ap.py / recall.py / panoptic_utils.py"]:::eval
        ExportPTONX["export/pytorch2onnx.py"]:::eval
        ExportHelper["export/onnx_helper.py"]:::eval
        DeployONNX["tools/deployment/pytorch2onnx.py"]:::eval
        DeployTRT["tools/deployment/onnx2tensorrt.py"]:::eval
        DeployTS["tools/deployment/mmdet2torchserve.py"]:::eval
    end

    %% External Services & Storage
    subgraph "External Services & Storage"
        direction TB
        SlurmTrain["slurm_train.sh"]:::ext
        SlurmTest["slurm_test.sh"]:::ext
        DistLaunchT["dist_train.sh"]:::ext
        DistLaunchTe["dist_test.sh"]:::ext
        GPUCluster["GPU Cluster (DDP/NCCL)"]:::ext
        DatasetStore["Dataset Storage"]:::ext
        ModelStore["Model Weights & Logs"]:::ext
    end

    %% Relationships
    DTSh -->|invoke| TrainPy
    DTSt -->|invoke| TestPy
    TrainPy -->|load config| PID1
    TrainPy --> PID2
    TestPy --> PID1
    TestPy --> PID2

    PID1 -->|includes| BaseRun
    PID1 --> BaseData
    PID1 --> BaseModel
    PID1 --> BaseSched

    BaseData --> Builder
    BaseData --> CustomDS
    Builder --> CoreDS
    Builder --> Pipelines

    PID1 --> MBBuilder
    MBBuilder --> MBInit
    MBBuilder --> UtilsBuild
    MBBuilder --> BrickWrap

    TrainPy --> TrainAPI
    TestPy --> InferenceAPI

    TrainAPI --> Builder
    TrainAPI --> MBBuilder
    TrainAPI --> HooksDir
    TrainAPI --> AnchorMod
    TrainAPI --> BBoxMod
    TrainAPI --> MaskMod
    TrainAPI --> OptMod
    TrainAPI --> PostProc

    HooksDir --> UtilsLog
    HooksDir --> UtilsCfg
    HooksDir --> UtilsDist

    TrainAPI -->|batch| InferenceAPI
    InferenceAPI --> EvalTools
    InferenceAPI --> TestAPI

    TestAPI --> EvalTools

    TrainAPI -->|save checkpoint| ModelStore
    TestAPI -->|write results| ModelStore

    TrainAPI --> DatasetStore
    TestAPI --> DatasetStore

    GPUCluster --> TrainAPI
    SlurmTrain --> GPUCluster
    SlurmTest --> GPUCluster
    DistLaunchT --> TrainAPI
    DistLaunchTe --> TestAPI

    %% Click Events
    click DTSh "https://github.com/lutao2021/pidray/blob/main/tools/dist_train.sh"
    click DTSt "https://github.com/lutao2021/pidray/blob/main/tools/dist_test.sh"
    click TrainPy "https://github.com/lutao2021/pidray/blob/main/tools/train.py"
    click TestPy "https://github.com/lutao2021/pidray/blob/main/tools/test.py"
    click PID1 "https://github.com/lutao2021/pidray/blob/main/configs/cascade_mask_rcnn_r101_with_R0R1.py"
    click PID2 "https://github.com/lutao2021/pidray/blob/main/configs/ddod_r101_with_R0R1.py"
    click BaseRun "https://github.com/lutao2021/pidray/blob/main/mmdet/.mim/configs/_base_/default_runtime.py"
    click BaseData "https://github.com/lutao2021/pidray/tree/main/mmdet/.mim/configs/_base_/datasets/"
    click BaseModel "https://github.com/lutao2021/pidray/tree/main/mmdet/.mim/configs/_base_/models/"
    click BaseSched "https://github.com/lutao2021/pidray/tree/main/mmdet/.mim/configs/_base_/schedules/"
    click Builder "https://github.com/lutao2021/pidray/blob/main/mmdet/datasets/builder.py"
    click CustomDS "https://github.com/lutao2021/pidray/blob/main/mmdet/datasets/custom.py"
    click MBBuilder "https://github.com/lutao2021/pidray/blob/main/mmdet/models/builder.py"
    click MBInit "https://github.com/lutao2021/pidray/blob/main/mmdet/models/__init__.py"
    click UtilsBuild "https://github.com/lutao2021/pidray/blob/main/mmdet/models/utils/builder.py"
    click BrickWrap "https://github.com/lutao2021/pidray/blob/main/mmdet/models/utils/brick_wrappers.py"
    click TrainAPI "https://github.com/lutao2021/pidray/blob/main/mmdet/apis/train.py"
    click InferenceAPI "https://github.com/lutao2021/pidray/blob/main/mmdet/apis/inference.py"
    click HooksDir "https://github.com/lutao2021/pidray/tree/main/mmdet/core/hook/"
    click AnchorMod "https://github.com/lutao2021/pidray/tree/main/mmdet/core/anchor/"
    click BBoxMod "https://github.com/lutao2021/pidray/tree/main/mmdet/core/bbox/"
    click MaskMod "https://github.com/lutao2021/pidray/tree/main/mmdet/core/mask/"
    click OptMod "https://github.com/lutao2021/pidray/tree/main/mmdet/core/optimizers/"
    click PostProc "https://github.com/lutao2021/pidray/tree/main/mmdet/core/post_processing/"
    click UtilsLog "https://github.com/lutao2021/pidray/blob/main/mmdet/utils/logger.py"
    click UtilsCfg "https://github.com/lutao2021/pidray/blob/main/mmdet/utils/compat_config.py"
    click UtilsDist "https://github.com/lutao2021/pidray/blob/main/mmdet/utils/util_distribution.py"
    click TestAPI "https://github.com/lutao2021/pidray/blob/main/mmdet/apis/test.py"
    click EvalTools "https://github.com/lutao2021/pidray/blob/main/mmdet/core/evaluation/mean_ap.py"
    click ExportPTONX "https://github.com/lutao2021/pidray/blob/main/mmdet/core/export/pytorch2onnx.py"
    click ExportHelper "https://github.com/lutao2021/pidray/blob/main/mmdet/core/export/onnx_helper.py"
    click DeployONNX "https://github.com/lutao2021/pidray/blob/main/mmdet/.mim/tools/deployment/pytorch2onnx.py"
    click DeployTRT "https://github.com/lutao2021/pidray/blob/main/mmdet/.mim/tools/deployment/onnx2tensorrt.py"
    click DeployTS "https://github.com/lutao2021/pidray/blob/main/mmdet/.mim/tools/deployment/mmdet2torchserve.py"
    click SlurmTrain "https://github.com/lutao2021/pidray/blob/main/mmdet/.mim/tools/slurm_train.sh"
    click SlurmTest "https://github.com/lutao2021/pidray/blob/main/mmdet/.mim/tools/slurm_test.sh"
    click DistLaunchT "https://github.com/lutao2021/pidray/blob/main/mmdet/.mim/tools/dist_train.sh"
    click DistLaunchTe "https://github.com/lutao2021/pidray/blob/main/mmdet/.mim/tools/dist_test.sh"

    %% Styles
    classDef cli fill:#FFF2CC,stroke:#E0A800
    classDef config fill:#CCE5FF,stroke:#0050B3
    classDef data fill:#D5E8D4,stroke:#2E7D32
    classDef model fill:#FFE0B2,stroke:#EF6C00
    classDef core fill:#E1BEE7,stroke:#6A1B9A
    classDef eval fill:#F8BBD0,stroke:#C2185B
    classDef ext fill:#F5F5F5,stroke:#9E9E9E
```
