usseg package

Submodules

usseg.General_functions module

A set of functions to segment and extract data from doppler ultrasound scans

usseg.General_functions.Annotate(input_image_obj, refined_segmentation_mask, Left_dimensions, Right_dimensions, Waveform_dimensions, Left_axis, Right_axis)

Visual aid for evaluating segmentation.

Annotates the original image with the computed components from each of the previous functions by overlaying polygons on the regions of interest (ROIs) and highlighting them in specific colors.

The function draws perimeters around the provided dimensions for the left, right, and waveform components on the segmentation mask. Then, it modifies the input image’s pixel data to overlay these perimeters and color-codes the different regions: the waveform in red and the left/right axes in green, and the bounds of the ticks and labels in magenta.

Parameters:

• input_image_obj (PIL.Image.Image) – The original image to be annotated.

• refined_segmentation_mask (numpy.ndarray) – The segmentation mask that indicates the regions of interest.

• Left_dimensions (tuple) – The (x_min, x_max, y_min, y_max) dimensions for the left region of interest.

• Right_dimensions (tuple) – The (x_min, x_max, y_min, y_max) dimensions for the right region of interest.

• Waveform_dimensions (tuple) – The (x_min, x_max, y_min, y_max) dimensions for the waveform region.

• Left_axis (numpy.ndarray) – The segmentation mask (ticks and labels) for the left axis.

• Right_axis (numpy.ndarray) – The segmentation mask (ticks and labels) for the right axis.

Returns:

The annotated image with ROIs color-coded and highlighted.

Return type:

PIL.Image.Image

usseg.General_functions.Colour_extract(input_image_obj, TargetRGB, cyl_length, cyl_radius)

Extract target colours from image.

The `Colour_extract()` function is deprecated and has been replaced by the function `Colour_extract_vectorised()`. See the documentation for `Colour_extract_vectorised()` for more information.

Parameters:

• input_image_obj (PIL Image) – PIL Image object.

• TargetRGB (list) – triplet of target Red Green Blue colour [Red,Green,Blue].

• cyl_length (int) – length of cylinder.

• cyl_radius (int) – radius of cylinder.

Returns:

PIL JpegImageFile of the filtered image highlighting selected text.

Return type:

COL (JpegImageFile)

usseg.General_functions.Colour_extract_vectorized(input_image_obj, TargetRGB, cyl_length, cyl_radius)

Extracts a specified color from an image using a cylindrical filter in RGB space.

Given an image object and a target RGB color, this function creates a cylindrical filter in RGB space defined by the specified length and radius. It extracts regions of the image that match the color within the defined cylindrical space.

Parameters:

• input_image_obj (np.ndarray) – A 3D numpy array representing the RGB image.

• TargetRGB (list) – A list of three integers representing the target RGB color.

• cyl_length (int) – The length of the cylindrical filter along the axis of the color in RGB space.

• cyl_radius (int) – The radius of the cylindrical filter in RGB space.

Returns:

An image where regions matching the target color are highlighted

and the rest of the image is set to black.

Return type:

output_image (PIL.Image.Image)

usseg.General_functions.Define_end_ROIs(segmentation_mask, Xmin, Xmax, Ymin, Ymax)

Defines regions of interest (ROIs) to the left and right of a segmented waveform for the purpose of searching for axis information. These regions are adjacent to the coarse waveform segmentation.

The function calculates the dimensions of the ROIs based on the given segmentation boundaries. These dimensions are then used to identify and analyze axis labels and tick marks related to the waveform data.

Parameters:

• segmentation_mask (ndarray) – A binary array mask showing the corse segmentation of waveform (1) against background (0).

• Xmin (float) – Minimum X coordinate of the corse segmentation.

• Xmax (float) – Maximum X coordinate of the corse segmentation.

• Ymin (float) – Minimum Y coordinate of the corse segmentation.

• Ymax (float) – Maximum Y coordinate of the corse segmentation.

Returns:

tuple containing:

• Left_dimensions (list) : edge points for the left axes ROI [Xmin, Xmax, Ymin, Ymax].

• Right_dimensions (list) : edge points for the left axes ROI [Xmin, Xmax, Ymin, Ymax].

Return type:

(tuple)

usseg.General_functions.Initial_segmentation(input_image_obj)

Initial segmentation of an ultrasound image.

The function performs an initial coarse segmentation on an RGB image to identify a waveform by converting it to a binary mask, where the waveform is represented by white pixels (1) and the background by black pixels (0). It applies a thresholding algorithm to differentiate the waveform from the background, with additional processing to remove noise, fill holes, and adjust the shape of the segmented area. It also calculates the bounding box coordinates of the waveform.

Parameters:

input_image_filename (str) – Name of file within current directory, or path to a file.

Returns:

tuple containing:

• segmentation_mask (ndarray): A binary array mask showing the coarse segmentation of waveform (1) against background (0).

• Xmin (float): Minimum X coordinate of the segmentation.

• Xmax (float): Maximum X coordinate of the segmentation.

• Ymin (float): Minimum Y coordinate of the segmentation.

• Ymax (float): Maximum Y coordinate of the segmentation.

Return type:

tuple

usseg.General_functions.Metric_check(df)

Performs validation and correction of ultrasound measurement metrics within a DataFrame.

This function identifies the prefix used in the metrics (either left, right, or uterine artery), checks for missing rows,and adds them if necessary. It applies common sense checks to the pulsatility index (PI) and time-averaged maximum velocity (TAmax) values to correct common OCR errors. The function also adjusts the peak systolic (PS) and end diastolic (ED) velocity values based on their relationship with other metrics, ensuring consistency. Lastly, it calculates the systolic over diastolic ratio (S/D), resistance index (RI), and TAmax from the corrected PS and ED values and checks them against the extracted metrics for consistency.

Args:

• df (DataFrame): Extracted data from image

Returns:

• df (DataFrame): DataFrame with corrected values after metric checking calculations

usseg.General_functions.Metric_check_DV(df)

Performs validation and correction of ultrasound measurement metrics within a DataFrame

for Ductus Venosus (DV).

This function performs the same function as Metric_check, but for Ductus Venosus. Metric_check works for left, right and ubilical arteries as their scans all contain the same patient measurements, but DV scans have a seperate set of measurements with their own unique relationship - this function corrects the values for DV scans.

Args:

df (DataFrame): Extracted data from image

Returns:

df(DataFrame): DataFrame with corrected values after metric checking calculations

usseg.General_functions.Plot_Digitized_data(Rticks, Rlocs, Lticks, Llocs, top_curve_coords)

Digitize and plot the data.

This function digitizes and plots the segmented data based on tick marks from the left and right axes and the top curve coordinates. It aligns the data with the given tick marks, inverts the waveform if necessary, and scales the data to an arbitrary time scale and flow rate. The plot is then generated with the x-axis representing the arbitrary time scale and the y-axis showing the flow rate.

Parameters:

• Rticks (list) – A list of tick values on the right axis, assumed to be in ascending order.

• Rlocs (list) – A list of the locations (x, y coordinates) for each tick on the right axis.

• Lticks (list) – A list of tick values on the left axis, assumed to be in ascending order.

• Llocs (list) – A list of the locations (x, y coordinates) for each tick on the left axis.

• top_curve_coords (list) – A list of (x, y) coordinates representing the top curve of the waveform to be digitized.

Returns:

tuple containing:

• Xplot (list): A list of x-values for the digitized data, scaled to an arbitrary time scale.

• Yplot (list): A list of y-values for the digitized data, representing flow rate in cm/s.

• Ynought (list): A list containing the 0 value y co-ordinate for the digitized data (not used).

Return type:

(tuple)

Note

The function adjusts for cases where there is only one tick mark on the right axis, ensuring the digitization process can proceed. It also inverts the waveform if the average flow rate is negative.

usseg.General_functions.Plot_correction(Xplot, Yplot, df)

Adjusts and corrects the digitized waveform data using extracted text data, identifies and filters peaks and troughs, computes hemodynamic parameters, scales the time axis, and plots the corrected waveform.

The function works by first inserting a new column for digitized values in the DataFrame. It processes the waveform to identify and filter peaks and troughs, computes key hemodynamic parameters (PS, ED, S/D, RI, TAmax, PI), and updates these values in the DataFrame. It also scales the x-axis to real-time based on heart rate information and generates a plot of the corrected waveform.

Exceptions are handled by printing traceback information.

Parameters:

• Xplot (list of float) – The x-coordinates (time axis) of the waveform data.

• Yplot (list of float) – The y-coordinates (flowrate axis) of the waveform data.

• df (pandas.DataFrame) – The DataFrame with extracted text data including hemodynamic parameters and heart rate.

Returns:

The DataFrame updated with computed parameters in the “Digitized Value” column.

Return type:

df (pandas.DataFrame)

usseg.General_functions.Scan_type_test(input_image_filename)

Function for yellow filtering an image and searching for a list of target words indicative of a doppler ultrasound scan taken using the Voluson E8, RAB6-D.

Parameters:

input_image_filename (str) – Name of file within current directory, or path to a file.

Returns:

Idicates if the file is a fail (1) - doesn’t meet criteria for a doppler ultrasound, or pass (0) - does meet criteria.

Return type:

Fail (int)

usseg.General_functions.Search_for_labels(Cs, ROIAX, CenPoints, onY, BCs, TYLshift, Side, Left_dimensions, Right_dimensions, input_image_obj, ROI2, ROI3)

Searches for labels within specified regions of an image, extracts text, and attempts to associate it with the nearest tick marks.

This function iterates over a range of threshold values to optimize text extraction from an image. It uses OpenCV for image processing and Pytesseract for OCR to extract text. The text is then attempted to be matched to the nearest tick marks based on center points. The function adapts to the side of the image being analyzed (left or right) and draws rectangles around the detected text. It also warns if characters are too close.

Parameters:

• Cs (tuple) – List of center points.

• ROIAX (ndarray) – Region of Interest (ROI) array for the X axis, modified

• function. (within the) –

• CenPoints (list) – List of center points for detected objects/ticks.

• onY (list) –

• BCs (list) – List of baseline coordinates, likely for the tick marks.

• TYLshift (int) – Shift along the Y axis for thresholding, specific to the

• side. (Left) –

• Side (str) – Side of the image being processed (‘Left’ or ‘Right’).

• Left_dimensions (list) – Dimensions for the left ROI.

• Right_dimensions (list) – Dimensions for the right ROI.

• input_image_obj (ndarray) – Image object to be processed.

• ROI2 (ndarray) – Secondary ROI, stores contour detection data during tick search.

• ROI3 (ndarray) – Axes ROI used for visualisation.

Returns:

tuple containing:

• ROIAX (ndarray): narray defining the ROI to search for the axes.

• number (list): A list of label values found on axis.

• positions (list): A list of positions of the label values.

• empty_to_fill (ndarray): A array showing bounding boxes on image.

Return type:

(tuple)

usseg.General_functions.Search_for_ticks(input_image_obj, Side, Left_dimensions, Right_dimensions)

Search for tick marks on either the left or right axis of an image.

This function locates contours that resemble tick marks by processing an image. It converts the image to grayscale, applies thresholding to generate a binary image, and identifies contours. The contours are then filtered based on their geometric properties. It returns the contours, the region of interest (ROI) of the axis, the center points of the ticks, and additional details of the processing.

Parameters:

• input_image_filename (str) – Name of file within current directory, or path to a file.

• Side (str) – Indicates the ‘Left’ or ‘Right’ axes.

• Left_dimensions (list) – edge points for the left axes ROI [Xmin, Xmax, Ymin, Ymax].

• Right_dimensions (list) – edge points for the left axes ROI [Xmin, Xmax, Ymin, Ymax].

Returns:

tuple containing:

• Cs (tuple) : list of contours for ticks found.

• ROIAX (ndarray) : narray defining the ROI to search for the axes.

• CenPoints (list) : center points for the ticks identified.

• onY (list) : indexes of the contours which lie on the target x plane.

• BCs (list) : Contours of the objects which lie on the target x plane.

• TYLshift (intc) : shift in the x coordninate bounds - reducing the axes ROI in which to search for axes text.

• thresholded_image (ndarray) : Threshold values iterated through.

• Side (str) : Indicates the ‘Left’ or ‘Right’ axes.

• Left_dimensions (list) : edge points for the left axes ROI [Xmin, Xmax, Ymin, Ymax].

• Right_dimensions (list) : edge points for the left axes ROI [Xmin, Xmax, Ymin, Ymax].

• ROI2 (ndarray) : Secondary ROI, stores contour detection data during tick search.

• ROI3 (ndarray) : Axes ROI used for visualisation (not used - only initialised here).

Return type:

(tuple)

usseg.General_functions.Segment_refinement(input_image_obj, Xmin, Xmax, Ymin, Ymax, df, Lnumber, Rnumber)

Refines the segmentation of a waveform within specified bounds, improving the separation between the waveform and background. It processes a given image object within the region of interest (ROI) and generates masks for the waveform and its top curve.

Parameters:

• input_image_obj (ndarray) – An image object, typically read from a file using a library such as OpenCV.

• Xmin (float) – Minimum X coordinate of the segmentation in pixels, defining the left boundary of the ROI.

• Xmax (float) – Maximum X coordinate of the segmentation in pixels, defining the right boundary of the ROI.

• Ymin (float) – Minimum Y coordinate of the segmentation in pixels, defining the bottom boundary of the ROI.

• Ymax (float) – Maximum Y coordinate of the segmentation in pixels, defining the top boundary of the ROI.

Returns:

tuple containing:

• refined_segmentation_mask (ndarray): A binary array mask showing the refined segmentation of the waveform (value 1) against the background (value 0).

• top_curve_mask (ndarray): A binary array representing a curve along the top of the refined waveform segmentation.

• top_curve_coords (ndarray): An array of coordinates (row, column) for the top curve of the waveform.

Return type:

(tuple)

usseg.General_functions.Text_from_greyscale(input_image_obj, COL)

Extracts and processes text from a greyscale image using OCR (Optical Character Recognition).

This function applies preprocessing to the image to enhance text recognition, then uses tesseract OCR to extract text data. It groups the text into lines and words, filters out irrelevant parts of the image, and performs post-processing to structure the data into a DataFrame. It also includes matching of specific target words and extraction of associated numeric values and units, and uses known relationships between extracted metrics to correct errors in text recognition. The function utilizes PIL for image manipulation, numpy for array operations, scipy for image processing, pytesseract for OCR, and OpenCV for drawing bounding boxes around the text.

Parameters:

• input_image_filename (str) – Name of file within current directory, or path to a file.

• COL (JpegImageFile) – PIL JpegImageFile of the filtered image highlighting yellow text.

Returns:

tuple containing:

• Fail (int) - Checks if the function has failed (1), or passed (0).

• df (DataFrame) - Dataframe with columns ‘Line’, ‘Word’, ‘Value’, ‘Unit’. populated with data extracted from the image with tesseract.

Return type:

(tuple)

usseg.General_functions.appendSpherical_1point(xyz)

Appends spherical coordinates to a 3D point in Cartesian coordinates.

This function takes a single point (xyz) in Cartesian coordinates and calculates its corresponding spherical coordinates. It appends the radial distance from the origin (r), the angle in the XY plane from the positive X-axis (theta), and the angle from the positive Z-axis (alpha), all in degrees.

Parameters:

xyz (np.ndarray) – A numpy array of shape (3,) representing the x, y, and z Cartesian coordinates of a point.

Returns:

The input array with the spherical coordinates appended, resulting in a numpy array of shape (7,).

Return type:

ptsnew (ndarray)

usseg.General_functions.check_inverted_curve(top_curve_mask, Ymax, Ymin, tol=0.25)

Checks to see if top curve mask is of an inverted waveform

Parameters:

• top_curve_mask (ndarray) – A binary array showing a curve along the top of the refined waveform.

• Ymax (float) – Maximum Y coordinate of the segmentation in pixels.

• Ymin (float) – Minimum Y coordinate of the segmentation in pixels.

• tol (float, optional) – If the top curve occupies less than tol * (Ymax - Ymin) rows, then the curve is assumed to be inverted (that is True is returned). If the top curve occupies more than or equal to this number of rows, the False is returned and the curve is assumed to be non-inverted. Defaults to 0.45.

Returns:

True if the top curve is of an inverted waveform, False is the top curve is of a non-inverted waveform.

Return type:

return value (bool)

usseg.General_functions.execute_on_main_thread_and_wait(func, *args, **kwargs)

Executes a function on the main thread and waits for it to complete.

This function is useful for ensuring that Tkinter objects are manipulated safely from worker threads. Tkinter objects are not thread-safe and can only be manipulated from the main thread.

Parameters:

• func – The function to be executed on the main thread.

• *args – The arguments to be passed to the function.

• **kwargs – The keyword arguments to be passed to the function.

Returns:

The result of the function, or None if the function raised an exception.

usseg.General_functions.upscale_both_images(PIL_img, cv2_img, max_length=950, min_length=950)

For testing improved text extraction

Upscales both a PIL and an OpenCV image to a specified maximum length while maintaining their aspect ratios. If the longest edge of an image is already greater than or equal to the specified minimum length, the image will not be upscaled.

Parameters:

• PIL_img (PIL.Image.Image) – The image to upscale using the PIL library.

• cv2_img (numpy.ndarray) – The image to upscale using the OpenCV library.

• max_length (int, optional) – The maximum length of the longest edge after upscaling. Defaults to 950.

• min_length (int, optional) – The minimum length required to trigger upscaling. If the longest edge of the image is already greater than or equal to this length, upscaling does not occur. Defaults to 950.

Returns:

A tuple containing the upscaled PIL.Image.Image and upscaled numpy.ndarray (OpenCV image) respectively.

Return type:

tuple

usseg.Organise_files module

Searches a directory and identifies images likely to be doppler ultrasounds

usseg.Organise_files.check_file_for_us(file_path)

Checks a single file to see if it’s a likely ultrasound and returns its path.

Parameters:

file_path – The path to the file to be checked.

Returns:

A tuple of (patient_id, file_path) if the file is a likely ultrasound, or None otherwise.

usseg.Organise_files.get_likely_us(root_dir, pickle_path=None, use_parallel=True)

Searches a directory and identifies the images that are likely to be doppler ultrasounds.

Parameters:

• root_dir – The path to the directory to be searched.

• pickle_path – The path to the pickle file to save the results to. If None, the results will be saved to the current directory.

• use_parallel – Whether to use a parallel thread pool to process the files.

Returns:

A list of paths to the images that are likely to be doppler ultrasounds.

usseg.Refined_anon_2_html module

Segments the ultrasound images

usseg.Refined_anon_2_html.segment(filenames=None, output_dir=None, pickle_path=None)

Segments the pre-selected ultrasound images

Parameters:

• filenames (str or list, optional) – If string, must be either a single file name path or a path to a pickle object containing the list of files. Pickle objects are expected to have the extension “.pkl” or “.pickle”. If a list, must be a list of filenames to ultrasound images to segment. If None, will load a test image.

• output_dir (str, optional) – Path to the output directory to store annoated images. If None, will load from config file. Defaults to None.

• pickle_path (str or bool) – If pickle_path is False, will not store the list of likely us images as a pickle file. If None, will load the pickle path from “config.toml”. Else if a string, will dump the pickled list to the specified path. Defaults to None.

Returns:

tuple containing:

• filenames (list): A list of the paths to the images that were segmented.

• Digitized_scans (list): A list of the paths to the digitized scans.

• Annotated_scans (list): A list of the paths to the annotated scans.

• Text_data (list): A list of the text data extracted from the scans, as strings.

Return type:

(tuple)

usseg.Refined_anon_2_html.setup_tesseract()

Checks tesseract is set up appropriately

Currently does nothing on a linux system and sets the pytesseract.pytesseract.tesseract_cmd to “C:/Program Files/Tesseract-OCR/tesseract.exe” for Windows and Cygwin systems.

Any other system (including MACOS) a warning is displayed and nothing is done. It is expected, for non-Windows/Cygwin systems that tesseract is available in the PATH.

If this is not the desired behaviour, please specify tesseract_cmd after running this script.

Returns:

Returns the tesseract version installed.

Return type:

tesseract_version (str)

usseg.Single_image_processing module

Segment a single ultrasound image object.

This module provides a number of functions for segmenting single ultrasound images, extracting segmentation and textual data from the images.

Usage:

To segment a single ultrasound image, you can use the following code:

```python from usseg.Single_image_processing import data_from_image

# Load the ultrasound image. PIL_img = … cv2_img = …

# Extract segmentation and textual data from the image. df, XYdata = data_from_image(PIL_img, cv2_img)```

usseg.Single_image_processing.data_from_image(PIL_img, cv2_img)

Extract segmentation and textual data from an image.

Parameters:

• PIL_img (Pillow Image object) – The image in Pillow format.

• cv2_img (cv2 Image object) – The image in cv2 format.

Returns:

Dataframe of extracted text. XYdata (list) : X and Y coordinates of the extracted segmentation.

Return type:

df (pandas dataframe)

usseg.example module

usseg.example.main(PIL_img, cv2_img)

Main function that performs all of the segmentation on a root directory

usseg.main module

Main script for running the file organisation and segmentation.

This script can be used to segment ultrasound images and generate an output.html file containing the segmented output.

Usage:

python usseg.main.py root_dir

where root_dir is the root directory containing the ultrasound images to be segmented.

Example:

To segment all of the ultrasound images in the directory E:/us-data-anon, you would run the following command:

python usseg.main.py E:/us-data-anon

This will generate an output.html file in the current directory containing the segmented output for all of the ultrasound images in the E:/us-data-anon directory.

Configuration options:

The script can be configured using the config.toml file. The config.toml file should be placed in the same directory as the script.

The only configuration option currently supported is the root_dir key. The root_dir key specifies the root directory containing the ultrasound images to be segmented.

Known issues and limitations:

The script is currently under development and may contain bugs.

usseg.main.main(root_dir)

Main function that performs all of the segmentation on a root directory

usseg.main.prof(fn, *args, **kwargs)

usseg.visualisation_html module

usseg.visualisation_html.generate_html(scans, Annotated_scans, Digitized_scans, tables)

usseg.visualisation_html.generate_html_from_pkl()

Generates a html file from the previously processed pickle files

Module contents

Initialises the ultrasound-segmenetation module