This notebook is part of the PyImageJ Tutorial Series, and assumes familiarity with the ImageJ API. Dedicated tutorials for ImageJ can be found here.

4 Converting from Java: works in reverse of and can be used to further process ImageJ data types with xarray, NumPy, scikit-image, etc.

First let’s initialize ImageJ and open an image from a URL with ImageJ and convert it into Python object. In thise case an xarray.DataArray.

4.1 Converting between Java and Python

Converting between Java and Python is done using the and functions. For more information about, checkout the previous notebook: 03-Sending-Data-to-Java. A table of common data types and their converted types is listed below.

Java object

Python Object
















tuple is capable of converting common Java/ImageJ/ImageJ2 data types into their Python and NumPy equivalents.

4.2 Converting Java objects to Python

We can see how works to convert Java objects to Python. In this section we will convert a sample image from Java to Python as an example. First we need to initialize ImageJ:

import imagej

# initialize imagej
ij = imagej.init(mode='interactive')
print(f"ImageJ2 version: {ij.getVersion()}")
ImageJ2 version: 2.14.0/1.54f

Now let’s get a test image and convert it from a Java object (net.imagej.DefaultDataset) to a Python object (xarray.DataArray).

# Load the image
url_colony = ''
cell_colony =

# Send the image to Python
xr_colony =

# Display the image, cmap='gray')

print(f"cell_colony type: {type(cell_colony)}")
print(f"xr_colony type: {type(xr_colony)}")
[INFO] Populating metadata
cell_colony type: <java class 'net.imagej.DefaultDataset'>
xr_colony type: <class 'xarray.core.dataarray.DataArray'>

4.3 Special Consideration: RGB and other axis conventions

NumPy/scikitimage dimension order is reverse indexed from ImageJ. ImageJ/ImgLib2 dimension order is [X, Y, Channel, Z, Time] by default. NumPy/scikitimage preferred dimension order is [t, pln, row, col, ch] where t = Time, pln = Z, row = Y, col = X and ch = Channel. Additionally, NumPy and matplotlib have a limited understanding of dimension/axis conventions and only natively handle 3-channel RGB images as [row, col, ch] or [Y, X, Channel]. To handle this difference in dimension/axis order preference, ImageJ images that are converted to output xarray.DataArray or numpy.ndarray have their re-ordered to match the destination order preference (retaining their metadata when possible).

# load 4D test data
dataset ='sample-data/test_timeseries.tif')

# get xarray
xarr =

# print out shape and dimensions
print(f"dataset dims, shape: {dataset.dims}, {dataset.shape}")
print(f"xarr dims, shape: {xarr.dims}, {xarr.shape}")
dataset dims, shape: ('X', 'Y', 'Channel', 'Time'), (250, 250, 3, 15)
xarr dims, shape: ('t', 'row', 'col', 'ch'), (15, 250, 250, 3)

Lets look at an RGB image next:

import skimage
import numpy as np

# load the image
astro_img =

# Convert the image to a numpy array
astro_arr =

(512, 512, 3)

Note that the channel dimension comes last. The image can be plotted diretly: