pyuff_ustb.objects.ChannelData

class pyuff_ustb.objects.ChannelData(_reader: Reader | str | None = None, **kwargs)

Bases: Uff

Uff class to hold channel data.

ChannelData contains raw ultrasound data as acquired from an ultrasound scanner. Data is stored in the property data with dimensions: [time-dimension x channel-dimension x wave-dimension x frame-dimension].

Original authors:

Alfonso Rodriguez-Molares <alfonso.r.molares@ntnu.no>

__init__(_reader: Reader | str | None = None, **kwargs)

Methods

__init__([_reader])
copy()	Return a (deep) copy of the Uff object.
read(name)	Read an Uff object from the file.
write(filepath, location[, overwrite, ...])	Write the Uff to a file.

Attributes

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]
author	Contact of the authors
data	Channel data [time dim.
info	Other information
initial_time	Time of the initial sample [s]
modulation_frequency	Modulation frequency [Hz]
name	Name of the dataset
phantom	UFF.PHANTOM object
probe	UFF.PROBE object
pulse	UFF.PULSE object
reference	Reference to the publication where it was used/acquired
sampling_frequency	Sampling frequency [Hz]
sequence	Collection of UFF.WAVE objects
sound_speed	Reference sound speed [m/s]
version	Version of the dataset
wavelength	Wavelength [m]

property sampling_frequency: float

Sampling frequency [Hz]

property initial_time: float

Time of the initial sample [s]

property sound_speed: float

Reference sound speed [m/s]

property modulation_frequency: float

Modulation frequency [Hz]

property sequence: Wave | List[Wave]

Collection of UFF.WAVE objects

property probe: Probe

UFF.PROBE object

property data: ndarray

Channel data [time dim. x channel dim. x wave dim. x frame dim.]

property pulse: Pulse

UFF.PULSE object

property phantom: Phantom

UFF.PHANTOM object

property PRF: float

Pulse repetition frequency [Hz]

property N_active_elements: int

Number of active transducers on receive

property N_samples: int

Number of samples in the data

property N_elements: int

Number of elements in the probe

property N_channels: int

Number of elements in the probe

property N_waves: int

Number of transmitted waves

property N_frames: int

Number of frames

property author: str | None

Contact of the authors

copy() → Uff

Return a (deep) copy of the Uff object.

In addition to the _reader, all compulsory and optional fields are copied (deeply) iff they are loaded/cached. This means that if a field has not been read from the file, it will not be copied. This is to avoid unintended eager loading of data.

See Uff.__deepcopy__() for implementation details.

Returns:

A deep copy of this object.

Return type:

Uff

property info: str | None

Other information

property name: str | None

Name of the dataset

read(name: str) → Uff

Read an Uff object from the file. A Reader must be provided in order to read.

>> uff = Uff(“/path/to/some/file.uff”) >> scan = uff.read(“scan”)

property reference: str | None

Reference to the publication where it was used/acquired

property version: str | None

Version of the dataset

write(filepath: str, location: str | Tuple[str, ...] | List[str], overwrite: bool = False, ignore_missing_compulsory_fields: bool = False)

Write the Uff to a file.

Parameters:

• filepath (Union[str, h5py.File]) – The filepath (or h5py.File) to write to.

• location (Union[str, Tuple[str, ...], List[str]]) – The location in the h5 file to write to. Can be a tuple/list of strings representing a path into the h5 file, or a string with the path separated by slashes.

• overwrite (bool) – Whether to overwrite the location if it already exists. If the location already exists and overwrite=False, a ValueError is raised. overwrite=False by default.

• ignore_missing_compulsory_fields (bool) – Whether to ignore missing compulsory fields. If a compulsory field is not set then usually a ValueError is raised. Setting ignore_missing_compulsory_fields=True will ignore this error and write the object anyway. ignore_missing_compulsory_fields=False by default.

Examples

We can write an object to a file like this:

>>> import pyuff_ustb as pyuff
>>> point = pyuff.Point(distance=0.0, azimuth=0.0, elevation=0.0)
>>> point.write("my_point.uff", "point")

If we try to write an object to the same location, we get an error:

>>> point.write("my_point.uff", "point")
Traceback (most recent call last):
    ...
ValueError: Location 'point' already exists in the file 'my_point.uff'. Use overwrite=True to overwrite it.

We can choose to overwrite the location by passing overwrite=True:

>>> point.write("my_point.uff", "point", overwrite=True)

We can also write the object to another arbitrary location if we want:

>>> point.write("my_point.uff", "sub_directory/point")

Compulsory fields may not be None when writing an object to an UFF file (unless ignore_missing_compulsory_fields=True).

>>> point.distance = None
>>> point.write("my_point.uff", "point2")
Traceback (most recent call last):
    ...
ValueError: The compulsory field 'distance' is set to None. Compulsory fields
may not be None when writing an object to an UFF file. To ignore this error and write
the object anyway, set ignore_missing_compulsory_fields=True.

Note that even though the previous step failed, the file was still partially written to (we don’t rollback changes when writing fails), so we will have to pass overwrite=True to write the object again.

>>> point.write(
...     "my_point.uff",
...     "point2",
...     overwrite=True,
...     ignore_missing_compulsory_fields=True,
... )

After running these steps, the file will contain the following fields:

>>> uff = pyuff.Uff("my_point.uff")
>>> uff
Uff(point=Point(<...>), point2=Point(<...>), sub_directory=<...>)

property wavelength: float

Wavelength [m]

Same as ChannelData.lambda in USTB, but lambda is a reserved keyword in Python.