crocodile-reid

🐊 Crocodile Re-ID Project

AI-powered crocodile individual identification using deep metric learning.

---

📁 Project Structure

croc_reid/
├── requirements.txt      ← Python packages to install
├── setup_project.py      ← Run this FIRST (creates folders, checks GPU)
├── model.py              ← Re-ID neural network (ResNet50 + Triplet Loss)
├── dataset.py            ← Image loading + augmentation + triplet sampling
├── train.py              ← Training loop with TensorBoard logging
├── inference.py          ← Identify crocs from new images
├── configs/
│   └── config.yaml       ← All settings (epochs, batch size, LR, etc.)
├── dataset/
│   ├── train/
│   │   ├── croc_001/     ← One folder per individual crocodile
│   │   │   ├── img1.jpg
│   │   │   └── img2.jpg
│   │   └── croc_002/
│   ├── val/
│   └── test/
├── models/
│   ├── checkpoints/      ← Saved during training
│   └── best/             ← Best model saved here
└── outputs/              ← Inference result images saved here

---

🚀 Step-by-Step Setup (Windows + NVIDIA GPU)

Step 1 — Install Python

Download Python 3.10 from https://python.org
During install: ✅ check "Add Python to PATH"

Step 2 — Install PyTorch with CUDA

Go to: https://pytorch.org/get-started/locally/
Select: Windows | Pip | Python | CUDA 11.8
Copy and run the install command (looks like):

pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu118

Step 3 — Install project dependencies

Open Command Prompt in the project folder and run:

pip install -r requirements.txt

Step 4 — Run setup script

python setup_project.py

You should see: ✅ GPU found: NVIDIA ...

---

🖼️ Prepare Your Dataset

Minimum requirement:

• At least 10 individual crocodiles
• At least 5 images per individual
• Images cropped to show the neck/dorsal scale region

Folder structure:

dataset/train/croc_001/img1.jpg
dataset/train/croc_001/img2.jpg
dataset/train/croc_002/img1.jpg
...
dataset/val/croc_001/img1.jpg    ← Use 20% of images for validation

Image tips:

• Any resolution works (they get resized to 128×128)
• JPG or PNG both work
• Try to include varied lighting / angles per individual

---

🏋️ Training

python train.py

Monitor training in real time:

tensorboard --logdir runs/tensorboard

Then open: http://localhost:6006

What to expect:

• First few epochs: loss drops quickly
• After 20 epochs: loss stabilizes
• Rank-1 accuracy target: > 0.7 (70%) for a small dataset

---

🔍 Inference

Build the database (once after training):

python inference.py --mode build --data_dir dataset/val

Identify a new crocodile:

python inference.py --mode identify --image path/to/new_croc.jpg

Register a new individual:

python inference.py --mode add --image path/to/croc.jpg --id croc_042

---

⚙️ Tuning configs/config.yaml

---

🐛 Common Errors

"CUDA out of memory"
→ Reduce batch_size to 16 or 8 in config.yaml

"DataLoader worker error"
→ Set num_workers: 0 in config.yaml

"No such file: model_best.pth"
→ Train the model first: python train.py

Low Rank-1 accuracy
→ Add more images per individual
→ Make sure your crops focus on scale patterns
→ Train for more epochs

---

📬 Next Phases

• Phase 2: Add YOLOv8 detection (auto-crop from full frames)
• Phase 3: Real-time video pipeline
• Phase 4: Jetson edge deployment
• Phase 5: Flutter mobile app