Cellpose-Gradio

In response to non-experts' struggles with Cellpose's complex process, I created this app to provide a more accessible solution.

The Cellpose-Gradio App is a modern, user-friendly interface built on the popular Cellpose library, making its powerful cell segmentation capabilities available to users without extensive technical expertise.

This app is designed for straightforward, single-image segmentation tasks, utilizing the core features of Cellpose. Additionally, it can serves as an educational tool to help users understand how to manage segmentation parameters effectively.

For more advanced control over segmentation, including human-in-the-loop training or accessing the image restoration features of the 3.0 version, please use the official Cellpose GUI.

By encapsulating the complexity of Cellpose within an intuitive Gradio app, users can easily:

• upload images.
• select from pre-trained models.
• adjust parameters to achieve high-quality cell segmentation results in just a few clicks.
• Save results to multiple file formats:
  • Segmentation masks in either .png or .npy format.
  • Outlines of segmentation masks as .png files.
  • Resulting figures displayed within the app as .png or .svg files.

Important

This app now has a colorblind-ready version.

If you are concerned about this, we welcome your feedback on our color choices. Please consider contacting us or opening an issue.

To access the colorblind version, please go to the release list and select the colorblind version of the latest release.

Table of Contents

• Requirements
• Automated Installation and Running (Recommended)
  • Windows (Initial Setup)
  • Linux and macOS (Initial Setup)
  • Run the App After the Initial Setup
• Manual Installation and Running
  • Using venv and PyPI
  • Using Conda
  • Using uv
• Acknowledgments

Requirements

Before proceeding with the installation process, please ensure that Python is installed on your system.

If Python is not already installed, please download and install it from the official Python website for your operating system.

Once Python is installed, you can proceed with the next steps in the installation process.

Important

For simplicity and ease of use, this Gradio-based app omits GPU acceleration, instead relying on CPU for all cell segmentation tasks.

If you plan to run multiple images or process very large images, you may benefit from installing the official Cellpose GUI with GPU support.

Automated Installation and Running (Recommended)

Windows (Initial Setup)

Note

First-time users, please follow these steps.

After setting it up the first time, simply run run_app.bat script to launch the app.

1. Download or clone this repository

To Download the Repository :

• Click on the <> Code button at the top of the repository page.
• Select either "Download ZIP" or "Download tar.gz" from the dropdown menu.
• Extract the downloaded file to your desired location.

to Clone the Repository :

• Open your terminal or command prompt.
• Run the following command to clone the repository:

git clone https://github.com/LSeu-Open/Cellpose_Gradio.git

2. Double-click on the setup_and_run.bat file to run the setup script.

3. Follow the on-screen prompts.

The script will perform the following actions:

• Check for Python Installation: Verify if Python is installed on your system.
• Create a New Environment: Set up a new virtual environment to isolate dependencies.
• Install Dependencies: Install all necessary packages and libraries required for the project. This process may take some time, depending on your computer's specifications.
• Launch the Cellpose Gradio App: Start the Cellpose application using Gradio

4. Open the app

Open your web browser and navigate to the URL displayed in the terminal (typically http://127.0.0.1:7860). Alternatively, you can simply click the URL in the terminal while holding down the Ctrl key.

Linux and macOS (Initial Setup)

Note

First-time users, please follow these steps.

After setting it up the first time, simply run run_app.sh script to launch the app.

1. Download or clone this repository.

2. Open a terminal in the repository directory.

3. Make the setup script executable:

chmod +x setup_and_run.sh

4. Run the setup script:

./setup_and_run.sh

5. Follow the on-screen prompts. The script will:

The script will perform the following actions:

• Check for Python Installation: Verify if Python is installed on your system.
• Create a New Environment: Set up a new virtual environment to isolate dependencies.
• Install Dependencies: Install all necessary packages and libraries required for the project. This process may take some time, depending on your computer's specifications.
• Launch the Cellpose Gradio App: Start the Cellpose application using Gradio

6. Open the app

Open your web browser and navigate to the URL displayed in the terminal (typically http://127.0.0.1:7860). Alternatively, you can simply click the URL in the terminal while holding down the Ctrl key.

Run the App After the Initial Setup

After the initial setup, you can use the following scripts to run the app:

• On Windows: Double-click run_app.bat
• On Linux/macOS: Run ./run_app.sh in the terminal

These scripts will activate the environment and launch the Cellpose Gradio app without repeating the setup process.

Manual Installation and Running

Using venv and PyPI

1. Clone this repository:

   git clone https://github.com/LSeu-Open/Cellpose_Gradio.git
   cd Cellpose-Gradio

2. Create a virtual environment:

   python -m venv cellpose-gradio-env

3. Activate the virtual environment:

   • On Windows:

     cellpose-gradio-env\Scripts\activate

   • On macOS and Linux:

     source cellpose-gradio-env/bin/activate

4. Install the required packages:

   pip install -r requirements.txt

5. Run the app:

   python Cellpose_gradio.py

6. Open your web browser and go to the URL displayed in the terminal (usually http://127.0.0.1:7860).

Using Conda

Note

we will assume that you have already installed Conda. If not, please install Conda from the official website.

1. Open Anaconda Prompt (on Windows) or Terminal (on macOS/Linux).

2. Clone this repository:

   git clone https://github.com/LSeu-Open/Cellpose_Gradio.git
   cd Cellpose-Gradio

3. Create a conda environment from the environment.yml file:

   conda env create -f environment.yml

4. Activate the environment:

   conda activate cellpose-gradio

5. Run the app:

   python Cellpose_gradio.py

6. Open your web browser and go to the URL displayed in the Anaconda Prompt/Terminal (usually http://127.0.0.1:7860).

Using uv

Note

UV is a cutting-edge and extremely fast Python package and project manager, written in Rust.

We will assume that you have already installed UV. If not, please install it by following the official documentation.

1. Clone this repository:

   git clone https://github.com/LSeu-Open/Cellpose_Gradio.git
   cd Cellpose-Gradio

2. Create a virtual environment and install dependencies:

   uv venv
   uv pip install -r requirements.txt

3. Activate the virtual environment:

   • On Windows:

   .venv\Scripts\activate

   • On macOS and Linux:

   source .venv/bin/activate

4. Run the app:

   python Cellpose_gradio.py

5. Open your web browser and go to the URL displayed in the terminal (usually http://127.0.0.1:7860).

Acknowledgments

This project uses the following open-source libraries:

• Cellpose, licensed under the BSD 3-Clause License
• Gradio, licensed under the Apache License 2.0

Please see the ACKNOWLEDGMENTS and Licence files for full license texts.

• This application is based on the Cellpose library. If you find it useful in your research, please cite the following papers:

If you use Cellpose 1, 2 or 3, please cite the Cellpose 1.0 paper: Stringer, C., Wang, T., Michaelos, M., & Pachitariu, M. (2021). Cellpose: a generalist algorithm for cellular segmentation. Nature methods, 18(1), 100-106.

If you use the new image restoration models or cyto3, please also cite the Cellpose3 paper: Stringer, C. & Pachitariu, M. (2024). Cellpose3: one-click image restoration for improved segmentation. bioRxiv.

• This application is build using the Gradio Package. If you use it for your research, please consider cite this paper :

Gradio: Build Machine Learning Web Apps — in Python paper Abubakar Abid, Ali Abdalla, Ali Abid, Dawood Khan, Abdulrahman Alfozan, James Y. Zou (2019) Gradio: Hassle-Free Sharing and Testing of ML Models in the Wild. bioRxiv.