DeepImageJ is a user-friendly plugin that enables the use of a variety of pre-trained deep learning models in ImageJ. The plugin bridges the gap between deep learning and standard life-science applications. DeepImageJ runs image-to-image operations on a standard CPU-based computer or on a GPU, and does not require any deep learning expertise.
Start using it with the guidelines in the Wiki.
Find further information about DeepImageJ environment at https://deepimagej.github.io
Run these examples in Fiji's macro editor (Plugins > New > Macro), or save them as .ijm files and use Plugins > Macros > Run. Replace the example paths with your own. Use forward slashes in paths on all operating systems, including Windows (C:/data/cells.tif), and surround option values containing spaces with square brackets.
To record a command, open Plugins > Macros > Record, configure the DeepImageJ dialog, and click Run. Use the recorded command that includes the model and other options; the initial command without options does not run a model.
For a BioImage.IO model, model_path accepts a model directory or a model nickname. The command uses the active image when input_path is omitted. To process a file or a folder of images and save the results:
run("DeepImageJ Run", "model_path=[/path/to/model] input_path=[/path/to/images] output_folder=[/path/to/results] display_output=all");
model_path is required. input_path, output_folder, and display_output are optional; display_output=all displays the results. Stack and channel support depend on the selected model.
DeepImageJ Cellpose processes the active image and displays <input>_labels.tif. Background is 0; positive integer labels identify objects. Dependencies and missing pretrained weights are installed on the first run, which needs internet access. The image, selected pixels, model, and parameters are captured when Run is clicked, so switching images during installation does not change the job.
| Option | Meaning |
|---|---|
model (required) |
cyto, cyto2, cyto3, nuclei, or the path to a custom weights file. |
cyto_channel (required) |
One-based source channel number (1, 2, 3, 4, ...), or red, green, blue for an RGB/three-channel image. gray selects a single-channel image. |
nuclei_channel |
Supporting nuclei channel, using the same numbers or RGB names. none or 0 disables it; omitting this option defaults to none. |
diameter |
Object diameter in pixels, for example 30. Omit to use JDLL's estimation/default behaviour; 0 can also be passed explicitly to Cellpose. |
display_all |
true displays flows and the restored image as well as labels; the default is false. |
Channel numbers refer to the input image. The GUI labels are Cytoplasm channel and Nuclei channel. RGB/three-channel inputs show colour names only (red, green, blue); grayscale inputs show only Gray in both selectors, with no supporting nuclei channel internally. Inputs with two or more than three channels show Channel 1, Channel 2, and so on. None is also available for nuclei on multichannel inputs. Valid selections are preserved when image focus changes. Colour names use red=1, green=2, blue=3; displayed LUT colours do not change this channel order. Numeric macro selections remain available for any channel count. Inputs with two, five, or any other number of channels are supported; DeepImageJ extracts the selected channels before inference. Flow and restored-image channels therefore describe the selected signals, not all source channels.
Grayscale image, without a supporting nuclei channel:
open("/path/to/cells.tif");
run("DeepImageJ Cellpose", "model=cyto3 cyto_channel=1 nuclei_channel=none diameter=30 display_all=false");
RGB image with green cytoplasm and blue nuclei:
open("/path/to/rgb-cells.png");
run("DeepImageJ Cellpose", "model=cyto3 cyto_channel=green nuclei_channel=blue diameter=30 display_all=false");
Two-channel image with cytoplasm in channel 1 and nuclei in channel 2:
open("/path/to/two-channel-cells.tif");
run("DeepImageJ Cellpose", "model=cyto3 cyto_channel=1 nuclei_channel=2 diameter=30");
Five-channel image, selecting channel 4 for segmentation and channel 2 for nuclei:
open("/path/to/five-channel-cells.tif");
run("DeepImageJ Cellpose", "model=cyto3 cyto_channel=4 nuclei_channel=2 diameter=30");
The old cyto_color and nuclei_color options remain aliases. Legacy cyto_color=gray nuclei_color=gray selects a grayscale image without a supporting nuclei channel. Supplying conflicting old and new options is an error. The previous green/blue mapping was reversed: update macros that deliberately swapped these colours to compensate. Recorded commands preserve colour names for RGB/three-channel inputs and gray for grayscale inputs; other multichannel inputs use channel numbers.
For custom weights, replace model=cyto3 with, for example, model=[C:/models/my-cellpose-weights].
DeepImageJ StarDist processes the active image and displays an instance mask named <input>_mask.tif. The pretrained fluorescence model expects one channel; the H&E model expects three channels. Dependencies and missing pretrained models are downloaded on the first run.
| Option | Meaning |
|---|---|
model (required) |
StarDist Fluorescence Nuclei Segmentation, StarDist H&E Nuclei Segmentation, or the path to a custom StarDist model directory. |
prob_thresh |
Detection probability threshold; the macro default is 0.5. |
min_percentile |
Lower intensity normalization percentile; use an explicit value such as 1. |
max_percentile |
Upper intensity normalization percentile; use an explicit value such as 99.8. |
Set both percentile options explicitly, with min_percentile < max_percentile: the current macro parser defaults both to 0.5, unlike the Java API's 1 and 99.8 defaults.
Fluorescence image:
open("/path/to/nuclei.tif");
run("DeepImageJ StarDist", "model=[StarDist Fluorescence Nuclei Segmentation] prob_thresh=0.5 min_percentile=1 max_percentile=99.8");
RGB H&E image:
open("/path/to/he-image.tif");
run("DeepImageJ StarDist", "model=[StarDist H&E Nuclei Segmentation] prob_thresh=0.5 min_percentile=1 max_percentile=99.8");
For a custom model, use a directory containing its configuration and weights, for example model=[C:/models/my-stardist-model].
With the 2D models above, a Z stack with one time point is segmented slice by slice, and a time series with one Z plane is segmented frame by frame. The results form an output stack, which may use ImageJ's T dimension even when the input uses Z. Object labels are assigned independently in each plane; they do not identify or track an object across planes.
Cellpose on a grayscale Z stack:
open("/path/to/cells-z-stack.tif");
run("DeepImageJ Cellpose", "model=cyto3 cyto_channel=1 nuclei_channel=none diameter=30 display_all=false");
StarDist on a fluorescence time series (one Z plane per frame):
open("/path/to/nuclei-time-series.tif");
run("DeepImageJ StarDist", "model=[StarDist Fluorescence Nuclei Segmentation] prob_thresh=0.5 min_percentile=1 max_percentile=99.8");
Cellpose processes every Z/time pair and returns a stack with Z changing fastest within each time point. For StarDist on a hyperstack containing both Z slices and time frames, the current 2D wrapper processes only the first Z plane when several frames are present. Use the following loop to process every Z/time pair and save one mask per plane. It preserves all channels when duplicating a plane and waits for the result window before saving it.
open("/path/to/nuclei-zt-hyperstack.tif");
input = getImageID();
getDimensions(width, height, channels, slices, frames);
outputDir = getDirectory("Choose output folder");
prefix = "plane-" + getTime();
command = "DeepImageJ StarDist";
options = "model=[StarDist Fluorescence Nuclei Segmentation] prob_thresh=0.5 min_percentile=1 max_percentile=99.8";
suffix = "_mask.tif";
for (t = 1; t <= frames; t++) {
for (z = 1; z <= slices; z++) {
selectImage(input);
planeTitle = prefix + "-z" + z + "-t" + t;
run("Duplicate...", "title=[" + planeTitle + "] duplicate channels=1-" + channels + " slices=" + z + " frames=" + t);
plane = getImageID();
run(command, options);
resultTitle = planeTitle + suffix;
while (!isOpen(resultTitle)) wait(50);
selectWindow(resultTitle);
saveAs("Tiff", outputDir + resultTitle);
close();
selectImage(plane);
close();
}
}
selectImage(input);
For Cellpose on a grayscale Z/time hyperstack, replace the three configuration lines with:
command = "DeepImageJ Cellpose";
options = "model=cyto3 cyto_channel=1 nuclei_channel=none diameter=30 display_all=false";
suffix = "_labels.tif";
These examples use the current macro parsers and stack handling in Cellpose_DeepImageJ.java and Stardist_DeepImageJ.java. See the ImageJ macro functions reference for image selection, dimensions, and saving.
The DeepImageJ project is an open source software (OSS) under the BSD 2-Clause License. All the resources provided here are freely available.
As a matter of academic integrity, we strongly encourage users to include adequate references whenever they present or publish results that are based on the resources provided here.
- If you used one of the material provided within DeepImageJ such as trained models or Python notebooks, cite their authors' work.
- E. Gómez-de-Mariscal, C. García-López-de-Haro, W. Ouyang, L. Donati, E. Lundberg, M. Unser, A. Muñoz-Barrutia, D. Sage, DeepImageJ: A user-friendly environment to run deep learning models in ImageJ, Nat Methods 18, 1192–1195 (2021).
@article{gomez2021deepimagej,
title={DeepImageJ: A user-friendly environment to run deep learning models in ImageJ},
author={G{\'o}mez-de-Mariscal, Estibaliz and Garc{\'i}a-L{\'o}pez-de-Haro, Carlos and Ouyang, Wei and Donati, Laur{\`e}ne and Lundberg, Emma and Unser, Michael and Mu{\~{n}}oz-Barrutia, Arrate and Sage, Daniel},
journal={Nature Methods},
year={2021},
volume={18},
number={10},
pages={1192-1195},
URL = {https://doi.org/10.1038/s41592-021-01262-9},
doi = {10.1038/s41592-021-01262-9}
}