System Architecture Overview

This document provides a high-level overview of the execution flow and modular design of the tracking system.
It serves as a technical reference for developers working on both the C++ and Python sides of the vision pipeline.

1. Overview

The system is organized into three major layers:

  1. Entry Layer (app/track.py)

    • Command-line interface and runtime entry point.

    • Initializes configurations, logging, and pipeline settings.

    • Manages execution modes (UI, service, headless, record-only).

  2. Context Layer (app/_contextgenerators.py)

    • Handles data input and frame acquisition.

    • Supports multiple sources: live network streams, local cameras, recorded datasets, or database entries.

  3. Pipeline Layer (app/_pipeline.py and submodules)

    • Performs the main image-processing pipeline.

    • Composed of modular stages:

      • Boundary detection _pipeline_boundary_stage.py

      • Process camera view _pipeline_process_camera_view.py

      • Triangulation _pipeline_triangulate_stage.py

      • Tip detection _pipeline_process_camera_view.py

      • Experimental extensions _pipeline_experimental_stage.py

  4. Interface Layer (app/_gui.py / service mode)

    • GUI via PyQt6 (MainWindow) connected through multiprocessing queues.

    • Optional REST/WebSocket server for telemetry (FastAPI + Uvicorn).

2. Execution Flow Summary

  1. Program start

    • app/track.py is executed as the entry point.

    • Command-line arguments are parsed (input mode, logging, config, UI/service flags, etc.).

  2. Configuration and context initialization

    • Loads pipeline configuration file (pipeline.config.json or .yaml).

    • Creates context_generator based on input type:

      • CameraContextGenerator

      • PhysicalCameraContextGenerator

      • DatabaseContextGenerator

      • DatasetContextGenerator

  3. Pipeline selection

    • If --record-only → disable pipeline (record frames only).

    • Otherwise import the actual pipeline() function from _pipeline.py.

  4. Execution modes

    • Service mode (--service):

      • Starts background process for context generation and pipeline execution.

      • Launches FastAPI server with:

        • /ws/telemetry → WebSocket streaming live ctx["export"] data.

        • /queue_size → Returns current queue depth.

    • UI mode (--ui):

      • Launches PyQt6 GUI, creates shared queue and event pool.

      • Displays real-time processing results.

    • Headless mode:

      • Runs context_generator.run(None, pipeline) directly in the main process.

  5. Output

    • Logs and results are stored in logs/runs/<timestamp>/ when enabled.

    • Optional dataset export controlled by --output-dataset and --manually-output-dataset.

3. File Hierarchy (Simplified)

project_root/
 ├──app
  ├── track.py                      # Entry point
  ├── _contextgenerators.py         # Context input sources
  ├── _pipeline.py                  # Main pipeline manager
  ├── _pipeline_boundary_stage.py
  ├── _pipeline_process_camera_view.py
  ├── _pipeline_triangulate_stage.py
  ├── _pipeline_tip_detection_stage.py
  ├── _pipeline_experimental_stage.py
  ├── _gui.py                       # GUI components (PyQt6)
 ├──vision 
  ├── detectors.py                  # Detection utilities

4. System Flowchart

        flowchart TD

    A[[Start: app/track.py]] --> B[Parse CLI arguments]
    B --> C[Load config & setup environment]
    C --> D{Input type?}

    D -->|network| D1[CameraContextGenerator]
    D -->|local|   D2[PhysicalCameraContextGenerator]
    D -->|db:name| D3[DatabaseContextGenerator]
    D -->|dataset| D4[DatasetContextGenerator]

    C --> E{Record-only?}
    E -->|yes| F[Record only (no pipeline)]
    E -->|no | G[Import pipeline from _pipeline.py]

    C --> H{Execution mode?}
    H -->|Service| I[service_mode()]
    H -->|UI|      J[Launch PyQt6 MainWindow]
    H -->|Headless| K[Run context_generator.run() directly]

    %% Service mode branch
    I --> I1[Background: context_generator.run(q, cmd_queue, pipeline)]
    I --> I2[FastAPI + Uvicorn server]
    I2 --> I3[/ws/telemetry<br/>Stream ctx.export + queue stats/]
    I2 --> I4[GET /queue_size]

    %% UI branch
    J --> J1[Create multiprocessing Manager/Queue/Event/Pool]
    J1 --> J2[Background: context_generator.run(q, cmd_queue, pipeline)]
    J --> J3[MainWindow.connect(q)<br/>display processed data]

    %% Headless
    K --> K1[context_generator.run(None, pipeline)]

    %% Pipeline internals
    G --> P[Pipeline stages]
    P --> P1[Boundary Stage]
    P --> P2[Process Camera View]
    P --> P3[Triangulate Stage]
    P --> P4[Tip Detection Stage]
    P --> P5[Experimental Stage]

    %% End
    I4 --> Z([End])
    J3 --> Z
    K1 --> Z
    P5 --> Z

5. Design Principles

  • Modularity:
    Each stage and context generator is self-contained, enabling isolated development and debugging.

  • Parallelism:
    Background processes (via multiprocessing.Pool and Manager.Queue) allow concurrent frame acquisition and processing.

  • Interoperability:
    Designed for hybrid Python/C++ usage (e.g., pybind11-linked modules).

  • Extensibility:
    New stages or detectors can be added simply by implementing corresponding _pipeline_*_stage.py modules and registering them.