# hongliang0/seaturtleid2022 architecture

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

- Interactive diagram: https://gitdiagram.com/hongliang0/seaturtleid2022
- Repository: https://github.com/hongliang0/seaturtleid2022

## Overview

This repo is **not a deployed “system” (no web app/services)**; it’s a **research/ML pipeline project** organized primarily around **Jupyter notebooks** for:
- **Dataset exploration + cleanup + consistent splitting**
- Training/evaluating **four independent model approaches**:
- KNN (feature-based)
- DeepLabV3+ (semantic segmentation)
- Mask R-CNN (instance segmentation)
- YOLOv8-Seg (segmentation)
- Producing and consuming **artifacts** (cleaned annotations, dataset cache `.pth`, trained weights in `models/`, generated YOLO dataset in `yolo-dataset/`)

From the tree + README, you effectively have these modules (even if they’re notebooks):
- **Data source (external)**: Kaggle `turtles-data/...` (explicitly not committed)
- **Data exploration / cleanup**:
- `dataVisualisation.ipynb` (primary canonical pipeline step)
- `utils/data_exploration.ipynb`, `utils/dataloader.ipynb`
- output: **cleaned JSON** (`updated_annotations.json` mentioned) + **dataset cache** `models/dataset.pth`
- **Model training/evaluation** (four independent branches):
- `knn.ipynb` and also `featureBasedWithknn.ipynb`
- `deeplab.ipynb`
- `mask-rcnn.ipynb` (+ archived utils notebooks about mrcnn)
- `yolo.ipynb` + `yolo-dataset/seaturtle-seg.yaml` + auto-generated `yolo-dataset/images|labels/...`
- **Utilities / helper code**:
- `utils/drawAndTest.py` (likely visualization/testing helpers)
- **Environment / dependencies**:
- `requirements.txt`
- **Model artifacts (external distribution)**:
- `models/best_*.pth`, `models/best_YOLO.pt` (stored on Google Drive per README)

##### Data layer
- **Kaggle Dataset (external)**
`turtles-data/data/images/`
`turtles-data/data/annotations.json`
`turtles-data/data/metadata*.csv` (splits)

##### Preprocessing & validation
- **Dataset Exploration & Cleanup**
`dataVisualisation.ipynb`
(and optionally: `utils/data_exploration.ipynb`, `utils/dataloader.ipynb`)
- **Outputs (artifacts)**
`updated_annotations.json` (or “cleaned annotations JSON”)
`models/dataset.pth` (cached dataset object)

##### KNN pipeline
`knn.ipynb` (+ `featureBasedWithknn.ipynb`)
Inputs: dataset cache / features extracted from images + labels

##### DeepLabV3+ pipeline
`deeplab.ipynb`
Inputs: cleaned dataset + masks
Outputs: `models/best_deeplab.pth` (or loaded from Drive)

##### Mask R-CNN pipeline
`mask-rcnn.ipynb`
Inputs: cleaned dataset + instance masks
Outputs: `models/best_maskrcnn.pth` (or loaded from Drive)
Notes: `utils/modified-mrcnn-model-archived.ipynb`, `utils/mrcnn-model-archive.ipynb` are “experiments/archived” (show as optional/greyed)

##### YOLOv8-Seg pipeline
`yolo.ipynb`
Inputs: cleaned dataset
Intermediate: **YOLO dataset generator** → `yolo-dataset/images/{train,test}`, `yolo-dataset/labels/{train,test}`, `yolo-dataset/seaturtle-seg.yaml`
Outputs: `models/best_YOLO.pt` (or loaded from Drive)

##### Shared utilities
- **Visualization/Test helpers**
`utils/drawAndTest.py`
(connect this to notebooks that call it, if true; otherwise annotate “used by notebooks for visualization”)

##### Runtime & dependencies
- **Python + requirements**
`requirements.txt`

##### Kaggle dataset → dataVisualisation.ipynb
(reads images/annotations/metadata splits)

##### cleaned dataset artifacts → each model notebook
- `models/dataset.pth` (or “cleaned dataset loader”) → `knn.ipynb`, `deeplab.ipynb`, `mask-rcnn.ipynb`, `yolo.ipynb`

##### yolo.ipynb → yolo-dataset/
(dataset conversion/generation step)

##### Model notebooks → models/
- save weights (or load weights)
- optionally generate metrics/plots

##### Google Drive → models/ (or directly into notebooks)
As: “Download pretrained weights” feeding `models/best_*.pth` and `models/best_YOLO.pt`.

A small note near preprocessing: **“must preserve official open-set splits from metadata”**—that constraint is architecturally important (it impacts every downstream evaluation).

##### Architectural patterns/design principles to highlight (specific to this repo)
- **Artifact-driven workflow**: notebooks communicate via generated files (`dataset.pth`, cleaned JSON, `yolo-dataset/`).
- **Single source of truth for dataset cleanup**: `dataVisualisation.ipynb` is the canonical step; everything else depends on it.
- **Branching experimentation**: four parallel model approaches share a common dataset foundation.
- **Reproducibility constraints**:
- fixed split strategy from dataset creators (metadata)
- dependencies pinned via `requirements.txt`
- large model artifacts stored externally (Drive)

##### Use clear labels that match the repo
- “dataVisualisation.ipynb (cleanup + split enforcement)”
- “yolo.ipynb (dataset conversion + YOLOv8-seg training)”
- “models/ (weights + dataset cache)”

##### Separate “required” vs “optional/archived”
`utils/*archive*.ipynb` in an “Archived Experiments” group with lighter styling so reviewers don’t assume it’s part of the main pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% High-level context (C4-ish for ML)
%% =========================
subgraph "High-level Workflow Context (ML notebook repo)"
  direction TB

  Kaggle["Kaggle (external)\n`turtles-data/`"]:::external
  GDrive["Google Drive (external)\npretrained weights"]:::external

  subgraph "Local Notebook Runtime"
    direction TB
    PyEnv["Python environment\n(pip install -r requirements.txt)"]:::runtime
  end

  subgraph "Repo Workspace (artifacts + notebooks)"
    direction TB

    subgraph "Data Sources (not committed)"
      direction TB
      TurtleImages[("turtles-data/data/images/")]:::data
      TurtleAnn[("turtles-data/data/annotations.json")]:::data
      TurtleMeta[("turtles-data/data/metadata*.csv\n(official splits)")]:::data
    end

    subgraph "Preprocessing & Validation (Single source of truth)"
      direction TB
      DV["dataVisualisation.ipynb\n(cleanup + split enforcement)"]:::compute
      AuxExplore["utils/data_exploration.ipynb\n(aux exploration)"]:::compute
      DLCache["utils/dataloader.ipynb\n(dataset cache creation)"]:::compute

      CleanJSON[("updated_annotations.json\n(cleaned annotations)")]:::data
      DatasetPth[("models/dataset.pth\n(dataset cache)")]:::data

      SplitNote["Constraint: preserve official open-set splits\n(from metadata*.csv)"]:::note
    end

    subgraph "Model Training & Evaluation (4 independent branches)"
      direction TB

      subgraph "KNN (feature-based)"
        direction TB
        KNN["knn.ipynb\n(train/eval)"]:::compute
        KNNVar["featureBasedWithknn.ipynb\n(variant)"]:::compute
        KNNOut[("Notebook outputs\n(metrics/plots)")]:::artifact
      end

      subgraph "DeepLabV3+ (semantic segmentation)"
        direction TB
        DeepLab["deeplab.ipynb\n(train/eval)"]:::compute
        DLWeights[("models/best_deeplab.pth")]:::artifact
      end

      subgraph "Mask R-CNN (instance segmentation)"
        direction TB
        MaskRCNN["mask-rcnn.ipynb\n(train/eval)"]:::compute
        MRCNNWeights[("models/best_maskrcnn.pth")]:::artifact
      end

      subgraph "YOLOv8-Seg (segmentation)"
        direction TB
        YOLO["yolo.ipynb\n(dataset conversion + train/eval)"]:::compute
        YoloDataset[("yolo-dataset/\n(images/labels + splits)")]:::data
        YoloYaml[("yolo-dataset/seaturtle-seg.yaml")]:::data
        YoloWeights[("models/best_YOLO.pt")]:::artifact
      end
    end

    subgraph "Shared Utilities"
      direction TB
      DrawTest["utils/drawAndTest.py\n(visualization/test helpers)"]:::util
    end

    subgraph "Archived Experiments (optional)"
      direction TB
      Arch1["utils/modified-mrcnn-model-archived.ipynb"]:::archived
      Arch2["utils/mrcnn-model-archive.ipynb"]:::archived
    end

    ModelsDir[("models/\n(weights + cache)")]:::data
  end

  Reqs["requirements.txt"]:::runtime
end

%% =========================
%% Data flows
%% =========================
Kaggle -->|"provides"| TurtleImages
Kaggle -->|"provides"| TurtleAnn
Kaggle -->|"provides"| TurtleMeta

TurtleImages -->|"read"| DV
TurtleAnn -->|"read"| DV
TurtleMeta -->|"read (splits)"| DV

AuxExplore -.->|"reads (optional)"| TurtleImages
AuxExplore -.->|"reads (optional)"| TurtleAnn
DLCache -.->|"supports"| DV

DV -->|"writes"| CleanJSON
DV -->|"writes"| DatasetPth
DV -->|"enforces"| SplitNote

DatasetPth -->|"input"| KNN
DatasetPth -->|"input"| KNNVar
DatasetPth -->|"input"| DeepLab
DatasetPth -->|"input"| MaskRCNN
DatasetPth -->|"input"| YOLO

KNN -->|"produces"| KNNOut
KNNVar -->|"produces"| KNNOut

DeepLab -->|"saves"| DLWeights
MaskRCNN -->|"saves"| MRCNNWeights

YOLO -->|"generates"| YoloDataset
YOLO -->|"uses"| YoloYaml
YoloDataset -->|"feeds"| YOLO
YoloYaml -->|"config"| YOLO
YOLO -->|"saves"| YoloWeights

DatasetPth -->|"stored in"| ModelsDir
DLWeights -->|"stored in"| ModelsDir
MRCNNWeights -->|"stored in"| ModelsDir
YoloWeights -->|"stored in"| ModelsDir

GDrive -.->|"download pretrained weights"| ModelsDir
GDrive -.->|"optional load"| DeepLab
GDrive -.->|"optional load"| MaskRCNN
GDrive -.->|"optional load"| YOLO

Reqs -->|"pins deps"| PyEnv
PyEnv -->|"runs"| DV
PyEnv -->|"runs"| AuxExplore
PyEnv -->|"runs"| DLCache
PyEnv -->|"runs"| KNN
PyEnv -->|"runs"| KNNVar
PyEnv -->|"runs"| DeepLab
PyEnv -->|"runs"| MaskRCNN
PyEnv -->|"runs"| YOLO

DrawTest -.->|"used by notebooks\n(viz/testing)"| DV
DrawTest -.->|"used by notebooks\n(viz/testing)"| KNN
DrawTest -.->|"used by notebooks\n(viz/testing)"| DeepLab
DrawTest -.->|"used by notebooks\n(viz/testing)"| MaskRCNN
DrawTest -.->|"used by notebooks\n(viz/testing)"| YOLO

Arch1 -.->|"historical reference"| MaskRCNN
Arch2 -.->|"historical reference"| MaskRCNN

%% =========================
%% Click events (from component_mapping)
%% =========================
click DV "https://github.com/hongliang0/seaturtleid2022/blob/main/dataVisualisation.ipynb"
click AuxExplore "https://github.com/hongliang0/seaturtleid2022/blob/main/utils/data_exploration.ipynb"
click DLCache "https://github.com/hongliang0/seaturtleid2022/blob/main/utils/dataloader.ipynb"
click KNN "https://github.com/hongliang0/seaturtleid2022/blob/main/knn.ipynb"
click KNNVar "https://github.com/hongliang0/seaturtleid2022/blob/main/featureBasedWithknn.ipynb"
click DeepLab "https://github.com/hongliang0/seaturtleid2022/blob/main/deeplab.ipynb"
click MaskRCNN "https://github.com/hongliang0/seaturtleid2022/blob/main/mask-rcnn.ipynb"
click YOLO "https://github.com/hongliang0/seaturtleid2022/blob/main/yolo.ipynb"
click YoloDataset "https://github.com/hongliang0/seaturtleid2022/tree/main/yolo-dataset/"
click YoloYaml "https://github.com/hongliang0/seaturtleid2022/blob/main/yolo-dataset/seaturtle-seg.yaml"
click DrawTest "https://github.com/hongliang0/seaturtleid2022/blob/main/utils/drawAndTest.py"
click Arch1 "https://github.com/hongliang0/seaturtleid2022/blob/main/utils/modified-mrcnn-model-archived.ipynb"
click Arch2 "https://github.com/hongliang0/seaturtleid2022/blob/main/utils/mrcnn-model-archive.ipynb"
click Reqs "https://github.com/hongliang0/seaturtleid2022/blob/main/requirements.txt"

%% =========================
%% Styles
%% =========================
classDef external fill:#ECEFF1,stroke:#546E7A,stroke-width:1.5px,color:#263238
classDef runtime fill:#E3F2FD,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1
classDef compute fill:#BBDEFB,stroke:#1E88E5,stroke-width:1.5px,color:#0D47A1
classDef util fill:#B3E5FC,stroke:#0288D1,stroke-width:1.5px,color:#01579B
classDef data fill:#C8E6C9,stroke:#2E7D32,stroke-width:1.5px,color:#1B5E20
classDef artifact fill:#D1C4E9,stroke:#5E35B1,stroke-width:1.5px,color:#311B92
classDef archived fill:#F5F5F5,stroke:#9E9E9E,stroke-width:1.2px,color:#616161,stroke-dasharray: 4 3
classDef note fill:#FFF9C4,stroke:#F9A825,stroke-width:1.2px,color:#5D4037
```
