tessl/pypi-pyimagej

Python wrapper for ImageJ2 that provides seamless integration between ImageJ and Python scientific computing ecosystems

—

Pending

Overview

Eval results

Files

Gateway Initialization

Name: tessl/pypi-pyimagej
Author: tessl

Core functionality for initializing and configuring the ImageJ2 environment. The gateway serves as the primary interface to ImageJ2 services and provides access to all ImageJ functionality from Python.

Capabilities

ImageJ2 Gateway Creation

Initialize ImageJ2 environment with configurable options for deployment scenarios.

def init(
    ij_dir_or_version_or_endpoint=None,
    mode: Union[Mode, str] = Mode.HEADLESS,
    add_legacy: bool = True,
    headless=None
) -> "ImageJ2Gateway":
    """
    Initialize an ImageJ2 environment.
    
    Args:
        ij_dir_or_version_or_endpoint: Path to local ImageJ2 installation, 
            version string (e.g. "2.3.0"), endpoint (e.g. "sc.fiji:fiji"), 
            or list of Maven artifacts. Default uses latest ImageJ2.
        mode: Environment behavior mode - HEADLESS, GUI, or INTERACTIVE
        add_legacy: Whether to include original ImageJ (ij.*) support
        headless: Deprecated - use mode parameter instead
        
    Returns:
        ImageJ2 gateway instance providing access to all ImageJ functionality
    """

Usage Examples:

# Use latest ImageJ2 in headless mode (default)
ij = imagej.init()

# Use specific version
ij = imagej.init("2.3.0")

# Use Fiji distribution
ij = imagej.init("sc.fiji:fiji")

# Use local installation
ij = imagej.init("/Applications/Fiji.app")

# Initialize with GUI mode
ij = imagej.init(mode=imagej.Mode.GUI)

# Use custom Maven artifacts
ij = imagej.init([
    "net.imagej:imagej:2.3.0",
    "net.imagej:imagej-legacy",
    "net.preibisch:BigStitcher"
])

Environment Modes

Control how ImageJ2 operates in different deployment scenarios.

class Mode(Enum):
    """ImageJ2 environment execution modes."""
    GUI = "gui"           # Start with GUI, display automatically, blocks execution
    HEADLESS = "headless" # No GUI, suitable for server/library usage  
    INTERACTIVE = "interactive" # GUI support available but not displayed automatically
    
    def __eq__(self, other): ...

Mode Characteristics:

HEADLESS: Default mode, suitable for library usage and server deployments
GUI: Shows ImageJ GUI automatically, blocks Python execution, terminates Python when ImageJ closes
INTERACTIVE: GUI available via ij.ui().showUI(), works in Jupyter/IPython environments

Startup Callbacks

def when_imagej_starts(f) -> None:
    """
    Register a function to be called immediately after ImageJ2 starts.
    
    Args:
        f: Single-argument function that receives the ImageJ2 Gateway
    """

Usage Example:

def configure_imagej(ij):
    """Custom configuration applied after ImageJ2 starts."""
    ij.ui().showUI()
    print(f"ImageJ2 initialized with {ij.getVersion()}")

# Register callback before initialization
imagej.when_imagej_starts(configure_imagej)

# Initialize - callback will be executed
ij = imagej.init(mode=imagej.Mode.INTERACTIVE)

Command Line Interface

Entry point for launching ImageJ from command line.

def imagej_main():
    """Entry point for the 'imagej' console command."""

This function is automatically called when using the imagej command installed with the package:

# Launch ImageJ2 GUI
imagej

# Launch in headless mode  
imagej --headless

Gateway Properties

Once initialized, the ImageJ2 gateway provides access to ImageJ services:

ij.py - Python convenience methods (ImageJPython class)
ij.legacy - Original ImageJ compatibility layer
ij.op() - ImageJ2 Ops framework for image processing
ij.io() - Image I/O services
ij.ui() - User interface services
ij.convert() - Data conversion services
ij.dataset() - Dataset creation and management
ij.script() - Script execution services

Error Handling

Common initialization issues:

Missing Java: PyImageJ requires Java 8+ and will download if needed
Version conflicts: Specify exact versions to avoid Maven resolution issues
Memory constraints: Use JVM options for large image processing: scyjava.config.add_option("-Xmx8g")
Legacy conflicts: Set add_legacy=False if experiencing ImageJ 1.x compatibility issues