# paulinamoskwa/detect-pikachu architecture

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

- Interactive diagram: https://gitdiagram.com/paulinamoskwa/detect-pikachu
- Repository: https://github.com/paulinamoskwa/detect-pikachu

## Overview

##### Project type and purpose
- This is a data-generation and model-training pipeline for object detection, specifically fine-tuning a YOLOv8 model to detect Pikachu using synthetic data.
- It combines 3D asset creation and cleanup, synthetic image/annotation generation in Unity, data conversion, model training (Jupyter notebook), and real-time inference.

##### File structure
- Top-level folders:
- 3d_modeling: contains raw and processed 3D assets (GLB, FBX).
- code: Python scripts (.py) and a Jupyter notebook (.ipynb) for dataset extraction, format conversion, model training, and inference.
- tutorial.md: a guide linking the pipeline steps.
- No dedicated “frontend/backend” but rather a linear pipeline of stages.
- Key files:
- extract_frame_and_data.py: converts Unity output to YOLOv8 format.
- train_yolov8_model.ipynb: notebook for model training.
- run_realtime_pikachu_detection.py: script for inference using the trained model.
- No build or deployment scripts, but Unity Perception is implied as an external project.

##### README for additional insights
- The README outlines a 5-stage workflow:
1. 3D scanning (MagiScan)
2. Cleanup in Blender
3. Import into Unity + Perception
4. Generate synthetic images + annotations
5. Convert annotations → YOLOv8 format → train model
6. (Bonus) Real-time inference using the trained model
- Technologies: Unity Perception, Blender, Python, YOLOv8, glTF/FBX.

##### Elements
- Clear labels on every block (e.g., “3D Cleanup (Blender)”, “Data Conversion Script”).
- Blue blocks for 3D/modeling tools
- Green blocks for data pipelines
- Orange blocks for training/inference
- Gray for external tools

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% 3D Modeling Stage
    subgraph "3D Modeling Stage"
        direction TB
        RawAsset(["Raw 3D Asset (.glb)"]):::data_store
        Blender["3D Cleanup (Blender)"]:::tool
        CleanGLB(["Cleaned Asset (.glb)"]):::data_store
        CleanFBX(["Cleaned Asset (.fbx)"]):::data_store
        RawAsset -->|imports| Blender
        Blender -->|exports| CleanGLB
        Blender -->|exports| CleanFBX
    end

    %% Synthetic Data Generation
    subgraph "Synthetic Data Generation"
        direction TB
        Unity["Unity Perception"]:::external
        SyntheticData(["Synthetic Images + Metadata (JSON/XML)"]):::data_store
        CleanGLB -->|inputs| Unity
        CleanFBX -->|inputs| Unity
        Unity -->|generates| SyntheticData
    end

    %% Data Conversion
    subgraph "Data Conversion"
        direction TB
        DataConversion["extract_frame_and_data.py"]:::pipeline
        YOLOData(["YOLOv8-formatted Dataset (images + txt)"]):::data_store
        SyntheticData -->|feeds| DataConversion
        DataConversion -->|outputs| YOLOData
    end

    %% Model Training
    subgraph "Model Training"
        direction TB
        TrainingNotebook["train_yolov8_model.ipynb"]:::training
        Weights(["Trained Weights (.pt)"]):::data_store
        YOLOData -->|used by| TrainingNotebook
        TrainingNotebook -->|produces| Weights
    end

    %% Inference
    subgraph "Inference / Deployment"
        direction TB
        Inference["run_realtime_pikachu_detection.py"]:::training
        Output(["Real-time Detection Output"]):::data_store
        Weights -->|loaded by| Inference
        Inference -->|displays| Output
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        Tutorial["Pipeline Overview Guide (tutorial.md)"]:::external
        Readme["Project README (README.md)"]:::external
    end

    %% Click Events
    click RawAsset "https://github.com/paulinamoskwa/detect-pikachu/blob/main/3d_modeling/modelpika.glb"
    click CleanGLB "https://github.com/paulinamoskwa/detect-pikachu/blob/main/3d_modeling/modelpika_updated.glb"
    click CleanFBX "https://github.com/paulinamoskwa/detect-pikachu/blob/main/3d_modeling/modelpika_updated.fbx"
    click DataConversion "https://github.com/paulinamoskwa/detect-pikachu/blob/main/code/extract_frame_and_data.py"
    click TrainingNotebook "https://github.com/paulinamoskwa/detect-pikachu/blob/main/code/train_yolov8_model.ipynb"
    click Inference "https://github.com/paulinamoskwa/detect-pikachu/blob/main/code/run_realtime_pikachu_detection.py"
    click Tutorial "https://github.com/paulinamoskwa/detect-pikachu/blob/main/tutorial.md"
    click Readme "https://github.com/paulinamoskwa/detect-pikachu/blob/main/README.md"

    %% Styles
    classDef tool fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef pipeline fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef training fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-width:1px;
    classDef data_store fill:#d1ecf1,stroke:#0c5460,color:#0c5460,stroke-width:1px;
```
