Image data manipulation

class pydetecdiv.domain.ImageResourceData.ImageResourceData

Bases: ABC

An abstract class to access image resources (files) on disk without having to load whole time series into memory

abstract property shape: tuple[int]

The image resource shape (should habitually be 5D with the following dimensions TCZYX)

abstract property dims: Dimensions

The image resource dimensions with their size

abstract property sizeT: int

The number of time frames

abstract property sizeC: int

The number of channels

abstract property sizeZ: int

The number of layers

abstract property sizeY

The image height

abstract property sizeX: int

the image width

compute_drift(method: str = 'phase correlation', **kwargs) → DataFrame

Compute drift along time using the specified method

Parameters:

  • method (str) – the method to compute drift

  • kwargs – keyword arguments passed to the drift computation method

Returns:

the cumulative transforms for drift correction

Return type:

pandas DataFrame

compute_drift_phase_correlation_cv2(Z: int = 0, C: int = 0, thread: QThread = None) → DataFrame | None

Compute the cumulative transforms (dx, dy) to apply in order to correct the drift using phase correlation

Parameters:

  • Z (int) – the layer index

  • C (int) – the channel index

  • max_mem (int) – maximum memory use when using memory mapped TIFF

Returns:

the cumulative drift transforms dx, dy, dr

Return type:

pandas DataFrame

compute_drift_vidstab(Z: int = 0, C: int = 0, thread: QThread = None, smoothing_window: int = 1) → DataFrame | None

Compute the cumulative transforms (dx, dy, dr) to apply in order to stabilize the time series and correct drift

Parameters:

  • Z (int) – the layer index

  • C (int) – the channel index

  • max_mem (int) – maximum memory use when using memory mapped TIFF

Returns:

the cumulative drift transforms dx, dy, dr

Return type:

pandas DataFrame

class pydetecdiv.domain.MultiFileImageResource.MultiFileImageResource(max_mem: int = 5000, image_resource: ImageResource = None)

Bases: ImageResourceData

A business-logic class defining valid operations and attributes of Image resources stored in multiple files

property shape: tuple[int, int, int, int, int]

The image resource shape (should be 5D with the following dimensions TCZYX)

property dims: Dimensions

the dimensions of the image resource

property sizeT: int

The number of frames

property sizeC: int

The number of channels

property sizeZ: int

The number of layers

property sizeY: int

The height of image

property sizeX: int

The width of image

class pydetecdiv.domain.SingleFileImageResource.SingleFileImageResource(image_resource: ImageResource = None, max_mem: int = 5000, **kwargs)

Bases: ImageResourceData

A business-logic class defining valid operations and attributes of Image resources stored in a single 5D file

property shape: tuple[int, ...]

The image resource shape (should be 5D with the following dimensions TCZYX)

property dims: Dimensions

the image dimensions

property sizeT: int

The number of frames

property sizeC: int

The number of channels

property sizeZ: int

The number of layers

property sizeY: int

The height of image

property sizeX: int

The width of image

data_sample(X: slice = None, Y: slice = None) → ndarray

Return a sample from an image resource, specified by X and Y slices. This is useful to extract resources for regions of interest from a field of view.

Parameters:

  • X – the X slice

  • Y – the Y slice

Returns:

the sample data (in-memory)

open() → None

Open the memory mapped file to access data

close() → None

Close the memory mapped file

flush() → None

Flush the data to save changes to the memory mapped file

refresh() → None

Close and open the memory mapped file to save memory if needed. Useful when creating a new file or making lots of changes.

class pydetecdiv.domain.Image.Image(data: ndarray | Tensor = None)

Bases: object

A business-logic class defining valid operations and attributes of 2D images

reset() → None

Resets the tensor values to their initial state

property shape: tuple[int, int, int]

the shape of this Image

property dtype: ImgDType

the dtype for this Image

as_array(dtype: ImgDType = None, grayscale: bool = False, channel_last: bool = False) → ndarray

property returning the image data for this image

as_tensor(dtype: ImgDType = None, grayscale: bool = False) → Tensor

Returns the Image as a tensor

Parameters:

  • dtype – the dtype for the tensor

  • grayscale – bool indicating whether the tensor should be 2D (grayscale) or 3D (RGB)

Returns:

the image as a tensor

as_torch(dtype: None | ImgDType = None, grayscale: bool = False) → Tensor

Returns the Image as a tensor

Parameters:

  • dtype – the dtype for the tensor

  • grayscale – bool indicating whether the tensor should be 2D (grayscale) or 3D (RGB)

Returns:

the image as a Torch tensor

rgb_to_gray() → Image

Return a grayscale Image obtained from an RGB Image

Returns:

grayscale Image

resize(shape: tuple[int, int] = None, method: InterpolationMode = InterpolationMode.NEAREST, antialias: bool = True) → Image

Resize image to the defined shape with the defined method.

Parameters:

  • shape – the target shape

  • method –

    the resizing method

    • bilinear: Bilinear interpolation. If antialias is true, becomes a hat/tent filter function with radius 1 when downsampling.

    • lanczos3: Lanczos kernel with radius 3. High-quality practical filter but may have some ringing, especially on synthetic images.

    • lanczos5: Lanczos kernel with radius 5. Very-high-quality filter but may have stronger ringing.

    • bicubic: Cubic interpolant of Keys. Equivalent to Catmull-Rom kernel. Reasonably good quality and faster than Lanczos3Kernel, particularly when upsampling.

    • gaussian: Gaussian kernel with radius 3, sigma = 1.5 / 3.0.

    • nearest: (default) Nearest neighbour interpolation. antialias has no effect when used with nearest neighbour interpolation.

    • area: Anti-aliased resampling with area interpolation. antialias has no effect when used with area interpolation; it always anti-aliases.

    • mitchellcubic: Mitchell-Netravali Cubic non-interpolating filter. For synthetic images (especially those lacking proper prefiltering), less ringing than Keys cubic kernel but less sharp.

Returns:

the resized Image object

show(ax: Axes, grayscale: bool = False, **kwargs)

Show the Image as a matplotlib image plot

Parameters:

  • ax – the matplotlib ax to plot the image in

  • grayscale – bool whether defining whether the image should be displayed as grayscale

  • kwargs – keyword arguments passed to the imshow method

histogram(ax: Axes, bins: str = 'auto', color: str = 'black')

Display a histogram of values

Parameters:

  • ax – the matplotlib ax toplot the histogram in

  • bins – the number of bins

  • color – the color

channel_histogram(ax: Axes, bins: str = 'auto')

Returns a histogram of channels’ values

Parameters:

  • ax – the matplotlib ax to plot the histogram in

  • bins – the number of bins

crop(offset_height: int, offset_width: int, target_height: int, target_width: int, new_image: bool = True) → Image

Crop the current Image

Parameters:

  • offset_height – the Y offset

  • offset_width – the X offset

  • target_height – the height of the cropped image

  • target_width – the width of the cropped image

  • new_image – if True, returns a new Image, otherwise, the current Image is replaced with its cropped version

Returns:

the cropped Image

auto_contrast(preserve_tone: bool = True) → Image

Adjust contrast automatically using PIL package. RGBA images cannot be used here

Parameters:

preserve_tone – if True, the tone is preserved

Returns:

the current Image after correction

adjust_contrast(factor: float = 2.0) → Image

Automatic contrast adjustment

Parameters:

factor – the contrast adjustment factor

Returns:

the current Image after correction

stretch_contrast(q: tuple[int, int] = None) → Image

Stretches the contrast of the Image

Parameters:

q – the quantile values for correction, the qlow will be set to 0 and the qhigh to 1

Returns:

the current Image after correction

equalize_hist(adapt: bool = False) → Image

Adjust exposure using the histogram equalization method

Parameters:

adapt – bool to set adaptative method

Returns:

the current Image after correction

sigmoid_correction() → Image

Exposure correction using the sigmoid method

Returns:

the current Image after correction

decompose_channels() → list[Image]

Split an RGB image in a list of channels

Returns:

list of one Image per channel

static add(images: list[Image]) → Image

Pixelwise addition of images in a list

Parameters:

images – the list of images

Returns:

the resulting Image

static mean(images: list[Image]) → Image

Compute the pixelwise mean of a list of images

Parameters:

images – the list of images to average

Returns:

the averaged image

static compose_channels(channels: list[Image] | tuple[Image], alpha: bool = False) → Image

Compose 3 channels into an RGB image, optionally adding an alpha channel determined as the maximum of the three channels if alpha is True

Parameters:

  • channels – the three channels to compose

  • alpha – bool, True if alpha should be added

Returns:

static auto_channels(image_resource_data: <module 'pydetecdiv.domain.ImageResourceData' from '/home/fred/PycharmProjects/pyDetecDiv/src/pydetecdiv/domain/ImageResourceData.py'>, C: int = 0, T: int = 0, Z: int | list[int] | tuple[int] = 0, crop: tuple[slice, slice] = None, drift: bool = False, alpha: bool = False) → Image

Returns a RGB, RGBA or grayscale image depending upon the C or Z values. If C (or Z) is a tuple, it is used as RGB values. If alpha is set to True, then the maximum value of every pixel across all channels defines its alpha value. If C and Z are both an index, then the returned image is grayscale.

Parameters:

  • image_resource_data – the image resource data used to create the Image

  • C – the channel or channels tuple

  • T – the time frame index

  • Z – the z-slice or z-slices tuple

  • crop – a tuple defining the crop values as slices = (slice(xmin, xmax), slice(ymin, ymax))

  • drift – bool defining whether drift correction should be applied

  • alpha – bool defining whether the image should contain an alpha channel

Returns:

Image

class pydetecdiv.domain.Image.ImgDType(value)

Bases: Enum

Enumeration of common names for numpy array/tensor dtypes