README.md

---
tags:
- coffee
- cherry count
- yield estimate
- ultralyticsplus
- yolov8
- ultralytics
- yolo
- vision
- object-detection
- pytorch
library_name: ultralytics
library_version: 8.0.75
inference: false
datasets:
- rgautron/croppie_coffee
model-index:
- name: rgautron/croppie_coffee
  results:
  - task:
      type: object-detection
    dataset:
      type: rgautron/croppie_coffee
      name: croppie_coffee
      split: val
    metrics:
    - type: precision
      value: 0.691
      name: mAP@0.5(box)
license: gpl-3.0
license_link: https://www.gnu.org/licenses/quick-guide-gplv3.html
base_model: Ultralytics/YOLOv8
---
[Croppie](https://croppie.org/) cherry detection model © 2024 by [Alliance Bioversity & CIAT](https://alliancebioversityciat.org/), [Producers Direct](https://producersdirect.org/) and [M-Omulimisa](https://m-omulimisa.com/) is licensed under [GNU-GPLv3](https://www.gnu.org/licenses/quick-guide-gplv3.html)

**Funded by**: Deutsche Gesellschaft für Internationale Zusammenarbeit (GIZ) [Fair Forward Initiative - AI for All](https://huggingface.co/fair-forward)

## General description
Ultralytics' Yolo V8 medium [model fined tuned](https://yolov8.org/how-to-use-fine-tune-yolov8/) for coffee cherry detection using the [Croppie coffee dataset](https://huggingface.co/datasets/rgautroncgiar/croppie_coffee_ug). 

This algorithm provides automated cherry count from RGB pictures. Takes as input a picture and returns the cherry count by class.

The predicted numerical classes correspond to the following cherry types:
```
{0: "dark_brown_cherry", 1: "green_cherry", 2: "red_cherry", 3: "yellow_cherry"}
```

**Examples of use**:
* yield estimates
* ripeness detection

**Limitations:** This algorithm does not include correction of cherry occlusion.

![](images/annotated_1688033955437_.jpg)

**Note: the low visibility/unsure class was not used for model fine tuning**


## Repository structure

```
.
├── images
│   ├── foo.bar # images for the documentation
├── model_v3_202402021.pt  # fine tuning of Yolo v8
├── README.md
├── LICENSE.txt # detailed term of the software license
└── scripts
    ├── custom_YOLO.py # script which overwrites the default YOLO class
    ├── render_results.py  # helper function to annotate predictions
    ├── requirements.txt  # pip requirements
    └── test_script.py  # test script
```

## Demonstration
Assuming you are in the ```scripts``` folder, you can run ```python3 test_script.py```. This script saves the annotated image in ```../images/annotated_1688033955437.jpg```.

Make sure that the Python packages found in ```requirements.txt``` are installed. In case they are not, simply run ```pip3 install -r requirements.txt```.

A live demonstration is freely accesible [here](https://croppie.org/).

## Training metrics
![](images/training_results.png)

The model has been trained using the custom YOLO class found in ```./scripts/custom_YOLO.py```. The custom YOLO class can be exactly used as the original [YOLO class](https://docs.ultralytics.com/reference/models/yolo/model/). The hyperparameters used during the training can be found in ```./scripts/args.yaml```.

The training maximize the mAP@0.5, which is the mean Average Precision calculated at a 0.5 Intersection over Union (IoU) threshold, measuring how well the model detects objects with at least 50% overlap between predicted and ground truth bounding boxes.

## Test metrics

<img src="images/F1_curve.png" width="300">
<img src="images/P_curve.png" width="300">
<img src="images/PR_curve.png" width="300">
<img src="images/R_curve.png" width="300">

## License
[Croppie](https://croppie.org/) cherry detection model © 2024 by [Alliance Bioversity & CIAT](https://alliancebioversityciat.org/), [Producers Direct](https://producersdirect.org/) and [M-Omulimisa](https://m-omulimisa.com/) is licensed under [GNU-GPLv3](https://www.gnu.org/licenses/quick-guide-gplv3.html)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

The detailed terms of the license are available in the ```LICENSE``` file in the repository.

## Funding

**Funded by**: Deutsche Gesellschaft für Internationale Zusammenarbeit (GIZ) [Fair Forward Initiative - AI for All](https://huggingface.co/fair-forward)