Skip to content

Latest commit

 

History

History
157 lines (102 loc) · 6.33 KB

README.md

File metadata and controls

157 lines (102 loc) · 6.33 KB
Raw

Streamlit web application for microorganism image classification (with FastAPI support)

Introduction

This project hosts a Streamlit web application designed to classify objects in images using a pre-trained model. Users can upload images, and the application will display the images along with their predicted classes, and a visual distribution of detection results.

Features:

  • Dark and light theme toggling for the application interface (preliminary version).
  • Image classification using a pretrained Pytorch model.
  • Visualization of the prediction results through an integrated Plotly graph:

Distribution of detected microorganisms

Usage

Prerequisites

Before running this application, make sure you have Docker installed on your system. If you do not have Docker, you can download it from the official Docker website.

Local Docker image build for local testing

Cloning the Repository

To clone the repository and navigate into the project directory, run:

git clone https://github.com/PlanktoScope/streamlit-classification-app-with-fastapi-support.git
cd streamlit-classification-app-with-fastapi-support

Creating a folder for pretrained models

To avoid errors later in running the docker container, please import your pretrained models (be sure to include the input image size in its name like sizexsize) and create a folder as follows:

models/<model_name>

By default, models must match Torchvision's efficientnet_v2_m architecture; to use models with a different architecture, you must specify the architecture with a TORCHVISION_MODEL_TYPE environment variable passed into the app.

Building the Docker Image

Build the Docker image using the following command (it takes a considerable time):

docker build -t <image_name>:<tag> .

Running the Docker Container

Run the Docker container with:

docker run -p 8501:8501 <image_name>:<tag>

The Streamlit app will be served on port 8501.

Accessing the application

Once the application is running, click on the link displayed in your terminal or open your web browser and navigate to:

http://localhost:8501

From there, you can use the web interface to:

  • Upload images for classification.
  • View model predictions and the distribution of detected objects.

FastAPI server for the classification of mussel and oyster larval stages

This version of the Streamlit web app contains the code for a FastAPI server hosting the model selected for the classification of mussel and oyster larvae. This model was trained on hatchery larvae images.

Starting the FastAPI Server:

  1. Navigate to the fastapi folder within the fastapi model serving version:
cd fastapi_model_serving/fastapi
  1. Run the FastAPI server:
uvicorn server:api_server --host 0.0.0.0 --port 8000

Deployment/Testing with Forklift

You can use Forklift to easily deploy the Docker container provided by this repository.

Prerequisites

You will need to have the Docker Engine installed on your computer. Installation instructions are available here.

Then, you will need to set up the forklift tool on your computer. Setup instructions are available here. Note that currently forklift is only tested for Linux computers, and that Forklift is still an experimental prototype.

First-time deployment

You can clone, stage, and apply the latest commit of this Forklift pallet to your computer, by using the forklift tool:

sudo -E forklift pallet switch --apply github.com/PlanktoScope/streamlit-classification-app@main

Warning: this will replace all Docker containers on your Docker host with the package deployments specified by this pallet and delete any Docker containers not specified by this pallet's package deployments.

If your user is in the docker group (so that you don't need to use sudo when running docker commands), then you don't need to use sudo with forklift:

forklift pallet switch --apply github.com/PlanktoScope/streamlit-classification-app@main

When this pallet is updated on GitHub and you want to apply the latest changes on your computer, you can use the same command as above (either forklift pallet switch --apply github.com/PlanktoScope/streamlit-classification-app@main or that command with sudo -E) to clone, stage, and apply the updated version of the pallet.

Subsequent deployment

Because the forklift tool uses Docker Compose to manage the Docker containers specified by this pallet, the containers will not be running after you restart your computer (this is true each time you restart your computer); you will need to run a command to start the containers again:

sudo -E forklift stage apply

Or if your user is in the docker group:

forklift stage apply

Operation

After you have applied the pallet so that the streamlit demo app's container is running, you can access the streamlit demo app from your web browser at http://localhost/ps/streamlit-demo.

Before you can use the demo app, you will need to download a classification model weights file (e.g. https://github.com/PlanktoScope/streamlit-classification-app/releases/download/models%2Fdemo-1/effv2s_no_norm_DA+sh_20patience_256x256_50ep_loss.pth) into ~/.local/share/planktoscope/models; by default the model weights file must be for the efficientnet_v2_s model architecture, but you can use the efficientnet_v2_m model architecture instead by disabling the torchvision-model-efficientnet-v2-s feature flag of the pallet's apps/ps/streamlit-demo package deployment.

Then you can upload input images (e.g. https://github.com/PlanktoScope/streamlit-classification-app/releases/download/models%2Fdemo-1/example-input-tots-ps-acq-20-02_49_37_288982.jpg) to the demo app.

License

This project is licensed under the Apache-2.0.

Copyright Wassim Chakroun and PlanktoScope project contributors.