vogel-model-trainer 0.1.0

Train custom bird species classifiers from video footage

🐦 Vogel Model Trainer

Languages: 🇬🇧 English | 🇩🇪 Deutsch

Train custom bird species classifiers from your own video footage using YOLOv8 and EfficientNet.

A specialized toolkit for creating high-accuracy bird species classifiers tailored to your specific monitoring setup. Extract training data from videos, organize datasets, and train custom models with >96% accuracy.

---

✨ Features

• 🎯 YOLO-based Bird Detection - Automated bird cropping from videos using YOLOv8
• 🤖 Three Extraction Modes - Manual labeling, auto-sorting, or standard extraction
• 📁 Wildcard Support - Batch process multiple videos with glob patterns
• 🖼️ Auto-Resize to 224x224 - Optimal image size for training
• 🧠 EfficientNet-B0 Training - Lightweight yet powerful classification model
• 🎨 Enhanced Data Augmentation - Rotation, affine transforms, color jitter, gaussian blur
• 📊 Optimized Training - Cosine LR scheduling, label smoothing, early stopping
• ⏸️ Graceful Shutdown - Save model state on Ctrl+C interruption
• 🔄 Iterative Training - Use trained models to expand your dataset
• 📈 Per-Species Metrics - Detailed accuracy breakdown by species

---

🚀 Quick Start

Installation

# Install from PyPI
pip install vogel-model-trainer

# Or install from source
git clone https://github.com/kamera-linux/vogel-model-trainer.git
cd vogel-model-trainer
pip install -e .

Basic Workflow

# 1. Extract bird images from videos
vogel-trainer extract video.mp4 --bird great-tit --output ~/training-data/

# 2. Organize into train/validation split
vogel-trainer organize --source ~/training-data/ --output ~/training-data/organized/

# 3. Train custom classifier
vogel-trainer train --data ~/training-data/organized/ --output ~/models/

# 4. Test the trained model
vogel-trainer test ~/models/final/ test_image.jpg

---

📖 Usage Guide

1. Extract Training Images

Manual Mode (Recommended for Initial Collection)

When you know the species in your video:

vogel-trainer extract ~/Videos/great-tit-*.mp4 \
  --bird great-tit \
  --output ~/training-data/ \
  --threshold 0.5 \
  --sample-rate 3

Auto-Sort Mode (For Iterative Training)

Use an existing model to automatically classify and sort:

vogel-trainer extract ~/Videos/mixed-*.mp4 \
  --species-model ~/models/classifier/final/ \
  --output ~/training-data/ \
  --threshold 0.6

Batch Processing with Wildcards

# Process all videos in a directory
vogel-trainer extract "~/Videos/*.mp4" --bird blue-tit --output ~/data/

# Recursive directory search
vogel-trainer extract ~/Videos/ \
  --species-model ~/models/classifier/final/ \
  --output ~/data/ \
  --recursive

Parameters:

• --threshold: YOLO confidence threshold (default: 0.5)
• --sample-rate: Process every Nth frame (default: 3)
• --bird: Manual species label
• --species-model: Path to trained model for auto-classification
• --no-resize: Keep original image size (default: resize to 224x224)

2. Organize Dataset

vogel-trainer organize \
  --source ~/training-data/ \
  --output ~/training-data/organized/ \
  --train-ratio 0.8

Creates an 80/20 train/validation split:

organized/
├── train/
│   ├── great-tit/
│   ├── blue-tit/
│   └── robin/
└── val/
    ├── great-tit/
    ├── blue-tit/
    └── robin/

3. Train Classifier

vogel-trainer train \
  --data ~/training-data/organized/ \
  --output ~/models/ \
  --epochs 50 \
  --batch-size 16

Training Configuration:

• Base Model: google/efficientnet-b0 (8.5M parameters)
• Optimizer: AdamW with cosine LR schedule
• Augmentation: Rotation, affine, color jitter, gaussian blur
• Regularization: Weight decay 0.01, label smoothing 0.1
• Early Stopping: Patience of 7 epochs

Output:

~/models/bird-classifier-20251108_143000/
├── checkpoints/     # Intermediate checkpoints
├── logs/           # TensorBoard logs
└── final/          # Final trained model
    ├── config.json
    ├── model.safetensors
    └── preprocessor_config.json

4. Test Model

# Test on single image
vogel-trainer test ~/models/final/ image.jpg

# Output:
# 🖼️  Testing: image.jpg
#    🐦 Predicted: great-tit (98.5% confidence)

---

🔄 Iterative Training Workflow

Improve your model by iteratively expanding your dataset:

# 1. Initial training with manual labels
vogel-trainer extract ~/Videos/batch1/*.mp4 --bird great-tit --output ~/data/
vogel-trainer organize --source ~/data/ --output ~/data/organized/
vogel-trainer train --data ~/data/organized/ --output ~/models/v1/

# 2. Use trained model to extract more data
vogel-trainer extract ~/Videos/batch2/*.mp4 \
  --species-model ~/models/v1/final/ \
  --output ~/data/iteration2/

# 3. Review and correct misclassifications manually
# Move incorrect predictions to correct species folders

# 4. Combine datasets and retrain
cp -r ~/data/iteration2/* ~/data/
vogel-trainer organize --source ~/data/ --output ~/data/organized/
vogel-trainer train --data ~/data/organized/ --output ~/models/v2/

# Result: Higher accuracy! 🎉

---

📊 Performance & Best Practices

Dataset Size Recommendations

Quality	Images per Species	Expected Accuracy
Minimum	20-30	~85-90%
Good	50-100	~92-96%
Optimal	100+	>96%

Tips for Better Results

1. Dataset Diversity

   • Include various lighting conditions
   • Capture different poses (side, front, back)
   • Cover different seasons (plumage changes)

2. Class Balance

   • Aim for similar image counts per species
   • Avoid having one dominant class

3. Quality Over Quantity

   • Use threshold 0.5-0.6 for clear detections
   • Manual review of auto-sorted images improves quality

4. Monitor Training

   • Check per-class accuracy for weak species
   • Use confusion matrix to identify similar species
   • Add more data for low-performing classes

---

🔗 Integration with vogel-video-analyzer

Use your trained model for species identification:

vogel-analyze --identify-species \
  --species-model ~/models/final/ \
  --species-threshold 0.3 \
  video.mp4

---

🛠️ Development

# Clone repository
git clone https://github.com/kamera-linux/vogel-model-trainer.git
cd vogel-model-trainer

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/

---

📝 License

MIT License - see LICENSE for details.

---

🙏 Credits

• YOLO by Ultralytics
• EfficientNet by Google Research
• Transformers by Hugging Face

---

📮 Support & Contributing

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Pull Requests: Contributions welcome!

---

Made with ❤️ for bird watching enthusiasts 🐦