# kaiyangzhou/deep-person-reid architecture

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

- Interactive diagram: https://gitdiagram.com/kaiyangzhou/deep-person-reid
- Repository: https://github.com/kaiyangzhou/deep-person-reid

## Overview

##### Project type and purpose
- Torchreid is an open-source PyTorch-based library for person re-identification.

a. CLI / Orchestrator (scripts/)
- scripts/main.py: entry point.
- scripts/default_config.py: default hyperparameters.
- Makefile / Dockerfile: build & deploy.
b. Configuration layer (configs/)
- YAML files: experiment-specific hyperparams.
- Parsed by a config loader in scripts/main.py.
c. Core Library (torchreid/)
- Data Module (torchreid/data/)
– ImageDataManager / VideoDataManager
– Datasets, Samplers, Transforms
- Model Module (torchreid/models/)
– Backbones (ResNet, OSNet, MobileNet, NASNet, etc.)
– Re-id heads, omni-scale blocks, IBN layers
- Engine Module (torchreid/engine/)
– Base Engine, ImageSoftmaxEngine, TripletEngine, Video variants
– Encapsulates training loop, forward/backward pass, evaluation hooks
- Losses Module (torchreid/losses/)
– CrossEntropy, Triplet, Hard-Mining, Label-Smooth
- Metrics Module (torchreid/metrics/)
– Accuracy, Rank, Distance; Cython extensions for fast ranking
- Optimizers & Schedulers (torchreid/optim/)
– Adam, RAdam, LR schedulers (single-step, Warmup, Cosine)
- Utils (torchreid/utils/)
– FeatureExtractor, Logger, Re-ranking, TensorBoard support
d. Example Projects (projects/)
– DML (Deep Mutual Learning)
– OSNet_AIN (NAS search)
– attribute_recognition (person attribute labels)
– Each contains its own main.py, configs, and custom code
e. Tools (tools/)
– compute_mean_std.py: dataset statistics
– export.py: model export (ONNX, OpenVINO, TFLite)
– parse_test_res.py: aggregate results
– visualize_actmap.py: activation map visualization
f. External Dependencies & Services
- PyTorch + CUDA GPU
- TensorBoard for visualization
- ONNX / OpenVINO / TFLite runtimes (export)
- Standard re-id datasets (Market1501, Duke, MSMT17, etc.)

1. User invokes CLI → parses command-line args + YAML config
2. CLI → Config Loader → populates a config object
3. CLI → DataManager Factory → Data Module → DataLoader → Engine
4. CLI → ModelBuilder Factory → Core Model Module → Engine
5. CLI → OptimizerBuilder & SchedulerBuilder → Engine
6. Engine → Loss Module + Metrics Module
7. Engine → Torch backend (autograd, GPU) → parameter updates
8. Engine → Logger / TensorBoard → persist training curves
9. Engine → Checkpoint Saver → disk (model.pth.tar)
10. CLI / Tools/export.py → loads checkpoint → performs model export
11. Example Projects → reuse Core Library via import torchreid → override or extend components

##### Architectural patterns & design principles
- Factory / Registry pattern for models, optimizers, schedulers (build_XXX APIs)
- Separation of concerns: data loading, model definition, training loop, evaluation, utilities
- Config-driven experiment management (YAML + defaults)
- Plugin-style extensibility: drop-in new datasets, samplers, losses, metrics
- High-performance extensions: Cython for re-ranking; multi-GPU via DataParallel

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User entry
    User["User"]:::external

    %% CLI / Orchestrator
    subgraph "CLI / Orchestrator"
        scripts_main["scripts/main.py"]:::cli
        default_cfg["scripts/default_config.py"]:::cli
        Makefile["Makefile"]:::cli
        Dockerfile["Dockerfile"]:::cli
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        configs["configs/*.yaml"]:::config
    end

    %% Core Library
    subgraph "Core Library (torchreid)"
        %% Data Module
        subgraph "Data Module" 
            datamanager["ImageDataManager / VideoDataManager"]:::data
            sampler["sampler.py"]:::data
            transforms["transforms.py"]:::data
            datasets["datasets/ (image & video)"]:::data
        end
        %% Model Module
        subgraph "Model Module"
            models_pkg["models/ (backbones & heads)"]:::model
        end
        %% Engine Module
        subgraph "Engine Module"
            engine_base["engine.py"]:::engine
            img_softmax["image/softmax.py"]:::engine
            img_triplet["image/triplet.py"]:::engine
            vid_softmax["video/softmax.py"]:::engine
            vid_triplet["video/triplet.py"]:::engine
        end
        %% Losses Module
        subgraph "Losses Module"
            loss_ce["cross_entropy_loss.py"]:::loss
            loss_hard["hard_mine_triplet_loss.py"]:::loss
        end
        %% Metrics Module
        subgraph "Metrics Module"
            metric_acc["accuracy.py"]:::metric
            metric_dist["distance.py"]:::metric
            metric_rank["rank.py"]:::metric
            metric_cy["rank_cylib/"]:::metric
        end
        %% Optimizers & Schedulers
        subgraph "Optim & Schedulers"
            optim_base["optimizer.py"]:::optim
            optim_radam["radam.py"]:::optim
            sched["lr_scheduler.py"]:::optim
        end
        %% Utils
        subgraph "Utils"
            util_avg["avgmeter.py"]:::util
            util_feat["feature_extractor.py"]:::util
            util_log["loggers.py"]:::util
            util_rerank["rerank.py"]:::util
            util_tools["tools.py"]:::util
            util_torchtools["torchtools.py"]:::util
            util_gpu["GPU-Re-Ranking/"]:::util
        end
    end

    %% Tools & Analysis
    subgraph "Tools"
        t_mean["compute_mean_std.py"]:::tools
        t_export["export.py"]:::tools
        t_parse["parse_test_res.py"]:::tools
        t_vis["visualize_actmap.py"]:::tools
    end

    %% Example Projects
    subgraph "Example Projects"
        proj_dml["projects/DML/"]:::project
        proj_osnet["projects/OSNet_AIN/"]:::project
        proj_attr["projects/attribute_recognition/"]:::project
    end

    %% External Dependencies & Services
    subgraph "External"
        pytorch["PyTorch"]:::external
        cuda["CUDA GPU"]:::external
        tb["TensorBoard"]:::external
        onnx_rt["ONNX/OpenVINO/TFLite runtime"]:::external
        datasets_ext["Market1501, Duke, MSMT17"]:::external
    end

    %% Storage
    checkpoint["Checkpoint (model.pth.tar)"]:::storage

    %% Relationships
    User -->|invokes CLI| scripts_main
    scripts_main -->|loads defaults| default_cfg
    scripts_main -->|parses YAML| configs
    scripts_main -->|DataManager Factory| datamanager
    datamanager --> sampler
    datamanager --> transforms
    datamanager --> datasets
    scripts_main -->|ModelBuilder Factory| models_pkg
    scripts_main -->|Optimizer/Scheduler Builder| optim_base
    optim_base --> optim_radam
    optim_base --> sched
    scripts_main -->|init Engine| engine_base
    engine_base --> img_softmax
    engine_base --> img_triplet
    engine_base --> vid_softmax
    engine_base --> vid_triplet
    engine_base -->|compute loss| loss_ce
    engine_base -->|compute loss| loss_hard
    engine_base -->|compute metrics| metric_acc
    engine_base -->|compute metrics| metric_dist
    engine_base -->|compute metrics| metric_rank
    engine_base -->|compute metrics| metric_cy
    engine_base -->|autograd & GPU| pytorch
    pytorch --> cuda
    engine_base -->|log metrics| util_log
    util_log --> tb
    engine_base -->|save checkpoint| checkpoint
    t_export -->|loads checkpoint| checkpoint
    t_export -->|export model| onnx_rt
    proj_dml -->|import torchreid / extend| models_pkg
    proj_osnet -->|import torchreid / extend| models_pkg
    proj_attr -->|import torchreid / extend| datamanager
    proj_attr -->|import torchreid / extend| models_pkg

    %% Click Events
    click scripts_main "https://github.com/kaiyangzhou/deep-person-reid/blob/master/scripts/main.py"
    click default_cfg "https://github.com/kaiyangzhou/deep-person-reid/blob/master/scripts/default_config.py"
    click Makefile "https://github.com/kaiyangzhou/deep-person-reid/tree/master/Makefile"
    click Dockerfile "https://github.com/kaiyangzhou/deep-person-reid/tree/master/Dockerfile"
    click configs "https://github.com/kaiyangzhou/deep-person-reid/tree/master/configs/"
    click datamanager "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/data/datamanager.py"
    click sampler "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/data/sampler.py"
    click transforms "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/data/transforms.py"
    click datasets "https://github.com/kaiyangzhou/deep-person-reid/tree/master/torchreid/data/datasets/"
    click models_pkg "https://github.com/kaiyangzhou/deep-person-reid/tree/master/torchreid/models/"
    click engine_base "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/engine/engine.py"
    click img_softmax "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/engine/image/softmax.py"
    click img_triplet "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/engine/image/triplet.py"
    click vid_softmax "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/engine/video/softmax.py"
    click vid_triplet "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/engine/video/triplet.py"
    click loss_ce "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/losses/cross_entropy_loss.py"
    click loss_hard "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/losses/hard_mine_triplet_loss.py"
    click metric_acc "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/metrics/accuracy.py"
    click metric_dist "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/metrics/distance.py"
    click metric_rank "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/metrics/rank.py"
    click metric_cy "https://github.com/kaiyangzhou/deep-person-reid/tree/master/torchreid/metrics/rank_cylib/"
    click optim_base "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/optim/optimizer.py"
    click optim_radam "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/optim/radam.py"
    click sched "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/optim/lr_scheduler.py"
    click util_avg "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/utils/avgmeter.py"
    click util_feat "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/utils/feature_extractor.py"
    click util_log "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/utils/loggers.py"
    click util_rerank "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/utils/rerank.py"
    click util_tools "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/utils/tools.py"
    click util_torchtools "https://github.com/kaiyangzhou/deep-person-reid/blob/master/torchreid/utils/torchtools.py"
    click util_gpu "https://github.com/kaiyangzhou/deep-person-reid/tree/master/torchreid/utils/GPU-Re-Ranking/"
    click t_mean "https://github.com/kaiyangzhou/deep-person-reid/blob/master/tools/compute_mean_std.py"
    click t_export "https://github.com/kaiyangzhou/deep-person-reid/blob/master/tools/export.py"
    click t_parse "https://github.com/kaiyangzhou/deep-person-reid/blob/master/tools/parse_test_res.py"
    click t_vis "https://github.com/kaiyangzhou/deep-person-reid/blob/master/tools/visualize_actmap.py"
    click proj_dml "https://github.com/kaiyangzhou/deep-person-reid/tree/master/projects/DML/"
    click proj_osnet "https://github.com/kaiyangzhou/deep-person-reid/tree/master/projects/OSNet_AIN/"
    click proj_attr "https://github.com/kaiyangzhou/deep-person-reid/tree/master/projects/attribute_recognition/"

    %% Styles
    classDef cli fill:#f8b195,stroke:#c06c84,color:#000;
    classDef config fill:#fff3b0,stroke:#f6a6b2,color:#000;
    classDef data fill:#c1e1c1,stroke:#3b7a57,color:#000;
    classDef model fill:#b2f7ef,stroke:#2a9d8f,color:#000;
    classDef engine fill:#a8dadc,stroke:#457b9d,color:#000;
    classDef loss fill:#d8f3dc,stroke:#2f5233,color:#000;
    classDef metric fill:#e3f2fd,stroke:#2196f3,color:#000;
    classDef optim fill:#d7bde2,stroke:#884ea0,color:#000;
    classDef util fill:#f0e68c,stroke:#b8860b,color:#000;
    classDef tools fill:#d1c4e9,stroke:#673ab7,color:#000;
    classDef project fill:#ffe0b2,stroke:#fb8c00,color:#000;
    classDef external fill:#cfd8dc,stroke:#607d8b,color:#000;
    classDef storage fill:#ececec,stroke:#999,color:#000;
```
