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 OpenJDK (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 Mambaforge.
Install PyImageJ into a new environment:
```
mamba create -n pyimagej pyimagej openjdk=8
```
This command will install PyImageJ with OpenJDK 8. If you would rather use OpenJDK 11, you can write openjdk=11 instead, or even just leave off the openjdk part altogether to get the latest version of OpenJDK. PyImageJ has been tested most thoroughly with OpenJDK 8, but it is also known to work with OpenJDK 11, and likely later OpenJDK versions as well.
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.5.0"); print(ij.getVersion())'

Should print 2.5.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=8
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=8
```
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.nih.gov/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=8 && \
    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);"