Wiki
Clone wikiUFF / v0.2 / draft
Draft of UFF v0.2
Data model
The UFF data model follows a well-defined structure that can be represented as a tree.
- Each node in the tree corresponds to a UFF object or simple data set.
- Nodes are named using descriptive names.
- Nodes may have attributes describing the object (such as linear or convex transducer array) and dimensions of UFF object arrays.
- UFF objects correspond to a concept or a physical entity such as an ultrasound probe, a wave geometry, or a position in space.
- Simple data sets correspond to scalars or arrays of any dimensionality of integer, floating point, or character datatypes.
- Arrays of UFF objects are represented with one node for the array and one node for each array element. These are respectively referred to as an "array node" and an "array element node".
- Array element nodes are named with an 8-digit number indicating the array index of the element. Arrays are 1-based. As an example, the first array element node is named 00000001.
- The array node has a property named "array_size" that contains a 1-D array with as many elements as the array has dimensions and with values the size of the array along each dimension.
- The size conforms to C-array ordering.
- For a 1-D array of UFF objects, the array_size property has 2 elements to differentiate between row- and column-arrays in certain programming languages (such as MATLAB).
- If an array in a given UFF file contains only 1 element (such as a probe with only 1 element), one array node and one array element node must still be used.
- Each edge in the tree indicates parent/child relations between two objects, an object and a data set, or an UFF object array and its elements.
- It is not possible for a node to be the destination of multiple edges (property of a tree as opposed to a graph).
- A correctly formed UFF structure does not contain any loops (property of a tree as opposed to a graph).
- References across the structure (such as a reference to the transmitting probe in a hydrophone measurement) use the integer array index of the UFF object being referenced. See https://bitbucket.org/ultrasound_file_format/uff/issues/10/make-file-format-description-independent#comment-48906811 for a discussion of this.
- This only allows references to UFF object array elements as opposed to any UFF object in the tree. So far, no need has been found for a reference to UFF objects outside arrays.
The model easily maps to commonly used programming techniques including nested structures in C and object oriented programming in many other programming languages. The model also maps directly to HDF5 files that are therefore used as the basis of the UFF.
Note that the UFF HDF5 file also contains a "version" HDF5 group at the root note with 32-bit unsigned integer datasets "major", "minor", and "patch" that describe the UFF file version number (major.minor.patch).
UFF structure
The UFF structure is defined for channel data only (future versions will include beamformed data, velocity estimates and possibly more). A channel data UFF object starts with a node named uff.channel_data. The list below shows the complete structure with a short description of each node. Indentation indicates relationship such that an entry is a child of the nearest UFF object above at one less level of indentation, i.e., for a node at indentation level n, there is an edge to each node at indentation level n+1 until the next node at indentation level n. For simple data sets, the type is written immediately after the name. The type "float" allows either single og double precision floating point numbers. The type "integer" allows any signed or unsigned integer type. The type "string" is a synonym for an array of characters. For units of measure, the unit is indicated immediately after the datatype.
XXX DEFINE HOW ROTATIONS WORK
- uff.channel_data, the root node for a channel data UFF object
- authors, string, author names
- description, string, description of the data
- system, string, description of the system used in the acquisition
- country_code, string, ISO 3166-1 Alpha-2 country code of data origin
- local_time, string, ISO 8601:2005 section 4.3.2 basic format without difference to UTC representing the local time at which the scan was conducted.
- repetition_rate, float, Hz, the rate at which sequences of emissions are repeated, i.e., the reciprocal of the difference in starting time between two sequences.
- sound_speed, float, m/s, the reference speed of sound
- data_real, float or integer, proportional to V, the real part of the channel data in a 4D array with dimensions [number_of_frames x number_of_events x number_of_channels x number_of_samples] (C-array ordering). If different events/channels have different numbers of channels/samples, the valid data should be stored from the beginning of the array dimension and the invalid data should be given the value 0.
- data_imag, optional, float or integer, proportional to V, the imaginary part of the channel data in a 4D array with identical dimensions to data_real. If data is real, this field should not be written.
- probes, array of probes, e.g., an array transducer and a hydrophone
- 00000001, a probe with node attribute "probe_type" with value one of "uff.probe.linear_array", "uff.probe.curvilinear_array", "uff.probe.matrix_array", or "uff.probe". The uff.probe type should only be used if nothing else fits. All probe types have the below fields, specific probe types have additional fields as described at XXX
- transform, the position of the probe in space
- translation, the translation of the probe in space
- x, float, x-coordinate [m]
- y, float, y-coordinate [m]
- z, float, z-coordinate [m]
- rotation, the rotation of the probe in space
- x, float, rotation around x-axis in radians
- y, float, rotation around y-axis in radians
- z, float, rotation around z-axis in radians
- translation, the translation of the probe in space
- focal_length, XXX
- element_geometry, array of unique element geometries for this probe
- element_impulse_response, array of unique impulse responses for this probe
- element, array of elements
- 00000001, the first element in the probe
- transform, the position and orientation of the element within the probe
- translation, the translation of the probe in space
- x, float, x-coordinate [m]
- y, float, y-coordinate [m]
- z, float, z-coordinate [m]
- rotation, the rotation of the probe in space
- x, float, rotation around x-axis in radians
- y, float, rotation around y-axis in radians
- z, float, rotation around z-axis in radians
- translation, the translation of the probe in space
- element_geometry, uint32, index in array of unique element geometries for this probe
- impulse_response, uint32, index in array of unique impulse responses for this probe
- transform, the position and orientation of the element within the probe
- 00000002, the second element in the probe
- ...
- 00000001, the first element in the probe
- transform, the position of the probe in space
- 00000002, the second probe
- ...
- 00000001, a probe with node attribute "probe_type" with value one of "uff.probe.linear_array", "uff.probe.curvilinear_array", "uff.probe.matrix_array", or "uff.probe". The uff.probe type should only be used if nothing else fits. All probe types have the below fields, specific probe types have additional fields as described at XXX
- unique_excitations, array of unique excitation waveform definitions
- 00000001, the first excitation
- pulse_shape, string, description of the pulse shape (e.g., sinusoidal, square wave, chirp), including necessary parameters
- waveform, array of float, sampled excitation waveform in normalized units
- sampling_frequency, float, sampling frequency of the excitation waveform [Hz]
- 00000002, the second excitation
- ...
- 00000001, the first excitation
- unique_events, array of unique combinations of transmit and receive setups
- 00000001, a unique event
- transmit_setup, the transmit setup for the event
- probe, index of transmitting probe in uff.channel_data/probes
- transmit_waves, array of transmit waves used
- 00000001, the first transmit wave in the event
- wave, index of wave in uff.channel_data/unique_waves
- time_offset, float, time delay between the start of the event and the moment this wave reaches the closest element in the probe [s]
- weight, float, weight applied to the wave within the event, no unit
- 00000001, the first transmit wave in the event
- channel_mapping, array of unsigned integers, map of transmit channels to transducer elements: the channel at array index i is connected to element channel_mapping(i). XXX HOW TO DEAL WITH ONE CHANNEL TO MULTIPLE ELEMENTS?
- sampled_delays, array of float, per channel transmit delays used in the system (quantized to the TX clock) in seconds
- sampled_excitations, 2D array of float, per channel excitation waveforms used in the system (quantized to DAC levels) in normalized values (between -1 and +1) to the transmit voltage
- sampling_frequency, float, sampling frequency of the excitation waveforms [Hz]
- transmit_voltage, float, peak amplitude of the pulse generator [V]
- receive_setup, the receive setup for the event
- probe, index of transmitting probe in uff.channel_data/probes
- time_offset, float, time delay between the start of the event and the acquisition of the first sample [s]
- channel_mapping, array of unsigned integers, map of receive channels to transducer elements: the channel at array index i is connected to element channel_mapping(i). XXX HOW TO DEAL WITH ONE CHANNEL TO MULTIPLE ELEMENTS?
- sampling_frequency, float, sampling frequency of the recorded (channel) data [Hz]
- tgc_profile, float, analog TGC profile sampled at tgc_sampling_frequency expressed in dB
- tgc_sampling_frequency, float, sampling frequency of the TGC profile [Hz]
- modulation_frequency, float, modulation frequency in case of IQ data generated by offset sampling [Hz]
- transmit_setup, the transmit setup for the event
- 00000001, a unique event
- unique_waves, array of unique wave definitions
- 00000001, the first unique wave
- wave_type, string, enumerated wave type: converging, diverging, plane, cylindrical, photoacoustic
- origin, geometric origin of the wave
- translation, for converging and diverging waves this is the focus/virtual source location
- x, float, x-coordinate [m]
- y, float, y-coordinate [m]
- z, float, z-coordinate [m]
- rotation, for plane waves this is the plane wave angle
- x, float, rotation around x-axis in radians
- y, float, rotation around y-axis in radians
- z, float, rotation around z-axis in radians
- translation, for converging and diverging waves this is the focus/virtual source location
- aperture, the aperture used for the wave
- origin, aperture center in space
- x, float, x-coordinate [m]
- y, float, y-coordinate [m]
- z, float, z-coordinate [m]
- window, string, description of window type and parameter, e.g. "Hamming", "Tukey(0.5)"
- f_number, array of float with 2 elements, desired F-number of the aperture; first array element is azimuth; second array element is elevation
- fixed_size, array of float with 2 elements, if greater than zero, it overwrites the dynamic aperture given by the f_number [m]
- minimum_size, array of float with 2 elements, if >0, it sets a minimum for the dynamic aperture given by the f_number [m]
- maximum_size, array of float with 2 elements, if >0, it sets a maximum for the dynamic aperture given by the f_number [m]
- origin, aperture center in space
- excitation, index of excitation in uff.channel_data/unique_excitations
- 00000002, the second unique wave
- ...
- 00000001, the first unique wave
- sequence, array of events
Links
Updated