# ziqinyeow/juxtapose architecture

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

- Interactive diagram: https://gitdiagram.com/ziqinyeow/juxtapose
- Repository: https://github.com/ziqinyeow/juxtapose

## Overview

##### Main Components
- Input / Data Ingestion: Include elements representing the various input types (images, videos, streams, screenshots, etc.) as detailed in the README. Indicate that the system handles different source types (file, URL, OpenCV image, numpy array, CSV, etc.).
- Core Inference Pipeline: This is the heart of the toolbox. Break it down into three modular components:
- Utility & Visualization: Include the Annotator and ROI tools (like the custom region of interests drawing tools) for visualizing results on images or video frames.
- Configuration and Model Selection: Since the RTM class is designed to integrate these components based on user-provided parameters (det, pose, tracker, and device), represent this decision/configuration engine as an orchestrator.
- Deployment and Integration: Include auxiliary components such as the FastAPI example (from the examples/fastapi-pyinstaller directory) for wrapping the inference pipeline into a deployable service, and additional documentation components for local development and Docker-based deployment.

##### Relationship and Data Flow
- Finally, the results flow into the “Visualization/Annotator” component where the data is used to render overlays on images/videos.
- Orchestrator (the RTM abstraction within src/juxtapose) as a central hub communicating between these modules.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize that the system splits core functionalities (detection, pose estimation, tracking) into separate but interchangeable modules.
- Extensibility: Indicate that new detectors or trackers can be integrated thanks to the registry and configuration architecture (e.g., src/juxtapose/detectors/registry.py).
- Abstraction: The high-level RTM interface abstracts away the complexity of combining these modules.
- Pipeline Design: Data flows sequentially through components (from preprocessing to final visualization), which can be represented as a pipeline.

##### Technologies, Frameworks, and External Dependencies
- Relevant libraries and frameworks: ONNX run-time for fast inference, Torch (and likely other deep learning frameworks), OpenCV (for image processing and visualization), and FastAPI (for deployment in some examples).
- Integration of external repositories (ultralytics, mmdeploy, mmpose, mmdetection) as a reference for the underlying deep learning models.

##### Elements
- Clear labels for each component (e.g., “Input Data Handler”, “Detector Module (RTMDET/YOLOv8/GroundingDINO)”, “Pose Estimator (RTMPose)”, “Tracker (ByteTrack/ BotSORT/ Tapnet)”, “Annotator”, “Orchestrator (RTM)”, and “Deployment API/FastAPI”).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Input & Data Ingestion
    subgraph "Input & Data Ingestion"
        IN["Input Data Handler"]:::input
        DL["Data Loaders"]:::input
        BS["Build Scripts"]:::input
    end

    %% Detector Module
    subgraph "Detector Module"
        RT["RTMDet Directory"]:::pipeline
        RT_INIT["RTMDet - __init__.py"]:::pipeline
        RT_LEG["RTMDet - legacy.py"]:::pipeline
        GD["GroundingDINO"]:::pipeline
        Y8["YOLOv8 - __init__.py"]:::pipeline
    end

    %% Pose Estimator Module
    subgraph "Pose Estimator Module"
        RP["RTMPose Directory"]:::pipeline
        RP_LEG["RTMPose - legacy.py"]:::pipeline
        RP_PRE["RTMPose - preprocessing.py"]:::pipeline
        RP_POST["RTMPose - postprocessing.py"]:::pipeline
    end

    %% Tracker Module
    subgraph "Tracker Module"
        TRK["Trackers Directory"]:::pipeline
        BT["ByteTracker (byte_tracker.py)"]:::pipeline
        BSORT["BotSORT (bot_sort.py)"]:::pipeline
        BTRACK["BaseTrack (basetrack.py)"]:::pipeline
        TAP["Tapnet Tracker"]:::pipeline
    end

    %% Utility & Visualization
    subgraph "Utility & Visualization"
        ROI["ROI Tool (roi.py)"]:::utility
        PLOT["Plotting Utility (plotting.py)"]:::utility
    end

    %% Orchestration & Configuration
    subgraph "Orchestration & Configuration"
        RTM["RTM Orchestrator"]:::orchestrator
        CONF["Configuration Files"]:::config
    end

    %% Deployment
    subgraph "Deployment"
        DEP1["FastAPI Deployment (PyInstaller)"]:::deployment
        DEP_SERVER["Server (server.py)"]:::deployment
        DEP2["FastAPI Example"]:::deployment
        DEP_MAIN["Main (main.py)"]:::deployment
        DEP_DOCK["Dockerfile"]:::deployment
    end

    %% Pipeline Data Flow
    IN -->|"data"| RT
    RT -->|"bounding_boxes"| RP
    RP -->|"keypoints"| TRK
    TRK -->|"tracking_results"| ROI

    %% Intra-Module Detailing
    RT --> RT_INIT
    RT --> RT_LEG
    RP --> RP_LEG
    RP --> RP_PRE
    RP --> RP_POST
    TRK --> BT
    TRK --> BSORT
    TRK --> BTRACK
    TRK --> TAP
    DEP1 --> DEP_SERVER
    DEP2 --> DEP_MAIN
    DEP2 --> DEP_DOCK

    %% Orchestration Interactions
    RTM --- RT
    RTM --- RP
    RTM --- TRK
    CONF --- RT
    CONF --- RP
    CONF --- TRK

    %% Deployment Integration
    RTM --> DEP1
    RTM --> DEP2

    %% Styles
    classDef input fill:#FFFACD,stroke:#333,stroke-width:2px;
    classDef pipeline fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef utility fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef orchestrator fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef config fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef deployment fill:#FFA07A,stroke:#333,stroke-width:2px;

    %% Click Events for Input & Data Ingestion
    click IN "https://github.com/ziqinyeow/juxtapose/tree/main/src/juxtapose/data"
    click DL "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/data/loaders.py"
    click BS "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/data/build.py"

    %% Click Events for Detector Module
    click RT "https://github.com/ziqinyeow/juxtapose/tree/main/src/juxtapose/detectors/rtmdet"
    click RT_INIT "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/detectors/rtmdet/__init__.py"
    click RT_LEG "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/detectors/rtmdet/legacy.py"
    click GD "https://github.com/ziqinyeow/juxtapose/tree/main/src/juxtapose/detectors/groundingdino"
    click Y8 "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/detectors/yolov8/__init__.py"

    %% Click Events for Pose Estimator Module
    click RP "https://github.com/ziqinyeow/juxtapose/tree/main/src/juxtapose/pose/rtmpose"
    click RP_LEG "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/pose/rtmpose/legacy.py"
    click RP_PRE "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/pose/rtmpose/preprocessing.py"
    click RP_POST "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/pose/rtmpose/postprocessing.py"

    %% Click Events for Tracker Module
    click TRK "https://github.com/ziqinyeow/juxtapose/tree/main/src/juxtapose/trackers"
    click BT "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/trackers/byte_tracker.py"
    click BSORT "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/trackers/bot_sort.py"
    click BTRACK "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/trackers/basetrack.py"
    click TAP "https://github.com/ziqinyeow/juxtapose/tree/main/src/juxtapose/trackers/tapnet"

    %% Click Events for Utility & Visualization
    click ROI "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/utils/roi.py"
    click PLOT "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/utils/plotting.py"

    %% Click Events for Orchestration & Configuration
    click RTM "https://github.com/ziqinyeow/juxtapose/blob/main/src/juxtapose/rtm.py"
    click CONF "https://github.com/ziqinyeow/juxtapose/tree/main/src/juxtapose/conf"

    %% Click Events for Deployment
    click DEP1 "https://github.com/ziqinyeow/juxtapose/tree/main/examples/fastapi-pyinstaller"
    click DEP_SERVER "https://github.com/ziqinyeow/juxtapose/blob/main/examples/fastapi-pyinstaller/server.py"
    click DEP2 "https://github.com/ziqinyeow/juxtapose/tree/main/examples/fastapi"
    click DEP_MAIN "https://github.com/ziqinyeow/juxtapose/blob/main/examples/fastapi/main.py"
    click DEP_DOCK "https://github.com/ziqinyeow/juxtapose/tree/main/examples/fastapi/Dockerfile"
```
