Upscale

class deeptrack.features.Upscale(feature: Feature, factor: int | tuple[int, int, int] = 1, **kwargs: dict[str, Any])

Bases: Feature

Simulate a pipeline at a higher resolution.

This feature scales up the resolution of the input pipeline by a specified factor, performs computations at the higher resolution, and then downsamples the result back to the original size. This is useful for simulating effects at a finer resolution while preserving compatibility with lower-resolution pipelines.

Internally, this feature redefines the scale of physical units (e.g., units.pixel) to achieve the effect of upscaling. It does not resize the input image itself but affects features that rely on physical units.

Parameters

feature: Feature

The pipeline or feature to resolve at a higher resolution.

factor: int or tuple[int, int, int], optional

The factor by which to upscale the simulation. If a single integer is provided, it is applied uniformly across all axes. If a tuple of three integers is provided, each axis is scaled individually. Defaults to 1.

**kwargs: dict of str to Any

Additional keyword arguments passed to the parent Feature class.

Attributes

__distributed__: bool

Indicates whether this feature distributes computation across inputs. Always False for Upscale.

Methods

get(image: np.ndarray | Image, factor: int | tuple[int, int, int], **kwargs) -> np.ndarray

Simulates the pipeline at a higher resolution and returns the result at the original resolution.

Notes

• This feature does not directly resize the image. Instead, it modifies the unit conversions within the pipeline, making physical units smaller, which results in more detail being simulated.

• The final output is downscaled back to the original resolution using block_reduce from skimage.measure.

• The effect is only noticeable if features use physical units (e.g., units.pixel, units.meter). Otherwise, the result will be identical.

Examples

>>> import deeptrack as dt
>>> import matplotlib.pyplot as plt

Define an optical pipeline and a spherical particle: >>> optics = dt.Fluorescence() >>> particle = dt.Sphere() >>> simple_pipeline = optics(particle)

Create an upscaled pipeline with a factor of 4: >>> upscaled_pipeline = dt.Upscale(optics(particle), factor=4)

Resolve the pipelines: >>> image = simple_pipeline() >>> upscaled_image = upscaled_pipeline()

Visualize the images: >>> plt.subplot(1, 2, 1) >>> plt.imshow(image, cmap=”gray”) >>> plt.title(“Original Image”) >>> plt.subplot(1, 2, 2) >>> plt.imshow(upscaled_image, cmap=”gray”) >>> plt.title(“Simulated at Higher Resolution”) >>> plt.show()

Compare the shapes (both are the same due to downscaling): >>> print(image.shape) (128, 128, 1) >>> print(upscaled_image.shape) (128, 128, 1)

Methods Summary

get(image, factor, **kwargs)

Simulate the pipeline at a higher resolution and return result.

Methods Documentation

get(image: np.ndarray, factor: int | tuple[int, int, int], **kwargs: dict[str, Any]) → np.ndarray

Simulate the pipeline at a higher resolution and return result.

Parameters

image: np.ndarray

The input image to process.

factor: int or tuple[int, int, int]

The factor by which to upscale the simulation. If a single integer is provided, it is applied uniformly across all axes. If a tuple of three integers is provided, each axis is scaled individually.

**kwargs: dict of str to Any

Additional keyword arguments passed to the feature.

Returns

np.ndarray

The processed image at the original resolution.

Raises

ValueError

If the input factor is not a valid integer or tuple of integers.