vogel-model-trainer 0.1.4__tar.gz

vogel_model_trainer-0.1.4/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,49 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior in vogel-model-trainer
+title: '[BUG] '
+labels: 'bug'
+assignees: ''
+
+---
+
+## 🐛 Bug Description
+<!-- A clear and concise description of what the bug is -->
+
+## 📝 Steps to Reproduce
+1. 
+2. 
+3. 
+
+## ✅ Expected Behavior
+<!-- What you expected to happen -->
+
+## ❌ Actual Behavior
+<!-- What actually happened -->
+
+## 🎯 Training/Dataset Information
+<!-- If applicable -->
+- Mode: [e.g., extract, extract-manual, extract-auto, train]
+- Dataset Size: [e.g., 500 images, 10 videos]
+- Number of Classes: [e.g., 5 bird species]
+- Model: [e.g., EfficientNet-B0, custom]
+
+## 💻 Environment
+- OS: [e.g., Ubuntu 22.04, Windows 11, macOS 14]
+- Python Version: [e.g., 3.11.5]
+- vogel-model-trainer Version: [e.g., 0.1.0]
+- Installation Method: [e.g., pip, pip install from git]
+
+## 📋 Error Output
+<!-- Please include the full error message/traceback -->
+```
+Paste error output here
+```
+
+## 🔍 Additional Context
+<!-- Add any other context about the problem here -->
+
+## ✔️ Checklist
+- [ ] I have searched existing issues to ensure this is not a duplicate
+- [ ] I have included all relevant information above
+- [ ] I can reproduce this issue consistently

vogel_model_trainer-0.1.4/.github/ISSUE_TEMPLATE/custom.md

@@ -0,0 +1,32 @@
+---
+name: Question / Discussion
+about: Ask a question or start a discussion about vogel-model-trainer
+title: '[QUESTION] '
+labels: 'question'
+assignees: ''
+
+---
+
+## ❓ Question / Topic
+<!-- Ask your question here -->
+
+## 🔍 Context
+<!-- Provide context about what you're trying to achieve -->
+
+## 📚 What I've Already Tried
+- [ ] I have read the [README.md](https://github.com/kamera-linux/vogel-model-trainer/blob/main/README.md)
+- [ ] I have searched existing issues and discussions
+
+<!-- Optional: What have you already attempted? -->
+
+## 💻 Environment (if applicable)
+- OS: [e.g., Ubuntu 22.04]
+- Python Version: [e.g., 3.11.5]
+- vogel-model-trainer Version: [e.g., 0.1.0]
+
+## 📝 Additional Information
+<!-- Any other relevant information, such as:
+- Your experience level with ML/computer vision
+- Your specific use case (bird monitoring setup, species, etc.)
+- Sample data or configuration (if applicable)
+-->

vogel_model_trainer-0.1.4/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,40 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement for vogel-model-trainer
+title: '[FEATURE] '
+labels: 'enhancement'
+assignees: ''
+
+---
+
+## 💡 Feature Description
+<!-- A clear and concise description of the feature you'd like to see -->
+
+## 🎯 Problem / Use Case
+<!-- Is your feature request related to a problem? Please describe.
+Example: "I'm training models for X species and it's difficult to Y because Z..." -->
+
+## ✨ Proposed Solution
+<!-- Describe the solution you'd like in detail -->
+
+## 🔄 Alternatives Considered
+<!-- Have you considered any alternative solutions or workarounds? -->
+
+## 📊 Benefits
+<!-- How would this feature benefit vogel-model-trainer users? -->
+- 
+- 
+
+## 🖼️ Examples / Mockups
+<!-- Optional: Add examples, mockups, or CLI output samples -->
+```
+# Example of how the feature might be used
+```
+
+## 🔗 Related Issues
+<!-- Link to related issues or discussions if applicable -->
+
+## ✔️ Checklist
+- [ ] I have searched existing issues to ensure this is not a duplicate
+- [ ] This feature aligns with the project's goals (bird species classification)
+- [ ] I am willing to help implement this feature (optional)

vogel_model_trainer-0.1.4/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,68 @@
+## 📝 Description
+
+<!-- Provide a clear and concise description of your changes -->
+
+## 🎯 Type of Change
+
+<!-- Mark the relevant option with an 'x' -->
+
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 📝 Documentation update
+- [ ] 🔧 Refactoring (no functional changes)
+- [ ] 🎨 Style/formatting changes
+- [ ] ⚡ Performance improvement
+- [ ] ✅ Test update
+
+## 🔗 Related Issues
+
+<!-- Link to related issues, e.g., "Fixes #123" or "Relates to #456" -->
+
+Closes #
+
+## 📋 Checklist
+
+<!-- Mark completed items with an 'x' -->
+
+- [ ] My code follows the project's style guidelines
+- [ ] I have performed a self-review of my code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] I have updated the CHANGELOG.md
+
+## 🧪 Testing
+
+<!-- Describe the tests you ran and how to reproduce them -->
+
+**Test Configuration:**
+- OS: 
+- Python Version: 
+- vogel-model-trainer Version: 
+
+**Test Steps:**
+1. 
+2. 
+3. 
+
+## 📸 Screenshots (if applicable)
+
+<!-- Add screenshots or videos to help explain your changes -->
+
+## 💭 Additional Context
+
+<!-- Add any other context about the pull request here -->
+
+## 📚 Documentation
+
+<!-- If you added new features, explain where users can find documentation -->
+- [ ] README.md updated
+- [ ] Docstrings added/updated
+- [ ] Examples added
+
+---
+
+**Note:** Please ensure you've read our [Contributing Guidelines](CONTRIBUTING.md) before submitting this PR.

vogel_model_trainer-0.1.4/.github/RELEASE_TEMPLATE.md

@@ -0,0 +1,47 @@
+## 🎉 What's New
+
+<!-- Describe the main highlights of this release -->
+
+## ✨ Features
+
+<!-- List new features added in this release -->
+- 
+
+## 🐛 Bug Fixes
+
+<!-- List bugs that were fixed in this release -->
+- 
+
+## 📝 Documentation
+
+<!-- List documentation improvements -->
+- 
+
+## 🔧 Improvements
+
+<!-- List improvements and enhancements -->
+- 
+
+## ⚠️ Breaking Changes
+
+<!-- List any breaking changes that users need to be aware of -->
+- None
+
+## 📦 Dependencies
+
+<!-- List any dependency updates -->
+- 
+
+## 🙏 Contributors
+
+<!-- Thank contributors to this release -->
+Thank you to everyone who contributed to this release!
+
+---
+
+## 📚 Resources
+
+- **Documentation:** [README.md](https://github.com/kamera-linux/vogel-model-trainer/blob/main/README.md)
+- **Installation:** `pip install vogel-model-trainer`
+- **Issues:** [Report a bug](https://github.com/kamera-linux/vogel-model-trainer/issues/new?template=bug_report.md)
+- **Changelog:** [CHANGELOG.md](https://github.com/kamera-linux/vogel-model-trainer/blob/main/CHANGELOG.md)

vogel_model_trainer-0.1.4/.github/RELEASE_v0.1.0.md

@@ -0,0 +1,151 @@
+# 🎉 vogel-model-trainer v0.1.0
+
+**Release Date:** November 8, 2025
+
+First official release of vogel-model-trainer! 🐦
+
+## 📦 Installation
+
+```bash
+pip install vogel-model-trainer
+```
+
+## ✨ Features
+
+### Core Functionality
+
+- **🎯 YOLO-based Bird Detection** - Automated bird cropping from videos using YOLOv8
+- **🤖 Three Extraction Modes**:
+  - Standard extraction mode
+  - Manual labeling mode (interactive species selection)
+  - Auto-sorting mode (using pre-trained classifier)
+- **📁 Wildcard Support** - Batch process multiple videos with glob patterns
+- **🖼️ Auto-Resize to 224x224** - Optimal image size for training
+- **📊 Dataset Organization** - Automatic 80/20 train/val split with shuffling
+
+### Model Training
+
+- **🧠 EfficientNet-B0 Training** - Lightweight yet powerful classification model
+- **🎨 Enhanced Data Augmentation**:
+  - Random resized crop (80-100%)
+  - Random horizontal flip (50%)
+  - Color jitter (brightness, contrast, saturation, hue)
+  - Gaussian blur for robustness
+- **📈 Optimized Training**:
+  - Cosine learning rate scheduling
+  - Label smoothing (0.1)
+  - Early stopping (patience: 7 epochs)
+  - Automatic checkpointing
+- **⏸️ Graceful Shutdown** - Save model state on Ctrl+C interruption
+- **📊 Per-Species Metrics** - Detailed accuracy breakdown by species
+
+### CLI Interface
+
+Comprehensive command-line interface with subcommands:
+
+```bash
+# Extract birds from videos
+vogel-trainer extract video.mp4 -o training-data/
+
+# Organize dataset
+vogel-trainer organize training-data/ -o organized/
+
+# Train model
+vogel-trainer train organized/ -o models/my-classifier/
+
+# Test model
+vogel-trainer test models/my-classifier/ -d organized/
+```
+
+### Documentation
+
+- **📖 Bilingual Documentation** - Complete README in English and German
+- **🎓 Training Guides** - Step-by-step workflow documentation
+- **💡 Examples** - Real-world usage examples
+- **🤝 Contributing Guidelines** - Clear contribution process
+- **🔒 Security Policy** - Responsible disclosure policy
+
+## 🚀 Getting Started
+
+### Quick Start
+
+```bash
+# 1. Install
+pip install vogel-model-trainer
+
+# 2. Extract birds from your videos
+vogel-trainer extract video.mp4 -o ~/training-data/kohlmeise/
+
+# 3. Organize dataset
+vogel-trainer organize ~/training-data/ -o ~/organized-data/
+
+# 4. Train your model
+vogel-trainer train ~/organized-data/ -o ~/models/my-classifier/
+
+# 5. Test the model
+vogel-trainer test ~/models/my-classifier/ -d ~/organized-data/
+```
+
+### System Requirements
+
+- **Python:** 3.9 or higher
+- **GPU:** Recommended for training (Raspberry Pi 5 supported)
+- **Disk Space:** Depends on dataset size
+- **RAM:** Minimum 4GB, 8GB+ recommended for training
+
+## 📊 Performance
+
+- **Extraction Speed:** ~5-10 FPS on Raspberry Pi 5
+- **Training Time:** ~3-4 hours for 500 images on Raspberry Pi 5
+- **Model Accuracy:** >96% on well-organized datasets
+- **Model Size:** ~17MB (EfficientNet-B0)
+
+## 🔄 Workflow
+
+1. **Extract** bird images from videos using YOLO detection
+2. **Organize** images by species into subdirectories
+3. **Split** dataset into 80% training / 20% validation
+4. **Train** custom EfficientNet-B0 classifier
+5. **Test** model accuracy on validation set
+6. **Deploy** trained model for species identification
+
+## 📚 Resources
+
+- **Documentation:** [README.md](https://github.com/kamera-linux/vogel-model-trainer/blob/main/README.md)
+- **German Docs:** [README.de.md](https://github.com/kamera-linux/vogel-model-trainer/blob/main/README.de.md)
+- **Contributing:** [CONTRIBUTING.md](https://github.com/kamera-linux/vogel-model-trainer/blob/main/CONTRIBUTING.md)
+- **Security:** [SECURITY.md](https://github.com/kamera-linux/vogel-model-trainer/blob/main/SECURITY.md)
+- **Changelog:** [CHANGELOG.md](https://github.com/kamera-linux/vogel-model-trainer/blob/main/CHANGELOG.md)
+- **PyPI:** [pypi.org/project/vogel-model-trainer](https://pypi.org/project/vogel-model-trainer/)
+
+## 🐛 Known Issues
+
+- Manual labeling mode not yet implemented (use standard extraction + manual sorting)
+- Auto-sorting mode not yet implemented (use standard extraction + manual sorting)
+- No GUI interface (CLI only)
+
+## 🔮 Future Plans
+
+- Interactive manual labeling during extraction
+- Automatic species sorting using pre-trained models
+- Support for additional model architectures
+- Real-time training monitoring dashboard
+- Dataset augmentation presets
+- Model optimization for embedded devices
+
+## 🙏 Acknowledgments
+
+- **Ultralytics** - For the excellent YOLOv8 implementation
+- **Hugging Face** - For the Transformers library
+- **PyTorch Team** - For the deep learning framework
+- **Contributors** - Thank you to everyone who helped test and improve this project!
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+**Full Changelog:** https://github.com/kamera-linux/vogel-model-trainer/commits/v0.1.0
+
+**Questions?** Open an issue at https://github.com/kamera-linux/vogel-model-trainer/issues

vogel_model_trainer-0.1.4/.github/RELEASE_v0.1.1.md

@@ -0,0 +1,124 @@
+# 🔧 vogel-model-trainer v0.1.1
+
+**Release Date:** November 8, 2025
+
+Bug fix release with corrected CLI parameters to match original training scripts.
+
+## 📦 Installation
+
+```bash
+pip install vogel-model-trainer==0.1.1
+```
+
+## 🐛 Bug Fixes
+
+### CLI Parameter Corrections
+
+Fixed CLI parameters to match the original `extract_birds.py` script:
+
+- ✅ **Changed `--output/-o` to `--folder`** - Matches original parameter naming
+- ✅ **Added `--bird` parameter** - Manual species naming (creates subdirectory)
+- ✅ **Added `--species-model` parameter** - Auto-sorting with trained classifier
+- ✅ **Added `--no-resize` flag** - Keep original image size
+- ✅ **Renamed `--model` to `--detection-model`** - Clearer naming for YOLO model
+- ✅ **Updated default `--threshold`** - Changed from 0.3 to 0.5 for higher quality
+- ✅ **Updated default `--sample-rate`** - Changed from 10 to 3 for better detection
+- ✅ **Added `--recursive/-r` flag** - Recursive directory search
+
+### Simplified CLI Interface
+
+- ✅ **Removed `extract-manual` command** - Now use `extract --bird species-name`
+- ✅ **Removed `extract-auto` command** - Now use `extract --species-model path`
+- ✅ **Single unified `extract` command** - Supports all three modes via flags
+
+## 📚 Updated Documentation
+
+- ✅ Updated README.md with correct CLI examples
+- ✅ Updated README.de.md (German documentation)
+- ✅ Corrected all code examples to use new parameter names
+
+## 🔄 Migration Guide
+
+### Before (v0.1.0):
+```bash
+# Manual extraction
+vogel-trainer extract video.mp4 -o training-data/
+
+# Manual labeling (separate command)
+vogel-trainer extract-manual video.mp4 -o training-data/
+
+# Auto-sorting (separate command)
+vogel-trainer extract-auto video.mp4 -o training-data/ --classifier model/
+```
+
+### After (v0.1.1):
+```bash
+# Standard extraction (all birds to one directory)
+vogel-trainer extract video.mp4 --folder training-data/
+
+# Manual labeling (creates subdirectory)
+vogel-trainer extract video.mp4 --folder training-data/ --bird rotkehlchen
+
+# Auto-sorting (with trained classifier)
+vogel-trainer extract video.mp4 --folder training-data/ --species-model model/final/
+```
+
+## 📖 Complete CLI Reference
+
+### Extract Command
+
+```bash
+vogel-trainer extract VIDEO --folder FOLDER [OPTIONS]
+```
+
+**Positional Arguments:**
+- `VIDEO` - Video file, directory, or glob pattern (e.g., `*.mp4`, `~/Videos/**/*.mp4`)
+
+**Required Options:**
+- `--folder` - Base directory for extracted bird images
+
+**Optional Flags:**
+- `--bird` - Manual bird species name (creates subdirectory)
+- `--species-model` - Path to species classifier for automatic sorting
+- `--no-resize` - Keep original image size instead of 224x224px
+- `--detection-model` - YOLO model path (default: `yolov8n.pt`)
+- `--threshold` - Detection confidence threshold (default: `0.5`)
+- `--sample-rate` - Analyze every Nth frame (default: `3`)
+- `--recursive, -r` - Search directories recursively
+
+**Examples:**
+```bash
+# Standard mode
+vogel-trainer extract video.mp4 --folder data/
+
+# Manual mode with species
+vogel-trainer extract video.mp4 --folder data/ --bird kohlmeise
+
+# Auto-sort mode
+vogel-trainer extract "*.mp4" --folder data/ --species-model ~/models/classifier/
+
+# Recursive search
+vogel-trainer extract ~/Videos/ --folder data/ --bird amsel --recursive
+
+# Custom parameters
+vogel-trainer extract video.mp4 --folder data/ --threshold 0.6 --sample-rate 5
+```
+
+## ⚙️ Technical Details
+
+- **Changed Files:** 
+  - `src/vogel_model_trainer/cli/main.py` - Complete CLI parameter overhaul
+  - `README.md` - Updated all examples
+  - `README.de.md` - Updated German examples
+
+- **Backward Compatibility:** ⚠️ **Breaking changes** - v0.1.0 commands will not work with v0.1.1
+
+## 🙏 Thank You
+
+Thanks to users who reported the parameter inconsistencies between the CLI and original training scripts!
+
+---
+
+**Full Changelog:** https://github.com/kamera-linux/vogel-model-trainer/compare/v0.1.0...v0.1.1
+
+**Questions?** Open an issue at https://github.com/kamera-linux/vogel-model-trainer/issues