# idogalil/people-counting-system architecture

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

- Interactive diagram: https://gitdiagram.com/idogalil/people-counting-system
- Repository: https://github.com/idogalil/people-counting-system

## Overview

##### Main Components
a. Input Sources
- IP Camera or Video File (external video feed)
b. Orchestration Layer
- main.py + FrameProcessor.py
- Coordinates reading frames, invoking detection, tracking, counting, and output.
c. Detection Module
- yolov3 package
- yolo_detection_model.py (loads the .h5 weights)
- decoder_layer.py, yolo_util.py (post-processing, anchor handling)
- model_data folder
- coco_anchors.txt, coco_classes.txt, downloaded YOLOv3-416.h5
d. Tracking Module
- tracker.py
- DCF-CSR / CSRT trackers encapsulated here
e. Counting Module
- counter.py
- Line-crossing logic, DI and MCDF parameters loaded from env.env
f. Utilities
- util/
- bounding_box.py (geometry)
- debugger.py (visual overlays)
- detection_roi.py (region-of-interest cropping)
- logger.py (structured logging)
- objects.py (track and detection data structures)
g. Output / Storage
- Annotated Video Stream (display, saved file, or streaming output)
- Logs / CSV or other counts output
- (Optionally) External Dashboard or Database
h. Configuration
- requirements.txt (dependency list)
- env.env (CUDA, GPU flags, DI, MCDF, other hyperparameters)

##### Relationships & Data Flow
1. Video Source → FrameProcessor
→ FrameProcessor pulls raw frames.
2. FrameProcessor → Detection Module (YOLOv3)
3. Detections → Tracking Module
→ tracker assigns persistent IDs across frames.
4. Tracks → Counting Module
→ logic checks ROI/virtual lines for “enter” vs “exit” events.
5. Counting Results → Logger & Output
→ annotated frame via Debugger + count updates logged to file or console.
6. Utilities invoked at each step for debugging, ROI filtering, and logging.
7. All modules read configuration from env.env and model_data.

##### Architectural Patterns & Principles
- Pipeline architecture: linear sequence (Input → Detect → Track → Count → Output)
- Separation of concerns: detection, tracking, counting, and utilities are in independent modules
- Modular design: easy to swap detector or tracker (noted in README)
- Config-driven parameters: DI, MCDF, paths set in env.env

##### Technologies & Frameworks
- Python 3.6.10
- TensorFlow / Keras (for YOLOv3 .h5 model)
- OpenCV (video I/O, CSRT tracker)
- CUDA 9.0 + GPU acceleration
- pip dependencies in requirements.txt

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input and Orchestration
    input[/IP Camera or Video File/]:::external
    input -->|"Frame"| main["main.py"]:::core
    click main "https://github.com/idogalil/people-counting-system/blob/master/main.py"
    
    %% Pipeline Core
    main -->|"Initialize & Read Frames"| fp["FrameProcessor.py"]:::core
    click fp "https://github.com/idogalil/people-counting-system/blob/master/FrameProcessor.py"
    
    fp -->|"Frame"| detSub

    subgraph "Detection Module" 
        det1["yolo_detection_model.py"]:::core
        det2["decoder_layer.py"]:::core
        det3["yolo_util.py"]:::core
    end
    detSub -->|"Frame"| det1
    det1 --> det2
    det2 --> det3
    det3 -->|"Detections"| trk

    click det1 "https://github.com/idogalil/people-counting-system/blob/master/yolov3/yolo_detection_model.py"
    click det2 "https://github.com/idogalil/people-counting-system/blob/master/yolov3/decoder_layer.py"
    click det3 "https://github.com/idogalil/people-counting-system/blob/master/yolov3/yolo_util.py"

    %% Tracking
    trk["tracker.py"]:::core
    click trk "https://github.com/idogalil/people-counting-system/blob/master/tracker.py"
    det3 -->|"Detections"| trk
    trk -->|"Tracks"| cnt

    %% Counting
    cnt["counter.py"]:::core
    click cnt "https://github.com/idogalil/people-counting-system/blob/master/counter.py"
    trk -->|"Tracks"| cnt

    %% Output
    outVid((Annotated Video Stream)):::external
    outLog((Logs / CSV Output)):::config
    cnt -->|"Counts"| outVid
    cnt -->|"Logs"| outLog

    %% Model Data
    subgraph "model_data" 
        md1["coco_anchors.txt"]:::config
        md2["coco_classes.txt"]:::config
    end
    click md1 "https://github.com/idogalil/people-counting-system/blob/master/model_data/coco_anchors.txt"
    click md2 "https://github.com/idogalil/people-counting-system/blob/master/model_data/coco_classes.txt"
    md1 -.-> det1
    md2 -.-> det1

    %% Configuration & Dependencies
    env["env.env"]:::config
    req["requirements.txt"]:::config
    readme["README.md"]:::config
    click env "https://github.com/idogalil/people-counting-system/blob/master/env.env"
    click req "https://github.com/idogalil/people-counting-system/blob/master/requirements.txt"
    click readme "https://github.com/idogalil/people-counting-system/blob/master/README.md"
    env -.-> cnt
    env -.-> main
    req -.-> main
    readme -.-> main

    %% Utilities
    utilBB("(bounding_box)"):::util
    utilDbg("(debugger)"):::util
    utilROI("(detection_roi)"):::util
    utilLog("(logger)"):::util
    utilObj("(objects)"):::util

    click utilBB "https://github.com/idogalil/people-counting-system/blob/master/util/bounding_box.py"
    click utilDbg "https://github.com/idogalil/people-counting-system/blob/master/util/debugger.py"
    click utilROI "https://github.com/idogalil/people-counting-system/blob/master/util/detection_roi.py"
    click utilLog "https://github.com/idogalil/people-counting-system/blob/master/util/logger.py"
    click utilObj "https://github.com/idogalil/people-counting-system/blob/master/util/objects.py"

    utilROI -.-> det3
    utilDbg -.-> det3
    utilDbg -.-> fp
    utilDbg -.-> cnt
    utilBB -.-> trk
    utilObj -.-> trk

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,stroke-width:2px;
    classDef external fill:#DFFFE0,stroke:#228B22,stroke-width:2px;
    classDef util fill:#F0F0F0,stroke:#888888,stroke-width:1px,stroke-dasharray: 2 2;
    classDef config fill:#FFF4E6,stroke:#DAA520,stroke-width:2px;
```
