libraries

class BlobHeterogeneity(xdim, ydim, zdim, spacing_mm, num_centers=None, cluster_std=None, target_mean=None, target_std=None, target_min=None, target_max=None, random_state=None)[source]

Bases: HeterogeneityGeneratorBase

This heterogeneity generator representes a blob-like random sampling between the given bounds using the sklearn.datasets.make_blobs method. Please look into their documentation for optimising the given hyperparameters.

Parameters:

  • xdim – the x dimension of the volume in voxels

  • ydim – the y dimension of the volume in voxels

  • zdim – the z dimension of the volume in voxels

  • spacing_mm – the spacing of the volume in mm

  • num_centers – the number of blobs

  • cluster_std – the size of the blobs

  • target_mean – (optional) the mean of the created heterogeneity map

  • target_std – (optional) the standard deviation of the created heterogeneity map

  • target_min – (optional) the minimum of the created heterogeneity map

  • target_max – (optional) the maximum of the created heterogeneity map

class HeterogeneityGeneratorBase(xdim, ydim, zdim, spacing_mm, target_mean=None, target_std=None, target_min=None, target_max=None, eps=1e-05)[source]

Bases: object

This is the base class to define heterogeneous structure maps.

Parameters:

  • xdim – the x dimension of the volume in voxels

  • ydim – the y dimension of the volume in voxels

  • zdim – the z dimension of the volume in voxels

  • spacing_mm – the spacing of the volume in mm

  • target_mean – (optional) the mean of the created heterogeneity map

  • target_std – (optional) the standard deviation of the created heterogeneity map

  • target_min – (optional) the minimum of the created heterogeneity map

  • target_max – (optional) the maximum of the created heterogeneity map

  • eps – (optional) the threshold when a re-normalisation should be triggered (default: 1e-5)

get_map()[source]
normalise_map()[source]

If mean and std are set, then the data will be normalised to have the desired mean and the desired standard deviation. If min and max are set, then the data will be normalised to have the desired minimum and the desired maximum value. If all four values are set, then the data will be normalised to have the desired mean and the desired standard deviation first. afterwards all values smaller than min will be ste to min and all values larger than max will be set to max.

class ImageHeterogeneity(xdim: int, ydim: int, zdim: int, heterogeneity_image: ~numpy.ndarray, spacing_mm: ~typing.Union[int, float] = None, image_pixel_spacing_mm: ~typing.Union[int, float] = None, scaling_type: [None, <class 'str'>] = None, constant: ~typing.Union[int, float] = 0, crop_placement=('centre', 'centre'), target_mean: ~typing.Union[int, float] = None, target_std: ~typing.Union[int, float] = None, target_min: ~typing.Union[int, float] = None, target_max: ~typing.Union[int, float] = None)[source]

Bases: HeterogeneityGeneratorBase

This heterogeneity generator takes a pre-specified 2D image, currently only supporting numpy arrays, and uses them as a map for heterogeneity within the tissue.

map

the np array of the heterogeneity map transformed and augments to fill the area

Parameters:

  • xdim – the x dimension of the volume in voxels

  • ydim – the y dimension of the volume in voxels

  • zdim – the z dimension of the volume in voxels

  • heterogeneity_image – the 2D prior image of the heterogeneity map

  • spacing_mm – the spacing of the volume in mm

  • image_pixel_spacing_mm – the pixel spacing of the image in mm (pixel spacing)

  • scaling_type – the scaling type of the heterogeneity map, with default being that no scaling occurs OPTIONS: TAGS.IMAGE_SCALING_SYMMETRIC: symmetric reflections of the image to span the area TAGS.IMAGE_SCALING_STRETCH: stretch the image to span the area TAGS.IMAGE_SCALING_WRAP: multiply the image to span the area TAGS.IMAGE_SCALING_EDGE: continue the values at the edge of the area to fill the shape TAGS.IMAGE_SCALING_CONSTANT: span the left-over area with a constant

  • constant – the scaling constant of the heterogeneity map, used only for scaling type ‘constant’ WARNING: scaling constant must be in reference to the values in the heterogeneity_image

  • crop_placement – the placement of where the heterogeneity map is cropped

  • target_mean – (optional) the mean of the created heterogeneity map

  • target_std – (optional) the standard deviation of the created heterogeneity map

  • target_min – (optional) the minimum of the created heterogeneity map

  • target_max – (optional) the maximum of the created heterogeneity map

change_resolution(image: ndarray, spacing_mm: Union[int, float], image_pixel_spacing_mm: Union[int, float]) → ndarray[source]

Method to change the resolution of an image :param image: input image :param image_pixel_spacing_mm: original image pixel spacing mm :param spacing_mm: target pixel spacing mm :return: image with new pixel spacing

crop_image(xdim: int, zdim: int, image: ndarray, crop_placement: Union[str, tuple] = 'centre') → ndarray[source]

Crop the image to fit specified dimensions xdim and zdim :param xdim: the x dimension of the area to be filled in voxels :param zdim: the z dimension of the area to be filled in voxels :param image: the input image :param crop_placement: the placement of where the heterogeneity map is cropped

OPTIONS: TAGS.CROP_PLACEMENT_[TOP,BOTTOM,LEFT,RIGHT,CENTRE,RANDOM] or position of left hand corner on image

Returns:

cropped image

upsize_to_fill_area(xdim: int, zdim: int, image: ndarray, scaling_type: Optional[str] = None, constant: Union[int, float] = 0) → ndarray[source]

Fills an area with an image through various methods of expansion :param xdim: the x dimension of the area to be filled in voxels :param zdim: the z dimension of the area to be filled in voxels :param image: the input image :param scaling_type: the scaling type of the heterogeneity map, with default being that no scaling occurs

OPTIONS: TAGS.IMAGE_SCALING_SYMMETRIC: symmetric reflections of the image to span the area TAGS.IMAGE_SCALING_STRETCH: stretch the image to span the area TAGS.IMAGE_SCALING_WRAP: multiply the image to span the area TAGS.IMAGE_SCALING_EDGE: continue the values at the edge of the area to fill the shape TAGS.IMAGE_SCALING_CONSTANT: span the left-over area with a constant

Parameters:

constant – the scaling constant of the heterogeneity map, used only for scaling type ‘constant’

:return:A numpy array of size (xdim, zdim) containing the filled image expanded to fill the shape

class RandomHeterogeneity(xdim, ydim, zdim, spacing_mm, gaussian_blur_size_mm=None, target_mean=None, target_std=None, target_min=None, target_max=None, eps=1e-05)[source]

Bases: HeterogeneityGeneratorBase

This heterogeneity generator represents a uniform random sampling between the given bounds. Optionally, a Gaussian blur can be specified. Please not that a Gaussian blur will transform the random distribution to a Gaussian.

Parameters:

  • xdim – the x dimension of the volume in voxels

  • ydim – the y dimension of the volume in voxels

  • zdim – the z dimension of the volume in voxels

  • spacing_mm – the spacing of the volume in mm

  • gaussian_blur_size_mm – the size of the standard deviation for the Gaussian blur

  • target_mean – (optional) the mean of the created heterogeneity map

  • target_std – (optional) the standard deviation of the created heterogeneity map

  • target_min – (optional) the minimum of the created heterogeneity map

  • target_max – (optional) the maximum of the created heterogeneity map

  • eps – (optional) the threshold when a re-normalisation should be triggered (default: 1e-5)

class MorphologicalTissueProperties[source]

Bases: object

This class contains a listing of morphological tissue parameters as reported in literature. The listing is not the result of a meta analysis, but rather uses the best fitting paper at the time pf implementation. Each of the fields is annotated with a literature reference or a descriptions of how the particular values were derived for tissue modelling.

ACCOMPANYING_VEIN_DEPTH_STD_MM = 1.5
ACCOMPANYING_VEIN_DISTANCE_MEAN_MM = 2.5
ACCOMPANYING_VEIN_DISTANCE_STD_MM = 0.4
ACCOMPANYING_VEIN_MEDIAN_DISTANCE_MEAN_MM = 1.0
ACCOMPANYING_VEIN_MEDIAN_DISTANCE_STD_MM = 0.2
ARTERY_X_POSITION_UNCERTAINTY_MM = 3.5355339059327373
DERMIS_THICKNESS_MEAN_MM = 2.3
DERMIS_THICKNESS_STD_MM = 1.2
DISTANCE_RADIAL_AND_ULNA_ARTERY_MEAN_MM = 30
DISTANCE_RADIAL_AND_ULNA_ARTERY_STD_MM = 5
EPIDERMIS_THICKNESS_MEAN_MM = 0.22
EPIDERMIS_THICKNESS_STD_MM = 0.1
MEDIAN_ARTERY_DEPTH_MEAN_MM = 19.0
MEDIAN_ARTERY_DEPTH_STD_MM = 1.0
MEDIAN_ARTERY_DIAMETER_MEAN_MM = 0.6
MEDIAN_ARTERY_DIAMETER_STD_MM = 0.25
MEDIAN_ARTERY_X_POSITION_MEAN_MM = 22.5
MEDIAN_VEIN_DIAMETER_MEAN_MM = 0.5
MEDIAN_VEIN_DIAMETER_STD_MM = 0.1
RADIAL_ARTERY_DEPTH_MEAN_MM = 6.0
RADIAL_ARTERY_DEPTH_STD_MM = 0.5
RADIAL_ARTERY_DIAMETER_MEAN_MM = 2.25
RADIAL_ARTERY_DIAMETER_STD_MM = 0.4
RADIAL_ARTERY_X_POSITION_MEAN_MM = 7.5
RADIAL_VEIN_DIAMETER_MEAN_MM = 1.0
RADIAL_VEIN_DIAMETER_STD_MM = 0.2
RADIUS_BONE_DEPTH_MEAN_MM = 22.0
RADIUS_BONE_DEPTH_STD_MM = 2.0
RADIUS_BONE_DIAMETER_MEAN_MM = 20.0
RADIUS_BONE_DIAMETER_STD_MM = 2.0
RADIUS_ULNA_BONE_POSITION_STD_MM = 2.0
RADIUS_ULNA_BONE_SEPARATION_MEAN_MM = 32.0
SUBCUTANEOUS_VEIN_DEPTH_MEAN_MM = 1.5
SUBCUTANEOUS_VEIN_DEPTH_STD_MM = 0.7
SUBCUTANEOUS_VEIN_DIAMETER_MEAN_MM = 0.8
SUBCUTANEOUS_VEIN_DIAMETER_STD_MM = 0.6
ULNAR_ARTERY_DEPTH_MEAN_MM = 6.0
ULNAR_ARTERY_DEPTH_STD_MM = 0.5
ULNAR_ARTERY_DIAMETER_MEAN_MM = 2.35
ULNAR_ARTERY_DIAMETER_STD_MM = 0.35
ULNAR_ARTERY_X_POSITION_MEAN_MM = 37.5
ULNAR_VEIN_DIAMETER_MEAN_MM = 1.0
ULNAR_VEIN_DIAMETER_STD_MM = 0.2
ULNA_BONE_DEPTH_MEAN_MM = 22.0
ULNA_BONE_DEPTH_STD_MM = 2.0
ULNA_BONE_DIAMETER_MEAN_MM = 15.0
ULNA_BONE_DIAMETER_STD_MM = 2.0
class OpticalTissueProperties[source]

Bases: object

This class contains a listing of optical tissue parameters as reported in literature. The listing is not the result of a meta analysis, but rather uses the best fitting paper at the time pf implementation. Each of the fields is annotated with a literature reference or a descriptions of how the particular values were derived for tissue modelling.

ARTERIAL_OXYGENATION = 0.95
ARTERIAL_OXYGENATION_VARIATION = 0.05
BACKGROUND_OXYGENATION = 0.5
BACKGROUND_OXYGENATION_VARIATION = 0.5
BLOOD_ANISOTROPY = 0.98
BLOOD_PLASMA_FRACTION = 0.55
BLOOD_VOLUME_FRACTION_LYMPH_NODE = 0.14
BLOOD_VOLUME_FRACTION_LYMPH_NODE_VARIATION = 0.07
BLOOD_VOLUME_FRACTION_MUSCLE_TISSUE = 0.01
BMIE_BACKGROUND_TISSUE = 1.091
BMIE_BLOOD = 0.93
BMIE_BONE = 0.326
BMIE_DERMIS = 3.5
BMIE_EPIDERMIS = 2.8
BMIE_FAT = 0.447
BMIE_MUSCLE_TISSUE = 1.5
BONE_ABSORPTION = 1.8
DERMIS_ANISOTROPY = 0.715
FRAY_BACKGROUND_TISSUE = 0.153
FRAY_BLOOD = 0.0
FRAY_BONE = 0.022
FRAY_DERMIS = 0.1
FRAY_EPIDERMIS = 0.29
FRAY_FAT = 0.174
FRAY_MUSCLE_TISSUE = 0.21
LYMPH_NODE_OXYGENATION = 0.73
LYMPH_NODE_OXYGENATION_VARIATION = 0.15
MELANIN_VOLUME_FRACTION_MEAN = 0.014
MELANIN_VOLUME_FRACTION_STD = 0.003
MUS500_BACKGROUND_TISSUE = 191.0
MUS500_BLOOD = 1170
MUS500_BONE = 153.0
MUS500_DERMIS = 175.0
MUS500_EPIDERMIS = 93.01
MUS500_FAT = 193.0
MUS500_MUSCLE_TISSUE = 161.0
STANDARD_ANISOTROPY = 0.9
VENOUS_OXYGENATION = 0.7
VENOUS_OXYGENATION_VARIATION = 0.1
WATER_VOLUME_FRACTION_BONE_MEAN = 0.19
WATER_VOLUME_FRACTION_BONE_STD = 0.01
WATER_VOLUME_FRACTION_HUMAN_BODY = 0.68
WATER_VOLUME_FRACTION_SKIN = 0.58
class StandardProperties[source]

Bases: object

This class contains a listing of default parameters that can be used. These values are sensible default values but are generally not backed up by proper scientific references, or are rather specific for internal use cases.

AIR_G = 1.0
AIR_MUA = 1e-10
AIR_MUS = 1e-10
ALPHA_COEFF_AIR = 0.0033875
ALPHA_COEFF_BLOOD = 0.2
ALPHA_COEFF_BONE = 4.7385
ALPHA_COEFF_FAT = 0.3785
ALPHA_COEFF_GEL_PAD = 0.277
ALPHA_COEFF_GENERIC = 0.02
ALPHA_COEFF_LYMPH_NODE = 2.5
ALPHA_COEFF_MUSCLE = 0.6175
ALPHA_COEFF_SKIN = 0.35
ALPHA_COEFF_WATER = 0.0021976
BODY_TEMPERATURE_CELCIUS = 37.0
DENSITY_AIR = 1.16
DENSITY_BLOOD = 1049.75
DENSITY_BONE = 1908
DENSITY_FAT = 911
DENSITY_GEL_PAD = 890
DENSITY_GENERIC = 1000
DENSITY_HEAVY_WATER = 1107
DENSITY_LYMPH_NODE = 1035
DENSITY_MUSCLE = 1090.4
DENSITY_SKIN = 1109
DENSITY_WATER = 1000
GELPAD_G = 1.0
GELPAD_MUA = 1e-10
GELPAD_MUS = 1e-10
HEAVY_WATER_MUA = 0.0008
SPEED_OF_SOUND_AIR = 343.0
SPEED_OF_SOUND_BLOOD = 1578.2
SPEED_OF_SOUND_BONE = 3514.9
SPEED_OF_SOUND_FAT = 1440.2
SPEED_OF_SOUND_GEL_PAD = 1583.0
SPEED_OF_SOUND_GENERIC = 1540.0
SPEED_OF_SOUND_HEAVY_WATER = 1540
SPEED_OF_SOUND_LYMPH_NODE = 1586
SPEED_OF_SOUND_MUSCLE = 1588.4
SPEED_OF_SOUND_SKIN = 1624.0
SPEED_OF_SOUND_WATER = 1482.3
WATER_G = 1.0
WATER_MUS = 1e-10
class MolecularComposition(segmentation_type: Optional[str] = None, molecular_composition_settings: Optional[dict] = None)[source]

Bases: SerializableSIMPAClass, list

A class representing a molecular composition which is a list of Molecules.

segmentation_type

The type of segmentation.

Type:

str

internal_properties

The internal tissue properties.

Type:

TissueProperties

Initialize the MolecularComposition object.

Parameters:

  • segmentation_type (str, optional) – The segmentation class associated with this molecular composition.

  • molecular_composition_settings – A settings dictionary or dict containing the molecules that constitute

this composition :type molecular_composition_settings: dict, optional

static deserialize(dictionary_to_deserialize: dict)[source]

Deserialize a dictionary into a MolecularComposition object.

Parameters:

dictionary_to_deserialize – The dictionary to deserialize.

Returns:

The deserialized MolecularComposition object.

get_properties_for_wavelength(settings, wavelength) → TissueProperties[source]

Get the tissue properties for a specific wavelength.

Parameters:

wavelength – The wavelength to get properties for.

Returns:

The updated tissue properties.

serialize() → dict[source]

Serialize the molecular composition to a dictionary.

Returns:

The serialized molecular composition.

update_internal_properties(settings)[source]

Re-defines the internal properties of the molecular composition. For each data field and molecule, a linear mixing model is used to arrive at the final parameters.

Raises:

AssertionError – If the total volume fraction of all molecules is not exactly 100%.

class MolecularCompositionGenerator[source]

Bases: object

The MolecularCompositionGenerator is a helper class to facilitate the creation of a MolecularComposition instance.

This class provides methods to build and retrieve a molecular composition by appending Molecule objects to a dictionary, which is then used to create a MolecularComposition instance.

Initialize a new MolecularCompositionGenerator.

The constructor initializes an empty dictionary to store the molecular composition.

append(value: Optional[Molecule] = None, key: Optional[str] = None)[source]

Append a Molecule to the molecular composition.

Adds the given Molecule object to the molecular composition dictionary with the specified key. If no key is provided, the name attribute of the Molecule is used as the key.

Parameters:

  • value – The Molecule object to add to the molecular composition.

  • key – The key under which the Molecule should be stored. If None, the Molecule’s name is used.

Raises:

KeyError – If the specified key already exists in the molecular composition.

Returns:

The current instance of MolecularCompositionGenerator.

get_molecular_composition(segmentation_type)[source]

Retrieve the molecular composition as a MolecularComposition instance.

Creates a MolecularComposition instance using the current state of the molecular composition dictionary and the specified segmentation type.

Parameters:

segmentation_type – The type of segmentation to be used in the MolecularComposition.

Returns:

A MolecularComposition instance.

class Molecule(name: Optional[str] = None, absorption_spectrum: Optional[Spectrum] = None, volume_fraction: Optional[float] = None, scattering_spectrum: Optional[Spectrum] = None, anisotropy_spectrum: Optional[Spectrum] = None, gruneisen_parameter: Optional[float] = None, density: Optional[float] = None, speed_of_sound: Optional[float] = None, alpha_coefficient: Optional[float] = None)[source]

Bases: SerializableSIMPAClass, object

A class representing a molecule with various properties.

name

The name of the molecule.

Type:

str

spectrum

The absorption spectrum of the molecule.

Type:

Spectrum

volume_fraction

The volume fraction of the molecule.

Type:

float

scattering_spectrum

The scattering spectrum of the molecule.

Type:

Spectrum

anisotropy_spectrum

The anisotropy spectrum of the molecule.

Type:

Spectrum

gruneisen_parameter

The Grüneisen parameter of the molecule.

Type:

float

density

The density of the molecule.

Type:

float

speed_of_sound

The speed of sound in the molecule.

Type:

float

alpha_coefficient

The alpha coefficient of the molecule.

Type:

float

Initialize the Molecule object.

Parameters:

  • name – The name of the molecule.

  • absorption_spectrum – The absorption spectrum of the molecule.

  • volume_fraction – The volume fraction of the molecule.

  • scattering_spectrum – The scattering spectrum of the molecule.

  • anisotropy_spectrum – The anisotropy spectrum of the molecule.

  • gruneisen_parameter – The Grüneisen parameter of the molecule.

  • density – The density of the molecule.

  • speed_of_sound – The speed of sound in the molecule.

  • alpha_coefficient – The alpha coefficient of the molecule.

__eq__(other) → bool[source]

Check equality between two Molecule objects.

Parameters:

other – The other Molecule object to compare.

Returns:

True if the Molecule objects are equal, False otherwise.

static deserialize(dictionary_to_deserialize: dict)[source]

Deserialize a dictionary into a Molecule object.

Parameters:

dictionary_to_deserialize – The dictionary to deserialize.

Returns:

The deserialized Molecule object.

get_volume_fraction()[source]
serialize()[source]

Serialize the molecule to a dictionary.

Returns:

The serialized molecule.

Return type:

dict

class MoleculeLibrary[source]

Bases: object

A class to create predefined molecules with specific properties.

Each method in this class returns a Molecule object with predefined settings representing different types of tissues or substances.

static air(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create an air molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing air

static bone(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create a bone molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing bone

static constant_scatterer(scattering_coefficient: float = 100.0, anisotropy: float = 0.9, volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create a constant scatterer molecule with predefined properties.

Parameters:

  • scattering_coefficient – The scattering coefficient, defaults to 100.0

  • anisotropy – The anisotropy factor, defaults to 0.9

  • volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing a constant scatterer

static deoxyhemoglobin(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create a deoxyhemoglobin molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing deoxyhemoglobin

static dermal_scatterer(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create a dermal scatterer molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing a dermal scatterer

static epidermal_scatterer(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create an epidermal scatterer molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing an epidermal scatterer

static fat(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create a fat molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing fat

static heavy_water(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create a heavy water molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing heavy water

static mediprene(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create a mediprene molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing mediprene

static melanin(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create a melanin molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing melanin

static muscle_scatterer(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create a muscle scatterer molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing a muscle scatterer

static oxyhemoglobin(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create an oxyhemoglobin molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing oxyhemoglobin

static soft_tissue_scatterer(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create a soft tissue scatterer molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing a soft tissue scatterer

static water(volume_fraction: (<class 'float'>, <class 'torch.Tensor'>) = 1.0) → Molecule[source]

Create a water molecule with predefined properties.

Parameters:

volume_fraction – The volume fraction of the molecule, defaults to 1.0

Returns:

A Molecule object representing water

class AbsorptionSpectrumLibrary(additional_folder_path: Optional[str] = None)[source]

Bases: SpectraLibrary

A library to manage and store absorption spectra data.

Initializes the AbsorptionSpectrumLibrary with absorption spectra data.

Parameters:

additional_folder_path – An additional folder path for more absorption spectra data.

static CONSTANT_ABSORBER_ARBITRARY(absorption_coefficient: float = 1) → Spectrum[source]

Creates a constant absorption spectrum with an arbitrary value.

Parameters:

absorption_coefficient – The absorption coefficient to use.

Returns:

A Spectrum instance with constant absorption.

class AnisotropySpectrumLibrary(additional_folder_path: Optional[str] = None)[source]

Bases: SpectraLibrary

A library to manage and store anisotropy spectra data.

Initializes the AnisotropySpectrumLibrary with anisotropy spectra data.

Parameters:

additional_folder_path – An additional folder path for more anisotropy spectra data.

static CONSTANT_ANISOTROPY_ARBITRARY(anisotropy: float = 1) → Spectrum[source]

Creates a constant anisotropy spectrum with an arbitrary value.

Parameters:

anisotropy – The anisotropy value to use.

Returns:

A Spectrum instance with constant anisotropy.

class ScatteringSpectrumLibrary(additional_folder_path: Optional[str] = None)[source]

Bases: SpectraLibrary

A library to manage and store scattering spectra data.

Initializes the ScatteringSpectrumLibrary with scattering spectra data.

Parameters:

additional_folder_path – An additional folder path for more scattering spectra data.

static CONSTANT_SCATTERING_ARBITRARY(scattering: float = 1) → Spectrum[source]

Creates a constant scattering spectrum with an arbitrary value.

Parameters:

scattering – The scattering value to use.

Returns:

A Spectrum instance with constant scattering.

static scattering_from_rayleigh_and_mie_theory(name: str, mus_at_500_nm: float = 1.0, fraction_rayleigh_scattering: float = 0.0, mie_power_law_coefficient: float = 0.0) → Spectrum[source]

Creates a scattering spectrum based on Rayleigh and Mie scattering theory.

Parameters:

  • name – The name of the spectrum.

  • mus_at_500_nm – Scattering coefficient at 500 nm.

  • fraction_rayleigh_scattering – Fraction of Rayleigh scattering.

  • mie_power_law_coefficient – Power law coefficient for Mie scattering.

Returns:

A Spectrum instance based on Rayleigh and Mie scattering theory.

class SpectraLibrary(folder_name: str, additional_folder_path: Optional[str] = None)[source]

Bases: object

A library to manage and store spectral data.

This class provides functionality to load and manage spectra data from specified folders.

spectra

A list to store spectra objects.

Type:

list

Initializes the SpectraLibrary with spectra data from the specified folder(s).

Parameters:

  • folder_name – The name of the folder containing spectra data files.

  • additional_folder_path – An additional folder path for more spectra data.

add_spectra_from_folder(folder_name: str)[source]

Adds spectra from a specified folder to the spectra list.

Parameters:

folder_name – The name of the folder containing spectra data files.

get_spectra_names() → list[source]

Returns the names of all spectra in the library.

Returns:

List of spectra names.

get_spectrum_by_name(spectrum_name: str) → Spectrum[source]

Retrieves a spectrum by its name.

Parameters:

spectrum_name – The name of the spectrum to retrieve.

Returns:

The spectrum with the specified name.

Raises:

LookupError – If no spectrum with the given name exists.

class Spectrum(spectrum_name: str, wavelengths: ndarray, values: ndarray)[source]

Bases: SerializableSIMPAClass, object

An instance of this class represents a spectrum over a range of wavelengths.

spectrum_name

The name of the spectrum.

Type:

str

wavelengths

Array of wavelengths.

Type:

np.ndarray

max_wavelength

Maximum wavelength in the spectrum.

Type:

int

min_wavelength

Minimum wavelength in the spectrum.

Type:

int

values

Corresponding values for each wavelength.

Type:

np.ndarray

values_interp

Interpolated values across a continuous range of wavelengths.

Type:

np.ndarray

Initializes a Spectrum instance.

Parameters:

  • spectrum_name – Name of the spectrum.

  • wavelengths – Array of wavelengths.

  • values – Corresponding values of the spectrum at each wavelength.

Raises:

ValueError – If the shape of wavelengths does not match the shape of values.

__eq__(other)[source]

Compares two Spectrum objects for equality.

Parameters:

other – Another Spectrum object to compare with.

Returns:

True if both objects are equal, False otherwise.

static deserialize(dictionary_to_deserialize: dict)[source]

Static method to deserialize a dictionary representation back into a Spectrum object.

Parameters:

dictionary_to_deserialize – Dictionary containing the serialized Spectrum object.

Returns:

Deserialized Spectrum object.

get_value_for_wavelength(wavelength: int) → float[source]

Retrieves the interpolated value for a given wavelength within the spectrum range.

Parameters:

wavelength – the wavelength to retrieve a value from the defined spectrum. Must be an integer value between the minimum and maximum wavelength.

Returns:

the best matching linearly interpolated values for the given wavelength.

Raises:

ValueError – if the given wavelength is not within the range of the spectrum.

get_value_over_wavelength() → ndarray[source]

Returns an array with the available wavelengths and their corresponding values.

Returns:

numpy array with the available wavelengths and the corresponding properties

serialize() → dict[source]

Serializes the spectrum instance into a dictionary format.

Returns:

Dictionary representation of the Spectrum instance.

get_simpa_internal_absorption_spectra_by_names(absorption_spectrum_names: list) → list[source]

Retrieves SIMPA internal absorption spectra by their names.

Parameters:

absorption_spectrum_names – List of absorption spectrum names to retrieve.

Returns:

List of Spectrum instances corresponding to the given names.

view_saved_spectra(save_path=None, mode='absorption')[source]

Opens a matplotlib plot and visualizes the available spectra.

Parameters:

  • save_path – If not None, then the figure will be saved as a PNG file to the destination.

  • mode – Specifies the type of spectra to visualize (“absorption”, “scattering”, or “anisotropy”).

class TissueLibrary[source]

Bases: object

A library, returning molecular compositions for various typical tissue segmentations.

blood(oxygenation: Optional[Union[float, int, ndarray]] = None) → MolecularComposition[source]

Create a molecular composition mimicking that of blood :param oxygenation: The oxygenation level of the blood(as a decimal). Default: random oxygenation between 0 and 1. :return: a settings dictionary containing all min and max parameters fitting for full blood.

bone() → MolecularComposition[source]

Create a molecular composition mimicking that of bone :return: a settings dictionary fitting for bone.

constant(mua: Union[float, int, ndarray] = 1e-10, mus: Union[float, int, ndarray] = 1e-10, g: Union[float, int, ndarray] = 0) → MolecularComposition[source]

A function returning a molecular composition as specified by the user. Typically intended for the use of wanting specific mua, mus and g values. :param mua: optical absorption coefficient Default: 1e-10 cm^⁻1 :param mus: optical scattering coefficient Default: 1e-10 cm^⁻1 :param g: optical scattering anisotropy Default: 0 :return: the molecular composition as specified by the user

dermis(oxygenation: Union[float, int, ndarray] = 0.5, blood_volume_fraction: Union[float, int, ndarray] = 0.002) → MolecularComposition[source]

Create a molecular composition mimicking that of dermis :param oxygenation: The oxygenation level of the blood volume fraction (as a decimal). Default: 0.5 :param blood_volume_fraction: The total blood volume fraction (including oxygenated and deoxygenated blood). Default: 0.002 :return: a settings dictionary containing all min and max parameters fitting for dermis tissue.

epidermis(melanin_volume_fraction: Union[float, int, ndarray] = 0.014) → MolecularComposition[source]

Create a molecular composition mimicking that of dermis :param melanin_volume_fraction: the total volume fraction of melanin :return: a settings dictionary containing all min and max parameters fitting for epidermis tissue.

generic_tissue(mua: ~simpa.utils.libraries.spectrum_library.Spectrum = <simpa.utils.libraries.spectrum_library.Spectrum object>, mus: ~simpa.utils.libraries.spectrum_library.Spectrum = <simpa.utils.libraries.spectrum_library.Spectrum object>, g: ~simpa.utils.libraries.spectrum_library.Spectrum = <simpa.utils.libraries.spectrum_library.Spectrum object>, molecule_name: ~typing.Optional[str] = 'generic_tissue') → MolecularComposition[source]

Returns a generic issue defined by the provided optical parameters.

Parameters:

  • mua – The absorption coefficient spectrum in cm^{-1}.

  • mus – The scattering coefficient spectrum in cm^{-1}.

  • g – The anisotropy spectrum.

  • molecule_name – The molecule name.

Returns:

The molecular composition of the tissue.

get_blood_volume_fractions(oxygenation: Union[float, int, ndarray] = 1e-10, blood_volume_fraction: Union[float, int, ndarray] = 1e-10) → List[Union[int, float, ndarray]][source]

A function that returns the volume fraction of the oxygenated and deoxygenated blood. :param oxygenation: The oxygenation level of the blood volume fraction (as a decimal). Default: 1e-10 :param blood_volume_fraction: The total blood volume fraction (including oxygenated and deoxygenated blood). Default: 1e-10 :return: the blood volume fraction of the oxygenated and deoxygenated blood separately.

heavy_water() → MolecularComposition[source]

Create a molecular composition mimicking that of heavy water :return: a settings dictionary containing all min and max parameters fitting for heavy water.

lymph_node(oxygenation: Union[float, int, ndarray] = 0.73, blood_volume_fraction: Union[float, int, ndarray] = 0.14) → MolecularComposition[source]

IMPORTANT! This tissue is not tested and it is not based on a specific real tissue type. It is a mixture of oxyhemoglobin, deoxyhemoglobin, and lymph node customized water. :param oxygenation: The oxygenation level of the blood volume fraction (as a decimal). Default: 0.175 :param blood_volume_fraction: The total blood volume fraction (including oxygenated and deoxygenated blood). Default: 0.06 :return: a settings dictionary fitting for generic lymph node tissue.

mediprene() → MolecularComposition[source]

Create a molecular composition mimicking that of mediprene :return: a settings dictionary fitting for mediprene.

muscle(oxygenation: Union[float, int, ndarray] = 0.175, blood_volume_fraction: Union[float, int, ndarray] = 0.06) → MolecularComposition[source]

Create a molecular composition mimicking that of muscle :param oxygenation: The oxygenation level of the blood volume fraction (as a decimal). Default: 0.175 :param blood_volume_fraction: The total blood volume fraction (including oxygenated and deoxygenated blood). Default: 0.06 :return: a settings dictionary containing all min and max parameters fitting for muscle tissue.

soft_tissue(oxygenation: Union[float, int, ndarray] = 0.5, blood_volume_fraction: Union[float, int, ndarray] = 0.01) → MolecularComposition[source]

IMPORTANT! This tissue is not tested and it is not based on a specific real tissue type. It is a mixture of muscle (mostly optical properties) and water (mostly acoustic properties). This tissue type roughly resembles the generic background tissue that we see in real PA images. :param oxygenation: The oxygenation level of the blood volume fraction (as a decimal). Default: OpticalTissueProperties.BACKGROUND_OXYGENATION :param blood_volume_fraction: The total blood volume fraction (including oxygenated and deoxygenated blood). Default: OpticalTissueProperties.BLOOD_VOLUME_FRACTION_MUSCLE_TISSUE :return: a settings dictionary containing all min and max parameters fitting for generic soft tissue.

subcutaneous_fat(oxygenation: Union[float, int, ndarray] = 0.5, blood_volume_fraction: Union[float, int, ndarray] = 0.01) → MolecularComposition[source]

Create a molecular composition mimicking that of subcutaneous fat :param oxygenation: The oxygenation level of the blood volume fraction (as a decimal). Default: OpticalTissueProperties.BACKGROUND_OXYGENATION :param blood_volume_fraction: The total blood volume fraction (including oxygenated and deoxygenated blood). Default: OpticalTissueProperties.BLOOD_VOLUME_FRACTION_MUSCLE_TISSUE :return: a settings dictionary containing all min and max parameters fitting for subcutaneous fat tissue.

ultrasound_gel() → MolecularComposition[source]

Create a molecular composition mimicking that of ultrasound gel :return: a settings dictionary fitting for generic ultrasound gel.