zea.display

Display functionality, including scan conversion frustrum conversion, etc.

Functions

cartesian_to_polar_matrix(cartesian_matrix)	Convert a Cartesian image matrix to a polar coordinate representation.
compute_scan_convert_2d_coordinates(...[, ...])	Precompute coordinates for 2d scan conversion from polar coordinates
compute_scan_convert_3d_coordinates(...[, ...])	Precompute coordinates for 3d scan conversion from polar coordinates
frustum_convert_rt2xz(rho, theta)	Convert coordinates from (rho, theta) space to (X,Z) space using the frustum coordinate conversion.
frustum_convert_rtp2xyz(rho, theta, phi)	Convert coordinates from (rho, theta, phi) space to (X,Y,Z) space using the frustum coordinate conversion.
frustum_convert_xyz2rtp(x, y, z, ...)	Convert coordinates from (X,Y,Z) space to (rho, theta, phi) space using the frustum coordinate conversion.
frustum_convert_xz2rt(x, z, theta_limits)	Convert coordinates from (X,Z) space to (rho, theta) space using the frustum coordinate conversion.
inverse_scan_convert_2d(cartesian_image[, ...])	Convert a Cartesian-format ultrasound image to a polar representation.
map_coordinates(inputs, coordinates, order)	map_coordinates using keras.ops or scipy.ndimage when order > 1.
overlay_masks(image, masks[, alpha, colors])	Overlay segmentation masks on top of an image using PIL.
polar_to_cartesian_matrix(polar_matrix, ...)	Resample a polar image onto a fixed Cartesian canvas with the apex at a chosen pixel.
scan_convert(image[, rho_range, ...])	Scan convert image based on number of dimensions.
scan_convert_2d(image[, rho_range, ...])	Perform scan conversion on a 2D ultrasound image from polar coordinates (rho, theta) to Cartesian coordinates (x, z).
scan_convert_3d(image[, rho_range, ...])	Perform scan conversion on a 3D ultrasound image from polar coordinates (rho, theta, phi) to Cartesian coordinates (z, x, y).
to_8bit(image[, dynamic_range, pillow])	Convert image to 8 bit image [0, 255].

zea.display.cartesian_to_polar_matrix(cartesian_matrix, fill_value=0.0, polar_shape=None, tip=None, r_max=None, theta_range=None, interpolation_order=1)

Convert a Cartesian image matrix to a polar coordinate representation.

Parameters:

• cartesian_matrix (tensor) – Input 2D image array in Cartesian coordinates.

• fill_value (float) – Value to use for points sampled outside the input image.

• polar_shape (tuple, optional) – Desired shape of the polar output (rows, cols). Defaults to the shape of the input image.

• tip (tuple, optional) – (x, y) coordinates of the origin for the polar transformation (typically the probe tip). Defaults to the center-top of the image.

• r_max (float, optional) – Maximum radius to consider in the polar transform. Defaults to the height of the input image.

• theta_range (tuple, optional) – (theta_min, theta_max) angular extent of the polar grid in radians, allowing asymmetric cones. Use this when the left and right cone boundaries do not have equal half-angles. Defaults to (-45, 45) degrees.

• interpolation_order (int) – Order of interpolation to use (0 = nearest-neighbor, 1 = linear, 2+ = spline). Matches the convention of scipy.ndimage.map_coordinates.

Returns:

The image re-sampled in polar coordinates with shape

polar_shape.

coordinates (Array): The Cartesian coordinates corresponding to each pixel in

the polar output.

Return type:

polar_matrix (Array)

zea.display.compute_scan_convert_2d_coordinates(image_shape, rho_range, theta_range, resolution=None, dtype='float32', distance_to_apex=0.0)

Precompute coordinates for 2d scan conversion from polar coordinates

zea.display.compute_scan_convert_3d_coordinates(image_shape, rho_range, theta_range, phi_range, resolution=None, dtype='float32')

Precompute coordinates for 3d scan conversion from polar coordinates

zea.display.frustum_convert_rt2xz(rho, theta)

Convert coordinates from (rho, theta) space to (X,Z) space using the frustum coordinate conversion.

Angles are defined in radians.

Parameters:

• rho (ndarray) – Radial coordinates of the points to convert.

• theta (ndarray) – Theta coordinates of the points to convert.

Returns:

X coordinates of the converted points. z (ndarray): Z coordinates of the converted points.

Return type:

x (ndarray)

zea.display.frustum_convert_rtp2xyz(rho, theta, phi)

Convert coordinates from (rho, theta, phi) space to (X,Y,Z) space using the frustum coordinate conversion.

Angles are defined in radians.

Parameters:

• rho (ndarray) – Radial coordinates of the points to convert.

• theta (ndarray) – Theta coordinates of the points to convert.

• phi (ndarray) – Phi coordinates of the points to convert.

Returns:

X coordinates of the converted points. y (ndarray): Y coordinates of the converted points. z (ndarray): Z coordinates of the converted points.

Return type:

x (ndarray)

zea.display.frustum_convert_xyz2rtp(x, y, z, theta_limits, phi_limits)

Convert coordinates from (X,Y,Z) space to (rho, theta, phi) space using the frustum coordinate conversion.

Angles are defined in radians.

Parameters:

• x (ndarray) – X coordinates of the points to convert.

• y (ndarray) – Y coordinates of the points to convert.

• z (ndarray) – Z coordinates of the points to convert.

• tlimits – Theta and phi limits, respectively, of the original volume. Any point that resides outside of these limits is potentially undefined, and therefore, the radial value for these points is made to be -1.

• plimits – Theta and phi limits, respectively, of the original volume. Any point that resides outside of these limits is potentially undefined, and therefore, the radial value for these points is made to be -1.

Returns:

Radial coordinates of the converted points. theta (ndarray): Theta coordinates of the converted points. phi (ndarray): Phi coordinates of the converted points.

Return type:

rho (ndarray)

zea.display.frustum_convert_xz2rt(x, z, theta_limits)

Convert coordinates from (X,Z) space to (rho, theta) space using the frustum coordinate conversion.

Angles are defined in radians.

Parameters:

• x (ndarray) – X coordinates of the points to convert.

• z (ndarray) – Z coordinates of the points to convert.

• theta_limits (list) – Theta limits of the original volume. Any point that resides outside of these limits is potentially undefined, and therefore, the radial value for these points is made to be -1.

Returns:

Radial coordinates of the converted points. theta (ndarray): Theta coordinates of the converted points.

Return type:

rho (ndarray)

zea.display.inverse_scan_convert_2d(cartesian_image, fill_value=0.0, theta_range=None, output_size=None, interpolation_order=1, find_scan_cone=True, image_range=None)

Convert a Cartesian-format ultrasound image to a polar representation.

This function can be used to recover a sector-shaped scan (polar format) from a Cartesian representation of an image. Optionally, it can detect and crop around the scan cone before conversion.

Parameters:

• cartesian_image (tensor) – 2D image array in Cartesian coordinates of type float.

• fill_value (float) – Value used to fill regions outside the original image during interpolation.

• theta_range (tuple, optional) – (theta_min, theta_max) angular extent of the polar grid in radians, allowing asymmetric cones. Defaults to (-45, 45) degrees.

• output_size (tuple, optional) – Shape (rows, cols) of the resulting polar image. If None, the shape of the input image is used.

• interpolation_order (int) – Order of interpolation used in resampling (0 = nearest-neighbor, 1 = linear, etc.).

• find_scan_cone (bool) – If True, automatically detects and crops around the scan cone in the Cartesian image before polar conversion, ensuring that the scan cone is centered without padding. Can be set to False if the image is already cropped and centered.

• image_range (tuple | None) – Tuple (vmin, vmax) for display scaling when detecting the scan cone.

Returns:

2D image in polar coordinates (sector-shaped scan).

Return type:

polar_image (Array)

zea.display.map_coordinates(inputs, coordinates, order, fill_mode='constant', fill_value=0)

map_coordinates using keras.ops or scipy.ndimage when order > 1.

zea.display.overlay_masks(image, masks, alpha=0.5, colors=None)

Overlay segmentation masks on top of an image using PIL.

Parameters:

• image (PIL.Image or ndarray) – Base image. If grayscale, it is converted to RGB. If ndarray, it is converted to a PIL Image first.

• masks (list of PIL.Image or ndarray) – Segmentation masks to overlay. Each mask should be an 8-bit single-channel image where non-zero pixels indicate the masked region.

• alpha (float) – Opacity of the mask overlays in [0, 1]. Defaults to 0.5.

• colors (list of tuple, optional) – RGB colors for each mask. If None, a default palette is used. If provided, must contain at least as many entries as masks (extra entries are ignored).

Returns:

RGB image with masks overlaid.

Return type:

PIL.Image

zea.display.polar_to_cartesian_matrix(polar_matrix, cartesian_shape, tip=None, r_max=None, theta_range=None, pitch=1.0, fill_value=0.0, order=1)

Resample a polar image onto a fixed Cartesian canvas with the apex at a chosen pixel.

Faithful inverse of cartesian_to_polar_matrix(). Where scan_convert_2d() fits the cone bounding box into the output (losing absolute position and scale), this pins the cone apex at pixel tip on a canvas of shape cartesian_shape and samples at pitch units per pixel, so a forward/inverse round-trip reproduces the original frame. Both share the _polar_sampling_coordinates() core; they differ only in how the output grid is built.

Parameters:

• polar_matrix (tensor) – Input polar image of shape (n_rho, n_theta), float type.

• cartesian_shape (Tuple[int, int]) – Output (rows, cols) = (n_z, n_x).

• tip (Optional[Tuple[float, float]]) – (col, row) pixel location of the cone apex in the output. Defaults to the centre-top (cols / 2, 0).

• r_max (Optional[float]) – Radius spanned by the polar image, in the same units as pitch (pixels by default). Defaults to rows.

• theta_range (Optional[Tuple[float, float]]) – angular extent in radians. The order is significant: it must match the column order of polar_matrix. cartesian_to_polar_matrix() lays its columns out from the larger to the smaller angle, so to invert it pass the range reversed, i.e. (theta_max, theta_min) – which is exactly what polar_geometry_from_coords_for_interp() returns. Defaults to (45, -45) degrees.

• pitch (float) – Output units per pixel (radial units of r_max). Defaults to 1.0, i.e. tip and r_max are in pixels.

• fill_value (float) – Value for pixels outside the polar domain.

• order (int) – Spline interpolation order. Defaults to 1.

Returns:

The polar image resampled onto the Cartesian canvas, with

shape cartesian_shape.

Return type:

cartesian_matrix (Array)

zea.display.scan_convert(image, rho_range=None, theta_range=None, phi_range=None, resolution=None, coordinates=None, fill_value=0.0, order=1, with_batch_dim=False)

Scan convert image based on number of dimensions.

zea.display.scan_convert_2d(image, rho_range=None, theta_range=None, resolution=None, coordinates=None, fill_value=0.0, order=1, distance_to_apex=0.0, **kwargs)

Perform scan conversion on a 2D ultrasound image from polar coordinates (rho, theta) to Cartesian coordinates (x, z).

Parameters:

• image (ndarray) – The input 2D ultrasound image in polar coordinates. Has dimensions (n_rho, n_theta) with optional batch.

• rho_range (Optional[Tuple[float, float]]) – A tuple specifying the range of rho values (min_rho, max_rho). Defined in mm.

• theta_range (Optional[Tuple[float, float]]) – A tuple specifying the range of theta values (min_theta, max_theta). Defined in radians.

• resolution (Optional[float]) – The resolution for the Cartesian grid. If None, it is calculated based on the input image. In mm / pixel.

• coordinates (Optional[ndarray]) – Precomputed coordinates for scan conversion. If provided, it will be used instead of computing new coordinates based on the input image shape and ranges.

• fill_value (float) – The value to fill in for coordinates outside the input image ranges. Defaults to 0.0. When set to NaN, no interpolation at the edges will happen.

• order (int) – The order of the spline interpolation. Defaults to 1.

• distance_to_apex (float) – Distance from the apex to the start of the z-axis in Cartesian grid. Defaults to 0.0.

Returns:

The scan-converted 2D ultrasound image in Cartesian coordinates.

Has dimensions (grid_size_z, grid_size_x). Coordinates outside the input image ranges are filled with NaNs.

parameters (dict): A dictionary containing information about the scan conversion.

Contains the resolution, x, and z limits, rho and theta ranges.

Return type:

ndarray

Note

Polar grid is inferred from the input image shape and the supplied rho and theta ranges. Cartesian grid is computed based on polar grid with resolutions specified by resolution parameter.

zea.display.scan_convert_3d(image, rho_range=None, theta_range=None, phi_range=None, resolution=None, coordinates=None, fill_value=0.0, order=1)

Perform scan conversion on a 3D ultrasound image from polar coordinates (rho, theta, phi) to Cartesian coordinates (z, x, y).

Parameters:

• image (ndarray) – The input 3D ultrasound image in polar coordinates. Has dimensions (n_rho, n_theta, n_phi) with optional batch.

• rho_range (Optional[Tuple[float, float]]) – A tuple specifying the range of rho values (min_rho, max_rho). Defined in mm.

• theta_range (Optional[Tuple[float, float]]) – A tuple specifying the range of theta values (min_theta, max_theta). Defined in radians.

• phi_range (Optional[Tuple[float, float]]) – A tuple specifying the range of phi values (min_phi, max_phi). Defined in radians.

• resolution (Optional[float]) – The resolution for the Cartesian grid. If None, it is calculated based on the input image. In mm / pixel.

• coodinates (ndarray, optional) – Precomputed coordinates for scan conversion. If provided, it will be used instead of computing new coordinates based on the input image shape and ranges.

• fill_value (float) – The value to fill in for coordinates outside the input image ranges. Defaults to 0.0. When set to NaN, no interpolation at the edges will happen.

• order (int) – The order of the spline interpolation. Defaults to 1.

Returns:

The scan-converted 3D ultrasound image in Cartesian coordinates.

Has dimensions (grid_size_z, grid_size_x, n_y). Coordinates outside the input image ranges are filled with NaNs.

parameters (dict): A dictionary containing information about the scan conversion.

Contains the resolution, x, y, and z limits, rho, theta, and phi ranges.

Return type:

ndarray

Note

Polar grid is inferred from the input image shape and the supplied rho, theta and phi ranges. Cartesian grid is computed based on polar grid with resolutions specified by resolution parameter.

zea.display.to_8bit(image, dynamic_range=None, pillow=True)

Convert image to 8 bit image [0, 255]. Clip between dynamic range.

Parameters:

• image (ndarray) – Input image(s). Should be in between dynamic range.

• dynamic_range (Optional[tuple]) – Dynamic range of input image(s).

• pillow (bool) – Whether to return PIL image. Defaults to True.

Returns:

Output 8 bit image(s) [0, 255].

Return type:

image (ndarray)

Note

If dynamic_range is None, it is assumed that the input image is already in the range [-60, 0] dB, which is a common range for ultrasound images.

Note

NaN values in the input image are replaced with the minimum value of the dynamic range before scaling, which ensures that they are represented as black (0) in the output image. +/- inf values are replaced with the min and max values of the dynamic range.

Example

>>> import numpy as np

>>> import zea

>>> file_path = (
...     "hf://zeahub/camus-sample/val/patient0401/patient0401_4CH_half_sequence.hdf5"
... )

>>> with zea.File(file_path, mode="r") as file:
...     data = file.data.image[0]

>>> image, _ = zea.display.scan_convert(
...     data,
...     rho_range=(0, 1),
...     theta_range=(-0.78, 0.78),
...     fill_value=np.nan,
... )
>>> image = zea.display.to_8bit(image, dynamic_range=(-60, 0))
>>> image.save("image.png")