Update README.md

README.md

@@ -1,6 +1,81 @@
----
-license: other
-license_name: bsg-bird-model-license
-license_link: >-
-  https://raw.githubusercontent.com/plauha/BSG_classifier_builder/refs/heads/main/BSG%20-%20Bird%20Model%20License
----
+---
+license: other
+license_name: bsg-bird-model-license
+license_link: >-
+  https://raw.githubusercontent.com/plauha/BSG_classifier_builder/refs/heads/main/BSG%20-%20Bird%20Model%20License
+---
+# BSG Finnish Birds Model – ONNX Optimized
+
+Optimized [ONNX](https://onnx.ai/) conversions of the **BSG – Finnish Birds Model**, a pretrained bird sound classification model fine-tuned for Finland. The original model was developed at the **University of Jyväskylä** and is based on the [BirdNET](https://github.com/kahst/BirdNET-Analyzer) model architecture.
+
+## Model Description
+
+The BSG Finnish Birds Model uses an **EfficientNet-B0** backbone (from BirdNET-Analyzer) with a custom classification head trained on vocalizations of **263 Finnish bird species**, covering all breeders, non-breeding migrants, and most common vagrants.
+
+**Key characteristics:**
+
+- Processes audio in **3-second overlapping segments** (spectrogram-based)
+- Outputs species-wise detection probabilities, calibrated per species via logistic regression
+- Predictions are filtered by species' seasonal and geographic plausibility to reduce misclassifications
+
+## Files
+
+| File | Description | Recommended Use |
+|------|-------------|-----------------|
+| `BSG_birds_Finland_v4_4_fp32.onnx` | Full precision (FP32) | GPU (CUDA/TensorRT), Desktop CPU |
+| `BSG_birds_Finland_v4_4_fp16.onnx` | Half precision (FP16) | RPi 5, Modern GPUs |
+| `BSG_birds_Finland_v4_4_labels_fi.txt` | Labels (Scientific name_Finnish name) | Class index mapping |
+
+## ONNX Optimization
+
+The ONNX models were converted from the original TFLite model and optimized for efficient inference using [birdnet-onnx-converter](https://github.com/thakala/birdnet-onnx-converter). ONNX enables deployment across a wide range of runtimes and hardware platforms including CPU, GPU, and edge devices via [ONNX Runtime](https://onnxruntime.ai/).
+
+## Training Data
+
+Training data combined:
+
+- Expert-annotated clips from [Xeno-canto](https://xeno-canto.org/)
+- Finnish soundscapes
+- Targeted field recordings
+- Selected mobile phone recordings
+
+## Usage
+
+The code for running inference with the model is available at: **[luomus/bird-identification](https://github.com/luomus/bird-identification)**
+
+For building locally fine-tuned classifiers, see the BSG classifier builder: **[plauha/BSG_classifier_builder](https://github.com/plauha/BSG_classifier_builder)**
+
+## License
+
+Usage is limited to **non-commercial purposes**. See the [LICENSE](LICENSE) file for details.
+
+## Citation
+
+If you use this model, please cite:
+
+```bibtex
+@article{nokelainen2024mobile,
+  title={A Mobile Application–Based Citizen Science Product to Compile Bird Observations},
+  author={Nokelainen, O. and Lauha, P. and Andrejeff, S. and H{\"a}nninen, J. and Inkinen, J. and Kallio, A. and Lehto, H.J. and Mutanen, M. and Paavola, R. and Schiestl-Aalto, P. and Somervuo, P. and Sundell, J. and Talaskivi, J. and Vallinm{\"a}ki, M. and Vancraeyenest, A. and Lehti{\"o}, A. and Ovaskainen, O.},
+  journal={Citizen Science: Theory and Practice},
+  volume={9},
+  number={1},
+  pages={24},
+  year={2024},
+  doi={10.5334/cstp.710}
+}
+```
+
+```bibtex
+@article{lauha2025bsg,
+  title={Bird Sounds Global - model builder: An end-to-end workflow for building locally fine-tuned bird classifiers},
+  author={Lauha, Patrik and Rannisto, Meeri and Somervuo, Panu and others},
+  journal={Authorea},
+  year={2025},
+  doi={10.22541/au.176599468.88578746/v1}
+}
+```
+
+## Acknowledgments
+
+This model was developed at the University of Jyväskylä. The ONNX conversion and optimization were performed independently to enable broader deployment options.