The USTB format

NTNU, UiO, Creatis and Pulse Lab have tried to merge their respective data formats during the last months. We present here the current state of that merge. The format is based on a collection of Matlab classes that can be saved into HDF5 files. This classes contain both data and sequence definition.

Overview

USTB stands for UltraSound ToolBox. USTB is an ongoing project to develop a MATLAB toolbox for processing ultrasonic signals. Its aim is to facilitate the comparisson of imaging techniques and the dissemination of research results. The USTB is currently developped by NTNU (Trondheim), UiO (Oslo), Creatis (Lyon), and PulseLab (Baltimore), but other groups are welcome to be part of the developping team.

USTB initiative can be followed through the website ustb.no. The toolbox is available at bitbucket repository for download. Contact the dev team for access.

USTB supports processing techniques for both tissue and flow visualization, as well as other image processing techniques. Part of the USTB is a file format for channel and beamformed data, which we called UFF (ultrasound file format). We describe that format in wat follows.

USTB's file format originates from the data class organization in USTB. A UFF class family is defined, composed of a uff superclass and 7 children classes. All UFF classes can be dumped into a hdf5 file dynamically, which we call a UFF file (extension .uff). All uff objects can go in a single UFF file. This approach is flexible (uff classes can be expanded without need of updating the read/write routines) and clean (datasets can be contained in a single file: both data and sequence parameters).

But it has limitations. Dumping attributes with the current matlab hdf5 commands is very slow which makes structure nesting unadvisable. Although HDF5 allows for partial loading it is not clear yet if this is as robust and efficient as splitting the data into several files.

Structure

• Data structure
• UFF superclass
• HDF5 read/write
• uff.point
• uff.probe
• uff.scan

File Examples

An example HDF5 file containing a uff data strcuture can be downloaded from here. To inpect it you can use any HDF5 viewer, such as HDFView

== File Example ==

An example of a HDF5 file containing a general '''uff.scan''' data structure can be downloaded from [http://www.ustb.no/datasets/uff_scan.uff here]. Other examples can be found:

• [http://www.ustb.no/datasets/uff_linear_scan.uff linear scan]
• [http://www.ustb.no/datasets/uff_sector_scan.uff sector scan]

Use any HDF5 viewer to inspect the files, such as [https://support.hdfgroup.org/products/java/release/download.html#bin HDFView].

= uff.apodization =

{|class="wikitable" |+ Table V. Data structures in uff.apodization class |- ! Parameter ! Type ! Description |- ! probe | uff.probe | needed to calculate transmit & receive apodization |- ! focus | uff.scan | needed to calculate transmit, receive, and synthetic apodization |- ! sequence | uff.wave[] | needed to compute synthetic apodization |- ! window | uff.window | Enumeration that defines the typo of apodization window |- ! f_number | double[1,2] | F-number in X and Y direction [Fx Fy] [unitless unitless] |- ! origo | uff.point | Location of the origin of the apodization window |- ! tilt | double[1,2] | azimuth and elevation angles applied to the origo [azimuth elevation] [rad rad] |}

The class '''uff.apodization''' contains all the information needed to compute the apodization values to be applied in transmit, receive, or in a synthetic case (such as STAI or CPWC). It contains information about the apodization ''origo'', ''tilt'', and ''window'', but also about the ''probe'' and ''scan'' the apodization will be used for. In addition, for synthetic cases, the sequence is also included.

== File Example ==

An example of a HDF5 file containing a '''uff.apodization''' data structure can be downloaded from [http://www.ustb.no/datasets/uff_apodization.uff here]. The file can be inspected with any HDF5 viewer, such as [https://support.hdfgroup.org/products/java/release/download.html#bin HDFView].

= uff.wave =

[[File:Wave.png|thumb|upright=1.9|right|alt=uff.wave|The plot method of '''uff.wave''' shows the delay and apodization profiles]]

{| class="wikitable" |+ Table V. Data structures in uff.wave class |- ! Parameter ! Type ! Description |- ! probe | uff.probe | probe used to transmit the wave |- ! apodization | uff.apodization | apodization used to generate the wave |- ! source | uff.point | location of the point source that generates the wave |- ! event | integer[] | index(es) of the transmit/receive events this wave refers to |- ! sound_speed | double | reference speed of sound |}

The '''uff-wave''' defines a transmitted waveform used in a transmit/receive event. It is assumed the wave is produced by a point source defined by '''source''' (which covers most of the beamforming techniques in the state-of-the-art). However in the future different types of waves can be defined, for instance to cover photoacoustics. It also holds information about the ''apodization'' and ''probe'' ('''NOTE:''' perhaps unncessarily) and the reference ''sound_speed'' in the media used to calculate delays. It also features an index ''event'' that defines the transmit/receive event in the '''channel_data''' structure. This enables multi-line transmit (MLT) schemes and simplifies the definition of packet acquisitions.

== Time zero convention ==

It is possible to express the most important transmission waves (diverging waves, focused beams, plane-wave, STA) as if they were generated by point sources. This simplifies the processing of different beamforming sequences as the same beamforming code can be used to process all schemes.

It is necessary, however, to set a inequivocal convention for what is defined as '''time zero'''. This is often defined as the moment the first element in the array is fired. While this is a perfect correct choice, in USTB we favored a convention that did not depend on the probe geometry. USTB assumes that time zero corresponds to the moment the transmitted wave passes by the origin of coordinates (0,0,0) ('''NOTE:''' This is to be made more flexible by including and ''origo'' parameter in the wave allowing the user to select the location of said reference point.)

== File Example ==

An example of a HDF5 file containing a '''uff.wave''' data structure can be downloaded from [http://www.ustb.no/datasets/uff_wave.uff here]. Any HDF5 viewer can be used to inspect the file, such as [https://support.hdfgroup.org/products/java/release/download.html#bin HDFView].

= uff.channel_data =

[[File:Channel_data.png|thumb|upright=1.7|right|alt=uff.channel_data|The plot method of '''uff.channel_data''' shows one transmit/receive event]]

{| class="wikitable" |+ Table VI. Data structures in uff.channel_data class |- ! Parameter ! Type ! Description |- ! sampling_frequency | double | channel data sampling frequency [Hz] |- ! initial_time | double | time of the initial sample [s] |- ! sound_speed | double | reference sound speed [m/s] |- ! modulation_frequency | double | modulation frequency in case of IQ data (0 for RF data) [Hz] |- ! sequence | uff.wave[] | collection of uff.waves defining the sequence |- ! probe | uff.probe[] | Probe used to acquire the sequence |- ! data | single[,,,] or double [,,,] | matrix of single/double with dimensions [time x channel x event x frame] containing data samples |}

The '''uff.channel_data''' class contains all the data needed to beamform a channel data dataset. It contains information about the sampling frequency, initial time sample, reference sound speed, and modulation frequency. It also contains the sequence information as a collection of '''uff.wave''' objects. It includes a '''uff.probe''' object but this will be removed as it less flexible than including the probe information in the '''uff.wave''' objects.

== data dimensions ==

The ''data'' property is a matrix of single with 4 dimensions. The first two dimensions are time and channels.

The third is the ''event'' dimmension. Often it will correspond to the number of waves in the '''sequence'''. But there are two situations where those number will differ.

First is the case of multi-line transmissions, i.e. when more than one wave is transmitted in a single transmit/receive event. In such case there will be more waves in the ''sequence'' than events in the ''channel_data''. Those are then addressed with the '''event''' parameter in the wave definition.

The other case is in case of packet acquisitions, i.e. when the same wave is transmitted in consecutive events. In this case there will be more events than waves in the sequence. This case is addressed by leting the '''event''' parameter in the wave definition to be an array of integers indicating the events that correspond to that wave.

The fourth dimension is ''frame''. For each element in ''frame'' the whole list of events is repeated. Note that after processing the total number of frames could be different from the number of frames in the channel data.

== File Example ==

An example of a HDF5 file containing a '''uff.channel_data''' data structure can be downloaded from [http://www.ustb.no/datasets/uff_channel_data.uff here]. Any HDF5 viewer can be used to inspect the file, such as [https://support.hdfgroup.org/products/java/release/download.html#bin HDFView].

= uff.beamformed_data =

[[File:Beamformed_data.png|thumb|upright=1.7|right|alt=uff.beamformed_data|Plot method of '''uff.beamformed_data''']]

{| class="wikitable" |+ Table VII. Data structures in uff.bemaformed_data class |- ! Parameter ! Type ! Description |- ! scan | uff.scan | scan class containing the location of the collection of pixels |- ! data | single[,,,] or double[,,,] | matrix of single our double with dimensions [pixel x channel x wave x frame] containing data samples |}

The class '''uff.beamformed_data''' contains all the information needed to display a beamformed dataset. It is composed of spatial data (or pixels) and the location of said pixels by means of a '''uff.scan''' object. ('''NOTE:''' The number of dimensions should be increased to hold vector information)

The first dimension of the ''data'' runs along the number of pixels in the reconstruction.

The Third dimension enables to separate the contribution of each wave to image formation. This is called "low resolution images" in the context of STAI and CPWC.

The second dimension enables to separate the contribution of each channel to image formation. This is equivalent to the "low resolution images" of teh third dimension but for channels.

The fourth dimension holds the same reconstructions for another time.

== File Example ==

An example of a HDF5 file containing a '''uff.beamformed_data''' data structure can be downloaded from [http://www.ustb.no/datasets/uff_beamformed_data.uff here]. Any HDF5 viewer can be used to inspect the file, such as [https://support.hdfgroup.org/products/java/release/download.html#bin HDFView].