# riips/aic24_track1_yachiyo_riips architecture

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

- Interactive diagram: https://gitdiagram.com/riips/aic24_track1_yachiyo_riips
- Repository: https://github.com/riips/aic24_track1_yachiyo_riips

## Overview

##### Project Type and Purpose
- This is an offline, multi-stage computer vision pipeline for people tracking across multiple cameras (the AI City Challenge Track 1 submission).
- It ingests raw video files, extracts frames, detects persons, computes embeddings (re‐identification features), estimates poses, performs single‐ and multi‐camera tracking, and outputs a unified tracking result for submission.

##### High-Level Components
a. Input Layer
- Raw video files organized by scene/camera (e.g., Original/scene_041/camera_0361/video.mp4)
b. Preprocessing
- Frame Extraction (scripts/extract_frame.sh → tools/extract_frame.py)
c. Detector Module
- Person detection via BoT-SORT (detector/aic24_get_detection.py invoked by scripts/detection.sh)
d. Embedder Module
- Feature extraction with deep‐person‐reid (embedder/aic24_extract.py via scripts/embedding.sh)
- Produces appearance embeddings per detected person
e. Pose Estimation Module
- Top-down pose estimation with mmpose (poser/top_down_video_demo_with_track_file.py via scripts/pose.sh)
- Produces keypoint annotations per person crop
f. Tracking Module
- Single‐camera tracking (mcpt.py)
- Multi‐camera tracking (scpt.py, run.py orchestrating clustering)
- Configurable per-scene parameters (tracking/config/*.py, JSON)
- Entry point: tracking/infer.py or scripts/tracking.sh
g. Submission Generator
- tools/generate_submission.py combines all scene outputs into a submission file

##### Architectural Patterns & Principles
- Modular, pipeline‐oriented design: each stage is independent, testable, and replaceable.
- Clear separation of concerns: detection, embedding, pose, tracking, and I/O are distinct.
- Configuration‐driven tracking: per-scene parameters and camera mappings live in config files.
- Leverages external frameworks: BoT-SORT, torchreid, and mmpose, isolating wrappers in `detector/`, `embedder/`, and `poser/`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    Raw["Raw Videos\n(Original/scene_x/cam_x/video.mp4)"]:::input

    %% Preprocessing Stage
    FEscript["1. Frame Extraction\nscripts/extract_frame.sh"]:::process
    FEtool["tools/extract_frame.py"]:::process

    %% Detection Stage
    DetScript["2. Detection\nscripts/detection.sh"]:::process
    DetWrapper["detector/aic24_get_detection.py"]:::process

    %% Embedding Stage
    EmbScript["3. Embedding\nscripts/embedding.sh"]:::process
    EmbWrapper["embedder/aic24_extract.py"]:::process

    %% Pose Estimation Stage
    PoseScript["4. Pose Estimation\nscripts/pose.sh"]:::process
    PoseWrapper["poser/top_down_video_demo_with_track_file.py"]:::process
    PoseHelper["poser/load_tracking_result.py"]:::process

    %% Tracking Stage
    TrackScript["5. Tracking\nscripts/tracking.sh"]:::process
    Infer["tracking/infer.py"]:::process
    subgraph "Single-Camera (MCPT)"
        MCPT["tracking/src/mcpt.py"]:::process
    end
    subgraph "Multi-Camera (SCPT)"
        SCPT["tracking/src/scpt.py"]:::process
        RunSC["tracking/src/run.py"]:::process
    end
    SharedLogic["tracking/src/tracking.py\ntracking/src/pose.py\ntracking/src/utils.py"]:::process
    ConfigFiles["tracking/config/\nparameters_per_scene.py\nscene_2_camera_id_file.json"]:::data
    Requirements["tracking/requirements.txt"]:::data

    %% Submission Stage
    SubGen["tools/generate_submission.py"]:::process
    SubmissionFile["track1.txt"]:::dataOutput

    %% Data Outputs
    Frames["Frames"]:::dataOutput
    Detections["Detections"]:::dataOutput
    Embeddings["Embeddings"]:::dataOutput
    Keypoints["Keypoints"]:::dataOutput
    Tracks["Track Outputs"]:::dataOutput

    %% External Frameworks
    subgraph "External Frameworks"
        BoTSORT["BoT-SORT"]:::external
        TorchReID["torchreid"]:::external
        MMPose["mmpose"]:::external
    end

    %% Data Flow Connections
    Raw --> FEscript
    FEscript --> FEtool
    FEtool -->|frames| Frames

    Frames --> DetScript
    DetScript --> DetWrapper
    DetWrapper -->|bboxes| Detections
    DetWrapper --> BoTSORT

    Detections --> EmbScript
    EmbScript --> EmbWrapper
    EmbWrapper -->|embeddings| Embeddings
    EmbWrapper --> TorchReID

    Detections --> PoseScript
    PoseScript --> PoseWrapper
    PoseWrapper --> PoseHelper
    PoseWrapper -->|keypoints| Keypoints
    PoseWrapper --> MMPose

    Detections --> TrackScript
    Embeddings --> TrackScript
    Keypoints --> TrackScript
    TrackScript --> Infer
    Infer --> MCPT
    Infer --> SCPT
    Infer --> SharedLogic
    Infer --> ConfigFiles
    Infer --> Requirements

    MCPT --> Tracks
    SCPT --> Tracks
    SharedLogic --> Tracks
    ConfigFiles --> Tracks

    Tracks --> SubGen
    SubGen -->|submission| SubmissionFile

    %% Click Events
    click FEscript "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/scripts/extract_frame.sh"
    click FEtool "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/tools/extract_frame.py"
    click DetScript "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/scripts/detection.sh"
    click DetWrapper "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/detector/aic24_get_detection.py"
    click EmbScript "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/scripts/embedding.sh"
    click EmbWrapper "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/embedder/aic24_extract.py"
    click PoseScript "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/scripts/pose.sh"
    click PoseWrapper "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/poser/top_down_video_demo_with_track_file.py"
    click PoseHelper "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/poser/load_tracking_result.py"
    click TrackScript "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/scripts/tracking.sh"
    click Infer "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/tracking/infer.py"
    click MCPT "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/tracking/src/mcpt.py"
    click SCPT "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/tracking/src/scpt.py"
    click RunSC "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/tracking/src/run.py"
    click SharedLogic "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/tracking/src/tracking.py"
    click ConfigFiles "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/tracking/config/parameters_per_scene.py"
    click ConfigFiles "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/tracking/config/scene_2_camera_id_file.json"
    click Requirements "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/tracking/requirements.txt"
    click SubGen "https://github.com/riips/aic24_track1_yachiyo_riips/blob/main/tools/generate_submission.py"

    %% Styles
    classDef input fill:#DCEEFB,stroke:#1E40AF,color:#1E40AF;
    classDef process fill:#DCFCE7,stroke:#166534,color:#166534;
    classDef data fill:#FEF9C3,stroke:#92400E,color:#92400E;
    classDef dataOutput fill:#FEF3C7,stroke:#B45309,color:#B45309;
    classDef external fill:#E5E7EB,stroke:#6B7280,color:#6B7280;
```
