SampleToMasks

class deeptrack.optical.optics.SampleToMasks(transformation_function: Callable[[ndarray | Tensor], ndarray | Tensor], number_of_masks: int | Callable[[...], int] = 1, output_region: tuple[int, int, int, int] | Callable[[...], tuple[int, int, int, int]] | None = None, merge_method: str | Callable | list[str | Callable] | Callable[[...], str | Callable | list[str | Callable]] = 'add', **kwargs: Any)

Bases: Feature

Create a mask from a list of images.

This feature applies a transformation function to each input image and merges the resulting masks into a single multi-layer image. Each input image must have a position property that determines its placement within the final mask. When used with scatterers, the voxel_size property must be provided for correct object sizing.

Parameters

transformation_function: Callable[[array | tensor], array | tensor]

A function that transforms each input image into a mask with number_of_masks layers.

number_of_masks: PropertyLike[int], optional

The number of mask layers to generate. Default is 1.

output_region: PropertyLike[tuple[int, int, int, int]], optional

The size and position of the output mask, typically aligned with optics.output_region.

merge_method: PropertyLike[str | Callable | list[str | Callable]], optional

Method for merging individual masks into the final image. Can be: - “add” (default): Sum the masks. - “overwrite”: Later masks overwrite earlier masks. - “or”: Combine masks using a logical OR operation. - “mul”: Multiply masks. - Function: Custom function taking two images and merging them.

**kwargs: Any

Additional keyword arguments passed to the parent Feature class.

Methods

get(image, transformation_function, …) -> np.ndarray | torch.Tensor

Applies the transformation function to the input image.

_process_and_get(images, …) -> np.ndarray | torch.Tensor

Processes a list of images and generates a multi-layer mask.

Returns

np.ndarray | torch.Tensor

The final mask image with the specified number of layers.

Raises

ValueError

If merge_method is invalid.

Examples

>>> import deeptrack as dt

Define number of particles:

>>> n_particles = 12

Define optics and particles:

>>> import numpy as np
>>>
>>> optics = dt.Fluorescence(output_region=(0, 0, 64, 64))
>>> particle = dt.PointParticle(
>>>     position=lambda: np.random.uniform(5, 55, size=2),
>>> )
>>> particles = particle ^ n_particles

Define pipelines:

>>> sim_im_pip = optics(particles)
>>> sim_mask_pip = particles >> dt.SampleToMasks(
...     lambda: lambda particles: particles > 0,
...     output_region=optics.output_region,
...     merge_method="or",
... )
>>> pipeline = sim_im_pip & sim_mask_pip
>>> pipeline.store_properties()

Generate image and mask:

>>> image, mask = pipeline.update()()

Get particle positions:

>>> positions = np.array(image.get_property("position", get_one=False))

Visualize results:

>>> import matplotlib.pyplot as plt
>>>
>>> plt.subplot(1, 2, 1)
>>> plt.imshow(image, cmap="gray")
>>> plt.title("Original Image")
>>> plt.subplot(1, 2, 2)
>>> plt.imshow(mask, cmap="gray")
>>> plt.scatter(positions[:,1], positions[:,0], c="y", marker="x", s = 50)
>>> plt.title("Mask")
>>> plt.show()

Methods Summary

get(scatterer, transformation_function, **kwargs)

Apply the transformation function to a single image.

Methods Documentation

get(scatterer: ScatteredVolume, transformation_function: Callable[[ndarray | Tensor], ndarray | Tensor], **kwargs: Any) → ndarray

Apply the transformation function to a single image.

Parameters

scatterer: ScatteredVolume

The wrapper object containing the image to be transformed.

transformation_function: Callable[[array | tensor], array | tensor]

Function to transform the image.

**kwargs: Any

Additional parameters.

Returns

np.ndarray

The transformed image.