Skip to content

Wrappers for external software calls (Cellpose, Elastix, Ilastix...) and java utilities (object conversions and display)

Notifications You must be signed in to change notification settings

BIOP/ijl-utilities-wrappers

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Wrappers for Fiji

This repository helps to set various tools external to the Java world:

  • Deep learning tools via conda environments:
    • cellpose, stardist(3D), deepslice
  • Direct executable programs:
    • elastix, transformix

On top of this, some converters that facilite the transmission of data to these external programs are part of this repository.

Cellpose

NOTE : up to cellpose 2.0

The Cellpose wrapper is an ImageJ2 command that enables using a working Cellpose virtual environment (either conda, or venv) from Fiji.

Briefly, Cellpose wrapper sequentially:

  • saves the current Fiji image in a temporary folder
  • starts the cellpose-env and runs Cellpose with defined parameters
  • opens the created label image in Fiji
  • cleans the temporary folder

I. Installation

You'll find here some instructions to install the Cellpose wrapper and some guidance to set up a Cellpose virtual environment.

NOTE : if you rely on conda, the Cellpose wrapper requires to enable the conda command outside of conda prompt cf installation instructions below.

I.A. Cellpose Virtual Environment

You can find instructions to install Cellpose environment on Cellpose repo

Please find below some information, provided "as is" without any warranties of successful installation, nor further support.

I.A.2. Conda installation

I.A.2.a. Windows

NOTE : if you rely on conda, the Cellpose wrapper requires to enable the conda command outside of conda prompt, cf installation instructions below : .

Enable conda command outside conda prompt

You need to follow this two steps procedure to enable Windows to use conda from cmd.exe.

  • 1-Into the environment variable , edit PATH , add path to your ..\Anaconda3\condabin default would be C:\ProgramData\Anaconda3\condabin
  • 2-Open a new PowerShell (and/or PowerShell (x86) ), run the following command once to initialize conda: conda init

From now on you don't need to run a conda prompt you can simply activate a conda env from cmd.exe .

To check if it works, you can:

  • 1.Press windows key, type cmd.exe (to get a command prompt)
  • 2.Type conda env list You should get the list of your conda envs.
Conda cellpose-GPU

A successful GPU installation was possible with Win10 & NVIDIA GeForce RTX 2080 Ti, following the detailed installation procedure described for venv following installation of drivers, VisualStudio, CUDA Toolkit, CuDDN before using Anaconda and the yml file below:

CUDA Toolkit cuDNN pytorch cellpose yml
CUDA Toolkit installer 10.1 (§) 7.6.0 x 0.6 cellpose_biop_gpu.yml file (§§)
CUDA Toolkit installer 11.3 8.2.1 x 0.6 cellpose06_biop_gpu_113-821.yml file
CUDA Toolkit installer 11.3 8.2.1 x 0.7 cellpose07_biop_gpu_113-821.yml file
CUDA Toolkit installer 11.3 8.2.1 1.12.0 2.2.1 cellpose221_biop_gpu_ctk113-cdn821-pyt112.yml file

NOTE if you experience "tensors error" Current fix (from cellpose issue) is :

  • locate dynamics.py
  • in line 104 replace :
    • meds = torch.from_numpy(centers.astype(int)).to(device)
    • by
    • meds = torch.from_numpy(centers.astype(int)).to(torch.long).to(device)

(§): nvcc is required for the installation procedure and "the cudatoolkit packages available via Conda do not include [it]" ( more about this issue here). To check nvcc status, you can (in a command prompt) type nvcc- V, you should get something close to :

nvcc: NVIDIA (R) Cuda compiler driver

Copyright (c) 2005-2019 NVIDIA Corporation

Built on Sun_Jul_28_19:12:52_Pacific_Daylight_Time_2019

Cuda compilation tools, release 10.1, V10.1.243

(§§) : a yml file subtlety I learnt on this journey, you can enforce a certain channel_name::package_name

I.A.2.b. Mac

You can find instructions to install Cellpose environment on Cellpose repo which work just fine for CPU ONLY.

Briefly , using the lines below:

conda create -n cellpose

conda activate cellpose

pip install cellpose

would do the job to have a working cellpose env (in CPU mode)!

I.A.2.c. Linux

Installation following Mac instructions worked for a couple of testers (no support)

I.B. Fiji - Cellpose wrapper

NOTE The Fiji - Cellpose wrapper is useless without a working Cellpose environment, please see installation above. To test if you have a working Cellpose environment: 1 - Activate your environment 2 - Type python -m cellpose --help You should not get an error.

  • Please activate our update site ( PTBIOP | https://biop.epfl.ch/Fiji-Update/ ) , find more details here.
  • Restart Fiji
  • Execute Plugins>BIOP>Cellpose>Cellpose setup...
    • Select the path to your working Cellpose virtual environment
    • Select EnvType : conda or venv
    • Select version : 0.6 , 0.7 , 1.0 or 2.0.

NOTE : on MacOSX, for a default anaconda install and a default cellpose install path should be something like: /opt/anaconda3/envs/cellpose .

Congratulations you can now use Cellpose on your first image from Fiji! :)

II. Using Fiji - Cellpose wrapper

The more "flexible" command is Cellpose Advanced (own model) which offers many parameters.

BUT in case you need more parameters, this command also comes with a string field for additional parameters following pattern : --channel_axis,CHANNEL_AXIS,--dir_above

For convenience 3 more commands exist:

  • Segment Nuclei, no parameter, ideal to test on blobs
  • Segment Nuclei Advanced, some parameter available
  • Cellpose Advanced (same parameters as command Cellpose Advanced (own model) without possibility to select your own model)

NOTE We recommend users to prepare in Fiji the minimal image to be processed by cellpose before using the plugin. For example, from a 4 channels image (with nuclei, membrane , proteinX, ... stainings) extract the membrane and nuclei channel, make a composite image and run cellpose command on it.

For more info about parameters please refer to cellpose.readthedocs.io

StarDist

The StarDist3D wrapper is an ImageJ2 command that enables using a working StarDist virtual environment (either conda, or venv) from Fiji.

Briefly, StarDist3D wrapper sequentially:

  • saves the current Fiji image in a temporary folder
  • starts the stardist-env and runs stardist with defined parameters
  • opens the created label image in Fiji
  • cleans the temporary folder

BIOP StarDist3D model(s) (and training dataset) can be found on the zenodo repository

I. Installation

You can have a look to the StarDist installation, but for now it works from a branch of the project (@Scripts). Recommended way is to use yml file you can find below (or in /resources).

I.A. StarDist Virtual Environment

Please find below some information, provided "as is" without any warranties of successful installation, nor further support.

I.A.1. More on venv installation

Please find here a very detailed installation procedure with venv.

I.A.2. More on conda installation

I.A.2.a. Windows

NOTE : if you rely on conda, the StarDist3d wrapper requires to enable the conda command outside of conda prompt, cf installation instructions below : .

Enable conda command outside conda prompt

You need to follow this two steps procedure to enable Windows to use conda from cmd.exe.

  • 1-Into the environment variable , edit PATH , add path to your ..\Anaconda3\condabin default would be C:\ProgramData\Anaconda3\condabin
  • 2-Open a new PowerShell (and/or PowerShell (x86) ), run the following command once to initialize conda: conda init

From now on you don't need to run a conda prompt you can simply activate a conda env from cmd.exe .

To check if it works, you can:

  • 1.Press windows key, type cmd.exe (to get a command promt)
  • 2.Type conda env list You should get the list of your conda envs.
Conda StarDist-GPU
CUDA Toolkit cuDNN Tensorflow stardist / branch yml
CUDA Toolkit installer 10.0 ($) 7.6.5 ($) 1.15 ($) 0.7.3 / @Scripts stardist_scripts.yml file ($)
CUDA Toolkit installer 10.0 ($) 7.6.5 ($) 1.15 ($) 0.8.3 stardist0.8_TF1.15.yml file ($)

($) This combination CUDA Toolkit and CuDNN are required to work with Tensorflow 1.15 (lastest available on Fiji) to train model for StarDist2D. Other combinations might work but were not tested (yet).

I.A.2.b. MAC OSX

The following procedure was validated on a Mac mini, M1 Chip 8-core CPU + 8-core GPU, 256GB SSD, 8GB Ram for CPU ONLY install.

First create a conda env in python 3.7 (otherwise I got issue with tensorflow)

conda create -n stardist_py37 python=3.7

Then activate the conda env

conda activate stardist_py37

Install tensorflow

conda install tensorflow

Install Stardist:

pip install stardist==0.8.3

Finally, I ran into an issue (OMP: Error #15: Initializing libomp.dylib, but found libomp.dylib already initialized) and I was lucky enough to found a fix using :

conda install nomkl

With all that I got a running conda env capable to run stardist-predict2D or -predict3D, in CPU.

I.B. Fiji - StarDist3D wrapper

NOTE The Fiji - StarDist3D wrapper is useless without a working StarDist3D environment, please see installation abobe (I.A.). To test if you have a working StarDist3D environment: 1 - Activate your environment 2 - Type stardist-predict3d -h You should not get an error and see available parameters

NOTE : on MacOS, for a default anaconda install and a default StarDist install, the path should be something like: /opt/anaconda3/envs/stardist_py37 (following the example above).

II. Using Fiji - StarDist3D wrapper

The more "flexible" command is StarDist3D... Advanced (own model) which offers many parameters.

DeepSlice

DeepSlice is a python library which automatically aligns mouse histology with the allen brain atlas common coordinate framework.

You'll find here some instructions to install the DeepSlice wrapper and some guidance to set up a DeepSlice virtual environment.

NOTE : the DeepSlice wrapper requires to enable the conda command outside of conda prompt cf instructions.

I. Installation

The DeepSlice wrapper requires a functioning conda environment with the DeepSlice library.

I.A. Conda installation

You need to install DeepSlice in a conda env that has python 3.7 (versions above do not work). You need to create an environment and install DeepSlice with pip.

conda create -n deepslice python=3.7
conda activate deepslice
conda install pip
pip install DeepSlice==1.1.5 # pinned version for which this wrapper has been tested
pip install urllib3==1.26.6 # see https://github.com/PolarBean/DeepSlice/issues/46
I.A.2.a. Windows

NOTE : if you rely on conda, the DeepSlice wrapper requires to enable the conda command outside of conda prompt, cf installation instructions.

Enable conda command outside conda prompt

You need to follow this two steps procedure to enable Windows to use conda from cmd.exe.

  • 1-Into the environment variable , edit PATH , add path to your ..\Anaconda3\condabin default would be C:\ProgramData\Anaconda3\condabin
  • 2-Open a new PowerShell (and/or PowerShell (x86) ), run the following command once to initialize conda: conda init

From now on you don't need to run a conda prompt you can simply activate a conda env from cmd.exe .

To check if it works, you can:

  • 1.Press windows key, type cmd.exe (to get a command prompt)
  • 2.Type conda env list You should get the list of your conda envs.
I.A.2.b. Mac

Nothing particular should be needed, but it has not been tested.

I.A.2.c. Linux

Nothing particular should be needed, but it has not been tested.

II. Using Fiji - DeepSlice wrapper

This wrapper essentially enables to run DeepSlice locally from within ABBA.

You can set up the location of the environment with the command Plugins>BIOP>DeepSlice>DeepSlice setup...

Elastix and Transformix

Note : this bridge only supports 2D registrations. For 3D registrations using elastix in Fiji, please look at https://github.com/embl-cba/elastixWrapper.

Elastix is a standalone program that performs image registration. It takes two images, a fixed and a moving one and outputs a transformation file.

The transformation file can then be used by Transformix to actually transform the moving image into the coordinates of the fixed image.

To use the wrapper, first install the binaries of elastix (transformix is included) for your OS. Then, in Fiji, you can start the Set and Check Wrappers command:

Set and Check Wrappers

and set the path to the elastix and transformix executable file:

set elastix path

You can then check whether the wrapper is working by running a test groovy gist. See how it should look like in this video.

Commands

A set of commands (= Fiji plugins) can now be used to register two images with Elastix. They are listed below

Plugins>BIOP>Elastix>Register

You can select the two images to register, a fixed and a moving one, and a model, optionnally a grid size for non-rigid registration, and the command returns a deformation field ( no image transformed ).

Plugins>BIOP>Elastix>Save Registration

The deformation field can be saved as a zip file.

Plugins>BIOP>Elastix>Load Registration

The deformation field can be reopened from the zip file.

Plugins>BIOP>Elastix>Inverse registration

The inverse of a deformation field can be computed with this command. You need to specify an image, which serves as defining the points over which the inverse computation will be optimized.

Plugins>BIOP>Transformix>Transform Image

You can use this image and a transformation model to actually transform an image.

Plugins>BIOP>Transformix>Transform Rois

You can transform ROI located in the ROI Manager according to a deformation field with this plugin.

About

Wrappers for external software calls (Cellpose, Elastix, Ilastix...) and java utilities (object conversions and display)

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages