README.md

---
language: de
license: apache-2.0
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 **Apache License 2.0**. See the [LICENSE](https://huggingface.co/kamera-linux/german-bird-classifier-v2/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)**