# sentient07/headhunter architecture

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

- Interactive diagram: https://gitdiagram.com/sentient07/headhunter
- Repository: https://github.com/sentient07/headhunter

## Overview

##### Project type and purpose
- This is a Python-based head-detection module built on PyTorch.
- It provides end-to-end functionality: data ingestion, model definition (ResNet backbones, detection heads, DeformConv), distributed training, evaluation, and inference.

##### File structure
- Top-level “train.py”, “evaluate.py”, “test.py” orchestrate training, evaluation, and qualitative testing.
- “config/” holds YAML files for pre-training (PT), fine-tuning (FT), and head-specific configs (SHead).
- The “head_detection” package breaks down into:
- data/ (anchors, dataset builders, configs)
- models/ (backbones, detection heads, NMS, Fast R-CNN wrapper, DeformConv)
- vision/ (Engine: training/eval loops; Transform: image preprocessing; Utils: helpers)
- utils/ (general utility functions)
- “setup.py” lets you pip-install the module; “env_super.yml” & requirements describe environment dependencies.

##### README for additional insights
- Dependencies: Python, PyTorch, CUDA/CUDNN, NVIDIA driver, conda env or pip.
- Primary workflows:
- Distributed training via torch.distributed and train.py
- Evaluation via evaluate.py (AP, MMR, F1, MODA, MODP metrics)
- Inference via test.py (qualitative outputs)
- Config files drive dataset paths, hyperparams, model choices.

a. Main Components
1. External Dependencies: NVIDIA GPU + CUDA/CUDNN, PyTorch, TorchVision, Conda/Pip
2. Config Manager: YAML reader (config/PT, config/FT, config/SHead)
3. Data Module:
- Anchors generator
- Dataset builder (ScutHead, CrowdHuman, CroHD)
- Transforms & Augmentations
4. Model Module:
- Backbone (ResNet50/ResNet150, optional MobileNet)
- Detection head (Fast R-CNN head, optional DeformConv)
- NMS post-processing
5. Engine (head_detection.vision.engine):
- Training loop with distributed support
- Validation loop
- Checkpointing
6. Evaluation Module (evaluate.py)
7. Inference Module (test.py)
8. Output Store: Model checkpoints, logs, metrics, qualitative images

b. Relationships & Data Flow
- Config Manager drives Data Module (dataset paths, batch size) and Model Module (architecture, learning rate).
- Engine ↔ Model Module (forward, backward pass, weight updates)
- Engine → Output Store (checkpoints, tensorboard logs)
- Evaluation Module loads checkpoint → Data Module (validation split) → Model → Metrics → Output Store
- Inference Module loads checkpoint → Data Module (test split/images) → Model → Qualitative images → Output Store

c. Architectural Patterns & Principles
- Modular package structure for separation of concerns (data, models, vision utilities)
- Config-driven execution to minimize CLI args
- Distributed training via torch.distributed
- Plug-and-play pip installable component (setup.py) to integrate with HeadHunter-T

d. Key Technologies & Frameworks
- Python 3.x, PyTorch, TorchVision
- CUDA 10.0 + cuDNN
- YAML for configuration
- Conda/Pip for environment management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies
    subgraph "External Dependencies"
        GPU["NVIDIA GPU + CUDA/CUDNN"]:::external
        PYT["PyTorch + TorchVision"]:::external
        ENV["Conda/Pip"]:::external
    end

    %% Config Manager
    subgraph "Config Manager"
        CFG_FILES["YAML Configs (config/)"]:::config
        CFG_LOADER["Runtime Config Loader\n(head_detection/data/config.py)"]:::config
    end

    %% Data Module
    subgraph "Data Module"
        ANCH["Anchor Generator\n(head_detection/data/anchors.py)"]:::core
        DS_BUILD["Dataset Builders\n(create_scuthead.py, create_chuman.py)"]:::core
        DS_INT["Dataset Interface\n(head_detection/data/dataset.py)"]:::core
    end

    %% Model Module
    subgraph "Model Module"
        NET["Backbone & Network\n(head_detection/models/net.py)"]:::core
        HEAD["Detection Heads\n(head_detection/models/head_detect.py)"]:::core
        RCNN["Fast R-CNN Wrapper\n(head_detection/models/fast_rcnn.py)"]:::core
        DEF["DeformConv2D\n(head_detection/models/deformconv2d.py)"]:::core
        NMS["Non-Maximum Suppression\n(head_detection/models/nms.py)"]:::core
    end

    %% Vision Engine & Utilities
    subgraph "Vision Engine & Utilities"
        ENG["Engine (Training/Eval)\n(head_detection/vision/engine.py)"]:::core
        TRANS["Transforms & Augmentations\n(head_detection/vision/transform.py)"]:::core
        VUTIL["Vision Utils\n(head_detection/vision/utils.py)"]:::core
    end

    %% General Utilities
    subgraph "General Utilities"
        GUTIL["General Utils\n(head_detection/utils/)"]:::core
    end

    %% Package Setup & Environment
    subgraph "Package & Environment"
        SETUP["setup.py"]:::pkg
        ENVYML["env_super.yml"]:::pkg
    end

    %% Scripts
    subgraph "External Execution Scripts"
        TRAIN["train.py"]:::script
        EVAL["evaluate.py"]:::script
        TEST["test.py"]:::script
    end

    %% Output Store
    subgraph "Output Store"
        CHKP[(Model Checkpoints)]:::store
        LOGS[(Logs & Metrics)]:::store
        IMGS[(Qualitative Images)]:::store
    end

    %% Relationships
    CFG_LOADER -->|drives| ANCH
    CFG_LOADER -->|drives| DS_BUILD
    CFG_LOADER -->|drives| NET
    CFG_LOADER -->|drives| HEAD

    ANCH --> DS_INT
    DS_BUILD --> DS_INT
    DS_INT --> ENG

    ENG -->|forward/backward| NET
    ENG -->|forward/backward| HEAD
    ENG -->|forward/backward| RCNN
    ENG -->|forward/backward| DEF
    ENG -->|post-process| NMS

    ENG --> CHKP
    ENG --> LOGS

    TRAIN -->|starts| ENG
    EVAL -->|loads checkpoint| DS_INT
    DS_INT -->|validation data| NET
    NET -->|predictions| EVAL
    EVAL --> LOGS

    TEST -->|loads checkpoint| DS_INT
    DS_INT -->|test images| NET
    NET -->|outputs| IMGS

    GUTIL --> ENG
    TRANS --> ENG
    VUTIL --> ENG

    GPU --> ENG
    PYT --> ENG
    ENV --> TRAIN
    ENV --> EVAL
    ENV --> TEST

    SETUP -->|installs| GUTIL
    SETUP -->|installs| DS_INT
    SETUP -->|installs| NET

    %% Click Events
    click TRAIN "https://github.com/sentient07/headhunter/blob/master/train.py"
    click EVAL "https://github.com/sentient07/headhunter/blob/master/evaluate.py"
    click TEST "https://github.com/sentient07/headhunter/blob/master/test.py"
    click CFG_FILES "https://github.com/sentient07/headhunter/tree/master/config/"
    click CFG_LOADER "https://github.com/sentient07/headhunter/blob/master/head_detection/data/config.py"
    click ANCH "https://github.com/sentient07/headhunter/blob/master/head_detection/data/anchors.py"
    click DS_BUILD "https://github.com/sentient07/headhunter/blob/master/head_detection/data/create_scuthead.py"
    click DS_BUILD "https://github.com/sentient07/headhunter/blob/master/head_detection/data/create_chuman.py"
    click DS_INT "https://github.com/sentient07/headhunter/blob/master/head_detection/data/dataset.py"
    click NET "https://github.com/sentient07/headhunter/blob/master/head_detection/models/net.py"
    click HEAD "https://github.com/sentient07/headhunter/blob/master/head_detection/models/head_detect.py"
    click RCNN "https://github.com/sentient07/headhunter/blob/master/head_detection/models/fast_rcnn.py"
    click DEF "https://github.com/sentient07/headhunter/blob/master/head_detection/models/deformconv2d.py"
    click NMS "https://github.com/sentient07/headhunter/blob/master/head_detection/models/nms.py"
    click ENG "https://github.com/sentient07/headhunter/blob/master/head_detection/vision/engine.py"
    click TRANS "https://github.com/sentient07/headhunter/blob/master/head_detection/vision/transform.py"
    click VUTIL "https://github.com/sentient07/headhunter/blob/master/head_detection/vision/utils.py"
    click GUTIL "https://github.com/sentient07/headhunter/tree/master/head_detection/utils/"
    click SETUP "https://github.com/sentient07/headhunter/blob/master/setup.py"
    click ENVYML "https://github.com/sentient07/headhunter/blob/master/env_super.yml"

    %% Styles
    classDef external fill:#f9d5a2,stroke:#e07a5f,color:#000
    classDef config fill:#dddddd,stroke:#999999,color:#000
    classDef core fill:#a8dadc,stroke:#457b9d,color:#000
    classDef script fill:#caffbf,stroke:#2b9348,color:#000
    classDef pkg fill:#fce8b2,stroke:#ffba08,color:#000
    classDef store fill:#ffe5d9,stroke:#f28482,color:#000
```
