Upload folder using huggingface_hub

README.md

@@ -0,0 +1,305 @@
+---
+language: de
+license: mit
+tags:
+- image-classification
+- birds
+- german-birds
+- computer-vision
+- efficientnet
+- wildlife
+datasets:
+- custom
+metrics:
+- accuracy
+- f1
+model-index:
+- name: german-bird-classifier-v2
+  results:
+  - task:
+      type: image-classification
+      name: Image Classification
+    dataset:
+      name: German Garden Birds
+      type: custom
+    metrics:
+    - type: accuracy
+      value: 0.9971
+      name: Accuracy
+    - type: f1
+      value: 0.997
+      name: Macro F1-Score
+---
+
+# German Bird Classifier v2 🐦
+
+**High-accuracy German garden bird species classifier based on EfficientNet-B2.**
+
+This is **version 2** of the German bird classifier with significantly improved performance:
+- ✅ **99.71% accuracy** (vs. 87.69% in v1)
+- ✅ **42× fewer errors** (3 vs. 128 misclassifications)
+- ✅ **Perfect classification** for 5 out of 8 species
+
+## Model Description
+
+This model classifies 8 common German garden bird species from images. It was trained using the [vogel-model-trainer](https://github.com/kamera-linux/vogel-model-trainer) toolkit on 4,160 training images extracted from real-world bird feeder camera footage.
+
+**Architecture:** EfficientNet-B2  
+**Framework:** PyTorch + Hugging Face Transformers  
+**Input:** RGB images (224×224)  
+**Output:** 8 species classes with confidence scores
+
+## Supported Species
+
+1. **Blaumeise** (Blue Tit) - *Cyanistes caeruleus*
+2. **Grünling** (European Greenfinch) - *Chloris chloris*
+3. **Haussperling** (House Sparrow) - *Passer domesticus*
+4. **Kernbeißer** (Hawfinch) - *Coccothraustes coccothraustes*
+5. **Kleiber** (Eurasian Nuthatch) - *Sitta europaea*
+6. **Kohlmeise** (Great Tit) - *Parus major*
+7. **Rotkehlchen** (European Robin) - *Erithacus rubecula*
+8. **Sumpfmeise** (Marsh Tit) - *Poecile palustris*
+
+## Performance
+
+### Overall Metrics (Validation Set: 1,040 images)
+
+| Metric | Value |
+|--------|-------|
+| **Accuracy** | **99.71%** |
+| **Macro F1-Score** | **99.7%** |
+| **Weighted F1-Score** | **99.7%** |
+| **Correct Classifications** | 1,037 / 1,040 |
+| **Misclassifications** | 3 |
+
+### Per-Species Performance
+
+| Species | Precision | Recall | F1-Score | Samples |
+|---------|-----------|--------|----------|---------|
+| Blaumeise | 98.5% | 100.0% | 99.2% | 130 |
+| Grünling | 100.0% | 100.0% | **100.0%** | 130 |
+| Haussperling | 100.0% | 100.0% | **100.0%** | 130 |
+| Kernbeißer | 100.0% | 100.0% | **100.0%** | 130 |
+| Kleiber | 100.0% | 100.0% | **100.0%** | 130 |
+| Kohlmeise | 99.2% | 99.2% | 99.2% | 130 |
+| Rotkehlchen | 100.0% | 99.2% | 99.6% | 130 |
+| Sumpfmeise | 100.0% | 99.2% | 99.6% | 130 |
+
+**5 out of 8 species achieve perfect 100% F1-score!**
+
+### Comparison to v1
+
+| Metric | v1 | v2 | Improvement |
+|--------|----|----|-------------|
+| **Overall Accuracy** | 87.69% | **99.71%** | **+12.0pp** |
+| **Macro F1-Score** | 87.3% | **99.7%** | **+12.4pp** |
+| **Misclassifications** | 128 | **3** | **-97.7%** |
+| **Error Rate Reduction** | - | - | **42.7×** |
+
+**Biggest improvements:**
+- 🎯 **Grünling:** 58.7% → 100.0% F1 (+41.3pp)
+- 🎯 **Haussperling:** 72.0% → 100.0% F1 (+28.0pp)
+- 🎯 **Rotkehlchen:** 89.5% → 99.6% F1 (+10.1pp)
+
+## Usage
+
+### Quick Start
+
+```python
+from transformers import AutoImageProcessor, AutoModelForImageClassification
+from PIL import Image
+import torch
+
+# Load model and processor
+model_name = "kamera-linux/german-bird-classifier-v2"
+processor = AutoImageProcessor.from_pretrained(model_name)
+model = AutoModelForImageClassification.from_pretrained(model_name)
+
+# Load and preprocess image
+image = Image.open("bird.jpg")
+inputs = processor(images=image, return_tensors="pt")
+
+# Predict
+with torch.no_grad():
+    outputs = model(**inputs)
+    logits = outputs.logits
+    predicted_class = logits.argmax(-1).item()
+    confidence = torch.softmax(logits, dim=-1)[0][predicted_class].item()
+
+# Get species name
+species = model.config.id2label[predicted_class]
+print(f"Species: {species} (Confidence: {confidence:.2%})")
+```
+
+### Using vogel-model-trainer CLI
+
+```bash
+# Install the toolkit
+pip install vogel-model-trainer
+
+# Classify images
+vogel-trainer classify \
+  --species-model kamera-linux/german-bird-classifier-v2 \
+  ~/bird-photos/ \
+  --sort-output ~/sorted/ \
+  --min-confidence 0.90 \
+  --csv-report results.csv
+
+# Evaluate model performance
+vogel-trainer evaluate \
+  --species-model kamera-linux/german-bird-classifier-v2 \
+  --test-dir ~/test-dataset/ \
+  --export-json metrics.json
+```
+
+### Batch Processing
+
+```python
+from transformers import pipeline
+
+# Create classifier pipeline
+classifier = pipeline(
+    "image-classification",
+    model="kamera-linux/german-bird-classifier-v2",
+    device=0  # GPU
+)
+
+# Classify multiple images
+images = ["bird1.jpg", "bird2.jpg", "bird3.jpg"]
+results = classifier(images, top_k=3)
+
+for img, preds in zip(images, results):
+    print(f"\n{img}:")
+    for pred in preds:
+        print(f"  {pred['label']}: {pred['score']:.2%}")
+```
+
+## Training Details
+
+### Dataset
+
+- **Training images:** 4,160 (520 per species)
+- **Validation images:** 1,040 (130 per species)
+- **Source:** Real-world bird feeder camera footage
+- **Image size:** 224×224 pixels
+- **Perfectly balanced:** Equal samples per class
+
+### Training Configuration
+
+```
+Model: google/efficientnet-b2
+Epochs: 50 (with early stopping)
+Batch Size: 32
+Learning Rate: 0.0001
+Optimizer: AdamW
+Scheduler: Cosine with warmup
+Augmentation: Heavy
+  - Random rotation
+  - Random horizontal flip
+  - Color jitter
+  - Random brightness/contrast
+Early Stopping Patience: 15 epochs
+Hardware: NVIDIA RTX 2070 SUPER (8GB)
+Training Time: ~35 minutes
+Framework: PyTorch 2.9.1 + Transformers 4.57.1
+```
+
+### Data Processing
+
+Images were extracted from videos using YOLOv8n bird detection:
+1. **Detection:** Birds detected in video frames
+2. **Extraction:** Cropped bird regions saved as images
+3. **Deduplication:** Similar frames removed using perceptual hashing
+4. **Organization:** Manual verification and species labeling
+5. **Split:** 80% training, 20% validation
+
+## Model Size & Performance
+
+| Metric | Value |
+|--------|-------|
+| **Model Size** | 16 MB (safetensors) |
+| **Parameters** | ~9.1M |
+| **Inference Speed (GPU)** | ~100 images/sec |
+| **Inference Speed (CPU)** | ~10 images/sec |
+| **Memory Usage (GPU)** | ~300 MB |
+| **Memory Usage (CPU)** | ~200 MB |
+
+## Limitations & Bias
+
+### Known Limitations
+
+1. **Species Scope:** Only trained on 8 common German garden birds
+2. **Tit Confusion:** Occasional confusion between similar tit species (Blaumeise, Kohlmeise, Sumpfmeise)
+3. **Image Quality:** Best performance on clear, well-lit images
+4. **Pose Dependency:** Trained primarily on frontal/side views from bird feeders
+5. **Juvenile Birds:** May struggle with juvenile plumage variations
+6. **Seasonal Variations:** Limited seasonal plumage data
+
+### Potential Biases
+
+- **Feeder Bias:** Trained on bird feeder footage, may not generalize to natural settings
+- **Geographic Bias:** German garden birds, regional appearance variations may exist
+- **Equipment Bias:** Optimized for similar camera setups and lighting conditions
+
+### Error Analysis
+
+The 3 misclassifications on validation set:
+1. **Kohlmeise → Blaumeise** (91% confidence) - Similar coloring in poor lighting
+2. **Rotkehlchen → Blaumeise** (23% confidence) - Low confidence, model uncertain
+3. **Sumpfmeise → Kohlmeise** (76% confidence) - Very similar tit species
+
+**Recommendation:** Use `--min-confidence 0.85` threshold to filter uncertain predictions.
+
+## Intended Use
+
+### Primary Use Cases
+
+✅ **Automated bird feeder monitoring**  
+✅ **Citizen science bird counting**  
+✅ **Wildlife camera image classification**  
+✅ **Educational bird identification apps**  
+✅ **Biodiversity research**
+
+### Out-of-Scope Uses
+
+❌ Classifying non-German bird species  
+❌ Identifying birds outside the 8 trained species  
+❌ Medical/diagnostic applications  
+❌ Legal evidence or regulatory decisions  
+❌ Security/surveillance applications
+
+## Citation
+
+If you use this model in your research, please cite:
+
+```bibtex
+@misc{german-bird-classifier-v2,
+  title={German Bird Classifier v2: High-Accuracy Garden Bird Species Classification},
+  author={kamera-linux},
+  year={2025},
+  publisher={Hugging Face},
+  url={https://huggingface.co/kamera-linux/german-bird-classifier-v2}
+}
+```
+
+## Related Resources
+
+- **Training Toolkit:** [vogel-model-trainer](https://github.com/kamera-linux/vogel-model-trainer)
+- **PyPI Package:** [vogel-model-trainer](https://pypi.org/project/vogel-model-trainer/)
+- **v1 Model (deprecated):** [german-bird-classifier](https://huggingface.co/kamera-linux/german-bird-classifier)
+- **Documentation:** [GitHub README](https://github.com/kamera-linux/vogel-model-trainer/blob/main/README.md)
+
+## License
+
+This model is released under the MIT License. See the [LICENSE](https://github.com/kamera-linux/vogel-model-trainer/blob/main/LICENSE) file for details.
+
+## Acknowledgments
+
+- **Ultralytics** for YOLOv8 bird detection
+- **Hugging Face** for Transformers library and model hosting
+- **PyTorch Team** for the deep learning framework
+- **Google** for EfficientNet architecture
+
+---
+
+**Trained with ❤️ using [vogel-model-trainer](https://github.com/kamera-linux/vogel-model-trainer)**

config.json

@@ -0,0 +1,109 @@
+{
+  "architectures": [
+    "EfficientNetForImageClassification"
+  ],
+  "batch_norm_eps": 0.001,
+  "batch_norm_momentum": 0.99,
+  "depth_coefficient": 1.0,
+  "depth_divisor": 8,
+  "depthwise_padding": [],
+  "drop_connect_rate": 0.2,
+  "dropout_rate": 0.2,
+  "dtype": "float32",
+  "expand_ratios": [
+    1,
+    6,
+    6,
+    6,
+    6,
+    6,
+    6
+  ],
+  "hidden_act": "swish",
+  "hidden_dim": 1280,
+  "id2label": {
+    "0": "blaumeise",
+    "1": "gr\u00fcnling",
+    "2": "haussperling",
+    "3": "kernbei\u00dfer",
+    "4": "kleiber",
+    "5": "kohlmeise",
+    "6": "rotkehlchen",
+    "7": "sumpfmeise"
+  },
+  "image_size": 224,
+  "in_channels": [
+    32,
+    16,
+    24,
+    40,
+    80,
+    112,
+    192
+  ],
+  "initializer_range": 0.02,
+  "kernel_sizes": [
+    3,
+    3,
+    5,
+    3,
+    5,
+    5,
+    3
+  ],
+  "label2id": {
+    "blaumeise": 0,
+    "gr\u00fcnling": 1,
+    "haussperling": 2,
+    "kernbei\u00dfer": 3,
+    "kleiber": 4,
+    "kohlmeise": 5,
+    "rotkehlchen": 6,
+    "sumpfmeise": 7
+  },
+  "model_type": "efficientnet",
+  "num_block_repeats": [
+    1,
+    2,
+    2,
+    3,
+    3,
+    4,
+    1
+  ],
+  "num_channels": 3,
+  "num_hidden_layers": 64,
+  "out_channels": [
+    16,
+    24,
+    40,
+    80,
+    112,
+    192,
+    320
+  ],
+  "out_features": null,
+  "pooling_type": "mean",
+  "squeeze_expansion_ratio": 0.25,
+  "stage_names": [
+    "stem",
+    "stage1",
+    "stage2",
+    "stage3",
+    "stage4",
+    "stage5",
+    "stage6",
+    "stage7"
+  ],
+  "strides": [
+    1,
+    2,
+    2,
+    2,
+    1,
+    2,
+    1
+  ],
+  "transformers_version": "4.57.1",
+  "width_coefficient": 1.0
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ccb4d1b06b5467538ae410fb5ba64c7959d0c3bc80f3858daf20e9acf4ecae0b
+size 16285880

preprocessor_config.json

@@ -0,0 +1,29 @@
+{
+  "crop_size": {
+    "height": 289,
+    "width": 289
+  },
+  "do_center_crop": false,
+  "do_normalize": true,
+  "do_rescale": true,
+  "do_resize": true,
+  "image_mean": [
+    0.485,
+    0.456,
+    0.406
+  ],
+  "image_processor_type": "EfficientNetImageProcessor",
+  "image_std": [
+    0.47853944,
+    0.4732864,
+    0.47434163
+  ],
+  "include_top": true,
+  "resample": 0,
+  "rescale_factor": 0.00392156862745098,
+  "rescale_offset": false,
+  "size": {
+    "height": 224,
+    "width": 224
+  }
+}

training_args.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1a15fcfe7b375866e2ccdaaeb75a29e149d8c521bbdbb94de0ebce24eb938e73
+size 5905

training_config.json

@@ -0,0 +1,18 @@
+{
+  "model_name": "google/efficientnet-b2",
+  "species": [
+    "blaumeise",
+    "gr\u00fcnling",
+    "haussperling",
+    "kernbei\u00dfer",
+    "kleiber",
+    "kohlmeise",
+    "rotkehlchen",
+    "sumpfmeise"
+  ],
+  "num_classes": 8,
+  "timestamp": "20251214_235745",
+  "batch_size": 32,
+  "num_epochs": 50,
+  "learning_rate": 0.0001
+}