pyuff_ustb.objects.CurvilinearArray

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

Bases: Probe

Uff class to define a curvilinear array probe geometry.

CurvilinearArray defines a array of regularly space elements on an arc in the azimuth dimensions. Optionally it can hold each element width and height, assuming the elements are rectangular.

Original authors:

Alfonso Rodriguez-Molares (alfonsom@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	Number of elements
N_elements	Number of elements
author	Contact of the authors
element_height	Height of the elements in the elevation direction [m]
element_width	Width of the elements in the azimuth direction [m]
geometry	An array with attitude of rectangular elements.
height	Element height [m]
info	Other information
maximum_angle	Angle of the outermost elements in the array
name	Name of the dataset
origin	Location of the probe respect to origin of coordinates
phi	Orientation of the element in the elevation direction [rad]
pitch	Distance between the elements in the azimuth direction [m]
r	Distance from the element center to the origin of coordinates [m]
radius	Radius of the curvilinear array [m]
reference	Reference to the publication where it was used/acquired
theta	Orientation of the element in the azimuth direction [rad]
version	Version of the dataset
width	Element width [m]
x	Center of the element in the x axis [m]
xyz	Center of the element as an array of shape (n_elements, 3) [m]
y	Center of the element in the y axis [m]
z	Center of the element in the z axis [m]

property N: int

Number of elements

property pitch: float

Distance between the elements in the azimuth direction [m]

property radius: float

Radius of the curvilinear array [m]

property element_width: float

Width of the elements in the azimuth direction [m]

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 element_height: float

Height of the elements in the elevation direction [m]

property height: ndarray

Element height [m]

property info: str | None

Other information

property name: str | None

Name of the dataset

property origin: Point

Location of the probe respect to origin of coordinates

property phi: ndarray

Orientation of the element in the elevation direction [rad]

property r: ndarray

Distance from the element center to the origin of coordinates [m]

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

Orientation of the element in the azimuth direction [rad]

property version: str | None

Version of the dataset

property width: ndarray

Element width [m]

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

Center of the element in the x axis [m]

property xyz: ndarray

Center of the element as an array of shape (n_elements, 3) [m]

property y: ndarray

Center of the element in the y axis [m]

property z: ndarray

Center of the element in the z axis [m]

property maximum_angle: float

Angle of the outermost elements in the array

property geometry: ndarray

An array with attitude of rectangular elements.

The returned array contains 7 fields (over all elements):

• x [meters]

• y [meters]

• z [meters]

• theta [radians]

• phi [radians]

• width [meters]

• height [meters]

Returns:

An array with attitude of rectangular elements with shape (7, n_elements).

Return type:

np.ndarray