pyuff_ustb.objects.Wave

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

Bases: Uff

Uff class that describes a transmitted wave.

Wave contains information to describe a wave: planar, spherical, or photoacoustic, and the apodization used to produce it.

wavefront defines the type of wave produced: Wavefront.plane, Wavefront.spherical, or Wavefront.photoacoustic.

source defines the wave attitude. If wavefront is Wavefront.spherical then source defines the point in space from which the wave originated. If source is behind the plane z=0 then the spherical wave will be diverging. If source is in front of the plane z=0 the the spherical wave will be converging. If the wavefront is Wavefront.plane then source defines the orientation through the azimuth and elevation angles, i.e. source.distance becomes meaningless. If the wavefront is Wavefront.photoacoustic then source is ignored.

Apodization is a Apodization class used to compute the apodization values that generate the Wave.

delay defines the time interval between the reference time t0 and the start of acquisition for this particular wave. We refer to reference time, or time zero, as the moment the wave passes through the origin of coordinates (0, 0, 0).

See also

Wavefront Apodization

Original authors:

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

• Ole Marius Hoel Rindal <olemarius@olemarius.net>

• Anders E. Vrålstad <anders.e.vralstad@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_elements	Number of elements
apodization	APODIZATION class
apodization_values	Apodization [unitless]
author	Contact of the authors
delay	Time interval between t0 and acquistion start [s]
delay_values	Delay [s]
event	Index of the transmit/receive event this wave refers to
info	Other information
name	Name of the dataset
origin	POINT class
probe	PROBE class.
reference	Reference to the publication where it was used/acquired
sound_speed	Reference speed of sound [m/s]
source	POINT class
version	Version of the dataset
wavefront	WAVEFRONT enumeration class

property wavefront: Wavefront

WAVEFRONT enumeration class

property source: Point

POINT class

property origin: Point

POINT class

property apodization: Apodization

APODIZATION class

property probe: Probe

PROBE class.

property event: int

Index of the transmit/receive event this wave refers to

property delay: float

Time interval between t0 and acquistion start [s]

property sound_speed: float

Reference speed of sound [m/s]

property N_elements: int

Number of elements

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 delay_values: ndarray

Delay [s]

property apodization_values: ndarray

Apodization [unitless]