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`(image_shape)	Precompute coordinates for 2d scan conversion from polar coordinates.
`compute_scan_convert_3d_coordinates`(image_shape)	Precompute coordinates for 3d scan conversion from frustum coordinates.
`frustum_convert_rt2xz`(rho, theta)	Deprecated, use `frustum_to_xz()` (`theta` is its `polar` angle).
`frustum_convert_rtp2xyz`(rho, theta, phi)	Deprecated, use `frustum_to_xyz()` (`theta` is its `polar` and `phi` its `elevation` angle).
`frustum_convert_xyz2rtp`(x, y, z, ...)	Deprecated, use `xyz_to_frustum()` (`theta_limits` is its `polar_limits` and `phi_limits` its `elevation_limits`).
`frustum_convert_xz2rt`(x, z, theta_limits)	Deprecated, use `xz_to_frustum()` (`theta_limits` is its `polar_limits`).
`frustum_to_xyz`(radius, polar, elevation)	Convert frustum coordinates (radius, polar angle, elevation angle) to (x, y, z).
`frustum_to_xz`(radius, polar)	Convert polar coordinates (radius, polar angle) to (x, z): the 2D case of `frustum_to_xyz()`, at elevation 0.
`histogram_match`(image, reference[, mode, ...])	Match the histogram of an image to a reference image, for fair visual comparison.
`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_coordinates`(...[, tip, ...])	(radius, polar angle) sampling grid that pins a polar cone's apex at pixel `tip`.
`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[, rlims, polar_limits, ...])	Scan convert image based on number of dimensions.
`scan_convert_2d`(image[, rlims, ...])	Perform scan conversion on a 2D ultrasound image from polar coordinates (radius, polar angle) to Cartesian coordinates (x, z).
`scan_convert_3d`(image[, rlims, ...])	Perform scan conversion on a 3D ultrasound image from frustum coordinates (radius, polar angle, elevation angle) to Cartesian coordinates (z, x, y).
`to_8bit`(image[, dynamic_range, pillow])	Convert image to 8 bit image [0, 255].
`xyz_to_frustum`(x, y, z, polar_limits, ...)	Convert (x, y, z) to frustum coordinates (radius, polar angle, elevation angle), the inverse of `frustum_to_xyz()`.
`xz_to_frustum`(x, z, polar_limits)	Convert (x, z) to polar coordinates (radius, polar angle), the inverse of `frustum_to_xz()`.

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, *, polar_limits=None)[source]¶

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.
polar_limits (tuple, optional) – Polar angle atan(x / z) [rad] of the first and last column of the polar output, positive toward +x (increasing column index of the Cartesian image), as in scan_convert_2d(). Unequal magnitudes describe an asymmetric cone. 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.
theta_range (tuple, optional) – Deprecated, use polar_limits. It measured angles toward -x, so theta_range=(a, b) is polar_limits=(-b, -a).

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, rlims=None, polar_limits=None, resolution=None, dtype='float32', distance_to_apex=None, *, grid_apex=None, extent=None, rho_range=None, theta_range=None)[source]¶

Precompute coordinates for 2d scan conversion from polar coordinates.

The polar image has one row per radius and one column per polar angle. The radius is measured from grid_apex, the point the polar grid fans out from (see zea.Parameters.grid_apex), and the polar angle is atan(x / z), from the z-axis in the x-z plane, positive towards +x. The returned coordinates index the polar image, so they live in that apex frame; grid_apex only moves the output window into the transducer frame, where the reported x_lim and z_lim are given (matching zea.Parameters.extent).

Parameters:

image_shape (tuple) – Shape of the polar image, (..., n_rho, n_theta).
rlims (Optional[Tuple[float, float]]) – Radius of the first and last row, measured from grid_apex.
polar_limits (Optional[Tuple[float, float]]) – Angle of the first and last column [rad].
resolution (Optional[float]) – Output pixel size. Derived from the polar image when not given.
dtype (str) – Dtype of the coordinates. Defaults to "float32".
grid_apex (array-like, optional) – The apex (x, y, z) in the transducer frame. Defaults to the origin, which makes the two frames coincide.
extent (array-like, optional) – The output window in the transducer frame, as zea.Parameters.extent gives it: (xmin, xmax, ..., zmin, zmax). Pixels outside the polar image are filled. Defaults to the bounding box of the polar image.
distance_to_apex (float, optional) – Deprecated, use grid_apex=(0, 0, -distance_to_apex).
rho_range (tuple, optional) – Deprecated, use rlims.
theta_range (tuple, optional) – Deprecated, use polar_limits.

Returns:

The sampling coordinates and a dict with resolution, x_lim, z_lim, rlims, polar_limits, dr and d_polar (the radius and angle steps between rows and columns).

Return type:

tuple

zea.display.compute_scan_convert_3d_coordinates(image_shape, rlims=None, polar_limits=None, elevation_limits=None, resolution=None, dtype='float32', *, rho_range=None, theta_range=None, phi_range=None)[source]¶

Precompute coordinates for 3d scan conversion from frustum coordinates.

The volume is indexed by radius, the polar angle atan(x / z) and the elevation angle atan(y / z) (see frustum_to_xyz()). Both angles are projections onto the x-z and y-z planes, not the spherical polar_angles and azimuth_angles of the transmits; at elevation 0 the volume reduces to the 2D sector of scan_convert_2d().

Parameters:

image_shape (tuple) – Shape of the volume, (..., n_radius, n_polar, n_elevation).
rlims (Optional[Tuple[float, float]]) – Radius of the first and last sample along the radius axis.
polar_limits (Optional[Tuple[float, float]]) – Polar angle atan(x / z) of the first and last sample along the polar axis [rad], ascending.
elevation_limits (Optional[Tuple[float, float]]) – Elevation angle atan(y / z) of the first and last sample along the elevation axis [rad], ascending.
resolution (Optional[float]) – Output voxel size. Derived from the volume when not given.
dtype (str) – Dtype of the coordinates. Defaults to "float32".
rho_range (tuple, optional) – Deprecated, use rlims.
theta_range (tuple, optional) – Deprecated, use polar_limits.
phi_range (tuple, optional) – Deprecated, use elevation_limits.

zea.display.frustum_convert_rt2xz(rho, theta)[source]¶: Deprecated, use frustum_to_xz() (theta is its polar angle).

zea.display.frustum_convert_rtp2xyz(rho, theta, phi)[source]¶: Deprecated, use frustum_to_xyz() (theta is its polar and phi its elevation angle).

zea.display.frustum_convert_xyz2rtp(x, y, z, theta_limits, phi_limits)[source]¶: Deprecated, use xyz_to_frustum() (theta_limits is its polar_limits and phi_limits its elevation_limits).

zea.display.frustum_convert_xz2rt(x, z, theta_limits)[source]¶: Deprecated, use xz_to_frustum() (theta_limits is its polar_limits).

zea.display.frustum_to_xyz(radius, polar, elevation)[source]¶

Convert frustum coordinates (radius, polar angle, elevation angle) to (x, y, z).

The polar angle atan(x / z) and the elevation angle atan(y / z) are projections onto the x-z and y-z planes, not the spherical polar_angles and azimuth_angles of the transmits (see Angle and radius names). Angles are defined in radians.

Parameters:

radius (ndarray) – Radial coordinates of the points to convert.
polar (ndarray) – Polar angles atan(x / z) of the points to convert.
elevation (ndarray) – Elevation angles atan(y / z) 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_to_xz(radius, polar)[source]¶

Convert polar coordinates (radius, polar angle) to (x, z): the 2D case of frustum_to_xyz(), at elevation 0.

The polar angle atan(x / z) is signed, positive toward +x. Angles are defined in radians.

Parameters:

radius (ndarray) – Radial coordinates of the points to convert.
polar (ndarray) – Polar angles atan(x / z) 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.histogram_match(image, reference, mode='full', n_bins=256, roi=None, allow_unequal_shapes=False, exclude_below=-300.0)[source]¶

Match the histogram of an image to a reference image, for fair visual comparison.

Image formation methods apply different dynamic range transformations, which biases visual as well as quantitative comparison. Matching the histogram of an image to a reference (typically a conventional B-mode image) puts the two on a common scale.

Reference

N. Bottenus, B. C. Byram, and D. Hyun, “Histogram Matching for Visual Ultrasound Image Comparison,” IEEE Transactions on Ultrasonics, Ferroelectrics, and Frequency Control, vol. 68, no. 5, pp. 1487–1495, 2021. doi.org/10.1109/TUFFC.2020.3035965

Their MATLAB implementation, referred to above as the reference implementation: https://github.com/nbottenus/histogram_matching/blob/main/histmatch.m

Parameters:

image (ndarray) – Image to transform, typically log-compressed (dB).
reference (ndarray) – Image to match to. Has to be of the shape of image, unless allow_unequal_shapes says otherwise.
mode (str) –
Class of transform to match with. Defaults to "full".
- "partial": affine match (Sec. III.A), the scale and offset that match mean and variance. It leaves the shape of the image’s own distribution intact, so pick it when that shape is the thing under comparison, when the fitted region contains structure rather than plain speckle, or when the CNR must survive the matching.
- "full": any monotone mapping (Sec. III.B), the one that carries the histogram of the image onto that of the reference, estimated on n_bins bins. It matches the shape of the distribution too, hence undoes non-linear compression, so pick it to compare methods whose transformations differ in more than scale and offset, or are unknown (“black box” images, Sec. III.C.2). Together with a speckle roi, the paper’s expected common use (Sec. V).
n_bins (Union[int, str]) – Number of bins the mapping of a "full" match is estimated on; ignored by "partial". Defaults to 256, the number of bins used in the paper, which it found enough for consistent results. Pass "all" for one bin per fitted pixel, the limit of the binning process (Sec. III.C.1): it reproduces the reference distribution down to its outliers and tails, which replicates them in the matched image. This is what skimage.exposure.match_histograms does.
roi (ndarray, optional) – Boolean mask, of the shape of both images, selecting a homogeneous speckle region (Sec. III.C.3, the paper’s expected common use). The mapping is fit inside the mask and applied to the whole image, extended linearly outside the fitted range. Defaults to None (fit on the whole image).
allow_unequal_shapes (bool) – Whether reference may be of a shape other than that of image. Only the two distributions are compared, so a match is well defined either way, but images of different shapes are more often a mistake (a stray transpose, the wrong frame of a sequence) than an intent. Defaults to False. Pass True to match against a reference deliberately not of the shape of the image, e.g. a region cut out of a larger acquisition. An roi has to index both images regardless, so it cannot be combined with unequal shapes.
exclude_below (Optional[float]) – Value at or below which a pixel of either image is kept out of the fit and the transform. Defaults to -300.0, which catches zea’s log(0) sentinel and nothing a log-compressed B-mode measures. Pass None to exclude nothing but the non-finite pixels.

Returns:

Transformed image (float64), unclipped: clipping to a display range is left to the caller (to_8bit, or vmin/vmax).

Return type:

ndarray

Note

Which image is matched to which is a choice (Sec. V): matching to B-mode is natural for a reader used to B-mode, but features outside its dynamic range are lost in the process, and matching in the other direction then shows them off better.

Example

>>> import numpy as np

>>> from zea.display import histogram_match

>>> rng = np.random.default_rng(0)
>>> image = 20 * np.log10(rng.rayleigh(0.1, (64, 64)))
>>> reference = 20 * np.log10(rng.rayleigh(1.0, (64, 64)))

>>> round(image.mean() - reference.mean())  # the image is 20 dB darker
-20

>>> matched = histogram_match(image, reference)
>>> round(matched.mean() - reference.mean())
0

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, *, polar_limits=None)[source]¶

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.
polar_limits (tuple, optional) – Polar angle atan(x / z) [rad] of the first and last column of the polar image, positive toward +x, as in scan_convert_2d(). Unequal magnitudes describe an asymmetric cone. 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.
theta_range (tuple, optional) – Deprecated, use polar_limits. It measured angles toward -x, so theta_range=(a, b) is polar_limits=(-b, -a).

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)[source]¶: map_coordinates using keras.ops or scipy.ndimage when order > 1.

zea.display.overlay_masks(image, masks, alpha=0.5, colors=None)[source]¶

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_coordinates(cartesian_shape, n_r, n_polar, tip=None, r_max=None, theta_range=None, pitch=1.0, dtype='float32', *, polar_limits=None)[source]¶

(radius, polar angle) sampling grid that pins a polar cone’s apex at pixel tip.

Shared core of polar_to_cartesian_matrix(): builds the fractional index grid that resamples an (n_r, n_polar) polar image onto a cartesian_shape canvas, with the apex at pixel tip and pitch units per pixel. Pass the result as coordinates to scan_convert_2d() (or the ScanConvert operation) to run the same resampling inside a pipeline. Unlike compute_scan_convert_2d_coordinates(), this uses the arctan2 mapping in _polar_sampling_coordinates(), so it covers a full circle rather than only a narrow (polar angle within pi/2) sector.

Parameters:

cartesian_shape (Tuple[int, int]) – Output (rows, cols) = (n_z, n_x).
n_r (int) – Radial samples (rows) of the polar image the indices address.
n_polar (int) – Angular samples (columns) of the polar image the indices address.
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.
polar_limits (Optional[Tuple[float, float]]) – Polar angle atan(x / z) [rad] of the first and last column of the polar image, positive toward +x (increasing column index of the output). 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.
dtype (str) – Compute dtype for the axes. Defaults to "float32".
theta_range (tuple, optional) – Deprecated, use polar_limits. It measured angles toward -x, so theta_range=(a, b) is polar_limits=(-a, -b).

Returns:

(2, cols, rows) stack of [rho_idx, theta_idx] sampling indices.

Return type:

coords (Array)

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, *, polar_limits=None)[source]¶

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_r, n_polar), 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.
polar_limits (Optional[Tuple[float, float]]) – Polar angle atan(x / z) [rad] of the first and last column of polar_matrix, positive toward +x (increasing column index of the output). Pass the polar_limits given to cartesian_to_polar_matrix() to invert it. 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.
theta_range (tuple, optional) – Deprecated, use polar_limits. It measured angles toward -x, so theta_range=(a, b) is polar_limits=(-a, -b).

Returns:

The polar image resampled onto the Cartesian canvas, with: shape cartesian_shape.

Return type:

cartesian_matrix (Array)

zea.display.scan_convert(image, rlims=None, polar_limits=None, elevation_limits=None, resolution=None, coordinates=None, fill_value=0.0, order=1, with_batch_dim=False, distance_to_apex=None, *, grid_apex=None, extent=None, rho_range=None, theta_range=None, phi_range=None)[source]¶

Scan convert image based on number of dimensions.

A 2D image goes to scan_convert_2d() with rlims and polar_limits; a 3D volume goes to scan_convert_3d(), which adds elevation_limits. The polar angle atan(x / z) means the same in both, so a 3D frustum extends the 2D sector in elevation. grid_apex and extent apply to 2D images only.

rho_range, theta_range and phi_range are deprecated aliases of rlims, polar_limits and elevation_limits.

zea.display.scan_convert_2d(image, rlims=None, polar_limits=None, resolution=None, coordinates=None, fill_value=0.0, order=1, distance_to_apex=None, *, grid_apex=None, extent=None, rho_range=None, theta_range=None, **kwargs)[source]¶

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

Parameters:

image (ndarray) – The input 2D ultrasound image in polar coordinates. Has dimensions (n_radius, n_polar) with optional batch.
rlims (Optional[Tuple[float, float]]) – Radius (rho_min, rho_max) of the first and last row, measured from grid_apex. In the same unit as the output grid.
polar_limits (Optional[Tuple[float, float]]) – Polar angle atan(x / z) of the first and last column [rad], from the z-axis in the x-z plane, positive towards +x.
resolution (Optional[float]) – The resolution for the Cartesian grid. If None, it is calculated based on the input image. In units of rlims per 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.
grid_apex (array-like, optional) – The point (x, y, z) that the radius is measured from, in the transducer frame (see zea.Parameters.grid_apex). Moves the reported x_lim and z_lim into the transducer frame. Defaults to the origin.
extent (array-like, optional) – Output window in the transducer frame, (xmin, xmax, ..., zmin, zmax) as zea.Parameters.extent gives it. Defaults to the bounding box of the polar image.
distance_to_apex (float, optional) – Deprecated, use grid_apex=(0, 0, -distance_to_apex).
rho_range (tuple, optional) – Deprecated, use rlims.
theta_range (tuple, optional) – Deprecated, use polar_limits.

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, rlims and polar_limits.

Return type:

ndarray

Note

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

zea.display.scan_convert_3d(image, rlims=None, polar_limits=None, elevation_limits=None, resolution=None, coordinates=None, fill_value=0.0, order=1, *, rho_range=None, theta_range=None, phi_range=None)[source]¶

Perform scan conversion on a 3D ultrasound image from frustum coordinates (radius, polar angle, elevation angle) to Cartesian coordinates (z, x, y).

The polar angle atan(x / z) and the elevation angle atan(y / z) (see frustum_to_xyz()) are projections onto the x-z and y-z planes, not the spherical polar_angles and azimuth_angles of the transmits.

Parameters:

image (ndarray) – The input 3D ultrasound image in frustum coordinates. Has dimensions (n_radius, n_polar, n_elevation) with optional batch.
rlims (Optional[Tuple[float, float]]) – Radius (rho_min, rho_max) of the first and last sample.
polar_limits (Optional[Tuple[float, float]]) – Polar angle atan(x / z) of the first and last sample [rad].
elevation_limits (Optional[Tuple[float, float]]) – Elevation angle atan(y / z) of the first and last sample [rad].
resolution (Optional[float]) – The resolution for the Cartesian grid. If None, it is calculated based on the input image. In units of rlims per 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.
rho_range (tuple, optional) – Deprecated, use rlims.
theta_range (tuple, optional) – Deprecated, use polar_limits.
phi_range (tuple, optional) – Deprecated, use elevation_limits.

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, rlims, polar_limits and elevation_limits.

Return type:

ndarray

Note

Frustum grid is inferred from the input image shape and the supplied limits. Cartesian grid is computed based on the frustum grid with resolutions specified by resolution parameter.

zea.display.to_8bit(image, dynamic_range=None, pillow=True)[source]¶

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.values[0]

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

zea.display.xyz_to_frustum(x, y, z, polar_limits, elevation_limits)[source]¶

Convert (x, y, z) to frustum coordinates (radius, polar angle, elevation angle), the inverse of frustum_to_xyz().

The polar angle atan(x / z) and the elevation angle atan(y / z) are projections onto the x-z and y-z planes (see Angle and radius names). 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.
polar_limits – Polar and elevation angle 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.
elevation_limits – Polar and elevation angle 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. polar (ndarray): Polar angles atan(x / z) of the converted points. elevation (ndarray): Elevation angles atan(y / z) of the converted points.

Return type:

radius (ndarray)

zea.display.xz_to_frustum(x, z, polar_limits)[source]¶

Convert (x, z) to polar coordinates (radius, polar angle), the inverse of frustum_to_xz().

The polar angle atan(x / z) is signed, positive toward +x. Angles are defined in radians.

Parameters:

x (ndarray) – X coordinates of the points to convert.
z (ndarray) – Z coordinates of the points to convert.
polar_limits (list) – Polar angle limits of the original image. 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. polar (ndarray): Polar angles atan(x / z) of the converted points.

Return type:

radius (ndarray)