core

class DetectionElementCreator[source]

Bases: object

A DetectionElementCreator can be used to create detection elements for the purposes of a standardised device representation within the IPASC data format.

It should be used in the following way:

dec = DetectionElementCreator()
dec.set_detector_position(position)
# ... set other attributes
element = dec.get_dictionary()

The element dictionary can then be added to the DeviceMetaDataCreator.

get_dictionary()[source]

Returns a copy of a dictionary describing the created detection element up to this point. Subsequent changes to the element via the DetectionElementCreator will not alter the dictionary returned by this function. If changes are done this functions needs to be called again.

Returns:: A dictionary representing the created detection element.
Return type:: dict

set_angular_response(angular_response: ndarray)[source]

Parameters:: angular_response – a two element array [angles, response] describing the angular response of the detecor. Angles and response are also arrays where len(angles) == len(response). The units can be found in MetadataDeviceTags.ANGULAR_RESPONSE.unit.
Returns:: No return value
Return type:: None

set_detector_geometry(geometry)[source]

Parameters:: geometry – a three element array [x1, x2, x3] describing the extent of the detector size in x1, x2, and x3 direction. The units can be found in MetadataDeviceTags.DETECTOR_SIZE.unit.
Returns:: No return value
Return type:: None

set_detector_geometry_type(geometry_type: str)[source]

Parameters:

geometry_type –

The detector geometry type defines how to interpret the data in the detector geometry field. The following geometry types are currently supported:

“CIRCULAR” - defined by a single value that determines the radius of the circle
“SPHERE” - defined by a single value that determines the radius of the sphere
“CUBOID” - defined by three values that determine the extent of the cuboid in x, y, and z dimensions, before the position and orientation transforms.
“MESH” - defined by a STL-formatted string that determines the positions of points and faces before the position and orientation transforms.

Returns:

No return value

Return type:

None

set_detector_orientation(orientation: ndarray)[source]

Parameters:: orientation – a n array of three float values that describe the orientation of the detector element in the x1, x2, and x3 direction. The units can be found in MetadataDeviceTags.DETECTOR_ORIENTATION.unit.
Returns:: No return value
Return type:: None

set_detector_position(detector_position: ndarray)[source]

Parameters:: detector_position – an array of three float values that describe the position of the detection element in the x1, x2, and x3 direction. The units can be found in MetadataDeviceTags.DETECTOR_POSITION.unit.
Returns:: No return value
Return type:: None

set_frequency_response(frequency_response: ndarray)[source]

Parameters:: frequency_response – a two element array [frequency, response] describing the frequency response of the detector. Frequency and response are also arrays where len(frequency) == len(response). The units can be found in MetadataDeviceTags.FREQUENCY_RESPONSE.unit.
Returns:: No return value
Return type:: None

class DeviceMetaDataCreator[source]

Bases: object

A helper class to create a dictionary that describes a digital device twin according to the IPASC data format. In the interplay with the DetectionElementCreator and the IlluminationElementCreator, elements can be added to the representation.

Example:

dmdc = DeviceMetaDataCreator()
dmdc.set_general_information(uuid, fov)
for _ in range(num_detection_elements):
    dec = DetectionElementCreator()
    dec.set_detector_position(position)
    # ... set other attributes
    element = dec.get_dictionary()
    dmdc.add_detection_element(element)
for _ in range(num_illuminators):
    iec = IlluminationElementCreator()
    iec.set_illuminator_position(position)
    # ... set other attributes
    element = iec.get_dictionary()
    dmdc.add_detection_element(element)
device_metadata_dict = dmdc.finalize_device_meta_data()

Initialises the DeviceMetaDataCreator.

add_detection_element(detection_element: dict)[source]

Parameters:: detection_element – is a dictionary for the detection element specific parameters
Returns:: No return value
Return type:: None

add_illumination_element(illumination_element: dict)[source]

Parameters:: illumination_element – is a dictionary for the illumination element specific parameters
Returns:: No return value
Return type:: None

finalize_device_meta_data()[source]

Returns a copy of a dictionary describing the created device up to this point. Subsequent changes to the element via the DeviceMetaDataCreator will not alter the dictionary returned by this function. If changes are done this functions needs to be called again.

Returns:: A dictionary representing the created digital device twin.
Return type:: dict

set_general_information(uuid: str, fov: ndarray)[source]

Parameters:

uuid – is a string that uniquely identifies the photoacoustic device
fov – is an array of six float values that describe the extent of the field of view of the device in the x1, x2, and x3 directions: [x1_start, x1_end, x2_start, x2_end, x3_start, x3_end].

Returns:

No return value

Return type:

None

class IlluminationElementCreator[source]

Bases: object

A IlluminationElementCreator can be used to create illumination elements for the purposes of a standardised device representation within the IPASC data format.

It should be used in the following way:

iec = IlluminationElementCreator()
iec.set_illuminator_position(position)
# ... set other attributes
element = iec.get_dictionary()

The element dictionary can then be added to the DeviceMetaDataCreator.

Instantiates a IlluminationElementCreator.

get_dictionary()[source]

Returns a copy of a dictionary describing the created illumination element up to this point. Subsequent changes to the element via the IlluminationElementCreator will not alter the dictionary returned by this function. If changes are done this functions needs to be called again.

Returns:: A dictionary representing the created illumination element.
Return type:: dict

set_beam_divergence_angles(angle: float)[source]

Parameters:: angle – a value describing the opening angle of the laser beam from the illuminator shape with respect to the orientation vector. This angle is represented by the standard deviation of the beam divergence. The units can be found in MetadataDeviceTags.BEAM_DIVERGENCE_ANGLES.unit.
Returns:: No return value
Return type:: None

set_beam_energy_profile(energy_profile: ndarray)[source]

Parameters:: energy_profile – a two element array [wavelengths, laser_energy] describing the laser energy profile. beam energy and wavelengths are also arrays where len(laser_energy) == len(profile) The units can be found in MetadataDeviceTags.BEAM_ENERGY_PROFILE.unit.
Return type:: None

set_beam_intensity_profile(intensity_profile: ndarray)[source]

Parameters:: intensity_profile – a two element array [wavelengths, intensity_profile] describing the beam itensity profile. Wavelengths and intensity_profile are also arrays where len(wavelengths) == len(intensity_profile) The units can be found in MetadataDeviceTags.BEAM_INTENSITY_PROFILE.unit.
Return type:: None

set_beam_stability_profile(stability_profile: ndarray)[source]

Parameters:: stability_profile – a two element array [wavelengths,laser_stability,] describing the laser stability profile. Beam stability and wavelengths are also arrays where len(stability_profile) == len(wavelengths). The units can be found in MetadataDeviceTags.BEAM_STABILITY_PROFILE.unit.
Return type:: None

set_illuminator_geometry(shape: ndarray)[source]

Parameters:: shape – is an array of three float values that describe the shape of the illuminator in the x1, x2, and x3 direction. The units can be found in MetadataDeviceTags.ILLUMINATOR_GEOMETRY.unit.
Return type:: None

set_illuminator_geometry_type(illuminator_geometry_type: str)[source]

Parameters:

illuminator_geometry_type –

The illuminator geometry type defines how to interpret the data in the illuminator geometry field. The following geometry types are currently supported:

“CIRCULAR” - defined by a single value that determines the radius of the circle
“SPHERE” - defined by a single value that determines the radius of the sphere
“CUBOID” - defined by three values that determine the extent of the cuboid in x, y, and z dimensions, before the position and orientation transforms.
“MESH” - defined by a STL-formatted string that determines the positions of points and faces before the position and orientation transforms.

Return type:

None

set_illuminator_orientation(orientation: ndarray)[source]

Parameters:: orientation – is an array of three float values that describe the orientation of the illumination element in the x1, x2, and x3 direction. The units can be found in MetadataDeviceTags.ILLUMINATOR_ORIENTATION.unit.
Return type:: None

set_illuminator_position(illuminator_position: ndarray)[source]

Parameters:: illuminator_position – is an array of three float values that describe the position of the illumination element in the x1, x2, and x3 direction. The units can be found in MetadataDeviceTags.ILLUMINATOR_POSITION.unit.
Return type:: None

set_pulse_width(pulse_width: float)[source]

Parameters:: pulse_width – a floating point value describing the pulse width of the laser in the units of MetadataDeviceTags.PULSE_WIDTH.unit.
Return type:: None

set_wavelength_range(wl_range: ndarray)[source]

Parameters:: wl_range – is an array of three float values that describe the minimum wavelength lambda_min, the maximum wavelength lambda_max and a metric for the accuracy lambda_accuracy. The units can be found in MetadataDeviceTags.WAVELENGTH_RANGE.unit.
Return type:: None

DIMENSIONALITY_STRINGS = ['time', 'space', 'time and space']: The Dimenstionality_STRINGS define what the value space of the metadatum DIMENSIONALITY is.

class EnumeratedString(tag, minimal, dtype, unit='N/A', permissible_strings=None)[source]

Bases: MetaDatum

This MetaDatum is defined to be a string that must be from a defined list of strings.

Instantiates a MetaDatum and sets all relevant values.

Parameters:

tag (str) – The tag that corresponds to this meta datum.
minimal (bool) – Defines if the metadatum is minimal (i.e. if is MUST be reported). Without the minimal parameters, the time series data cannot be reconstructed into an image. All parameters that are not minimal are interpreted as “report if present”.
dtype (type, tuple) – The data type of the meta datum. Can either be a single type or a tuple of possible types.
unit (str) – The unit associated with this metadatum. Must be one of the strings defined in pacfish.Units.

Raises:

TypeError: – if one of the parameters is not of the correct type.

evaluate_value_range(value) → bool[source]

Evaluates if a given value fits to the acceptable value range of the MetaDatum.

Parameters:: value (object) – value to evaluate
Returns:: True if the given value is acceptable for the respective MetaDatum
Return type:: bool

class MetaDatum(tag: str, minimal: bool, dtype: (<class 'type'>, <class 'tuple'>), unit: str = 'N/A')[source]

Bases: ABC

This class represents a meta datum. A meta datum contains all necessary information to fully characterize the meta information represented by an instance of this class.

Instantiates a MetaDatum and sets all relevant values.

Parameters:

tag (str) – The tag that corresponds to this meta datum.
minimal (bool) – Defines if the metadatum is minimal (i.e. if is MUST be reported). Without the minimal parameters, the time series data cannot be reconstructed into an image. All parameters that are not minimal are interpreted as “report if present”.
dtype (type, tuple) – The data type of the meta datum. Can either be a single type or a tuple of possible types.
unit (str) – The unit associated with this metadatum. Must be one of the strings defined in pacfish.Units.

Raises:

TypeError: – if one of the parameters is not of the correct type.

abstract evaluate_value_range(value) → bool[source]

Evaluates if a given value fits to the acceptable value range of the MetaDatum.

Parameters:: value (object) – value to evaluate
Returns:: True if the given value is acceptable for the respective MetaDatum
Return type:: bool

class MetadataAcquisitionTags[source]

Bases: object

This class defines the MetaData that compose all information needed to describe the measurement circumstances for a given measurement of photoacoustic time series data.

It also specifies the naming conventions of the underlying HDF5 data fields. Furthermore, it is specified if a certain meta datum is minimal or not, the data type is defined and the units of the metadatum are given.

ACOUSTIC_COUPLING_AGENT = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

ACQUISITION_WAVELENGTHS = <pacfish.core.Metadata.NDimensionalNumpyArray object>

AD_SAMPLING_RATE = <pacfish.core.Metadata.NonNegativeNumber object>

COMPRESSION = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

DATA_TYPE = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

DIMENSIONALITY = <pacfish.core.Metadata.EnumeratedString object>

ELEMENT_DEPENDENT_GAIN = <pacfish.core.Metadata.NonNegativeNumbersInArray object>

ENCODING = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

FREQUENCY_DOMAIN_FILTER = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

MEASUREMENTS_PER_IMAGE = <pacfish.core.Metadata.NonNegativeWholeNumber object>

MEASUREMENT_SPATIAL_POSES = <pacfish.core.Metadata.NDimensionalNumpyArray object>

MEASUREMENT_TIMESTAMPS = <pacfish.core.Metadata.NonNegativeNumbersInArray object>

OVERALL_GAIN = <pacfish.core.Metadata.NonNegativeNumber object>

PHOTOACOUSTIC_IMAGING_DEVICE_REFERENCE = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

PULSE_ENERGY = <pacfish.core.Metadata.NonNegativeNumbersInArray object>

REGIONS_OF_INTEREST = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

SCANNING_METHOD = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

SIZES = <pacfish.core.Metadata.NonNegativeNumbersInArray object>

SPEED_OF_SOUND = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

TAGS = [<pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.EnumeratedString object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.NonNegativeNumber object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NonNegativeNumber object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NonNegativeWholeNumber object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>]

TAGS_ACQUISITION = [<pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.NonNegativeNumber object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NonNegativeNumber object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NonNegativeWholeNumber object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>]

TAGS_BINARY = [<pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.EnumeratedString object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>]

TAGS_CONTAINER = [<pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>]

TEMPERATURE_CONTROL = <pacfish.core.Metadata.NonNegativeNumbersInArray object>

TIME_GAIN_COMPENSATION = <pacfish.core.Metadata.NonNegativeNumbersInArray object>

UUID = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

class MetadataDeviceTags[source]

Bases: object

This class defines the MetaData that compose all information needed to describe a digital twin of a photoacoustic device.

It also specifies the naming conventions of the underlying HDF5 data fields. Furthermore, it is specified if a certain meta datum is minimal or not, the data type is defined and the units of the metadatum are given.

ANGULAR_RESPONSE = <pacfish.core.Metadata.NDimensionalNumpyArray object>

BEAM_DIVERGENCE_ANGLES = <pacfish.core.Metadata.NumberWithUpperAndLowerLimit object>

BEAM_ENERGY_PROFILE = <pacfish.core.Metadata.NDimensionalNumpyArray object>

BEAM_INTENSITY_PROFILE = <pacfish.core.Metadata.NDimensionalNumpyArray object>

BEAM_STABILITY_PROFILE = <pacfish.core.Metadata.NDimensionalNumpyArray object>

DETECTION_ELEMENT = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

DETECTORS = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

DETECTOR_GEOMETRY = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

DETECTOR_GEOMETRY_TYPE = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

DETECTOR_ORIENTATION = <pacfish.core.Metadata.NDimensionalNumpyArray object>

DETECTOR_POSITION = <pacfish.core.Metadata.NDimensionalNumpyArray object>

FIELD_OF_VIEW = <pacfish.core.Metadata.NDimensionalNumpyArrayWithMElements object>

FREQUENCY_RESPONSE = <pacfish.core.Metadata.NonNegativeNumbersInArray object>

GENERAL = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

ILLUMINATION_ELEMENT = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

ILLUMINATORS = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

ILLUMINATOR_GEOMETRY = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

ILLUMINATOR_GEOMETRY_TYPE = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

ILLUMINATOR_ORIENTATION = <pacfish.core.Metadata.NDimensionalNumpyArray object>

ILLUMINATOR_POSITION = <pacfish.core.Metadata.NDimensionalNumpyArray object>

INTENSITY_PROFILE_DISTANCE = <pacfish.core.Metadata.NonNegativeNumber object>

NUMBER_OF_DETECTION_ELEMENTS = <pacfish.core.Metadata.NonNegativeWholeNumber object>

NUMBER_OF_ILLUMINATION_ELEMENTS = <pacfish.core.Metadata.NonNegativeWholeNumber object>

PULSE_WIDTH = <pacfish.core.Metadata.NonNegativeNumber object>

TAGS = [<pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NDimensionalNumpyArrayWithMElements object>, <pacfish.core.Metadata.NonNegativeWholeNumber object>, <pacfish.core.Metadata.NonNegativeWholeNumber object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NonNegativeNumber object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NonNegativeNumber object>, <pacfish.core.Metadata.NumberWithUpperAndLowerLimit object>]

TAGS_DETECTORS = [<pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NonNegativeNumbersInArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>]

TAGS_GENERAL = [<pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NDimensionalNumpyArrayWithMElements object>, <pacfish.core.Metadata.NonNegativeWholeNumber object>, <pacfish.core.Metadata.NonNegativeWholeNumber object>]

TAGS_ILLUMINATORS = [<pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.UnconstrainedMetaDatum object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NonNegativeNumber object>, <pacfish.core.Metadata.NDimensionalNumpyArray object>, <pacfish.core.Metadata.NonNegativeNumber object>, <pacfish.core.Metadata.NumberWithUpperAndLowerLimit object>]

UNIQUE_IDENTIFIER = <pacfish.core.Metadata.UnconstrainedMetaDatum object>

WAVELENGTH_RANGE = <pacfish.core.Metadata.NDimensionalNumpyArray object>

class NDimensionalNumpyArray(tag, minimal, dtype, unit='N/A', expected_array_dimension=1)[source]

Bases: MetaDatum

This MetaDatum is defined to be an array of unconstrained numbers.

Instantiates a MetaDatum and sets all relevant values.

Parameters:

tag (str) – The tag that corresponds to this meta datum.
minimal (bool) – Defines if the metadatum is minimal (i.e. if is MUST be reported). Without the minimal parameters, the time series data cannot be reconstructed into an image. All parameters that are not minimal are interpreted as “report if present”.
dtype (type, tuple) – The data type of the meta datum. Can either be a single type or a tuple of possible types.
unit (str) – The unit associated with this metadatum. Must be one of the strings defined in pacfish.Units.

Raises:

TypeError: – if one of the parameters is not of the correct type.

evaluate_value_range(value) → bool[source]

Evaluates if a given value fits to the acceptable value range of the MetaDatum.

Parameters:: value (object) – value to evaluate
Returns:: True if the given value is acceptable for the respective MetaDatum
Return type:: bool

class NDimensionalNumpyArrayWithMElements(tag, minimal, dtype, unit='N/A', expected_array_dimension=1, elements_per_dimension=None)[source]

Bases: MetaDatum

This MetaDatum is defined to be an array with a specific dimensionality.

Instantiates a MetaDatum and sets all relevant values.

Parameters:

tag (str) – The tag that corresponds to this meta datum.
minimal (bool) – Defines if the metadatum is minimal (i.e. if is MUST be reported). Without the minimal parameters, the time series data cannot be reconstructed into an image. All parameters that are not minimal are interpreted as “report if present”.
dtype (type, tuple) – The data type of the meta datum. Can either be a single type or a tuple of possible types.
unit (str) – The unit associated with this metadatum. Must be one of the strings defined in pacfish.Units.

Raises:

TypeError: – if one of the parameters is not of the correct type.

evaluate_value_range(value) → bool[source]

Evaluates if a given value fits to the acceptable value range of the MetaDatum.

Parameters:: value (object) – value to evaluate
Returns:: True if the given value is acceptable for the respective MetaDatum
Return type:: bool

class NonNegativeNumber(tag, minimal, dtype, unit='N/A')[source]

Bases: MetaDatum

This MetaDatum is defined to be a non-negative number.

Instantiates a MetaDatum and sets all relevant values.

Parameters:

tag (str) – The tag that corresponds to this meta datum.
minimal (bool) – Defines if the metadatum is minimal (i.e. if is MUST be reported). Without the minimal parameters, the time series data cannot be reconstructed into an image. All parameters that are not minimal are interpreted as “report if present”.
dtype (type, tuple) – The data type of the meta datum. Can either be a single type or a tuple of possible types.
unit (str) – The unit associated with this metadatum. Must be one of the strings defined in pacfish.Units.

Raises:

TypeError: – if one of the parameters is not of the correct type.

evaluate_value_range(value) → bool[source]

Evaluates if a given value fits to the acceptable value range of the MetaDatum.

Parameters:: value (object) – value to evaluate
Returns:: True if the given value is acceptable for the respective MetaDatum
Return type:: bool

class NonNegativeNumbersInArray(tag, minimal, dtype, unit='N/A')[source]

Bases: MetaDatum

This MetaDatum is defined to be an array containing non-negative whole numbers.

Instantiates a MetaDatum and sets all relevant values.

Parameters:

tag (str) – The tag that corresponds to this meta datum.
minimal (bool) – Defines if the metadatum is minimal (i.e. if is MUST be reported). Without the minimal parameters, the time series data cannot be reconstructed into an image. All parameters that are not minimal are interpreted as “report if present”.
dtype (type, tuple) – The data type of the meta datum. Can either be a single type or a tuple of possible types.
unit (str) – The unit associated with this metadatum. Must be one of the strings defined in pacfish.Units.

Raises:

TypeError: – if one of the parameters is not of the correct type.

evaluate_value_range(value) → bool[source]

Evaluates if a given value fits to the acceptable value range of the MetaDatum.

Parameters:: value (object) – value to evaluate
Returns:: True if the given value is acceptable for the respective MetaDatum
Return type:: bool

class NonNegativeWholeNumber(tag, minimal, dtype, unit='N/A')[source]

Bases: MetaDatum

This MetaDatum is defined to be a non-negative whole number.

Instantiates a MetaDatum and sets all relevant values.

Parameters:

tag (str) – The tag that corresponds to this meta datum.
minimal (bool) – Defines if the metadatum is minimal (i.e. if is MUST be reported). Without the minimal parameters, the time series data cannot be reconstructed into an image. All parameters that are not minimal are interpreted as “report if present”.
dtype (type, tuple) – The data type of the meta datum. Can either be a single type or a tuple of possible types.
unit (str) – The unit associated with this metadatum. Must be one of the strings defined in pacfish.Units.

Raises:

TypeError: – if one of the parameters is not of the correct type.

evaluate_value_range(value) → bool[source]

Evaluates if a given value fits to the acceptable value range of the MetaDatum.

Parameters:: value (object) – value to evaluate
Returns:: True if the given value is acceptable for the respective MetaDatum
Return type:: bool

class NumberWithUpperAndLowerLimit(tag, minimal, dtype, unit='N/A', lower_limit=-inf, upper_limit=inf)[source]

Bases: MetaDatum

This MetaDatum is defined to be a whole number in between a lower and an upper bound (inclusive).

Instantiates a MetaDatum and sets all relevant values.

Parameters:

tag (str) – The tag that corresponds to this meta datum.
minimal (bool) – Defines if the metadatum is minimal (i.e. if is MUST be reported). Without the minimal parameters, the time series data cannot be reconstructed into an image. All parameters that are not minimal are interpreted as “report if present”.
dtype (type, tuple) – The data type of the meta datum. Can either be a single type or a tuple of possible types.
unit (str) – The unit associated with this metadatum. Must be one of the strings defined in pacfish.Units.

Raises:

TypeError: – if one of the parameters is not of the correct type.

evaluate_value_range(value) → bool[source]

Evaluates if a given value fits to the acceptable value range of the MetaDatum.

Parameters:: value (object) – value to evaluate
Returns:: True if the given value is acceptable for the respective MetaDatum
Return type:: bool

class UnconstrainedMetaDatum(tag, minimal, dtype, unit='N/A')[source]

Bases: MetaDatum

This MetaDatum has no limitations on the values associated with it.

Instantiates a MetaDatum and sets all relevant values.

Parameters:

tag (str) – The tag that corresponds to this meta datum.
minimal (bool) – Defines if the metadatum is minimal (i.e. if is MUST be reported). Without the minimal parameters, the time series data cannot be reconstructed into an image. All parameters that are not minimal are interpreted as “report if present”.
dtype (type, tuple) – The data type of the meta datum. Can either be a single type or a tuple of possible types.
unit (str) – The unit associated with this metadatum. Must be one of the strings defined in pacfish.Units.

Raises:

TypeError: – if one of the parameters is not of the correct type.

evaluate_value_range(value) → bool[source]

Evaluates if a given value fits to the acceptable value range of the MetaDatum.

Parameters:: value (object) – value to evaluate
Returns:: True if the given value is acceptable for the respective MetaDatum
Return type:: bool

class Units[source]

Bases: object

A list of the SI and compound units that are used in the IPASC format.

DIMENSIONLESS_UNIT = 'one'

HERTZ = 'Hz'

JOULES = 'J'

KELVIN = 'K'

METERS = 'm'

METERS_PER_SECOND = 'm/s'

NO_UNIT = 'N/A'

RADIANS = 'rad'

SECONDS = 's'

class PAData(binary_time_series_data: Optional[ndarray] = None, meta_data_acquisition: Optional[dict] = None, meta_data_device: Optional[dict] = None)[source]

Bases: object

The PAData class is the core class for accessing the information contained in the HDF5 files. Using the pacfish.load_data method yields an instance of this class.

It is structured into three main parts:

a numpy array containing the binary data

a dictionary with the acquisition metadata

a dictionary with the device metadata

Furthermore, this class contains convenience methods to access all fields within the HDF5 dictionary, without the necessity to know the internal structure by heart.

Creates an empty instance of the PAData class. To instantiate with a path to an HDF5 file, please use the pacfish.load_data method.

Parameters:

binary_time_series_data (np.ndarray) – a numpy array that must not be None
meta_data_acquisition (dict) – If None will be initialized as an empty dictionary.
meta_data_device (dict) – If None will be initialized as an empty dictionary.

Returns:

An empty PADta instance to be populated

Return type:

pacfish.PAData

get_acoustic_coupling_agent()[source]

A string representing the acoustic coupling agent that is used.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: str

get_acquisition_meta_datum(meta_data_tag: MetaDatum) → object[source]

This method returns data from the acquisition metadata dictionary

Parameters:: meta_data_tag – the MetaDatum instance for which to get the information.
Returns:: return value might be None, if the specified metadata tag was not found in the dictionary.
Return type:: object

get_acquisition_wavelengths()[source]

A 1D array that contains all wavelengths used for the image acquisition.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_angular_response(identifier=None)[source]

The angular response field characterizes the angular sensitivity of the detection element to the incident angle (relative to the elements orientation) of the incoming pressure wave.

Parameters:: identifier (str) – The ID of a specific detection element. If None then all detection elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_beam_divergence(identifier=None)[source]

The beam divergence angles represent the opening angles of the beam from the illuminator shape with respect to the orientation vector. This angle represented by the standard deviation of the beam divergence.

Parameters:: identifier (str) – The ID of a specific illumination element. If None then all illumination elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: float

get_beam_energy_profile(identifier=None)[source]

The beam energy profile field is a discretized functional of wavelength (nm) that represents the light energy of the illuminator with regard to the wavelength. Thereby, systematic differences in multispectral image acquisitions can be accounted for.

Parameters:: identifier (str) – The ID of a specific illumination element. If None then all illumination elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_beam_profile(identifier=None)[source]

The beam intensity profile is a function of a spatial position that specifies the relative beam intensity according to the planar emitting surface of the illuminator shape.

Parameters:: identifier (str) – The ID of a specific illumination element. If None then all illumination elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: str

get_beam_profile_distance(identifier=None)[source]

The distance from the light source for measuring its beam intensity profile.

Parameters:: identifier (str) – The ID of a specific illumination element. If None then all illumination elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: float

get_beam_stability_profile(identifier=None)[source]

The beam noise profile field is a functional of wavelength (nm) that represents the standard deviation of the pulse-to-pulse energy of the illuminator with regard to the wavelength.

Parameters:: identifier (str) – The ID of a specific illumination element. If None then all illumination elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarrayy

get_compression()[source]

The compression field is representative of the compression method that was used to compress the binary data. E.g. one of ‘raw’, ‘gzip’, …

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: str

get_custom_meta_datum(meta_data_tag: str) → object[source]

This method returns data from the acquisition metadata dictionary.

Parameters:: meta_data_tag – a string instance for which to get the information.
Returns:: return value might be None, if the specified metadata tag was not found in the dictionary.
Return type:: object

get_data_UUID()[source]

128-bit Integer displayed as a hexadecimal string in 5 groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters. The UUID is randomly generated using the UUID Version 4 standard.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: str

get_data_type()[source]

The data type field represents the datatype of the binary data. This field is given in the C++ data type naming convention. E.g. ‘short’, ‘unsigned short’, ‘int’, ‘unsigned int’, ‘long’, ‘unsigned long’, ‘long long’, ‘float’, ‘double’, ‘long double’.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: str

get_detector_attribute_for_tag(metadatum, identifier=None)[source]

Method all convenience functions regarding the detection elements are delegated to.

Parameters:

metadatum (MetaDatum) – The metadatum that corresponds to the information that should be extracted from the metadata dictionary.
identifier (str) – The ID of a specific detection element. If None then all detection elements are queried.

Returns:

return value can be None, of the key was not found in the metadata dictionary.

Return type:

object

get_detector_geometry(identifier=None)[source]

The element size defines the size of the detection element in 3D cartesian coordinates [x1, x2, x3] relative to its position and orientation.

Parameters:: identifier (str) – The ID of a specific detection element. If None then all detection elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_detector_geometry_type(identifier=None)[source]

The detector geometry type defines how to interpret the data in the detector geometry field. The following geometry types are currently supported:

“CIRCULAR” - defined by a single value that determines the radius of the circle

“SPHERE” - defined by a single value that determines the radius of the sphere

“CUBOID” - defined by three values that determine the extent of the cuboid in x, y, and z dimensions before the position and orientation transforms.

“MESH” - defined by a STL-formatted string that determines the positions of points and faces before the position and orientation transforms.

Parameters:: identifier (str) – The ID of a specific detection element. If None then all detection elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: str

get_detector_ids() → list[source]

Returns a list of all IDs of the detection elements that are added in this PAData instance.

Returns:: a list of all ids of the detection elements
Return type:: list

get_detector_orientation(identifier=None)[source]

The element orientation defines the rotation of the detection element in 3D cartesian coordinates [r1, r2, r3] in radians.

Parameters:: identifier (str) – The ID of a specific detection element. If None then all detection elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_detector_position(identifier=None)[source]

The detector position defines the position of the detection element centroid in 3D cartesian coordinates [x1, x2, x3].

Parameters:: identifier (str) – The ID of a specific detection element. If None then all detection elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_device_uuid()[source]

The UUID is a universally unique identifier to the device description that can be referenced.

Returns:: return value can be None, of no UUID was found in the metadata.
Return type:: str

get_dimensionality()[source]

The dimensionality field represents the acquisition format of the binary data and specifies the number of spatiotemporal dimensions of the data that is comprised of one or more frames. E.g. ‘1D’, ‘2D’, ‘3D’, ‘1D+t’, 2D+t’, ‘3D+t’. In this notion, the time series sampling of one transducer would count as a “spatial” dimension. These are defined as 1D = [𝝉], 2D = [x1, 𝝉], 3D = [x1, 𝝉, x2]. The “+t” will then add a time dimension for multiple of these frames.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: str

get_element_dependent_gain()[source]

An array that contains the relative factors used for apodisation or detection element-wise sensitivity corrections.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_encoding()[source]

The encoding field is representative of the character set that was used to encode the binary data and the metadata. E.g. one of ‘UTF-8’, ‘ASCII’, ‘CP-1252’, …

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: str

get_field_of_view()[source]

An array defining an approximate cuboid (3D) area that should be reconstructed in 3D Cartesian coordinates [x1_start, x1_end, x2_start, x2_end, x3_start, x3_end]. A 2D Field of View can be defined by setting the start and end coordinate of the respective dimension to the same value.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_frequency_domain_filter()[source]

The frequency threshold levels that have been applied to filter the raw time series data.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_frequency_response(identifier=None)[source]

The frequency response is a functional that characterizes the response of the detection element to the frequency of the incident pressure waves.

Parameters:: identifier (str) – The ID of a specific detection element. If None then all detection elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_illuminator_attribute_for_tag(metadatum, identifier=None)[source]

Method all convenience functions regarding the illumination elements are delegated to.

Parameters:

metadatum (MetaDatum) – The metadatum that corresponds to the information that should be extracted from the metadata dictionary.
identifier (str) – The ID of a specific illumination element. If None then all illumination elements are queried.

Returns:

return value can be None, of the key was not found in the metadata dictionary.

Return type:

object

get_illuminator_geometry(identifier=None)[source]

The illuminator shape defines the shape of the optical fibres, so it describes whether the illuminator is a point illuminator, or has a more continuous form. Illuminators can only have planar emitting surfaces.

Parameters:: identifier (str) – The ID of a specific illumination element. If None then all illumination elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_illuminator_geometry_type(identifier=None)[source]

The illuminator geometry type defines the shape of the optical fibre (bundle) output. It determines the interpretation of the data in the illuminator geometry field. The following geometry types are currently supported:

- "CIRCULAR" - defined by a single value that determines the radius of the circle
- "SPHERE" - defined by a single value that determines the radius of the sphere
- "CUBOID" - defined by three values that determine the extent of the cuboid in x, y,nand z dimensions before the position and orientation transforms.
- "MESH" - defined by a STL-formatted string that determines the positions of points and faces before the position and orientation transforms.

Parameters:: identifier (str) – The ID of a specific illumination element. If None then all illumination elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: str

get_illuminator_ids() → list[source]

Returns a list of all IDs of the illumination elements that are added in this PAData instance.

Returns:: a list of all ids of the illumination elements
Return type:: list

get_illuminator_orientation(identifier=None)[source]

The illuminator orientation defines the rotation of the illuminator in 3D cartesian coordinates [r1, r2, r3]. It is the normal of the planar illuminator surface.

Parameters:: identifier (str) – The ID of a specific illumination element. If None then all illumination elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_illuminator_position(identifier=None)[source]

The illuminator position defines the position of the illuminator centroid in 3D cartesian coordinates [x1, x2, x3] .

Parameters:: identifier (str) – The ID of a specific illumination element. If None then all illumination elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_measurement_spatial_poses()[source]

Coordinates describing the position and orientation changes of the acquisition system relative to the measurement of reference (first measurement).

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_measurement_time_stamps()[source]

An array specifying the time at which a measurement was recorded.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_measurements_per_image()[source]

A single value describing the number of measurements that constitute the dataset corresponding to one image.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: int

get_number_of_detectors()[source]

The number of detectors quantifies the number of transducer elements that are used in the respective PA imaging device. Each of these transducer elements is described by a set of detection geometry parameters.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: int

get_number_of_illuminators()[source]

The number of illuminators quantifies the number of illuminators that are used in the respective PA imaging device. Each of these illuminators is described by a set of illumination geometry parameters.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: int

get_overall_gain()[source]

A single value describing a factor used to modify the amplitude of the raw time series data.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: float

get_photoacoustic_imaging_device_reference()[source]

A string referencing the UUID of the PA imaging device description as defined in the Device Metadata.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: str

get_pulse_energy()[source]

A value specifying the pulse energy used to generate the photoacoustic signal. If the pulse energies are averaged over many pulses, the average value must be specified.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_pulse_width(identifier=None)[source]

The pulse duration or pulse width describes the total length of a light pulse, measured as the time interval between the half-power points on the leading and trailing edges of the pulse.

Parameters:: identifier (str) – The ID of a specific illumination element. If None then all illumination elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: str

get_regions_of_interest()[source]

A list of named regions within the underlying 3D Cartesian coordinate system (cf. Device Metadata). Strings containing the region names are mapped to arrays that define either an approximate cuboid area (cf. Field of View) or a list of coordinates describing a set of 3D Cartesian coordinates surrounding the named region.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_sampling_rate()[source]

A single value referring to the rate at which samples of the analogue signal are taken to be converted into digital form.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: float

get_scanning_method()[source]

A string representing the scanning method that is used. The following descriptions can be used: (“composite_scan”, “full_scan”). This flag determines the way the metadatum “measurement” is defined.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: str

get_sizes()[source]

The sizes field quantifies the number of data points in each of the dimensions specified in the dimensionality field. e.g. [128, 2560, 26] with a “2D+t” dimensionality.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_speed_of_sound()[source]

Either a single value representing the mean global speed of sound in the entire imaged medium or a 3D array representing a heterogeneous speed of sound map in the device coordinate system. This definition covers both the imaged medium and the coupling agent.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_temperature()[source]

An array describing the temperature of the imaged space (covering both the imaged medium and the coupling agent) for each measurement.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_time_gain_compensation()[source]

An array containing relative factors that have been used to correct the time series data for the effect of acoustic attenuation.

Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray

get_wavelength_range(identifier=None)[source]

The wavelength range quantifies the wavelength range that the illuminator is capable of generating by reporting three values: the minimum wavelength max, the maximum wavelength max and a metric for the accuracy accuracy: (min, max, accuracy). This parameter could for instance be (700, 900, 1.2), meaning that this illuminator can be tuned from 700 nm to 900 nm with an accuracy of 1.2 nm.

Parameters:: identifier (str) – The ID of a specific illumination element. If None then all illumination elements are queried.
Returns:: return value can be None, of the key was not found in the metadata dictionary.
Return type:: np.ndarray