# krawal19/artag_detection_and_tracking architecture

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

- Interactive diagram: https://gitdiagram.com/krawal19/artag_detection_and_tracking
- Repository: https://github.com/krawal19/artag_detection_and_tracking

## Overview

##### Project type and purpose
- This is a command‐line, Python-based computer vision application rather than a client-server or full-stack web app.
- Purpose: take raw video(s) of fiducial AR tags, detect and track each tag, then superimpose either a 2D image (Lena) or a 3D cube onto the tag in every frame, producing annotated output videos.

##### File structure
- Top-level:
- data/ – raw input videos
- images_for_readme/ – static illustration images
- output/ – generated AVI files
- src/ – two entry scripts: cube.py (3D cube overlay) and lena.py (Lena overlay)
- LICENSE, README.md
- There are no sub-folders under src/, so the architecture is flat but conceptually modular: each script invokes a common tag‐processing pipeline plus its own overlay logic.

##### Key architectural insights from README
- Core pipeline stages:
A. Tag corner detection
B. Tag orientation detection
C. Tag ID detection
- Two distinct “post‐processing” branches:
- Superimpose Lena image via homography & masking
- Superimpose 3D cube via projection matrix & line drawing
- Dependencies: Python 3.5.4, OpenCV 4.1.1

##### Components
a. Main components (blocks):
1) Frame Reader (VideoCapture)
2) Tag Detection Module
– grayscale & threshold → contour extraction → quad approximation
3) Tag Orientation Module
– compute homography → warp to upright → detect orientation marker
4) Tag ID Module
– sample interior squares → decode bits → tag ID
5) Overlay Branch
- Lena Overlay: template image loader → homography → warp → mask → composite
6) Frame Writer (VideoWriter)
7) CLI Scripts: cube.py and lena.py invoke pipeline + branch
8) File I/O: data/ → input videos; output/ → result AVI files
9) External libraries: OpenCV

b. Relationships & data flow
- cube.py vs. lena.py both share steps 1–3 but fork at Overlay Branch
- File I/O connects the CLI scripts to data/ and output/

c. Architectural patterns & design principles
- Pipeline (linear sequence of transform stages)
- Strategy/branching for overlay logic (select one of two extensions)
- Single-responsibility: each module does one processing step
- Data-driven: video frames pass through stages in memory

d. Key technologies/frameworks
- Python 3.x
- OpenCV 4.x (Video I/O, image processing, homography, contour detection)
- NumPy (arrays, linear algebra) implicitly via OpenCV

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Scripts
    subgraph "CLI Entry Points"
        direction TB
        CLI_Cube["cube.py"]:::cli
        CLI_Lena["lena.py"]:::cli
    end

    %% File I/O Input
    data["data/ (raw videos)"]:::io

    %% Core Pipeline
    subgraph "Core Processing Pipeline"
        direction TB
        FrameReader["Frame Reader\n(VideoCapture)"]:::core
        TagDetection["Tag Detection\n(grayscale → threshold → contours → quad)"]:::core
        TagOrientation["Tag Orientation\n(homography → warp upright)"]:::core
        TagID["Tag ID\n(sample interior → decode bits)"]:::core
    end

    %% Overlay Branch
    subgraph "Overlay Branch"
        direction TB
        subgraph "Lena Overlay" 
            direction TB
            LenaOverlay["Lena Overlay\n(load template → homography & mask → composite)"]:::overlayLena
        end
        subgraph "Cube Overlay"
            direction TB
            CubeOverlay["Cube Overlay\n(load calibration → proj matrix → project & draw)"]:::overlayCube
        end
    end

    %% Frame Writer Output
    FrameWriter["Frame Writer\n(VideoWriter)"]:::core
    output["output/ (AVI files)"]:::io

    %% Documentation & License
    subgraph "Documentation & Licensing"
        direction TB
        README["README.md"]:::docs
        Images["images_for_readme/"]:::docs
        License["LICENSE"]:::docs
    end

    %% External Dependencies
    Ext["Python 3.x, OpenCV 4.x, NumPy"]:::ext

    %% Connections
    CLI_Cube --> data
    CLI_Lena --> data

    data --> FrameReader
    FrameReader --> TagDetection
    TagDetection --> TagOrientation
    TagOrientation --> TagID

    TagID --> LenaOverlay
    TagID --> CubeOverlay

    LenaOverlay --> FrameWriter
    CubeOverlay --> FrameWriter

    FrameWriter --> output

    %% Documentation & Ext
    CLI_Cube -.-> README
    CLI_Lena -.-> README
    README -.-> Images
    README -.-> License
    CoreProcessing[Core Processing Pipeline] -.-> Ext

    %% Click Events
    click CLI_Cube "https://github.com/krawal19/artag_detection_and_tracking/blob/master/src/cube.py"
    click CLI_Lena "https://github.com/krawal19/artag_detection_and_tracking/blob/master/src/lena.py"
    click data "https://github.com/krawal19/artag_detection_and_tracking/tree/master/data/"
    click output "https://github.com/krawal19/artag_detection_and_tracking/tree/master/output/"
    click README "https://github.com/krawal19/artag_detection_and_tracking/blob/master/README.md"
    click Images "https://github.com/krawal19/artag_detection_and_tracking/tree/master/images_for_readme/"
    click License "https://github.com/krawal19/artag_detection_and_tracking/tree/master/LICENSE"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef overlayLena fill:#d4edda,stroke:#155724,color:#155724;
    classDef overlayCube fill:#fff3cd,stroke:#856404,color:#856404;
    classDef io fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef cli fill:#f5c6cb,stroke:#721c24,color:#721c24;
    classDef docs fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef ext fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
