# pyresearch/pyresearch architecture

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

- Interactive diagram: https://gitdiagram.com/pyresearch/pyresearch
- Repository: https://github.com/pyresearch/pyresearch

## Overview

##### Project type and purpose
- It’s a Python package (“pyresearch”) providing multiple real-time computer-vision and tracking modules (e.g. face detection, hand tracking, pose estimation, segmentation, object tracking/heatmap).
- The README shows usage examples built atop OpenCV and models like MediaPipe, YOLOv8, ByteTrack, Supervison.

##### File structure
Top-level:
- setup.py, MANIFEST, LICENSE, README.md
- Folder “pyresearch/” containing:
– ClassificationModule.py, ColorModule.py, FPS.py, FaceDetectionModule.py, FaceMeshModule.py,
HandTrackingModule.py, PIDModule.py, PlotModule.py, PoseModule.py, SelfiSegmentationModule.py,
SerialModule.py, Utils.py, heatmap_and_track.py, objectron.py, __init__.py
No “frontend/backend”—it’s a library. However, there is a clear layering:
- Data-acquisition (Camera, Video file, Serial port)
- Preprocessing & Utilities (ColorModule, Utils, PlotModule, FPS, PIDModule)
- CV-modules (Face…, Hand…, Pose…, SelfiSegmentation, Objectron, Classification)
- Pipeline (heatmap_and_track orchestrating YOLOv8 → ByteTrack → heatmap generation)

##### README for tech stack & flow
- External dependencies: OpenCV, MediaPipe, Ultralytics YOLOv8, ByteTrack, Supervision, NumPy, plus possible serial devices.

##### Main components & interactions
a. External Entities (outside the package)
- Input sources: Camera/Webcam, Video file, Background image file, Serial device
- Output sinks: OpenCV imshow window, VideoWriter/file, Serial device (for control signals)
- Utilities layer
– Utils (common helper functions)
– PlotModule (drawing utilities)
– FPS (frame-rate calculator)
– PIDModule (feedback/control logic)
– SerialModule (UART/serial I/O)
- CV Modules layer
– FaceDetectionModule
– FaceMeshModule
– HandTrackingModule
– PoseModule
– SelfiSegmentationModule
– Objectron (3D object detection)
– ClassificationModule (generic classifier wrappers)
- Pipeline layer
– heatmap_and_track.py (glues YOLOv8 detection + ByteTrack tracking + heatmap via Supervision API)
c. Dependencies & flows
- Each CV Module calls MediaPipe or an ML model for inference
- Utilities modules are leveraged by both CV modules and by user scripts (stackImages lives in Utils)
- setup.py assembles the package for pip distribution

##### Architectural patterns / design principles
- Modular layering: separate utilities, individual CV features, orchestration/pipelines
- Single responsibility: each module wraps one kind of detection or transformation
- Plugin-like: users import only the modules they need
- Pipeline composition: heatmap_and_track wires multiple sub-modules into an end-to-end workflow

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Sources
    subgraph "External Sources"
        Camera("Camera/Webcam"):::external
        Video("Video File"):::external
        Image("Background Image"):::external
        SerialIn("Serial Device"):::external
    end

    %% Utilities Layer
    subgraph "Utilities"
        Utils("Utils"):::util
        Color("ColorModule"):::util
        Plot("PlotModule"):::util
        FPS("FPS Calculator"):::util
        PID("PID Module"):::util
        Serial("SerialModule"):::util
    end

    %% CV Modules Layer
    subgraph "CV Modules"
        FaceDet("FaceDetectionModule"):::cv
        FaceMesh("FaceMeshModule"):::cv
        Hand("HandTrackingModule"):::cv
        Pose("PoseModule"):::cv
        Seg("SelfiSegmentationModule"):::cv
        Obj("Objectron"):::cv
        Class("ClassificationModule"):::cv
    end

    %% Pipeline Layer
    subgraph "Pipeline"
        Heat("heatmap_and_track"):::pipe
    end

    %% External Sinks
    subgraph "External Sinks"
        Display("Display Window"):::external
        Writer("VideoWriter/File"):::external
        SerialOut("Serial Device"):::external
    end

    %% Data Flow: Sources to Modules
    Camera --> FaceDet
    Camera --> FaceMesh
    Camera --> Hand
    Camera --> Pose
    Camera --> Seg
    Camera --> Obj
    Camera --> Class
    Camera --> Heat

    Video --> Heat
    Image --> Heat
    SerialIn --> Serial

    %% Modules to Utilities
    FaceDet --> Plot
    FaceDet --> Utils
    FaceMesh --> Plot
    Hand --> Plot
    Pose --> Plot
    Seg --> Plot
    Obj --> Plot
    Class --> Plot
    Heat --> Plot
    Heat --> Utils

    %% Modules to Sinks
    FaceDet --> Display
    FaceMesh --> Display
    Hand --> Display
    Pose --> Display
    Seg --> Display
    Obj --> Display
    Class --> Display
    Heat --> Display
    Heat --> Writer
    Serial --> SerialOut

    %% Click Events
    click Utils "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/Utils.py"
    click Color "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/ColorModule.py"
    click Plot "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/PlotModule.py"
    click FPS "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/FPS.py"
    click PID "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/PIDModule.py"
    click Serial "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/SerialModule.py"
    click FaceDet "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/FaceDetectionModule.py"
    click FaceMesh "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/FaceMeshModule.py"
    click Hand "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/HandTrackingModule.py"
    click Pose "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/PoseModule.py"
    click Seg "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/SelfiSegmentationModule.py"
    click Obj "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/objectron.py"
    click Class "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/ClassificationModule.py"
    click Heat "https://github.com/pyresearch/pyresearch/blob/main/pyresearch/heatmap_and_track.py"

    %% Styles
    classDef external fill:#e0f7e0,stroke:#2d7f2d,stroke-width:1px;
    classDef util fill:#cfe2f3,stroke:#2b579a,stroke-width:1px;
    classDef cv fill:#fce5cd,stroke:#c55a11,stroke-width:1px;
    classDef pipe fill:#e4d5f7,stroke:#8e44ad,stroke-width:1px;
```
