zea.data.convert.verasonics¶

Functionality to convert Verasonics MATLAB workspace to the zea format.

Example of saving the entire workspace to a .mat file (MATLAB):

>> setup_script;
>> VSX;
>> save_raw('C:/path/to/raw_data.mat');

Then convert the saved raw_data.mat file to zea format using the following code (Python):

from zea.data.convert.verasonics import VerasonicsFile

VerasonicsFile("C:/path/to/raw_data.mat").to_zea("C:/path/to/output.hdf5")

Or alternatively, use the script below to convert all .mat files in a directory:

python zea/data/convert/verasonics.py "C:/path/to/directory"

or without the directory argument, the script will prompt you to select a directory using a file dialog.

Event structure¶

By default the zea dataformat saves all the data to an hdf5 file with the following structure:

regular_zea_dataset.hdf5
├── data
└── scan
      └── center_frequency: 1MHz

The data is stored in the data group and the scan parameters are stored in the scan. However, when we do an adaptive acquisition, some scanning parameters might change. These blocks of data with consistent scanning parameters we call events. In the case we have multiple events, we store the data in the following structure:

zea_dataset.hdf5
├── event_0
│   ├── data
│   └── scan
│       └── center_frequency: 1MHz
├── event_1
│   ├── data
│   └── scan
│       └── center_frequency: 2MHz
├── event_2
│   ├── data
│   └── scan
└── event_3
    ├── data
    └── scan

This structure is supported by the zea toolbox. The way we can save the data in this structure from the Verasonics, is by changing the setup script to keep track of the TX struct at each event.

The way this is done is still in development, an example of such an acquisition script that is compatible with saving event structures is found here: setup_agent.m

Adding additional elements¶

You can add additional elements to the dataset by defining a function that reads the data from the file and returns a DatasetElement. Then pass the function to the to_zea method as a list.

def read_max_high_voltage(file):
    lens_correction = file["Trans"]["lensCorrection"][:].item()
    return lens_correction


def read_high_voltage_func(file):
    return DatasetElement(
        group_name="scan",
        dataset_name="max_high_voltage",
        data=read_max_high_voltage(file),
        description="The maximum high voltage used by the Verasonics system.",
        unit="V",
    )


VerasonicsFile("C:/path/to/raw_data.mat").to_zea(
    "C:/path/to/output.hdf5",
    [read_high_voltage_func],
)

Functions

`convert_verasonics`(args)	Converts a Verasonics MATLAB workspace file (.mat) or a directory containing multiple such files to the zea format.
`get_answer`(prompt[, additional_options])	Get a yes or no answer from the user.

Classes

VerasonicsFile(name[, mode, driver, libver, ...])

HDF5 File class for Verasonics MATLAB workspace files.

class zea.data.convert.verasonics.VerasonicsFile(name, mode='r', driver=None, libver=None, userblock_size=None, swmr=False, rdcc_nslots=None, rdcc_nbytes=None, rdcc_w0=None, track_order=None, fs_strategy=None, fs_persist=False, fs_threshold=1, fs_page_size=None, page_buf_size=None, min_meta_keep=0, min_raw_keep=0, locking=None, alignment_threshold=1, alignment_interval=1, meta_block_size=None, *, track_times=False, **kwds)[source]¶

Bases: File

HDF5 File class for Verasonics MATLAB workspace files.

This class extends the h5py.File class to handle Verasonics-specific data structures and conventions.

Create a new file object.

See the h5py user guide for a detailed explanation of the options.

name

Name of the file on disk, or file-like object. Note: for files created with the ‘core’ driver, HDF5 still requires this be non-empty.

mode

r Readonly, file must exist (default) r+ Read/write, file must exist w Create file, truncate if exists w- or x Create file, fail if exists a Read/write if exists, create otherwise

driver

Name of the driver to use. Legal values are None (default, recommended), ‘core’, ‘sec2’, ‘direct’, ‘stdio’, ‘mpio’, ‘ros3’.

libver

Library version bounds. Supported values: ‘earliest’, ‘v108’, ‘v110’, ‘v112’, ‘v114’, ‘v200’ and ‘latest’ depending on the version of libhdf5 h5py is built against.

userblock_size

Desired size of user block. Only allowed when creating a new file (mode w, w- or x).

swmr

Open the file in SWMR read mode. Only used when mode = ‘r’.

rdcc_nslots

The number of chunk slots in the raw data chunk cache for this file. Increasing this value reduces the number of cache collisions, but slightly increases the memory used. Due to the hashing strategy, this value should ideally be a prime number. As a rule of thumb, this value should be at least 10 times the number of chunks that can fit in rdcc_nbytes bytes. For maximum performance, this value should be set approximately 100 times that number of chunks. The default value is 521. Applies to all datasets unless individually changed.

rdcc_nbytes

Total size of the dataset chunk cache in bytes. The default size per dataset is 1024**2 (1 MiB) for HDF5 before 2.0 and 8 MiB for HDF5 2.0 and later. Applies to all datasets unless individually changed.

rdcc_w0

The chunk preemption policy for all datasets. This must be between 0 and 1 inclusive and indicates the weighting according to which chunks which have been fully read or written are penalized when determining which chunks to flush from cache. A value of 0 means fully read or written chunks are treated no differently than other chunks (the preemption is strictly LRU) while a value of 1 means fully read or written chunks are always preempted before other chunks. If your application only reads or writes data once, this can be safely set to 1. Otherwise, this should be set lower depending on how often you re-read or re-write the same data. The default value is 0.75. Applies to all datasets unless individually changed.

track_order

Track dataset/group/attribute creation order under root group if True. If None use global default h5.get_config().track_order.

track_times: bool or None, default: False

If True, store timestamps for this group in the file. If None, fall back to the default value.

fs_strategy

The file space handling strategy to be used. Only allowed when creating a new file (mode w, w- or x). Defined as: “fsm” FSM, Aggregators, VFD “page” Paged FSM, VFD “aggregate” Aggregators, VFD “none” VFD If None use HDF5 defaults.

fs_page_size

File space page size in bytes. Only used when fs_strategy=”page”. If None use the HDF5 default (4096 bytes).

fs_persist

A boolean value to indicate whether free space should be persistent or not. Only allowed when creating a new file. The default value is False.

fs_threshold

The smallest free-space section size that the free space manager will track. Only allowed when creating a new file. The default value is 1.

page_buf_size

Page buffer size in bytes. Only allowed for HDF5 files created with fs_strategy=”page”. Must be a power of two value and greater or equal than the file space page size when creating the file. It is not used by default.

min_meta_keep

Minimum percentage of metadata to keep in the page buffer before allowing pages containing metadata to be evicted. Applicable only if page_buf_size is set. Default value is zero.

min_raw_keep

Minimum percentage of raw data to keep in the page buffer before allowing pages containing raw data to be evicted. Applicable only if page_buf_size is set. Default value is zero.

locking

The file locking behavior. Defined as:

False (or “false”) – Disable file locking
True (or “true”) – Enable file locking
“best-effort” – Enable file locking but ignore some errors
None – Use HDF5 defaults

Warning

The HDF5_USE_FILE_LOCKING environment variable can override this parameter.

alignment_threshold

Together with alignment_interval, this property ensures that any file object greater than or equal in size to the alignment threshold (in bytes) will be aligned on an address which is a multiple of alignment interval.

alignment_interval

This property should be used in conjunction with alignment_threshold. See the description above. For more details, see https://support.hdfgroup.org/documentation/hdf5/latest/group___f_a_p_l.html#gab99d5af749aeb3896fd9e3ceb273677a

meta_block_size

Set the current minimum size, in bytes, of new metadata block allocations. See https://support.hdfgroup.org/documentation/hdf5/latest/group___f_a_p_l.html#ga8822e3dedc8e1414f20871a87d533cb1

Additional keywords

Passed on to the selected file driver.

property bandwidth_percent¶: Receive bandwidth as a percentage of center frequency.

static cast_to_integer(dataset)[source]¶: Cast a h5py dataset to an integer.

static decode_string(dataset)[source]¶

Decode a string dataset.

Return type:: str

property demodulation_frequency¶: Demodulation frequency of the probe from the file in Hz.

dereference_all(dataset, func=None)[source]¶

Dereference all elements in a dataset.

Parameters:

dataset (h5py.Dataset) – The dataset to dereference.
func (callable, optional) – A function to apply to each dereferenced element.

Returns:

The dereferenced data.

Return type:

list

dereference_index(dataset, index, event=None, subindex=None)[source]¶

Get the element at the given index from the dataset, dereferencing it if necessary.

MATLAB stores items in struct array differently depending on the size. If the size is 1, the item is stored as a regular dataset. If the size is larger, the item is stored as a dataset of references to the actual data.

This function dereferences the dataset if it is a reference. Otherwise, it returns the dataset.

Parameters:

dataset (h5py.Dataset) – The dataset to read the element from.
index (int) – The index of the element to read.
event (int, optional) – The event index. Usually we store each event in the second dimension of the dataset. Defaults to None in this case we assume that there is only a single event.
subindex (slice, optional) – The subindex of the element to read after referencing the actual data. Defaults to None. In this case, all the data is returned.

property element_width¶: The element width in meters from the file.

property end_samples¶: The index of the last sample for each receive event.

get_frame_count(buffer_index=0)[source]¶: Get the total number of frames in the RcvBuffer buffer.

get_frame_indices(frames, buffer_index=0)[source]¶

Creates a numpy array of frame indices from the file and the frames argument.

Parameters:: frames (str) – The frames argument. This can be “all”, a range of integers (e.g. “4-8”), or a list of frame indices.
Returns:: The frame indices.
Return type:: frame_indices (np.ndarray)

get_image_data_p_frame_order(buffer_index=0)[source]¶

The order of frames in the ImgDataP buffer.

Because of the circular buffer used in Verasonics, the frames in the ImgDataP buffer are not necessarily in the correct order. This function computes the correct order of frames.

get_indices_to_reorder(first_frame, n_frames)[source]¶

get_raw_data_order(buffer_index=0)[source]¶

The order of frames in the RcvBuffer buffer.

Because of the circular buffer used in Verasonics, the frames in the RcvBuffer buffer are not necessarily in the correct order. This function computes the correct order of frames.

static get_reference_size(dataset)[source]¶: Get the size of a reference dataset.

property is_baseband_mode¶

If the data is captured in ‘BS100BW’ mode or ‘BS50BW’ mode.

The data is stored as complex IQ data.
The sampling frequency is halved.
Two sequential samples are interpreted as a single complex sample. Therefore, we need to halve the sampling frequency.

property is_new_save_raw_format¶

property lens_correction¶

1 way delay in wavelengths thru lens

Type:: The lens correction

load_convert_config()[source]¶

Can load additional conversion configuration from a convert.yaml file.

The convert.yaml file should be in the same directory as the .mat file and have the following structure:

files:
- name: raw_data.mat
  first_frame: 26  # 0-based indexing
  frames: 30-99  # 0-based indexing

If first_frame is provided, it will reorder the frames first and use the frames key to subsample afterwards.

In the example frames: 30-99 means frames 30 to 99 inclusive.

Returns:

The configuration for the current file, or an empty dict if no: configuration is found.

Return type:

dict

property n_ax¶: Number of axial samples.

planewave_focal_distance_to_inf(focus_distances, t0_delays, tx_apodizations)[source]¶

Detects plane wave transmits and sets the focus distance to infinity.

Parameters:

focus_distances (np.ndarray) – The focus distances of shape (n_tx,).
t0_delays (np.ndarray) – The t0 delays of shape (n_tx, n_el).
tx_apodizations (np.ndarray) – The apodization of shape (n_tx, n_el).

Returns:

The focus distances of shape (n_tx,).

Return type:

focus_distances (np.ndarray)

Note

This function assumes that the probe_geometry is a 1d uniform linear array. If not it will warn and return.

property probe_center_frequency¶: Center frequency of the probe from the file in Hz.

property probe_connector¶: Probe connector indices.

property probe_geometry¶: The probe geometry of shape (n_el, 3).

property probe_name¶: The name of the probe from the file.

property probe_unit¶: The unit the probe dimensions are defined in.

read_azimuth_angles(tx_order, event=None)[source]¶: Read the azimuth angles of shape (n_tx,) from the file.

read_beamsteering_angles(tx_order, event=None)[source]¶

Beam steering angles in radians (theta, alpha) for each transmit.

Returns:: The beam steering angles of shape (n_tx, 2).
Return type:: angles (np.ndarray)

read_center_frequencies(tx_waveform_indices)[source]¶: Center frequencies of the transmits from the file in Hz.

read_center_frequency(waveform_index)[source]¶: Center frequency of the transmit from the file in Hz.

read_focus_distances(tx_order, event=None)[source]¶

Reads the focus distances from the file.

Parameters:: tx_order (list) – The order in which the transmits appear in the events.
Returns:: The focus distances of shape (n_tx,) in meters.
Return type:: focus_distances (list)

read_image_data_p(event=None, frames='all', buffer_index=0)[source]¶

Reads the image data from the file.

Uses the ImgDataP buffer, which is used for spatial filtering and persistence processing. Generally, this buffer does not contain the same frames as the raw data buffer. This happens because the Verasonics often does not reconstruct every acquired frame. This means that the images in this buffer often skip frames, and span a longer time period than the raw data buffer.

Returns:: The image data.
Return type:: image_data (np.ndarray)

read_initial_times(rcv_order)[source]¶

Reads the initial times from the file.

Parameters:

rcv_order (list) – The order in which the receives appear in the events.
wavelength (float) – The wavelength of the probe.

Returns:

The initial times of shape (n_rcv,).

Return type:

initial_times (np.ndarray)

read_polar_angles(tx_order, event=None)[source]¶: Read the polar angles of shape (n_tx,) from the file.

read_raw_data(event=None, frames='all', buffer_index=0, first_frame_idx=None)[source]¶

Read the raw data from the file.

Returns:: The raw data of shape (n_rcv, n_samples).
Return type:: raw_data (np.ndarray)

read_t0_delays_apod(tx_order, event=None)[source]¶

Read the t0 delays and apodization from the file.

Returns:: The t0 delays of shape (n_tx, n_el). apod (np.ndarray): The apodization of shape (n_el,).
Return type:: t0_delays (np.ndarray)

read_transmit_events(event=None, frames='all', allow_accumulate=False, buffer_index=0)[source]¶

Read the events from the file and finds the order in which transmits and receives appear in the events.

Parameters:

event (int, optional) – The event index. Defaults to None.
frames (str or list, optional) – The frames to read. Defaults to “all”.
allow_accumulate (bool, optional) – Sometimes, some transmits are already accumulated on the Verasonics system (e.g. harmonic imaging through pulse inversion). In this case, the mode in the Receive structure is set to 1 (accumulate). If this flag is set to False, an error is raised when such a mode is detected.
buffer_index (int, optional) – The buffer index to read from. Defaults to 0.

Returns:

(tx_order, rcv_order, time_to_next_acq): tx_order (list): The order in which the transmits appear in the events. rcv_order (list): The order in which the receives appear in the events. time_to_next_acq (np.ndarray): The time to next acquisition of shape (n_acq, n_tx).

Return type:

tuple

read_transmit_origins(tx_order, event=None)[source]¶

Reads the transmit origins from the file.

Parameters:: tx_order (list) – The order in which the transmits appear in the events.
Returns:: The transmit origins of shape (n_tx, 3) in meters.
Return type:: origins (np.ndarray)

read_verasonics_file(event=None, additional_functions=None, frames=None, allow_accumulate=False, buffer_index=0)[source]¶

Reads data from a .mat Verasonics output file.

Parameters:

event (int, optional) – The event index. Defaults to None in this case we assume the data file is stored without event structure.
additional_functions (list, optional) – A list of functions that read additional data from the file. Each function should take the file as input and return a DatasetElement. Defaults to None.
frames (str or list of int, optional) – The frames to add to the file. This can be a list of integers, a range of integers (e.g. 4-8), or ‘all’. Defaults to None, which means all frames, unless specified in a convert.yaml file.
allow_accumulate (bool, optional) – Sometimes, some transmits are already accumulated on the Verasonics system (e.g. harmonic imaging through pulse inversion). In this case, the mode in the Receive structure is set to 1 (accumulate). If this flag is set to False, an error is raised when such a mode is detected.
buffer_index (int, optional) – The buffer index to read from. Defaults to 0.

read_waveforms(tx_order, event=None)[source]¶

Read the waveforms from the file.

Returns:: The waveforms of shape (n_tx, n_samples).
Return type:: waveforms (np.ndarray)

property sampling_frequency¶: The sampling frequency in Hz from the file.

property sound_speed¶: Speed of sound in the medium in m/s.

property start_samples¶: The index of the first sample for each receive event.

property tgc_gain_curve¶: The TGC gain curve from the file interpolated to the number of axial samples (n_ax,).

to_zea(output_path, additional_functions=None, frames=None, allow_accumulate=False, enable_compression=True)[source]¶

Converts the Verasonics file to the zea format.

Parameters:

output_path (str) – The path to the output file (.hdf5 file).
additional_functions (list, optional) – A list of functions that read additional data from the file. Each function should take the file as input and return a DatasetElement. Defaults to None.
frames (str or list of int, optional) – The frames to add to the file. This can be a list of integers, a range of integers (e.g. 4-8), or ‘all’. Defaults to None, which means all frames are used, unless specified otherwise in a convert.yaml file.
allow_accumulate (bool, optional) – Sometimes, some transmits are already accumulated on the Verasonics system (e.g. harmonic imaging through pulse inversion). In this case, the mode in the Receive structure is set to 1 (accumulate). If this flag is set to False, an error is raised when such a mode is detected. Defaults to False.
enable_compression (bool, optional) – Whether to enable compression when saving the zea file. Defaults to True.

property wavelength¶: Wavelength of the probe from the file in meters.

zea.data.convert.verasonics.convert_verasonics(args)[source]¶

Converts a Verasonics MATLAB workspace file (.mat) or a directory containing multiple such files to the zea format.

Parameters:

args (argparse.Namespace) –

An object with attributes:

src (str): Source folder path.
dst (str): Destination folder path.
frames (list[str]): MATLAB frames spec (e.g., [“all”], integers, or ranges like “4-8”)
allow_accumulate (bool): Whether to allow accumulate mode.
device (str): Device to use for processing.

zea.data.convert.verasonics.get_answer(prompt, additional_options=None)[source]¶

Get a yes or no answer from the user. There is also the option to provide additional options. In case yes or no is selected, the function returns a boolean. In case an additional option is selected, the function returns the selected option as a string.

Parameters:

prompt (str) – The prompt to show the user.
additional_options (list, optional) – Additional options to show the user. Defaults to None.

Returns:

The user’s answer.

Return type:

str