DOCSEARCHbyAlgolia
Submit Docs

PyImageJ

repository·main·Indexed 19 days ago

https://github.com/imagej/pyimagej

A Python wrapper for ImageJ2 that enables integration between the ImageJ2 ecosystem and the Python scientific stack, including NumPy, SciPy, and xarray. It provides a gateway to ImageJ2 Java functions, convenience methods for data conversion via the ij.py module, and support for running ImageJ macros, scripts, and plugins. PyImageJ allows for flexible initialization modes (interactive, gui, or headless) and supports the use of Fiji plugins and legacy ImageJ classes.

Tokens
45.5K
Snippets
162
Records
216
Agent score
65%

What's inside pyimagej

  1. Overview of PyImageJ

    main
    PyImageJ is a Python wrapper designed to integrate ImageJ2 with the Python software ecosystem. It allows users to combine the image processing capabilities of ImageJ and ImageJ2 with powerful Python libraries such as NumPy, SciPy, scikit-image, OpenCV, ITK, and CellProfiler. It supports both the modern ImageJ2 API and the original ImageJ API and data structures.

  2. Handle Image Creation Modes in ImageJ Ops

    main

    ImageJ Ops follow three distinct execution patterns depending on how arguments are provided:

    1. Function mode (New Image): The most common mode. The operation creates and returns a new image. You do not provide an output argument.
    2. Computer mode (Pre-allocated Output): You provide a pre-allocated output image. The operation fills this existing image instead of creating a new one.
    3. Inplace mode (Direct Modification): The operation modifies the input image directly. This is rare for filters but common for mathematical operations. This is achieved by passing the same image as both input and output.

    To avoid unnecessary memory overhead, use Computer mode by providing a copy or a pre-allocated buffer if you want to preserve the original image while avoiding a new allocation.

    # Function mode: creates NEW images by default
blurred = ij.op().filter().gauss(image, sigma=2.0)

# Computer mode: fill pre-allocated output
output = image.copy()  # Or use duplicate()
ij.op().filter().gauss(output, image, sigma=2.0)  # Modifies output

  4. Understand limitations in headless environments

    main

    Running PyImageJ in a headless environment imposes several functional constraints compared to a GUI-based installation:

    • RoiManager: Functionality is limited; GUI-based operations are unavailable.
    • WindowManager: Only basic operations are supported.
    • Plugins: Interactive plugins that require user input or windows will not work.
    • Visualization: You cannot view images in real-time; all visualizations must be saved to files to be inspected later.

  6. Access NumPy-like properties on Java images

    main

    PyImageJ enhances Java images (like RandomAccessibleInterval) with NumPy-like properties, making them easier to work with in Python.

    Supported Properties:

    • image.shape: Tuple of dimensions.
    • image.dims: Tuple of axis labels (e.g., ('X', 'Y', 'Channel')).
    • image.dim_axes: Tuple of CalibratedAxis objects.
    • image.dtype: Data type.
    • image.ndim: Number of dimensions.
    • image.T or image.transpose: Transposed view.

    Supported Operations:

    • Slicing: img[0, :, :], img[10:20, 30:40], img[::2, ::2].
    • Math: img1 + img2, img1 - img2, img1 * img2, img1 / img2 (element-wise).
    # Accessing properties
print(f"Shape: {dataset.shape}")
print(f"Dims: {dataset.dims}")

# Slicing
subregion = img[10:20, 30:40]

# Math
result = img1 + img2

  7. Key differences between PyImageJ (ImageJ2) and ImageJ 1.x

    main

    When transitioning from ImageJ 1.x to PyImageJ/ImageJ2, be aware of these fundamental changes:

    • 0-based indexing: ImgLib2 uses 0-based indexing (ImageJ 1.x uses 1-based for slices).
    • New images by default: Most ops return new images rather than performing in-place operations on an ImageProcessor.
    • Immutable Views: Use Views for virtual transformations instead of mutable ImageStack objects.
    • Type-generic: Operations work across any pixel type via ImgLib2, rather than requiring specific processors (e.g., ByteProcessor).
    • Shape objects: Neighborhood operations use Shape objects for kernels instead of fixed kernels.
    • No ROI Manager: Use labeling and segmentation operations instead of the legacy ROI Manager workflow.

  8. Initialize PyImageJ with different modes

    main

    When initializing PyImageJ outside of environments like Google Colab, you can control the execution mode to suit your workflow. Common modes include:

    • headless: For server-side, batch processing, or distributed environments where no GUI is required.
    • interactive: For development environments where you want to interact with the ImageJ interface.
    • gui: To launch the full ImageJ graphical user interface.

    Advanced users should also consider using specific Maven endpoints during initialization to ensure reproducible environments and control dependency resolution.

  10. Use PyImageJ convenience and addon methods

    main

    PyImageJ extends the gateway and various Java objects with Pythonic convenience methods and addons. Key functional areas include:

    • ImageJPython: Provides core convenience methods for interacting with the gateway.
    • RAIOperators: Operators for handling RandomAccessibleInterval (RAI) objects.
    • GatewayAddons: Extensions to the ImageJ2 gateway itself.
    • ImagePlusAddons: Extensions for ImagePlus objects.
    • Interval addons: Extensions for image intervals.
    • Space addons: Specialized addons for EuclideanSpace, TypedSpace, and AnnotatedSpace.

    These addons allow you to perform complex image processing and data manipulation by bridging Java and Python capabilities.

  11. Note on macOS INTERACTIVE mode

    main
    On macOS, the INTERACTIVE mode (which returns immediately after imagej.init) may not work in all scenarios. This is because the CoreFoundation/AppKit event loop must be started from the main thread, which blocks it. PyImageJ attempts to detect your environment and report if INTERACTIVE mode is unavailable.

  12. Understand ImageJ1 vs ImageJ2 image types

    main

    When working with PyImageJ, it is important to distinguish between the two primary image representations:

    1. ImageJ2 (Dataset): The modern standard used by ij.io().open().
    2. ImageJ1 (ImagePlus): The legacy format, often accessed via ij.IJ.openImage().

    Understanding which type you are working with is critical for choosing the correct processing methods and conversion workflows.