uff Data Classes

The uff data classes represent the Ultrasound File Format (UFF) and are used to store ultrasound data, probes, scans, and related structures. All data classes can be written to and read from UFF files.

Data Classes

class channel_data

CHANNEL_DATA UFF data class for raw ultrasound channel data

CHANNEL_DATA holds the raw RF or IQ data as acquired from an ultrasound scanner or generated by a simulator. The data array has dimensions [time x channel x wave x frame].

When modulation_frequency is zero the data is RF (real-valued). When nonzero the data is IQ (complex baseband).

Properties:: sampling_frequency sampling frequency [Hz] initial_time time of the first sample [s] sound_speed reference sound speed [m/s] modulation_frequency modulation frequency [Hz] (0 = RF data) sequence array of UFF.WAVE objects probe UFF.PROBE object data data [time x channel x wave x frame] PRF pulse repetition frequency [Hz] pulse UFF.PULSE object phantom UFF.PHANTOM object
Dependent properties:: N_samples number of time samples N_elements number of probe elements N_channels number of receive channels N_waves number of transmit events N_frames number of frames lambda wavelength [m]
Example:: ch = uff.channel_data(); ch.sampling_frequency = 40e6; ch.sound_speed = 1540;

See also UFF.BEAMFORMED_DATA, UFF.WAVE, UFF.PROBE

Property Summary

N_active_elements: number of active transducers on receive

N_channels: number of elements in the probe

N_elements: number of elements in the probe

N_frames: number of frames

N_samples: number of samples in the data

N_waves: number of transmitted waves

PRF: pulse repetition frequency [Hz]

data: channel data [time dim. x channel dim. x wave dim. x frame dim.]

initial_time: time of the initial sample [s]

lambda: wavelength [m]

modulation_frequency: modulation frequency [Hz]

phantom: UFF.PHANTOM object

probe: UFF.PROBE object

pulse: UFF.PULSE object

sampling_frequency: sampling frequency [Hz]

sequence: collection of UFF.WAVE objects

sound_speed: reference sound speed [m/s]

Method Summary

plot(h, figure_handle_in, n_wave, plot_abs): PLOT Plots channel data

class beamformed_data

BEAMFORMED_DATA UFF data class for beamformed image data

BEAMFORMED_DATA holds the output of the beamforming (midprocess) stage or any postprocess step. The data array has dimensions [pixel x channel x wave x frame].

After a midprocess.das with dimension.both the data reduces to [pixel x 1 x 1 x frame]. Intermediate results (e.g. dimension.receive) preserve the wave dimension for further processing.

Properties:: scan UFF.SCAN defining pixel positions data data [pixel x channel x wave x frame] phantom UFF.PHANTOM object sequence array of UFF.WAVE objects probe UFF.PROBE object pulse UFF.PULSE object sampling_frequency effective sampling frequency [Hz] modulation_frequency modulation frequency [Hz] frame_rate frame rate for video export [fps]
Dependent properties:: N_pixels number of pixels N_channels number of channels N_waves number of waves N_frames number of frames
Example:: b_data = uff.beamformed_data(); b_data.plot();

See also UFF.CHANNEL_DATA, UFF.SCAN, MIDPROCESS.DAS

Property Summary

N_channels: number of channels

N_frames: number of frames

N_pixels: number of pixels

N_waves: number of waves (transmit events)

data: data [pixel x channel x wave x frame]

frame_rate: Framerate for Video or GIF file to be saved [fps]

modulation_frequency: Modulation frequency in [Hz]

phantom: PHANTOM object

probe: PROBE object

pulse: PULSE object

sampling_frequency: Sampling frequency in the depth direction in [Hz]

scan: SCAN object or array of SCAN objects

sequence: array of WAVE objects

Method Summary

plot(h, parent_handle_in, in_title, dynamic_range, compression, indeces, frame_idex, spatial_units, mode)

PLOT Plots beamformed data

Usage: figure_handle=plot(figure_handle,title,dynamic_range)

figure_handle Handle to the figure to plot to (default: none) title Figure title (default: none) dynamic_range Displayed dynamic range (default: 60 dB) compression String specifying compression type: ‘log’,’none’,’sqrt’ (default: ‘log’) indeces Pair of integers [nrx ntx] indicating receive and transmit events (default: []) indeces Tripler of integers [nrx ntx frame] indicating which receive and transmit and frame must be plotted (default: [])

Probe Classes

class probe

PROBE UFF data class defining an arbitrary transducer geometry

PROBE is the base class for all probe types in the USTB. It stores element positions and orientations in a geometry matrix with one row per element:

[x y z theta phi width height]
m m m rad rad m m

Subclasses such as LINEAR_ARRAY, CURVILINEAR_ARRAY, and MATRIX_ARRAY provide convenient constructors that compute the geometry from higher-level parameters (N, pitch, radius, etc.).

Properties:: origin UFF.POINT location of the probe w.r.t. global origin geometry element matrix [x y z theta phi width height]
Dependent properties:: N_elements number of elements x element x-coordinates [m] y element y-coordinates [m] z element z-coordinates [m] theta element azimuth orientation [rad] phi element elevation orientation [rad] width element width [m] height element height [m] r distance from element to origin [m]
Example:: prb = uff.probe(); prb.geometry = [0 0 0 0 0 300e-6 5e-3];

See also UFF.LINEAR_ARRAY, UFF.CURVILINEAR_ARRAY, UFF.MATRIX_ARRAY

Property Summary

N_elements: number of elements

geometry: matrix with attitude of rectangular elements [x y z theta phi width height] - [m m m rad rad m m]

height: element height [m]

origin: uff.point class location of the probe respect to origin of coordinates

phi: orientation of the element in the elevation direction [rad]

r: distance from the element center to the origin of coordinates [m]

theta: orientation of the element in the azimuth direction [rad]

width: element width [m]

x: center of the element in the x axis[m]

y: center of the element in the y axis[m]

z: center of the element in the z axis[m]

class linear_array

LINEAR_ARRAY UFF data class for a linear (1-D) transducer array

LINEAR_ARRAY defines an array of elements equally spaced along a straight line (the x-axis). The geometry is computed automatically when N and pitch are set.

Properties:: N number of elements pitch inter-element spacing [m] element_width element width [m] (default: pitch) element_height element height [m] (default: 10 * element_width)
Example:: prb = uff.linear_array(); prb.N = 128; prb.pitch = 300e-6;

See also UFF.PROBE, UFF.CURVILINEAR_ARRAY, UFF.MATRIX_ARRAY

Property Summary

N: number of elements

element_height: height of the elements in the elevation direction [m]

element_width: width of the elements in the azimuth direction [m]

pitch: distance between the elements in the azimuth direction [m]

class curvilinear_array

CURVILINEAR_ARRAY UFF data class for a curvilinear (convex) transducer array

CURVILINEAR_ARRAY defines elements equally spaced along an arc in the azimuth direction. The geometry is computed from N, pitch, and radius.

Properties:: N number of elements pitch inter-element spacing along the arc [m] radius radius of curvature [m] element_width element width [m] (default: pitch) element_height element height [m] (default: 10 * element_width)
Dependent properties:: maximum_angle angle of the outermost elements [rad]
Example:: prb = uff.curvilinear_array(); prb.N = 128; prb.pitch = 500e-6; prb.radius = 70e-3;

Scan Classes

class scan

SCAN UFF data class defining a collection of pixel positions

SCAN is the base class for all pixel grids. It stores arbitrary pixel positions as x, y, z coordinate vectors. Use the subclasses LINEAR_SCAN and SECTOR_SCAN for structured grids.

Properties:: x x-coordinates of each pixel [m] y y-coordinates of each pixel [m] z z-coordinates of each pixel [m]
Dependent properties:: N_pixels total number of pixels xyz Nx3 matrix of pixel positions [m]
Example:: sca = uff.scan(); x_axis = linspace(-20e-3, 20e-3, 256); z_axis = linspace(0e-3, 40e-3, 256); [X, Z] = meshgrid(x_axis, z_axis); sca.xyz = [X(:), zeros(numel(X), 1), Z(:)];

See also UFF.LINEAR_SCAN, UFF.SECTOR_SCAN

Property Summary

N_pixels: total number of pixels in the matrix

x: Vector containing the x coordinate of each pixel in the matrix

xyz: location of the source [m m m] if the source is not at infinity

y: Vector containing the x coordinate of each pixel in the matrix

z: Vector containing the z coordinate of each pixel in the matrix

Method Summary

plot(h, figure_handle_in, title_in): plotting scan

class linear_scan

LINEAR_SCAN UFF data class for a Cartesian pixel grid

LINEAR_SCAN defines a regular grid in Cartesian coordinates using x_axis, y_axis, and z_axis vectors. Pixel positions are generated on an ndgrid of these axes.

Properties:

x_axis x-axis sample positions [m] y_axis y-axis sample positions [m] (default: 0) z_axis z-axis sample positions [m] transform UFF.TRANSFORM applied to pixel positions

Dependent properties:

N_x_axis number of x-axis samples N_y_axis number of y-axis samples N_z_axis number of z-axis samples x_step step size in x [m] z_step step size in z [m] reference_distance distance for phase term calculation [m]

Example:

scan = uff.linear_scan(‘x_axis’, linspace(-20e-3, 20e-3, 256).’, …: ‘z_axis’, linspace(0e-3, 40e-3, 256).’);

Wave and Pulse

class wave

WAVE UFF data class describing a transmitted or received wave event

WAVE defines a single transmit event in the acquisition sequence. The wave type is set by the wavefront property. A virtual source model determines the transmit delays used in beamforming.

For spherical waves (diverging or focused imaging) the source property defines the virtual source position. If source.z < 0 the wave is diverging; if source.z > 0 the wave is converging (focused). For plane waves the source azimuth and elevation angles set the steering direction.

Properties:: wavefront UFF.WAVEFRONT type (plane, spherical, photoacoustic) source UFF.POINT virtual source location origin UFF.POINT origin for delay calculations apodization UFF.APODIZATION transmit apodization probe UFF.PROBE reference event index of the transmit/receive event delay time between t0 and acquisition start [s] sound_speed reference speed of sound [m/s]
Dependent properties:: N_elements number of probe elements delay_values per-element transmit delays [s] apodization_values per-element transmit apodization weights
Example:: w = uff.wave(); w.wavefront = uff.wavefront.plane; w.source.azimuth = 0.1;

See also UFF.CHANNEL_DATA, UFF.WAVEFRONT, UFF.POINT, UFF.APODIZATION

Property Summary

N_elements: number of elements

apodization: APODIZATION class

apodization_values: apodization [unitless]

delay: time interval between t0 and acquistion start

delay_values: delay [s]

event: index of the transmit/receive event this wave refers to

origin: POINT class

probe: PROBE class

sound_speed: reference speed of sound

source: POINT class

t0_origin: delay [s] needed in case the t0 should be calculated from origin.xyz rather than [0, 0, 0]

wavefront: WAVEFRONT enumeration class

Method Summary

fix_origin_from_source(h)

FIX_ORIGIN_FROM_SOURCE Set origin from source when not stored

For spherical waves (focused or diverging) where origin was not explicitly stored in the UFF file (i.e. still at default [0,0,0]), sets origin from the source position:

Focused (source.z > 0): origin at source x,y with z=0

Diverging (source.z < 0): origin at source x,y,z

This ensures correct scanline apodization and delay calculations for RTB and diverging wave examples.

Support Classes

class apodization

APODIZATION UFF data class for receive and transmit apodization

APODIZATION computes pixel-dependent apodization weights for receive elements or transmit waves. It supports expanding aperture (f-number based), fixed aperture, and various window functions. In the Generalized Beamformer, this implements the receive weighting w_m^Rx(x) from Eq. (22) and the transmit wave weighting w_a^Tx(x) from Eq. (23).

Properties:: probe UFF.PROBE (for receive/transmit apodization) focus UFF.SCAN (pixel positions) sequence array of UFF.WAVE (for transmit apodization) window UFF.WINDOW type (default: uff.window.none) f_number F-number [Fx Fy] tilt tilt angle [azimuth elevation] [rad] minimum_aperture minimum aperture size [x y] [m] maximum_aperture maximum aperture size [x y] [m] apodization_vector manual override of apodization values origin UFF.POINT to override aperture center
Dependent properties:: data computed apodization matrix N_elements number of elements or waves
Example:: apo = uff.apodization(); apo.window = uff.window.hamming; apo.f_number = 1.7;

See also UFF.WINDOW, UFF.WAVE, MIDPROCESS.DAS

Property Summary

MLA: number of multi-line acquisitions, only valid for uff.window.scanline

MLA_overlap: number of multi-line acquisitions, only valid for uff.window.scanline

N_elements: number of elements (real or synthetic)

apodization_vector: apodization vector to override the dynamic calculation of apodization

data: apodization data

f_number: F-number [Fx Fy] [unitless unitless]

focus: UFF.SCAN class (needed for transmit, receive & synthetic apodization)

grating_lobe_angle: grating lobe angle for masking

maximum_aperture: maximum aperture size in the [x y] direction

minimum_aperture: minimum aperture size in the [x y] direction

origin: POINT class to overwrite the location of the aperture window as computed on the wave source location

probe: UFF.PROBE class (needed for transmit & receive apodization)

sequence: collection of UFF.WAVE classes (needed for synthetic apodizaton)

tilt: tilt angle [azimuth elevation] [rad rad]

window: UFF.WINDOW class, default uff.window.none

Method Summary

apply_window(h, ratio_theta, ratio_phi): SWITCH

compute(h): if no pixel matrix -> we set it at (0,0,0)

incidence_aperture(h): Location of the elements

plot(h, figure_handle_in, n_element): PLOT Plot apodization

class phantom

PHANTOM UFF data class describing a scattering phantom

PHANTOM defines point scatterers and medium properties used by simulators such as FRESNEL.

Properties:: points Nx4 matrix of scatterers [x y z Gamma] [m m m unitless] time time instant [s] sound_speed medium speed of sound [m/s] density medium density [kg/m3] alpha attenuation coefficient [dB/cm/MHz]
Dependent properties:: N_points number of point scatterers x, y, z scatterer coordinates [m] Gamma reflection coefficients
Example:: pha = uff.phantom(); pha.sound_speed = 1540; pha.points = [0, 0, 20e-3, 1];

Functions

read_object(filename, location, verbose)

READ_OBJECT Read a UFF object from an HDF5 file

Reads and reconstructs a USTB object stored at the given location within a UFF (.uff / .h5) file.

object = uff.read_object(filename, location, verbose)

Parameters:: filename path to the UFF file location HDF5 group path (default: ‘/’) verbose display progress messages (default: true)
Example:: ch = uff.read_object(‘data.uff’, ‘/channel_data’);

See also UFF.WRITE_OBJECT, UFF.INDEX, UFF.VERSION

write_object(filename, object, name, location, verbose)

WRITE_OBJECT Write a UFF object to an HDF5 file

Serializes a USTB object and stores it at the given location in a UFF (.uff / .h5) file.

uff.write_object(filename, object, name, location, verbose)

Parameters:: filename path to the UFF file object USTB object to store name name for the HDF5 group location parent HDF5 group (default: ‘/’) verbose display progress messages (default: true)
Example:: ch = uff.channel_data(); uff.write_object(‘data.uff’, ch, ‘channel_data’);

See also UFF.READ_OBJECT, UFF.INDEX, UFF.VERSION

version()

VERSION Return the current UFF file format version string

v = uff.version()

See also UFF.READ_OBJECT, UFF.WRITE_OBJECT

index(filename, location, display)

INDEX List contents of a UFF file at a given location

Returns a cell array of dataset and group names stored at the specified location within a UFF (.uff / .h5) file.

out = uff.index(filename, location, display)

Parameters:: filename path to the UFF file location HDF5 group path (default: ‘/’) display print list to screen (default: false)
Example:: list = uff.index(‘data.uff’, ‘/’, true);

See also UFF.READ_OBJECT, UFF.WRITE_OBJECT, UFF.VERSION