Ultrasound Processing

ultrasound_processing

ultrasound_processing.transform

ultrasound_processing.transform.calculate_geometry(temp, d, alpha)[source]

Calculates geometric parameters from the ultrasound image.

Parameters:

  • temp (np.ndarray) – Cleaned image array.

  • d (float) – Pixel-to-centimeter ratio.

  • alpha (float) – Half angle of the ultrasound beam in radians.

Returns:

  • Depth of the offset in pixels.

  • Height in pixels of the ultrasound window.

  • Offset in centimeters.

  • Height in centimeters of the ultrasound window.

  • First row index of the window.

Return type:

Tuple[float, int, float, float, int]

ultrasound_processing.transform.clean_image(gray_array)[source]

Cleans the grayscale image by cropping and filtering pixel values.

Parameters:

gray_array (np.ndarray) – Grayscale image array.

Returns:

  • Processed image as a float array with noise filtered.

  • Index of the first row retained after cropping.

Return type:

Tuple[np.ndarray, int]

ultrasound_processing.transform.compute_coordinate_grid(offset_cm, r_cm, d, temp, offset_px, first, alpha_deg, res)[source]

Computes the coordinate grid for the ultrasound image transformation.

Parameters:

  • offset_cm (float) – Offset in centimeters.

  • r_cm (float) – Range in centimeters.

  • d (float) – Pixel-to-centimeter ratio.

  • temp (np.ndarray) – Processed grayscale image.

  • offset_px (float) – Offset in pixels.

  • first (int) – Index of the first pixel row used.

  • alpha_deg (float) – Half angle of ultrasound beam in degrees.

  • res (float) – Image resolution scaling factor.

Returns:

  • X coordinates in the transformed space.

  • Y coordinates in the transformed space.

Return type:

Tuple[np.ndarray, np.ndarray]

ultrasound_processing.transform.convert_to_grayscale(image)[source]

Converts a PIL image to a grayscale NumPy array.

Parameters:

image (PIL.Image.Image) – Input image in PIL.Image format.

Returns:

Grayscale image as a 2D NumPy array.

Return type:

np.ndarray

ultrasound_processing.transform.detect_cm_marks(gray_array)[source]

Detects centimeter marks in the grayscale image along rows and columns.

Parameters:

gray_array (np.ndarray) – Grayscale image array.

Returns:

  • Estimated distance in pixels between cm marks (float).

  • List of detected row indices (List[int]).

  • List of detected column indices (List[int]).

Return type:

Tuple[float, List[int], List[int]]

ultrasound_processing.transform.interpolate_image(X, Y, temp)[source]

Applies bilinear interpolation to map intensity values from input coordinates.

Parameters:

  • X (np.ndarray) – X coordinate grid.

  • Y (np.ndarray) – Y coordinate grid.

  • temp (np.ndarray) – Processed grayscale image.

Returns:

Interpolated intensity values.

Return type:

np.ndarray

ultrasound_processing.transform.transform_image(img: PIL.Image.Image, alpha_deg: float, res: float)[source]

Transforms an ultrasound image into a rectified coordinate system.

Parameters:

  • img (PIL.Image.Image) – Input image to process.

  • alpha_deg (float) – Half angle of the ultrasound beam in degrees.

  • res (float) – Image resolution scaling factor.

Returns:

  • Transformed image as a 2D array.

  • Depth of the ultrasound window in pixels.

  • Offset from the top in centimeters.

Return type:

Tuple[np.ndarray, float, float]

ultrasound_processing.masking

ultrasound_processing.masking.compute_threshold(image: ndarray, top_percent: float) → int[source]

Compute the intensity threshold such that the top top_percent fraction of pixel values in the grayscale image will be set to white in the binary mask.

Parameters:

  • image – 2D numpy array of grayscale pixel intensities (0-255).

  • top_percent – Number between 0 and 1 that determines the fraction of pixels to be set to white.

Returns:

An integer threshold value in the range [0, 255].

ultrasound_processing.masking.dilate_contour(contour: ndarray, kernel_size: Tuple[int, int] = (2, 2), iterations: int = 1) → ndarray[source]

Thicken the one- pixel-wide contour by applying dilation.

Parameters:

  • contour – Binary contour image (0 or 255) with single-pixel lines.

  • kernel_size – Size of the rectangular structuring element.

  • iterations – Number of dilation iterations.

Returns:

The dilated contour mask.

ultrasound_processing.masking.do_closing(mask: ndarray, kernel_size: Tuple[int, int] = (2, 2)) → ndarray[source]

Apply a morphological closing operation (dilation followed by erosion) to fill small holes and connect nearby white regions in the binary mask.

Parameters:

  • mask – Binary mask (0 or 255) to be processed.

  • kernel_size – Size of the structuring element used for closing.

Returns:

The mask after morphological closing.

ultrasound_processing.masking.extract_top_contour(mask: ndarray) → ndarray[source]

Extract the top contour of the white regions in the binary mask by keeping only the first white pixel in each column.

Parameters:

mask – Cleaned binary mask (0 or 255).

Returns:

A binary image where each column has at most one white pixel.

ultrasound_processing.masking.mask(image: ndarray, top_percent: float = 0.93, top_margin: int = 5, apply_closing_flag: bool = True) → ndarray[source]

Complete pipeline that generates a masked ultrasound image that keeps only the contour of a certain object.

Parameters:

  • image – Input 2D grayscale image.

  • top_percent – Fraction of pixels to threshold as white (default 0.93).

  • top_margin – Pixel row margin to remove top noise components (default 5).

  • apply_closing_flag – Whether to perform morphological closing (default True).

Returns:

A grayscale image where only the contour region retains its original intensities.

ultrasound_processing.masking.original_intensity_mask(image: ndarray, smooth: ndarray) → ndarray[source]

Preserve the original grayscale intensities.

Parameters:

  • image – Original 2D grayscale image.

  • smooth – Smooth mask with values in [0, 255].

Returns:

Masked image where the contour regions preserve their original intensities.

ultrasound_processing.masking.remove_small_components(mask: ndarray, top_margin: int) → ndarray[source]

Remove white components (noise) from the top part of the image.

Parameters:

  • mask – Binary mask (0 or 255) (after closing).

  • top_margin – Number of pixels from the top; any component starting above this line will be removed.

Returns:

The mask with small top components removed.

ultrasound_processing.masking.smooth_mask(dilated: ndarray, blur_ksize: Tuple[int, int] = (5, 5)) → ndarray[source]

Apply a Gaussian blur to the dilated contour mask.

Parameters:

  • dilated – Dilated binary contour mask.

  • blur_ksize – Kernel size for Gaussian blur.

Returns:

A smooth mask with values in [0, 255].

ultrasound_processing.masking.threshold_mask(image: ndarray, threshold_value: int) → ndarray[source]

Create a binary mask by thresholding the image: pixels with intensity >= threshold_value become 255 (white), others become 0 (black).

Parameters:

  • image – 2D numpy array of grayscale pixel intensities.

  • threshold_value – Intensity cutoff for binarization.

Returns:

A binary mask as a 2D numpy array of 0s and 255s.

ultrasound_processing.transform_back

ultrasound_processing.transform_back.bilinear_interpolation(frame: ndarray, indices, weights, shape, cone_mask_indices)[source]

Performs bilinear interpolation on the image.

Parameters:

  • frame (np.ndarray) – The input frame.

  • indices (tuple) – Index arrays for R and THETA.

  • weights (tuple) – Weight arrays.

  • shape (tuple) – Shape of the output image.

  • cone_mask_indices (tuple) – Indices for valid cone region.

Returns:

Interpolated image.

Return type:

np.ndarray

ultrasound_processing.transform_back.find_nearest_indices(image_R, image_THETA, frame_R, frame_THETA)[source]

Finds the nearest neighbor indices and interpolation weights.

ultrasound_processing.transform_back.generate_cartesian_volume(depth, thetas, offset, resolution)[source]

Creates a Cartesian grid and corresponding spherical coordinates within a conic frustum.

Returns:

Tuple containing the image shape, filtered R, THETA arrays and valid indices.

ultrasound_processing.transform_back.transform_back(frame, depth, alpha, offset_frame, offset=0, resolution=0.01)[source]

Transforms back the masked image to the original coordinate system. This is the main function that calls the other functions to perform the interpolation.

Parameters:

  • frame (np.ndarray) – The input frame.

  • depth (float) – Depth of the frustum.

  • thetas (Tuple[float, float]) – The range of theta values.

  • alpha (float) – Half angle of the ultrasound device in radians.

  • offset (float) – Offset value between the top of the frame and the US source.

  • offset_frame (float) – Offset value for the frame.

  • resolution (float) – Resolution value for upscaling or downscaling.

Returns:

Interpolated frame.

Return type:

np.ndarray

ultrasound_processing.transform_back.transform_cartesian_to_spherical(X: ndarray, Z: ndarray)[source]

Converts Cartesian coordinates (X, Z) to spherical coordinates (R, THETA).

Parameters:

  • X (np.ndarray) – X coordinates.

  • Z (np.ndarray) – Z coordinates.

Returns:

Radial distances R and polar angles THETA.

Return type:

Tuple[np.ndarray, np.ndarray]

ultrasound_processing.transform_back.transform_spherical_to_cartesian(R: ndarray, THETA: ndarray)[source]

Converts spherical coordinates (R, THETA) to Cartesian (X, Z).

Parameters:

  • R (np.ndarray) – Radial distances.

  • THETA (np.ndarray) – Polar angles.

Returns:

X and Z Cartesian coordinates.

Return type:

Tuple[np.ndarray, np.ndarray]