# xg-chu/crowddet architecture

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

- Interactive diagram: https://gitdiagram.com/xg-chu/crowddet
- Repository: https://github.com/xg-chu/crowddet

## Overview

##### Project type and purpose
- This is a PyTorch-based, research-oriented object‐detection toolkit for crowded scenes (“CrowdDet”), implementing the CVPR-2020 paper “One Proposal, Multiple Predictions.”
- It is not a web or full-stack app but an open‐source machine-learning framework focusing on training, inference, and evaluation of detection models.

##### File structure
- Top-level files and folders:
- Dockerfile, requirements.txt: deployment and dependencies
- lib/: core library components (backbone networks, data loaders, detection operators, custom layers, model utilities, loss functions, evaluation toolkits)
- model/: ready‐to‐configure model definitions (each subfolder has a config.py and network.py for variants: RCNN/RetinaNet, FPN vs. EMD, baseline vs. refined)
- tools/: CLI entry points (train.py, test.py, inference.py, eval_json.py, visulize_json.py)
- Patterns:
- Modular architecture separating data, model definition, ops, training/inference scripts
- Strategy pattern in model configs for selecting network variant
- Pipeline structure: data → backbone → feature pyramid → proposals → heads → losses → postprocessing → evaluation

##### Insights from the README
- The system expects the CrowdHuman dataset (data path set in config.py)
- External dependencies: PyTorch, MegEngine-converted pretrained weights.

1. Data Ingestion & Preprocessing
- CrowdHuman dataset loader (lib/data/CrowdHuman.py)
- Transformations, batching
2. Core Model Library
- Backbone (lib/backbone/*.py): ResNet50, FPN
- Detection Operators (lib/det_oprs/*.py): anchor generation, proposal filtering, ROI target assignment, EMD loss
- Custom Layers (lib/layers/*.py): batch norm, pooler
- Modules (lib/module/rpn.py): RPN head, ROI heads
3. Model Configurations & Networks (model/*)
- Config file (hyperparameters, dataset paths)
- Network defs (assembling backbone + FPN + heads + EMD extensions)
4. Training & Inference Scripts (tools/*.py)
- train.py: orchestrates data loader → model → optimizer (SGD_bias) → loss → checkpointing
- test.py, inference.py: load checkpoint → forward pass → postprocessing
5. Evaluation Toolkits (lib/evaluate/*)
- APMRToolkits, JIToolkits: matching and metric computation
6. Deployment Environment
- Docker container, GPU resources

- Data Loader → Model Input
- Model Components: Backbone → FPN → RPN → ROI Heads → EMD Loss & Set NMS → Predictions
- Predictions → Postprocessing (nms_utils) → Output JSON
- Output JSON → Evaluation Toolkits → Metrics

c. Architectural patterns & principles:
- Modular separation of concerns: data / model / ops / utils
- Plugin-style model variants via config + network pairing
- Pipeline design for training versus inference branching
- Extensibility: new detection ops or backbones can be dropped into lib/ and wired via config

d. Key technologies, frameworks, libraries:
- Python 3, PyTorch, NVIDIA-Docker
- Custom modules in lib/ for performance (vectorized ops, CUD A-compatible)
- MegEngine pretrained model loader (converted to PyTorch)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & I/O Layer (Blue)
    subgraph "Data & I/O" 
        direction TB
        Dataset[(CrowdHuman Dataset)]:::data_blue
        DataLoader["Data Loader\n(lib/data/CrowdHuman.py)"]:::data_blue
        Transforms["Transformations\n(batching, augmentation)"]:::data_blue
    end

    %% Core Model & Operators (Green)
    subgraph "Core Model & Operators"
        direction TB
        subgraph "Backbone & FPN"
            direction TB
            ResNet50["ResNet50\n(lib/backbone/resnet50.py)"]:::core_green
            FPN["FPN\n(lib/backbone/fpn.py)"]:::core_green
        end
        subgraph "Detection Operators"
            direction TB
            Anchors["Anchor Generation\n(lib/det_oprs/anchors_generator.py)"]:::core_green
            RPNProposals["Proposal Filtering\n(lib/det_oprs/find_top_rpn_proposals.py)"]:::core_green
            AnchorTargets["Anchor Targeting\n(lib/det_oprs/fpn_anchor_target.py)"]:::core_green
            ROITargets["ROI Targeting\n(lib/det_oprs/fpn_roi_target.py)"]:::core_green
            LossOps["EMD Loss & Utilities\n(lib/det_oprs/loss_opr.py)"]:::core_green
        end
        subgraph "Custom Layers"
            direction TB
            BatchNorm["BatchNorm\n(lib/layers/batch_norm.py)"]:::core_green
            Pooler["Pooler\n(lib/layers/pooler.py)"]:::core_green
        end
        subgraph "Heads & Modules"
            direction TB
            RPNHead["RPN & ROI Heads\n(lib/module/rpn.py)"]:::core_green
        end
        PostProc["Set NMS & Postprocessing\n(lib/utils/nms_utils.py)"]:::core_green
    end

    %% Evaluation (Purple)
    subgraph "Evaluation Toolkits"
        direction TB
        APMR["AP/MR Toolkits\n(lib/evaluate/APMRToolkits)"]:::eval_purple
        JI["JI Toolkits\n(lib/evaluate/JIToolkits)"]:::eval_purple
        ComputeAPMR["compute_APMR.py"]:::eval_purple
        ComputeJI["compute_JI.py"]:::eval_purple
    end

    %% Tools & Scripts (Orange)
    subgraph "CLI Scripts"
        direction TB
        Train["train.py"]:::tool_orange
        Test["test.py"]:::tool_orange
        Infer["inference.py"]:::tool_orange
        EvalJSON["eval_json.py"]:::tool_orange
        Visualize["visulize_json.py"]:::tool_orange
    end

    %% Deployment (Gray)
    Docker(("Docker Container\n+ GPU")):::deploy_gray
    Req([requirements.txt]):::deploy_gray

    %% Data Flow Arrows
    Dataset -->|images| DataLoader
    DataLoader -->|batches| Transforms
    Transforms -->|tensors| ResNet50

    %% Model Pipeline
    ResNet50 -->|feature maps| FPN
    FPN -->|multi-scale maps| Anchors
    Anchors -->|anchors| RPNProposals
    RPNProposals -->|filtered proposals| RPNHead
    RPNHead -->|roi features| ROITargets
    ROITargets -->|roi batches| Pooler
    Pooler -->|pooled features| RPNHead
    RPNHead -->|predictions| PostProc

    %% Inference & Training Branch
    PostProc -->|detections JSON| EvalJSON
    PostProc -->|detections JSON| Visualize

    %% Loss Computation (Training)
    RPNHead -->|features + gt| LossOps
    LossOps -->|loss| Train

    %% Tools Driving Flow
    Train -->|calls| DataLoader
    Train -->|calls| FPN
    Train -->|calls| LossOps
    Test -->|loads checkpoint| PostProc
    Infer -->|loads checkpoint| PostProc
    EvalJSON -->|inputs JSON| ComputeAPMR
    EvalJSON -->|inputs JSON| ComputeJI
    Visualize -->|inputs JSON| ComputeAPMR

    %% Evaluation Arrows
    ComputeAPMR --> APMR
    ComputeJI --> JI

    %% Deployment Links
    Docker --> Train
    Docker --> Test
    Docker --> Infer
    Docker --> EvalJSON
    Docker --> Visualize
    Docker --> Req

    %% Click Events
    click DataLoader "https://github.com/xg-chu/crowddet/blob/master/lib/data/CrowdHuman.py"
    click ResNet50 "https://github.com/xg-chu/crowddet/blob/master/lib/backbone/resnet50.py"
    click FPN "https://github.com/xg-chu/crowddet/blob/master/lib/backbone/fpn.py"
    click Anchors "https://github.com/xg-chu/crowddet/blob/master/lib/det_oprs/anchors_generator.py"
    click RPNProposals "https://github.com/xg-chu/crowddet/blob/master/lib/det_oprs/find_top_rpn_proposals.py"
    click AnchorTargets "https://github.com/xg-chu/crowddet/blob/master/lib/det_oprs/fpn_anchor_target.py"
    click ROITargets "https://github.com/xg-chu/crowddet/blob/master/lib/det_oprs/fpn_roi_target.py"
    click LossOps "https://github.com/xg-chu/crowddet/blob/master/lib/det_oprs/loss_opr.py"
    click BatchNorm "https://github.com/xg-chu/crowddet/blob/master/lib/layers/batch_norm.py"
    click Pooler "https://github.com/xg-chu/crowddet/blob/master/lib/layers/pooler.py"
    click RPNHead "https://github.com/xg-chu/crowddet/blob/master/lib/module/rpn.py"
    click PostProc "https://github.com/xg-chu/crowddet/blob/master/lib/utils/nms_utils.py"
    click Train "https://github.com/xg-chu/crowddet/blob/master/tools/train.py"
    click Test "https://github.com/xg-chu/crowddet/blob/master/tools/test.py"
    click Infer "https://github.com/xg-chu/crowddet/blob/master/tools/inference.py"
    click EvalJSON "https://github.com/xg-chu/crowddet/blob/master/tools/eval_json.py"
    click Visualize "https://github.com/xg-chu/crowddet/blob/master/tools/visulize_json.py"
    click APMR "https://github.com/xg-chu/crowddet/blob/master/lib/evaluate/APMRToolkits/database.py"
    click JI "https://github.com/xg-chu/crowddet/blob/master/lib/evaluate/JIToolkits/JI_tools.py"
    click ComputeAPMR "https://github.com/xg-chu/crowddet/blob/master/lib/evaluate/compute_APMR.py"
    click ComputeJI "https://github.com/xg-chu/crowddet/blob/master/lib/evaluate/compute_JI.py"

    %% Styles
    classDef data_blue fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef core_green fill:#DFF7DF,stroke:#228B22,color:#228B22
    classDef tool_orange fill:#FFE8CC,stroke:#FF8C00,color:#FF8C00
    classDef eval_purple fill:#F0DEFF,stroke:#800080,color:#800080
    classDef deploy_gray fill:#F2F2F2,stroke:#808080,color:#808080
```
