How hongliang0/seaturtleid2022 works
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.