pyquantus.parse.clarius module

class pyquantus.parse.clarius.ClariusParser(rf_raw_path: str, env_tgc_yml_path: str, rf_yml_path: str, visualize: bool = False, use_tgc: bool = False)

Bases: object

class ClariusInfoStruct

Bases: InfoStruct

ClariusInfoStruct is a subclass of InfoStruct that represents information about an ultrasound scan’s data structure.

samplesPerLine

The number of samples per line in the scan.

Type:

int

numLines

The total number of lines in the scan.

Type:

int

sampleSize

The size of each sample, typically represented as a string.

Type:

str

class ParserVisualizations(rf_raw_data_3d: ndarray, rf_no_tgc_raw_data_3d: ndarray, default_frame: int, rf_sampling_rate: int, full_depth_mm: ndarray, delay_samples: int, hilbert_transform_axis: int = 1)

Bases: object

This class is responsible for visualizing the data processed by the ClariusParser. It includes methods to plot 1D signals, their FFTs, and 2D images of the envelope.

image_envelope_2d(envelope_type: str, title: str, clip_fact: float, dyn_range: float) → None

Plots a 2D signal envelope in decibels.

This function takes a 2D array representing a signal envelope, applies a rotation and flipping transformation, converts it to a logarithmic decibel scale, applies clipping and normalization, and displays it as an image plot.

Parameters:

  • envelope_type (str) – ‘TGC’ or ‘No TGC’

  • title (str) – The title of the plot.

  • clip_fact (float) – Clipping factor for dynamic range.

  • dyn_range (float) – Dynamic range in dB.

Returns:

None

plot_1d_signal_and_fft(signal_type: str, title: str)

Plots a 1D signal and its corresponding FFT.

Parameters:

  • signal_type (str) – Type of the signal to be plotted (‘TGC’ or ‘No TGC’).

  • title (str) – Title for the plots.

static rotate_flip(two_dimension_array: ndarray) → ndarray

Rotates the input 2D array counterclockwise by 90 degrees and then flips it vertically.

Parameters:

two_dimension_array (np.ndarray) – The input 2D array to be transformed.

Returns:

The rotated and flipped 2D array.

Return type:

np.ndarray

class YmlParser(yml_path)

Bases: object

This class reads YAML file data related to ultrasound imaging parameters. It extracts information from two YAML files:

1. *rf.yml - Contains data such as sampling frequency, probe details, imaging parameters, and transmission settings. 2. *env.tgc.yml - Contains time gain compensation (TGC) data.

The extracted data is used to generate new imaging data without TGC, requiring TGC values for processing.

assess_software_version(software_version)

Checks if the current software version (from env.yml or rf.yml) is in the list of valid versions.

Logs an informational message if the version is valid and a warning if it is not.

load_env_tgc_yml()

Loads and parses an environmental TGC YAML file if the file extension is “env.tgc.yml”. The method reads the YAML file, extracts relevant fields, and maps them to class attributes.

Attributes Populated: - frames (int): Number of frames specified in the file. - timestamps (dict): Dictionary mapping timestamps to lists of depth and dB values. Each entry in the list is a dictionary with:

  • depth (float): Depth value in millimeters.

  • dB (float): Gain value in decibels.

Raises: - Exception: If an error occurs while loading the YAML file.

load_rf_yml()

Loads and parses an RF YAML file if the file extension is “rf.yml”. The method reads the YAML file, extracts relevant fields, and maps them to class attributes.

Attributes Populated: - software_version (str): Software version from the YAML file. - iso_time_date (str): ISO formatted timestamp. - probe_version (str): Version of the probe. - probe_elements (int): Number of probe elements. - probe_pitch (float): Probe pitch value. - probe_radius (float): Probe radius value. - frames (int): Number of frames in the file. - frame_rate (float): Frame rate value. - transmit_frequency (float): Transmit frequency. - imaging_depth (float): Imaging depth. - focal_depth (float): Focal depth. - auto_gain (bool): Whether auto gain is enabled. - mla (bool): Multi-line acquisition status. - tgc (dict): Time gain compensation settings. - size (dict): Size specifications. - type (str): Type information. - compression (str): Compression method. - sampling_rate (float): Sampling rate value. - delay_samples (int): Number of delay samples. - lines (dict): Line specifications. - focus (list): List of focus parameters.

Raises: - Exception: If an error occurs while loading the YAML file.

create_full_imaging_depth_array()

Generates an array representing the full imaging depth in millimeters.

This function calculates the depth array based on the imaging depth and delay samples, ensuring accurate mapping of signal depth.

Returns:

tuple: (full_imaging_depth_array_1d_mm, trimmed_signal_length, delay_samples)

  • full_imaging_depth_array_1d_mm: 1D NumPy array of depth values in mm.

  • trimmed_signal_length: Length of the trimmed RF signal.

  • delay_samples: Number of delay samples before the valid signal starts.

static extract_first_num(input_string: str) → float | int | None

Extracts the first number (integer or floating-point) from a string. Returns an int if the number is an integer, otherwise returns a float. If no number is found, returns None.

read_rf_raw()

Reads raw RF data from a binary file, extracting header information, timestamps, and frame data.

This function follows the format used by Clarius’ ultrasound raw data, as found in their GitHub repository: https://github.com/clariusdev/raw/blob/master/common/python/rdataread.py

The function parses: - A 5-field header (id, frames, lines, samples, samplesize) - Timestamps for each frame - RF data for each frame

The loaded data is stored as instance attributes: - self.rf_raw_hdr: Dictionary containing header information - self.rf_raw_timestamps_1d: NumPy array of frame timestamps - self.rf_raw_data_3d: NumPy array of the RF data

Raises:

  • FileNotFoundError – If the file is not found.

  • ValueError – If the file format is incorrect.

reconstruct_bmode()
remove_tgc(visualize=False) → None

Processes RF data to remove the time-gain compensation (TGC) effect.

self.clean_tgc_data

A dictionary where: - Keys (str): Timestamps from env_tgc_yml_obj.timestamps. - Values (list[dict]): Processed TGC data lists, falling back to previous valid data or default TGC data if necessary.

Type:

dict

Returns:

None

set_data_of_clarius_info_struct()
set_default_tgc_data() → None

Extracts and processes TGC (Time Gain Compensation) data from the RF YAML object.

This function parses key-value pairs from the RF TGC data, extracts depth and dB values, and stores them in a structured format within self.default_tgc_data.

self.default_tgc_data

A list of dictionaries, each containing: - ‘depth’ (float): The extracted depth value from the length key. - ‘dB’ (float): The extracted dB value from the dB key.

Type:

list[dict]

Returns:

None

class pyquantus.parse.clarius.ClariusTarUnpacker(path: str, extraction_mode: str)

Bases: object

A class for extracting and processing .tar archives containing .lzo and .raw files.

tar_files_path

The path to the directory containing .tar files.

Type:

str

extraction_mode

Extraction mode - either “single” or “multiple”.

Type:

str

lzo_py_file_path

Path to the LZO executable for decompression (Windows only).

Type:

str

check_input_path()

Validates the input path based on the specified extraction mode.

This method checks whether the provided path exists and conforms to the expected format for different extraction modes:

  • “single_sample”: The path must be a directory containing at least

one .tar file. - “multiple_samples”: The path must be a directory containing at least one subdirectory. - “single_tar”: The path must be a valid .tar file.

Returns:

True if the path is valid for the specified extraction mode,

otherwise False with a warning message.

Return type:

bool

delete_hidden_files_in_extracted_folders()

Deletes hidden files (starting with a dot) in extracted folders.

extract_tar_files()

Extracts all non-hidden tar files in the specified sample folder. If self.single_tar_extraction is True, self.path should be a .tar file.

static get_folder_path_from_file_path(file_path: str) → str

Returns the absolute directory path of the given file.

read_lzo_files()

Detects the operating system and decompresses .lzo files accordingly.

Workflow: 1. Determines whether the system is Windows or macOS. 2. Logs the detected operating system. 3. If running on Windows:

  • Constructs the path to the LZO executable.

  • Checks if the executable exists.

  • Iterates through the .lzo files and decompresses them using lzop.py.

  1. If running on macOS:

    • Attempts to decompress .lzo files using the lzop command.

    • If lzop is missing, checks for Homebrew.

    • Installs lzop via Homebrew if necessary.

    • Decompresses .lzo files after ensuring lzop is installed.

  2. Logs successes and failures, handling potential errors like:

    • FileNotFoundError

    • PermissionError

    • subprocess.CalledProcessError

    • Other unexpected exceptions.

Returns: - Logs the status of each decompression attempt. - Exits the program if lzop is missing on macOS and cannot be installed.

set_path_of_extracted_folders()

Finds and stores paths of extracted folders inside self.path.

set_path_of_lzo_files_inside_extracted_folders()

Finds and stores paths of .lzo files inside extracted folders.

set_path_of_raw_files_inside_extracted_folders()

Searches for .raw files inside extracted folders and stores their paths.

pyquantus.parse.clarius.clariusRfParser(imgFilename: str, imgTgcFilename: str, infoFilename: str, phantomFilename: str, phantomTgcFilename: str, phantomInfoFilename: str, visualize: bool = False, use_tgc: bool = False) → tuple
pyquantus.parse.clarius.get_signal_envelope_xd(signal_xd: ndarray, hilbert_transform_axis: int) → ndarray

Computes the envelope of an x-dimensional signal using the Hilbert transform.

This function mirrors the input signal along all its dimensions, applies the Hilbert transform along the specified axis, and then extracts the original signal envelope from the analytic signal.

Parameters:

  • signal_xd (np.ndarray) – The input x-dimensional signal represented as a NumPy array.

  • hilbert_transform_axis (int) – The axis along which the Hilbert transform is applied.

Returns:

The computed signal envelope of the input signal.

Return type:

np.ndarray