README.md

---
language:
- en
library_name: ultralytics
license: gpl-3.0
pipeline_tag: image-classification
base_model: Ultralytics/YOLOv8
metrics:
- f1-score
- mAP50-95
tags:
- trapper
- trapperai
- ecology
- biology
- wildlife
- animal detection
- species classification
---

<p align="center">
  <img src="https://gitlab.com/trapper-project/trapper-ai-worker/-/raw/main/OSCF-TRAPPER-AI-logo.png">
</p>

<div align="center"> 
<font size="6">TrapperAI model for for 18 European mammal species classification</font>
<br>
<hr>
</div>

## 🐺 Overview

The TrapperAI model is responsible for the detection and classification of 18 European mammal species with a **95% F1-score** and **93% mAP50-95**. This model is based on the fine-tuned [YOLOv8-m](https://github.com/ultralytics/ultralytics) model and can be loaded and utilized directly through the Ultralytics package interface or via the TRAPPER ecosystem ([TrapperAI Worker](https://gitlab.com/trapper-project/trapper-ai-worker)).

The dataset used for model training and evaluation comprised **401,458** camera trap images from Poland, Germany, Sweden, Austria, and Switzerland. The data repository consisted of **5,680 deployments** and **2,944 locations**.

List of supported species:

* Bird
* Cat
* Chamois
* Dog
* Eurasian Lynx
* Eurasian Red Squirrel
* European Badger
* European Mouflon
* Fallow Deer
* Gray Wolf
* Hare
* Marten
* Moose
* Red Deer
* Red Fox
* Reindeer
* Roe Deer
* Wild Boar

The recommended image resolution for the model is 1024px. The model's performance enables the processing of ~30,000 images in one hour using a single NVIDIA GPU with more than 11 GB of vRAM.

## 📥 Installation

```bash
$ python3 -m venv env
$ source env/bin/activate
$ pip install ultralytics dill ipython # IPython is optional
```

## 🚀 Usage

```ipython
In [1]: from ultralytics import YOLO
In [2]: model = YOLO("TrapperAI-v02.2024-YOLOv8-m.pt")
In [3]: results = model.predict("fox36-Vulpes-vulpes.jpg")

In [4]: len(results) # how many animals were detected
Out[4]: 1

In [5]: results[0].show() # open image viewer with detection and classification results

In [6]: results[0].boxes.conf # return best confidence score for detection and classification results
Out[6]: tensor([0.9558], device='cuda:0')

In [7]: results[0].boxes.cls # return index value for detection and classification results
Out[7]: tensor([14.], device='cuda:0') # Red Fox
```

If your image contains more than one object (animal), you will need to iterate through the results list to obtain the confidence score and species index value for each detected object.

## 🏢 Who is using TRAPPER?
* Mammal Research Institute Polish Academy of Sciences;
* Karkonosze National Park;
* Swedish University of Agricultural Sciences;
* Svenska Jägareförbundet;
* Meles Wildbiologie;
* University of Freiburg Wildlife Ecology and Management;
* Bavarian Forest National Park;
* Georg-August-Universität Göttingen;
* KORA - Carnivore Ecology and Wildlife Management;
* and many more individual scientists and ecologies;

## 💲 Funders and Partners
<p align="center">
  <img src="https://gitlab.com/trapper-project/trapper-ai-worker/-/raw/main/TRAPPER-funds.png">
</p>
<p align="center">
  <img src="https://gitlab.com/trapper-project/trapper-ai-worker/-/raw/main/TRAPPER-partners.png">
</p>

## 🤝 Support

Feel free to add a new issue with a respective title and description on the [TRAPPER issue tracker](https://gitlab.com/trapper-project/trapper/-/issues). If you already found a solution to your problem, we would be happy to review your pull request.

If you prefer direct contact, please let us know: `contact@os-conservation.org`

We also have [TRAPPER Mailing List](https://groups.google.com/d/forum/trapper-project) and [TRAPPER Slack](https://join.slack.com/t/trapperproject/shared_invite/zt-2f360a5pu-CzsIqJ6Y~iCa_dmGXVNB7A).

## 📜 License

Read more in [TRAPPER License](https://gitlab.com/oscf/trapper-ai-worker/-/blob/main/LICENSE).