allencell-segmenter-ml

allencell-segmenter-ml

A plugin to leverage ML segmentation in napari

    Test and lint

    What is Allen Cell Segmenter ML

    A deep learning-based segmentation Napari plugin to curate datasets, train your own model (UNET), and run inference on 2D and 3D cell data.

    📰 News

    • [2024.09.24] :tada: Initial release of the plugin and Megaseg models!

    :hammer_and_wrench: Installation

    System Requirements

    We currently support Windows, MacOS, and Linux operating systems. The minimum system requirements are:

    • 8GB of RAM
    • 8 CPU Cores
    • 1 NVIDIA GPU with 8GB of VRAM (optional)

    NOTE: If you plan to use the plugin without a GPU, training will default to using your CPU and will be significantly slower. A GPU is highly recommended for training models. Depending on how large your images are---2D vs 3D, resolution, model size---running inference may also be slow without a GPU.

    Pre-Installation

    STEP 1. Install Python

    Before installing the plugin, please make sure you have the following installed:

    • Python 3.10 or later

    New to Python? We recommend installing Python 3.10 through the official Python website. This will include the pip package manager, which is required to install the plugin.

    If you are unsure if you have Python installed or which version you may have, you can check by running the following command in your terminal or powershell:

    # Check version of python
    python --version
    
    # If the above does not work, try this one
    python3 --version
    
    # Specifically check for Python 3.10
    python3.10 --version
    STEP 2. Create a Virtual Environment

    Next we will create a new Python environment to install the plugin. This will help avoid conflicts with other packages you may have installed by creating an isolated environment for the plugin to live in. In general, it is good practice to choose a name for your environment that is related to either the project you are working on or the software you are installing. In this case, we use venv-allen-segmenter-ml where venv stands for virtual environment.

    Navigate to where you want to create a new environment (Example. Documents), run the following command in your terminal or powershell:

    # Create a new environment
    python3.10 -m venv venv-allen-segmenter-ml
    
    # Activate the environment
    source venv-allen-segmenter-ml/bin/activate

    Confirm Virtual Environment is Activated

    To confirm that the virtual environment has been successfully activated, you can follow these steps:

    1. Check that the prompt includes the name of your virtual environment, venv-allen-segmenter-ml. It should look something like this:

      (venv-allen-segmenter-ml) $
      
      # Example on a Windows machine
      (venv-allen-segmenter-ml) PS C:\Users\Administrator\Documents> 
    2. Run the following command to verify Python 3.10 is being used within the virtual environment:

      python --version
      
      # Python 3.10.11   <-- Example output

    Install the Plugin

    To install the latest version of the plugin:

    pip install allencell-segmenter-ml

    :rotating_light: Post-Installation :rotating_light:

    :memo: NOTE: This section is specifically for users with at least one NVIDIA GPU installed on their machine. Not sure if you have an NVIDIA GPU? You can check by running nvidia-smi as shown below. If you do not have an NVIDIA GPU system, you can skip this section.

    Required Package

    After installing the plugin, you need to install a PyTorch version that is compatible with your system. PyTorch is a deep learning library that is used to train and run the models in the plugin. We understand that everyone manages CUDA drivers and PyTorch versions differently depending on their system and use cases, and we want to respect those decisions because CUDA drivers can be a pain.

    STEP 1. Checking CUDA Version

    To check your CUDA version, you can run the following command in your terminal or powershell:

    nvidia-smi

    As an example, the output will look similar to this. My CUDA Version is 11.8:

    PS C:\Users\Administrator> nvidia-smi
    Fri Sep 13 03:22:15 2024
    +-----------------------------------------------------------------------------+
    | NVIDIA-SMI 522.06       Driver Version: 522.06       CUDA Version: 11.8     |
    |-------------------------------+----------------------+----------------------+
    | GPU  Name            TCC/WDDM | Bus-Id        Disp.A | Volatile Uncorr. ECC |
    | Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
    |                               |                      |               MIG M. |
    |===============================+======================+======================|
    |   0  Tesla T4           TCC   | 00000000:00:1E.0 Off |                    0 |
    | N/A   27C    P8     9W /  70W |      0MiB / 15360MiB |      0%      Default |
    |                               |                      |                  N/A |
    +-------------------------------+----------------------+----------------------+
    
    +-----------------------------------------------------------------------------+
    | Processes:                                                                  |
    |  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
    |        ID   ID                                                   Usage      |
    |=============================================================================|
    |  No running processes found                                                 |
    +-----------------------------------------------------------------------------+

    STEP 2. PyTorch Installation

    To Install PyTorch, please visit the PyTorch website and select the appropriate installation options for your system. An example is provided below.

    torch-install

    PyTorch Installation for Windows, MacOS, and Linux

    Example

    For instance, if I am using

    • Windows workstation
    • pip package manager
    • Python (3.10)
    • CUDA 11.8

    Then the command for me would be:

    pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

    If the installation is successful, let's test just to be sure that your GPU is detected by PyTorch. Run the following command in your terminal or powershell:

    python -c "import torch; print(torch.cuda.is_available())"

    You should see True if your GPU is detected (see below). If you see False, then PyTorch is not detecting your GPU. You may need to reinstall PyTorch or check your CUDA drivers. Double check that your virtual environement is activated (venv-allen-segmenter-ml).

    (venv-allen-segmenter-ml) PS C:\Users\Administrator\Documents> python -c "import torch; print(torch.cuda.is_available())"
    True

    :tada: You have successfully installed the plugin and PyTorch. You are now ready to use the plugin!


    Running the Plugin

    To run the plugin (and verify the installation), you can use the following command in your terminal or powershell:

    napari

    You should see the below window pop up. To start using the plugin, click on the Plugins tab and select Allen Cell Segmenter ML:

    plugin

    Allen Cell Segmenter ML Launching the Plugin.

    Models

    ModelModel NameAvailable in PluginModel Size (MB)Supported Magnifications
    MegaSeg-Smegaseg_light4.8MB100X
    MegaSeg-Mmegaseg_mediumComing soon!TBDTBD
    MegaSeg-Lmegaseg_large191MB20X, 40X, 67X, 100X

    Download and using the Megaseg Models

    To use the MegaSeg models in the plugin, you can download them from the dropdown menu shown below:

    download-model

    Download the MegaSeg Model for use in the Plugin

    A popup window will appear and you can select which model you would like to download. Once the download is complete, another popup will let you know the download was successful and where the model was downloaded.

    select-megaseg

    Select the MegaSeg model to Run Inference

    To use the model for inference on your images, choose Select an existing model, select the megaseg model you downloaded, and click Apply. You can now use the model to segment your images!

    License

    Distributed under the terms of the Allen Institute Software License license.

    Issues

    If you encounter any problems, please file an issue along with a detailed description.

    Version:

    • 0.1.16rc1

    Last updated:

    • 24 September 2024

    First released:

    • 20 September 2024

    License:

    • Allen Institute Software License – This software license is the 2-clause BSD license plus clause a third clause that prohibits redistribution for commercial purposes without further permission. Copyright © 2024. Allen Institute. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Redistributions for commercial purposes are not permitted without the Allen Institute’s written permission. For purposes of this license, commercial purposes is the incorporation of the Allen Institute's software into anything for which you will charge fees or other compensation. Contact terms@alleninstitute.org for commercial licensing opportunities. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    Supported data:

    • Information not submitted

    Plugin type:

    GitHub activity:

    • Stars: 1
    • Forks: 0
    • Issues + PRs: 136

    Python versions supported:

    Operating system:

    Requirements:

    • napari>=0.4.18
    • npe2>=0.6.2
    • numpy
    • hydra-core==1.3.2
    • bioio
    • tifffile>=2023.4.12
    • watchdog
    • cyto-dl==0.1.8
    • scikit-image!=0.23.0