Installation

There are two supported ways to install PyImageJ: via conda/mamba or via pip. Although both tools are great for different reasons, if you have no strong preference then we suggest using mamba because it will manage PyImageJ’s non-Python dependencies: Java (a.k.a. Java) and Maven. If you use pip, you will need to install those two things separately.

Installing via conda/mamba

Note: We strongly recommend using Mamba rather than plain Conda, because Conda is unfortunately terribly slow at configuring environments.

Install Miniforge3. OR: If you already have mamba installed, activate conda-forge:

conda config --add channels conda-forge
conda config --set channel_priority strict

Install PyImageJ into a new environment:
```
mamba create -n pyimagej pyimagej openjdk=11
```
This command will install PyImageJ with OpenJDK 11. PyImageJ requires a minimum of OpenJDK 8. PyImageJ has been tested most thoroughly with OpenJDKs 8 and 11, but it is likely to work with later OpenJDK versions as well.

Please note that openjdk=8 from conda-forge is broken on M1 Mac. If you are using an M1 Mac, you should use openjdk=11 or newer.
Whenever you want to use PyImageJ, activate its environment:
```
mamba activate pyimagej
```

Installing via pip

If installing via pip, we recommend using a virtualenv to avoid cluttering up or mangling your system-wide or user-wide Python environment. Alternately, you can use mamba just for its virtual environment feature (mamba create -n pyimagej python=3.8; mamba activate pyimagej) and then simply pip install everything into that active environment.

There are several ways to install things via pip, but we will not enumerate them all here; these instructions will assume you know what you are doing if you chose this route over conda/mamba above.

Install Python 3. As of this writing, PyImageJ has been tested with Python 3.6, 3.7, 3.8, 3.9, and 3.10. You might have issues with Python 3.10 on Windows.
Install OpenJDK 8 or OpenJDK 11. PyImageJ should work with whichever distribution of OpenJDK you prefer; we recommend Zulu JDK+FX 8. Another option is to install openjdk from your platform’s package manager.
Install Maven. You can either download it manually or install it via your platform’s package manager, if available there. The mvn command must be available on your system path.
Install pyimagej via pip:
```
pip install pyimagej
```

Testing your installation

Here’s one way to test that it works:

python -c 'import imagej; ij = imagej.init("2.14.0"); print(ij.getVersion())'

Should print 2.14.0 on the console.

Dynamic installation within Jupyter

It is possible to dynamically install PyImageJ from within a Jupyter notebook.

For your first cell, write:

import sys, os
!mamba install --yes --prefix {sys.prefix} pyimagej openjdk=11
os.environ['JAVA_HOME'] = os.sep.join(sys.executable.split(os.sep)[:-2] + ['jre'])

This approach is useful for JupyterHub on the cloud, e.g. Binder, to utilize PyImageJ in select notebooks without advance installation. This reduces time needed to create and launch the environment, at the expense of a longer startup time the first time a PyImageJ-enabled notebook is run. See this itkwidgets example notebook for an example.

Dynamic installation within Google Colab

It is possible to dynamically install PyImageJ on Google Colab. A major advantage of Google Colab is free GPU in the cloud.

Here is an example set of notebook cells to run PyImageJ on Google Colab with a wrapped local Fiji installation:

Install condacolab:

!pip install -q condacolab
import condacolab
condacolab.install()

Verify that the installation is functional:
```
import condacolab
condacolab.check()
```
Install PyImageJ:
```
!mamba install pyimagej openjdk=11
```
You can also install other deps here as well (scikit-image, opencv, etc).

Download and install Fiji, and optionally custom plugins as well:

!wget https://downloads.imagej.net/fiji/latest/fiji-linux64.zip > /dev/null && unzip fiji-linux64.zip > /dev/null
!rm fiji-linux64.zip
!wget  https://imagej.net/ij/plugins/download/Filter_Rank.class > /dev/null
!mv Filter_Rank.class Fiji.app/plugins

Set JAVA_HOME:
```
import os
os.environ['JAVA_HOME']='/usr/local'
```
We need to do this so that the openjdk installed by mamba gets used, since a conda env is not actually active in this scenario.

Start PyImageJ wrapping the local Fiji:

import imagej
ij = imagej.init("/content/Fiji.app")
print(ij.getVersion())

Start running plugins, even custom plugins:

imp = ij.IJ.openImage("http://imagej.net/images/blobs.gif")
ij.py.run_plugin("Filter Rank", {"window": 3, "randomise": True}, imp=imp)
ij.IJ.resetMinAndMax(imp)
ij.py.run_plugin("Enhance Contrast", {"saturated": 0.35}, imp=imp)

Install pyimagej in Docker

We leverage Micromamba-docker since conda activate will not work. Note that running Python scripts during build is extremely slow.

# Micromamba-docker @ https://github.com/mamba-org/micromamba-docker
FROM mambaorg/micromamba:1.0.0

# Retrieve dependencies
USER root
RUN apt-get update
RUN apt-get install -y wget unzip > /dev/null && rm -rf /var/lib/apt/lists/* > /dev/null
RUN micromamba install -y -n base -c conda-forge \
        python=3.8\
        pyimagej  \
        openjdk=11 && \
    micromamba clean --all --yes
ENV JAVA_HOME="/usr/local"
# Set MAMVA_DOCKERFILE_ACTIVATE (otherwise python will not be found)
ARG MAMBA_DOCKERFILE_ACTIVATE=1  
# Retrieve ImageJ and source code
RUN wget https://downloads.imagej.net/fiji/latest/fiji-linux64.zip &> /dev/null
RUN unzip fiji-linux64.zip > /dev/null
RUN rm fiji-linux64.zip
# test: note that "Filter Rank" is not added yet, below is just an example.
RUN python -c "import imagej; \
    ij = imagej.init('/tmp/Fiji.app', mode='headless'); \
    print(ij.getVersion()); \
    imp = ij.IJ.openImage('http://imagej.net/images/blobs.gif'); \
    ij.py.run_plugin('Filter Rank', {'window': 3, 'randomise': True}, imp=imp); \
    ij.IJ.resetMinAndMax(imp); \
    ij.py.run_plugin('Enhance Contrast', {'saturated': 0.35}, imp=imp);"