Image Processor

This module contains the ImageProcessor class for handling image normalization, filtering, and compositing.

Important

For a comprehensive guide to all image processing operations, including:

  • Detailed explanations of each operation

  • Examples of how to use operations in pipelines

  • Common use cases and best practices

  • Function handling patterns

See image_processing_operations.

The documentation below provides the API reference for the ImageProcessor class, while image_processing_operations provides more user-friendly documentation focused on practical usage.

ImageProcessor

class ezstitcher.core.image_processor.ImageProcessor

Handles image normalization, filtering, and compositing. All methods are static and do not require an instance.

static preprocess(image, channel, preprocessing_funcs=None)

Apply preprocessing to a single image for a given channel.

Parameters:

  • image (numpy.ndarray) – Input image

  • channel (str) – Channel identifier

  • preprocessing_funcs (dict, optional) – Dictionary mapping channels to preprocessing functions

Returns:

Processed image

Return type:

numpy.ndarray

static blur(image, sigma=1)

Apply Gaussian blur to an image.

Parameters:

  • image (numpy.ndarray) – Input image

  • sigma (float) – Standard deviation for Gaussian kernel

Returns:

Blurred image

Return type:

numpy.ndarray

static sharpen(image, radius=1, amount=1.0)

Sharpen an image using unsharp masking.

Parameters:

  • image (numpy.ndarray) – Input image

  • radius (float) – Radius of Gaussian blur

  • amount (float) – Sharpening strength

Returns:

Sharpened image

Return type:

numpy.ndarray

static normalize(image, target_min=0, target_max=65535)

Normalize image to specified range.

Parameters:

  • image (numpy.ndarray) – Input image

  • target_min (int) – Target minimum value

  • target_max (int) – Target maximum value

Returns:

Normalized image

Return type:

numpy.ndarray

static percentile_normalize(image, low_percentile=1, high_percentile=99, target_min=0, target_max=65535)

Normalize image using percentile-based contrast stretching.

Parameters:

  • image (numpy.ndarray) – Input image

  • low_percentile (float) – Lower percentile (0-100)

  • high_percentile (float) – Upper percentile (0-100)

  • target_min (int) – Target minimum value

  • target_max (int) – Target maximum value

Returns:

Normalized image

Return type:

numpy.ndarray

static stack_percentile_normalize(stack, low_percentile=1, high_percentile=99, target_min=0, target_max=65535)

Normalize a stack of images using global percentile-based contrast stretching. This ensures consistent normalization across all images in the stack.

For examples and common use cases, see operation-normalize in image_processing_operations.

Parameters:

  • stack (list or numpy.ndarray) – Stack of images

  • low_percentile (float) – Lower percentile (0-100)

  • high_percentile (float) – Upper percentile (0-100)

  • target_min (int) – Target minimum value

  • target_max (int) – Target maximum value

Returns:

Normalized stack of images

Return type:

numpy.ndarray

static create_composite(images, weights=None)

Create a grayscale composite image from multiple channels.

Parameters:

  • images (dict or list) – Dictionary mapping channel names to images or list of images

  • weights (dict or list, optional) – Optional dictionary with weights for each channel or list of weights

Returns:

Grayscale composite image (16-bit)

Return type:

numpy.ndarray

static apply_mask(image, mask)

Apply a mask to an image.

Parameters:
Returns:

Masked image

Return type:

numpy.ndarray

static create_weight_mask(shape, margin_ratio=0.1)

Create a weight mask for blending images.

Parameters:

  • shape (tuple) – Shape of the mask (height, width)

  • margin_ratio (float) – Ratio of image size to use as margin

Returns:

Weight mask

Return type:

numpy.ndarray

static max_projection(stack)

Create a maximum intensity projection from a Z-stack.

Parameters:

stack (list or numpy.ndarray) – Stack of images

Returns:

Maximum intensity projection

Return type:

numpy.ndarray

static mean_projection(stack)

Create a mean intensity projection from a Z-stack.

Parameters:

stack (list or numpy.ndarray) – Stack of images

Returns:

Mean intensity projection

Return type:

numpy.ndarray

static stack_equalize_histogram(stack, bins=65536, range_min=0, range_max=65535)

Apply true histogram equalization to an entire stack of images. This ensures consistent contrast enhancement across all images in the stack.

Parameters:

  • stack (list or numpy.ndarray) – Stack of images

  • bins (int) – Number of bins for histogram computation

  • range_min (int) – Minimum value for histogram range

  • range_max (int) – Maximum value for histogram range

Returns:

Histogram-equalized stack of images

Return type:

numpy.ndarray

static create_projection(stack, method='max_projection', focus_analyzer=None)

Create a projection from a stack using the specified method.

Parameters:

  • stack (list) – List of images

  • method (str) – Projection method (max_projection, mean_projection, best_focus)

  • focus_analyzer (FocusAnalyzer, optional) – Focus analyzer for best_focus method

Returns:

Projected image

Return type:

numpy.ndarray

static tophat(image, selem_radius=50, downsample_factor=4)

Apply white top-hat transform to an image.

Parameters:

  • image (numpy.ndarray) – Input image

  • selem_radius (int) – Radius of structuring element

  • downsample_factor (int) – Factor to downsample image for faster processing

Returns:

Top-hat transformed image

Return type:

numpy.ndarray