zea.beamform.pixelgrid¶

Pixel grid calculation for ultrasound beamforming.

Functions

cartesian_pixel_grid(xlims, zlims[, ylims, ...])

Generate a Cartesian pixel grid.

check_for_aliasing(parameters)

Checks if the Parameters will cause spatial aliasing due to a too low pixel density.

polar_pixel_grid(polar_limits, zlims, ...[, ...])

Generate a polar grid.

radial_pixel_grid(rlims, dr, oris, dirs)

Generate a focused pixel grid based on input parameters.

scanline_aligned_apodization(n_tx, ...)

Compounding apodization mask that isolates each pixel's owning transmit.

scanline_pixel_grid(transmit_origins, ...[, ...])

Pixel grid for scanline beamforming: one column of pixels per transmit.
zea.beamform.pixelgrid.cartesian_pixel_grid(xlims, zlims, ylims=(0.0, 0.0), grid_size_x=None, grid_size_y=None, grid_size_z=None, dx=None, dy=None, dz=None)[source]¶

Generate a Cartesian pixel grid.

Behaviour:

  • If ylims has zero extent (abs(ymax - ymin) < eps) the function returns a 2D grid with shape (nz, nx, 3) that contains (x, y=0, z) per-pixel (y omitted as a dimension).

  • If ylims has non-zero extent the function returns a 3D grid with shape (nz, nx, ny, 3) containing (x, y, z) per-voxel.

Parameters:

  • xlims (tuple) – [xmin, xmax]

  • ylims (tuple) – [ymin, ymax] — if ymax == ymin (within tol) treated as “no y extent”

  • zlims (tuple) – [zmin, zmax]

  • grid_size_x (int) – number of samples along each axis. For 2D (no y extent) only grid_size_x and grid_size_z are required if using sizes.

  • grid_size_y (int) – number of samples along each axis. For 2D (no y extent) only grid_size_x and grid_size_z are required if using sizes.

  • grid_size_z (int) – number of samples along each axis. For 2D (no y extent) only grid_size_x and grid_size_z are required if using sizes.

  • dx (float) – spacings along axes. For 2D, only dx and dz are required if using spacings.

  • dy (float) – spacings along axes. For 2D, only dx and dz are required if using spacings.

  • dz (float) – spacings along axes. For 2D, only dx and dz are required if using spacings.

Returns:

  • 2D: shape (nz, nx, 3) with per-pixel [x, y, z] (y will be zeros)

  • 3D: shape (nz, nx, ny, 3) with per-voxel [x, y, z]

Return type:

np.ndarray

zea.beamform.pixelgrid.check_for_aliasing(parameters)[source]¶

Checks if the Parameters will cause spatial aliasing due to a too low pixel density. If so, a warning is printed with a suggestion to increase the pixel density by either increasing the number of pixels, or decreasing the pixel spacing, depending on which parameter was set by the user.

zea.beamform.pixelgrid.polar_pixel_grid(polar_limits, zlims, num_radial_pixels, num_polar_pixels, distance_to_apex=0.0)[source]¶

Generate a polar grid.

Uses radial_pixel_grid but based on parameters that are present in the scan class. Currently only 2D grids (no elevation steering) are supported.

Parameters:

  • polar_limits (tuple) – Polar limits of pixel grid ([polar_min, polar_max])

  • zlims (tuple) – Depth limits of pixel grid ([zmin, zmax])

  • num_radial_pixels (int) – Number of depth pixels.

  • num_polar_pixels (int) – Number of polar pixels.

  • distance_to_apex (float) – Distance from transducer to apex of pixel grid.

Returns:

Pixel grid of size (num_radial_pixels, num_polar_pixels, 3) in Cartesian coordinates (x, y, z)

Return type:

grid (np.ndarray)

zea.beamform.pixelgrid.radial_pixel_grid(rlims, dr, oris, dirs)[source]¶

Generate a focused pixel grid based on input parameters.

To accommodate the multitude of ways of defining a focused transmit grid, we define pixel “rays” or “lines” according to their origins (oris) and directions (dirs). The position along the ray is defined by its limits (rlims) and spacing (dr).

Parameters:

  • rlims (tuple) – Radial limits of pixel grid ([rmin, rmax]) with respect to each ray origin

  • dr (float) – Pixel spacing in radius

  • oris (np.ndarray) – Origin of each ray in Cartesian coordinates (x, y, z) with shape (nrays, 3)

  • dirs (np.ndarray) – Steering direction of each ray in azimuth, in units of radians (nrays, 2)

Returns:

Pixel grid of size (nr, nrays, 3) in

Cartesian coordinates (x, y, z), with nr being the number of radial pixels.

Return type:

grid (np.ndarray)

zea.beamform.pixelgrid.scanline_aligned_apodization(n_tx, num_depth_pixels)[source]¶

Compounding apodization mask that isolates each pixel’s owning transmit.

For a grid built by scanline_pixel_grid() (shape (num_depth_pixels, n_tx, 3), flattened row-major to (n_pix, 3)), pixel (i, n) at flat index i * n_tx + n belongs to transmit n. This returns the corresponding one-hot weight (1 for the owning transmit, 0 for every other transmit) to feed to zea.ops.AlignedApodization, turning the regular pixel-based DAS pipeline into scanline (line-by-line) beamforming.

Parameters:

  • n_tx (int) – Number of transmits (grid columns).

  • num_depth_pixels (int) – Number of depth samples per line (grid rows).

Returns:

Apodization weights of shape (num_depth_pixels * n_tx, n_tx).

Return type:

np.ndarray

zea.beamform.pixelgrid.scanline_pixel_grid(transmit_origins, focus_distances, polar_angles, zlims, num_depth_pixels, azimuth_angles=None, grid_type='cartesian')[source]¶

Pixel grid for scanline beamforming: one column of pixels per transmit.

Scanline (line-by-line) imaging is a special case of pixel-based DAS beamforming where each transmit is beamformed to a single column of pixels. This builds that grid in the same (grid_size_z, grid_size_x, 3) layout as cartesian_pixel_grid() (one column n per transmit n, num_depth_pixels rows), so it can be beamformed by the regular pixel-based Beamform pipeline. Pair with scanline_aligned_apodization() (fed to AlignedApodization) to zero out every transmit except the one whose column each pixel belongs to.

Parameters:

  • transmit_origins (np.ndarray) – Beam origins (n_tx, 3) in meters.

  • focus_distances (np.ndarray) – Focus distances (n_tx,) in meters.

  • polar_angles (np.ndarray) – Steering angles (n_tx,) in radians.

  • zlims (tuple) – Depth range (z_min, z_max) in meters.

  • num_depth_pixels (int) – Number of samples along each line.

  • azimuth_angles (np.ndarray, optional) – Azimuth angles (n_tx,). Defaults to zeros.

  • grid_type (str) – "cartesian" for a vertical column at each beam’s lateral focus position (linear-scan geometry), matching cartesian_pixel_grid(). "polar" for a steered ray from each transmit’s own origin (sector / phased-array geometry), matching polar_pixel_grid(). Defaults to "cartesian".

Returns:

Pixel positions of shape (num_depth_pixels, n_tx, 3) in Cartesian (x, y, z) coordinates (meters); column n is the beam line of transmit n.

Return type:

np.ndarray