# luckye993/gcxl2025 architecture

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

- Interactive diagram: https://gitdiagram.com/luckye993/gcxl2025
- Repository: https://github.com/luckye993/gcxl2025

## Overview

##### Project type and purpose
- This is a Python-based object-detection and inference/control pipeline built around the YOLO framework. It provides:
- A real-time inference loop (camera → detect → control → communicate),
- Data-collection utilities for building a training set,
- A training/export/validation pipeline (via YOLO CLI) to produce .pt, .onnx, and OpenVINO models.

##### File structure
- Top-level directories:
- config/           ← JSON and YAML files for runtime parameters
- notebook/         ← Jupyter notebooks for prototyping and state-machine testing
- src/              ← main application code (split into config, core, utils, entry-point)
- tests/            ← unit tests for controller logic and main program
- Key modules under src/core:
- camera.py        ← captures frames from a camera or video source
- detect.py        ← loads a model (ONNX/OpenVINO) and runs inference
- control.py       ← applies business logic or a state machine to detection results
- communication.py ← sends control commands to external hardware or network
- Utils under src/utils:
- dataCollect.py   ← scripts to capture and label images for training
- helpers.py       ← shared helper functions
- Entry-point: src/main.py reads config, wires up modules, starts the loop.

##### README for additional insights
- The README confirms:
- You must point config/settings.py at the correct config file.
- Training and export are done via the YOLO CLI (ultralytics).
- There are separate commands for .pt→.onnx and .pt→OpenVINO (int8 quantization).
- Validation of each model format is also supported via the CLI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Configuration Files
    subgraph "Runtime Configuration Files"
        cf1["config/config.json"]:::external
        cf2["config/config car.json"]:::external
        cf3["gcxl2025.yaml"]:::external
    end

    %% Prototyping Notebooks
    subgraph "Prototyping Notebooks"
        nb1["stateMachine.ipynb"]:::external
        nb2["detector_test.ipynb"]:::external
        nb3["onnx-test.ipynb"]:::external
    end

    %% Real-time Inference & Control Pipeline
    subgraph "Real-time Inference & Control Pipeline"
        main["Entry Point (src/main.py)"]:::realtime
        config["Config Manager"]:::realtime
        camera["Camera Module"]:::realtime
        detect["Detector Module"]:::realtime
        control["Control Module"]:::realtime
        comm["Communication Module"]:::realtime
        actuators["Actuators/Hardware"]:::external
    end

    %% Offline Training & Export Pipeline
    subgraph "Offline Training & Export Pipeline"
        dataCollect["Data-Collection Utility"]:::util
        storage["Storage (Datasets & Models)"]:::storage
        cli["YOLO CLI (train/export/val)"]:::external
    end

    %% Shared Utilities
    helpers["Shared Helpers"]:::util

    %% Configuration and Orchestration
    cf1 --> config
    cf2 --> config
    cf3 --> config
    main --> config
    main --> camera
    main --> detect
    main --> control
    main --> comm

    %% Real-time Flow
    config --> camera
    config --> detect
    config --> control
    config --> comm
    camera -->|"frame"| detect
    detect -->|"inference result"| control
    control -->|"command"| comm
    comm -->|"actuator command"| actuators

    %% Offline Flow
    camera -->|"frame"| dataCollect
    dataCollect -->|"dataset"| storage
    storage -->|"data.yaml, .pt"| cli
    cli -->|"models (.pt, .onnx, .xml)"| storage
    storage -->|"model files"| detect

    %% Utilities Integration
    helpers --> dataCollect
    helpers --> camera
    helpers --> detect
    helpers --> control
    helpers --> comm

    %% Notebook Connections
    nb1 --> control
    nb2 --> detect
    nb3 --> detect

    %% Click Events
    click config "https://github.com/luckye993/gcxl2025/blob/main/src/config/settings.py"
    click camera "https://github.com/luckye993/gcxl2025/blob/main/src/core/camera.py"
    click detect "https://github.com/luckye993/gcxl2025/blob/main/src/core/detect.py"
    click control "https://github.com/luckye993/gcxl2025/blob/main/src/core/control.py"
    click comm "https://github.com/luckye993/gcxl2025/blob/main/src/core/communication.py"
    click dataCollect "https://github.com/luckye993/gcxl2025/blob/main/src/utils/dataCollect.py"
    click helpers "https://github.com/luckye993/gcxl2025/blob/main/src/utils/helpers.py"
    click main "https://github.com/luckye993/gcxl2025/blob/main/src/main.py"
    click cf1 "https://github.com/luckye993/gcxl2025/blob/main/config/config.json"
    click cf2 "https://github.com/luckye993/gcxl2025/blob/main/config/config car.json"
    click cf3 "https://github.com/luckye993/gcxl2025/blob/main/gcxl2025.yaml"
    click nb1 "https://github.com/luckye993/gcxl2025/blob/main/notebook/stateMachine.ipynb"
    click nb2 "https://github.com/luckye993/gcxl2025/blob/main/notebook/detector_test.ipynb"
    click nb3 "https://github.com/luckye993/gcxl2025/blob/main/notebook/onnx-test.ipynb"

    %% Styles
    classDef realtime fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef training fill:#d4edda,stroke:#333,stroke-width:1px
    classDef util fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef storage fill:#fff2cc,stroke:#333,stroke-width:1px
```
