PyImageJ

PyImageJ provides seamless integration between ImageJ2/ImageJ and Python, enabling developers to combine powerful ImageJ image processing capabilities with Python's scientific computing ecosystem including NumPy, SciPy, scikit-image, xarray, and matplotlib.

Package Information

• Package Name: pyimagej
• Package Type: pypi
• Language: Python
• Installation: pip install pyimagej
• Version: 1.7.0

Core Imports

import imagej

Basic Usage

import imagej
import numpy as np

# Initialize ImageJ2 with the newest available version
ij = imagej.init()

# Load an image from URL
image_url = "https://imagej.net/images/clown.png"
jimage = ij.io().open(image_url)

# Convert the image from ImageJ2 to xarray
image_xarray = ij.py.from_java(jimage)

# Display the image (backed by matplotlib)
ij.py.show(image_xarray, cmap="gray")

# Convert Python data to ImageJ2 format
numpy_array = np.random.rand(100, 100)
dataset = ij.py.to_dataset(numpy_array)

# Run ImageJ2 operations
result = ij.op().filter().gauss(dataset, 2.0)

# Convert back to Python
result_array = ij.py.from_java(result)

Architecture

PyImageJ operates through a gateway architecture that provides:

• ImageJ2 Gateway: Central access point to ImageJ2 services and API
• JPype Bridge: Low-level Java-Python interoperability via JVM
• ScyJava Layer: High-level Java object conversion and management
• Conversion System: Bidirectional translation between Python and Java data structures
• Legacy Support: Optional compatibility with original ImageJ (ij.*) API

The system maintains two primary data flow paths:

• Java → Python: ImageJ2/ImgLib2 objects converted to NumPy arrays and xarray DataArrays
• Python → Java: NumPy arrays and xarray DataArrays converted to ImageJ2 Datasets and ImgLib2 structures

Capabilities

ImageJ2 Gateway Initialization

Core functionality for initializing and configuring the ImageJ2 environment with various modes and settings. Supports local installations, specific versions, or automatic downloads.

def init(
    ij_dir_or_version_or_endpoint=None,
    mode: Union[Mode, str] = Mode.HEADLESS,
    add_legacy: bool = True,
    headless=None
) -> "ImageJ2Gateway": ...

class Mode(Enum):
    GUI = "gui"
    HEADLESS = "headless" 
    INTERACTIVE = "interactive"

def when_imagej_starts(f) -> None: ...

Gateway Initialization

Data Conversion & Translation

Comprehensive conversion system for translating data between Python (NumPy, xarray, pandas) and Java (ImageJ2, ImgLib2, ImagePlus) formats with full metadata preservation.

# Core conversion methods (via ij.py.*)
def from_java(data): ...
def to_java(data, **hints): ...
def to_dataset(data, dim_order=None) -> "Dataset": ...
def to_img(data, dim_order=None) -> "Img": ...
def to_imageplus(data) -> "ImagePlus": ...
def to_xarray(data, dim_order=None) -> xr.DataArray: ...

# Type and format checking
def dtype(image_or_type): ...

Data Conversion

Image Processing Operations

Access to ImageJ2's extensive image processing capabilities through Python-friendly interfaces, including filters, mathematical operations, and analysis functions.

# Mathematical operations (on RandomAccessibleInterval objects)
def __add__(self, other): ...
def __sub__(self, other): ...
def __mul__(self, other): ...
def __truediv__(self, other): ...

# Array-like operations
def __getitem__(self, key): ...
def squeeze(axis=None): ...
def transpose() -> "RandomAccessibleInterval": ...

Image Processing

Script & Plugin Execution

Execute ImageJ macros, plugins, and scripts in various languages with argument passing and result retrieval capabilities.

def run_macro(macro: str, args=None): ...
def run_plugin(plugin: str, args=None, ij1_style: bool = True, imp=None): ...
def run_script(language: str, script: str, args=None): ...
def argstring(args, ij1_style=True): ...
def jargs(*args): ...

Script Execution

Image Display & Visualization

Display and visualization functions with matplotlib backend support for showing images, managing windows, and synchronizing data between ImageJ and Python.

def show(image, cmap=None): ...
def sync_image(imp=None): ...
def active_dataset() -> "Dataset": ...
def active_imageplus(sync: bool = True) -> "ImagePlus": ...
def active_xarray(sync=True) -> xr.DataArray: ...

Display & Visualization

Environment & Diagnostics

Tools for environment configuration, troubleshooting, and system health checks to ensure proper PyImageJ operation.

def checkup(output=print): ...
def debug_to_stderr(): ...

Environment & Diagnostics