Was krabbelt da ?

Was krabbelt da provides journalistic tools to report on the biodiversity in your area. Based on a DIY camera trap, developed by Maximilian Sittinger, this project provides a platform to automatically receive and classify the images, as well as, a dashboard to visualize and analyze the data.
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Deployment
4. Usage
5. Technical Details
6. License
7. Contact
8. Acknowledgments
9. Funding

About The Project

Use this repository to setup your own API and dashboard for the insect-detect camera trap. The API provides endpoints to classify images and store the classification data and images. The classification and image data can then be accessed via various data endpoints. The Dashboard provides a user interface to explore classified image data, visualize the data and download the collected data.

(back to top)

Built With

• 
• 

Based on

• Streamlit FastAPI Model Serving by Davide Fiocco

(back to top)

Getting Started

Prerequisites

For local development, you need to have the following installed:

• Docker: https://docs.docker.com/get-docker/

Installation

1. Clone the repo

   git clone https://github.com/Was-krabbelt-da/waskrabbeltda

2. Create an API key e.g. by running the following in your command line:

   openssl rand -base64 128 | tr -d '\n' | pbcopy

3. Create a .env file in the fastapi folder (e.g. by copying or renaming the .env.example file) and fill in the created API key value.

   API_KEY=

4. Create a .env file in the streamlit folder (e.g. by copying or renaming the .env.example file) and fill in the created API key value. You can also add a name for the camera trap which will be displayed in the dashboard and used for downloadable files. The DATA_ENDPOINT should be the URL of the FastAPI service, in the case of a local setup with no changes to the docker-compose file, it should be http://fastapi:8000.

   API_KEY=
   CAMERA_NAME=
   DATA_ENDPOINT="http://fastapi:8000"

5. Build the project with docker-compose

   docker compose build

6. Start the project with docker-compose

    docker compose up

7. Visit the FastAPI documentation of the resulting service at http://localhost:8000/docs with a web browser.
8. Visit the streamlit UI at http://localhost:8501.

You should be able to see an empty dashboard with no data (currently the dashboard displays an error if it is completely empty, send a request with mock data to the API to resolve this an be able to fix it). You can fill it by sending requests to the endpoints specified in the FastAPI documentation at http://localhost:8000/docs.

(back to top)

Usage

The endpoints of the FastAPI service are documented in the FastAPI documentation at http://localhost:8000/docs. Send requests to the /classify endpoint to classify images and store the classification data and images. The classification and image data can then be accessed via various data endpoints. E.g. you can query all currently stored classifications with a GET request to the /data/classification endpoint.

The Streamlit UI provides a user interface to explore classified image data, automatically visualizes the data, shows images of the last captured insects, allows exploring all captured tracking runs and downloading the collected data. The UI is accessible at http://localhost:8501 or the respective URL of the deployed service.

(back to top)

Deployment

The project is setup to be deployed via two fly machines with a volume attached to the FastAPI machine for persistence. fly.io is a platform that allows you to deploy your container-based applications with as little overhead as possible.

Prerequisites

• A fly.io account and the flyctl CLI installed, which you can obtain here.

Deployment Steps

• The WasKrabbeltDa project is setup in two services, a FastAPI service and a Streamlit service, corresponding to the two folders in the repository.

• Each service has its own Dockerfile and fly.toml and can/has to be deployed independently.

  • (fly.toml files configure the deployment settings for the fly.io platform)

• For a full deployment:

1. Deploy the FastAPI service

• Change into the fastapi folder and deploy the service for the first time with the following command:

  cd fastapi
  fly launch

• Follow the instructions in the terminal to configure the deployment.
• After the deployment is finished, you can set the API key as a secret with the following command:

  fly secrets set API_KEY=...

• The deployment should automatically included an attached volume for persistence. See the technical details for more information.

2. Deploy the Streamlit service

• Change into the streamlit folder and deploy the service for the first time with the following command:

  cd streamlit
  fly launch

• Follow the instructions in the terminal to configure the deployment.
• After the deployment is finished, you can set the API key and the data endpoint as secrets with the following command:

  fly secrets set API_KEY=... DATA_ENDPOINT=...

• Data endpoint should be the URL of the FastAPI service, e.g. https://fastapi-1234.fly.dev.

After the deployment of both services, you can visit the Streamlit UI at the URL provided by the Streamlit service deployment.

For further deployment steps it's sufficient to run fly deploy in the respective folder of the service you want to update.

(back to top)

Technical Details

Classification

The API provides an classify endpoint that accepts images (>= 1 image) of one tracking run. During processing the request the images are stored and the insect detected in the tracking run is classified by a pretrained YOLOv5 model. The relevant code is located in prediction/yolov5 and is based on the yolo5 fork by Max Sittinger. To reduce docker image size to allow deployment with fly.io the repository has been striped of everything not necessary for the actual classification. Further information about the classification model can be found in the insect-detect documentation.

Communication between Dashboard and API Service

The dashboard queries all data via HTTP requests from the API. For statistical data (stored in the classification_data.csv) a new request is issued on each reload of the dashboard, which allows displaying new data after each reload. Images are queried on a tracking run basis (all images per tracking run together) and are cached in temporary storage, meaning that all images have to be queried anew after a redeployment. The images for a tracking run are stored in an analogous fashion to the storage on the API server in data/<date>/<tracking_run_id>.

Persistence

The current persistence for data works with a volume attached to the FastAPI server. The classification data is stored in a CSV, that gets read and written to on every request. Fly.io keeps snapshots of the last five days of the volume, which is the current backup strategy. This approach is sufficient and time-efficient for the prototype phase, but should be replaced with a more robust solution featuring a database in case of further development. To ensure data consistency with this approach we need to ensure that only one request is handled at a time. See 'Synchronicity' for more details. To manage the volume size an auto-extend strategy is used. See 'Storage space' for more details.

Synchronicity

To ensure data consistency (as explained in the Persistence section) we need to ensure that only one request is handled at a time. This is achieved by limiting the FastAPI instances to exactly one and by locking the classify endpoint to only allow one request at a time.

In the fly.toml file of the FastAPI service, the following settings are used to achieve exactly one machine running at all times:

  min_machines_running = 1
  max_machines_running = 1

To lock the classify endpoint, the classify endpoint acquires a lock before processing the request and releases it after the request is processed.

Storage space

Currently, the volume is set to 1GB and will auto-extend up until 3GB if needed (at an 80% capacity threshold). 3GB is the current limit of total free provisioned storage capacity on fly.io per organization. Depending on the expected storage requirements, this limit might need to be adjusted. As the stored images are small cropped versions of the original images, the storage requirements are expected to be low and the 1GB volume proved sufficient in our trial runs.

License

This repository is distributed under the MIT License with one exception: The subdirectory fastapi is distributed under the GPL3 License.

See the respective LICENSE.txt files for more information.

(back to top)

Contact

Development: Theresa Hradilak - theresa.hradilak@gmail.com

Content/Journalistic Inquiries: Joachim Budde - @Joachim Budde - https://www.joachimbudde.de - ich@joachimbudde.de

Project Webpage: https://waskrabbeltda.de

(back to top)

Acknowledgments

• Maximilian Sittinger for developing the insect-detect camera trap, making it available as an open-source project and documenting it extensively here, which made this project possible in the first place. And for the great support for this project.
• Davide Fiocco for the Streamlit FastAPI Model Serving template that made the setup of this project a enjoyable efficient experience.
• Othneil Drew for the actual best README template.

(back to top)

Funding

The Medieninnovationszentrum Babelsberg funded the development of this project.

(back to top)