structure_library

priority_sorted_structures(settings: Settings, volume_creator_settings: dict)

A generator function to lazily construct structures in descending order of priority

class Background(global_settings: Settings, background_settings: Optional[Settings] = None)

Bases: GeometricalStructure

Defines a background that fills the whole simulation volume. It is always given the priority of 0 so that other structures can overwrite it when necessary.

Example usage:

background_dictionary = Settings()
background_dictionary[Tags.MOLECULE_COMPOSITION] = TISSUE_LIBRARY.constant(0.1, 100.0, 0.9)
background_dictionary[Tags.STRUCTURE_TYPE] = Tags.BACKGROUND

get_enclosed_indices()

Gets indices of the voxels that are either entirely or partially occupied by the GeometricalStructure. :return: mask for a numpy array

get_params_from_settings(single_structure_settings)

Gets all the parameters required for the specific GeometricalStructure. :param single_structure_settings: Settings which describe the specific GeometricalStructure. :return: Tuple of parameters

to_settings() → dict

Creates a Settings dictionary which contains all the parameters needed to create the same GeometricalStructure again. :return : A tuple containing the settings key and the needed entries

define_background_structure_settings(molecular_composition: MolecularComposition)

TODO

class CircularTubularStructure(global_settings: Settings, single_structure_settings: Optional[Settings] = None)

Bases: GeometricalStructure

Defines a circular tube which is defined by a start and end point as well as a radius. This structure implements partial volume effects. The tube can be set to adhere to a deformation defined by the simpa.utils.deformation_manager. The start and end points of the tube will then be shifted along the z-axis accordingly. Example usage:

# single_structure_settings initialization structure = Settings()

structure[Tags.PRIORITY] = 9 structure[Tags.STRUCTURE_START_MM] = [50, 0, 50] structure[Tags.STRUCTURE_END_MM] = [50, 100, 50] structure[Tags.STRUCTURE_RADIUS_MM] = 5 structure[Tags.MOLECULE_COMPOSITION] = TISSUE_LIBRARY.blood() structure[Tags.CONSIDER_PARTIAL_VOLUME] = True structure[Tags.ADHERE_TO_DEFORMATION] = True structure[Tags.STRUCTURE_TYPE] = Tags.CIRCULAR_TUBULAR_STRUCTURE

get_enclosed_indices()

Gets indices of the voxels that are either entirely or partially occupied by the GeometricalStructure. :return: mask for a numpy array

get_params_from_settings(single_structure_settings)

Gets all the parameters required for the specific GeometricalStructure. :param single_structure_settings: Settings which describe the specific GeometricalStructure. :return: Tuple of parameters

to_settings()

Creates a Settings dictionary which contains all the parameters needed to create the same GeometricalStructure again. :return : A tuple containing the settings key and the needed entries

define_circular_tubular_structure_settings(tube_start_mm: list, tube_end_mm: list, molecular_composition: MolecularComposition, radius_mm: float = 2, priority: int = 10, consider_partial_volume: bool = False, adhere_to_deformation: bool = False)

TODO

class EllipticalTubularStructure(global_settings: Settings, single_structure_settings: Optional[Settings] = None)

Bases: GeometricalStructure

Defines a elliptical tube which is defined by a start and end point as well as a radius and an eccentricity. The elliptical geometry corresponds to a circular tube of the specified radius which is compressed along the z-axis until it reaches the specified eccentricity under the assumption of a constant volume. This structure implements partial volume effects. The tube can be set to adhere to a deformation defined by the simpa.utils.deformation_manager. The start and end points of the tube will then be shifted along the z-axis accordingly. Example usage:

# single_structure_settings initialization structure = Settings()

structure[Tags.PRIORITY] = 9 structure[Tags.STRUCTURE_START_MM] = [50, 0, 50] structure[Tags.STRUCTURE_END_MM] = [50, 100, 50] structure[Tags.STRUCTURE_RADIUS_MM] = 5 structure[Tags.STRUCTURE_ECCENTRICITY] = 0.8 structure[Tags.MOLECULE_COMPOSITION] = TISSUE_LIBRARY.blood() structure[Tags.CONSIDER_PARTIAL_VOLUME] = True structure[Tags.ADHERE_TO_DEFORMATION] = True structure[Tags.STRUCTURE_TYPE] = Tags.ELLIPTICAL_TUBULAR_STRUCTURE

get_enclosed_indices()

Gets indices of the voxels that are either entirely or partially occupied by the GeometricalStructure. :return: mask for a numpy array

get_params_from_settings(single_structure_settings)

Gets all the parameters required for the specific GeometricalStructure. :param single_structure_settings: Settings which describe the specific GeometricalStructure. :return: Tuple of parameters

to_settings()

Creates a Settings dictionary which contains all the parameters needed to create the same GeometricalStructure again. :return : A tuple containing the settings key and the needed entries

define_elliptical_tubular_structure_settings(tube_start_mm: list, tube_end_mm: list, molecular_composition: MolecularComposition, radius_mm: float = 2, eccentricity: float = 0.5, priority: int = 10, consider_partial_volume: bool = False, adhere_to_deformation: bool = False)

TODO

class HorizontalLayerStructure(global_settings: Settings, single_structure_settings: Optional[Settings] = None)

Bases: GeometricalStructure

Defines a Layer structure which spans the xy-plane in the SIMPA axis convention. The thickness of the layer is defined along the z-axis. This layer can be deformed by the simpa.utils.deformation_manager. Example usage:

# single_structure_settings initialization structure = Settings()

structure[Tags.PRIORITY] = 10 structure[Tags.STRUCTURE_START_MM] = [0, 0, 0] structure[Tags.STRUCTURE_END_MM] = [0, 0, 100] structure[Tags.MOLECULE_COMPOSITION] = TISSUE_LIBRARY.epidermis() structure[Tags.CONSIDER_PARTIAL_VOLUME] = True structure[Tags.ADHERE_TO_DEFORMATION] = True structure[Tags.STRUCTURE_TYPE] = Tags.HORIZONTAL_LAYER_STRUCTURE

get_enclosed_indices()

Gets indices of the voxels that are either entirely or partially occupied by the GeometricalStructure. :return: mask for a numpy array

get_params_from_settings(single_structure_settings)

Gets all the parameters required for the specific GeometricalStructure. :param single_structure_settings: Settings which describe the specific GeometricalStructure. :return: Tuple of parameters

to_settings()

Creates a Settings dictionary which contains all the parameters needed to create the same GeometricalStructure again. :return : A tuple containing the settings key and the needed entries

update_molecule_volume_fractions(single_structure_settings)

In particular cases, only molecule volume fractions are determined by tensors that expand the structure. This method allows the tensor to only have the size of the structure, with the rest of the volume filled with volume fractions of 0. In the case where the tensors defined are such that they fill the volume, they will be left. Later, when using priority_sorted_structures the volume used will be that within the boundaries in the shape. :param single_structure_settings: Settings which describe the specific GeometricalStructure.

define_horizontal_layer_structure_settings(molecular_composition: MolecularComposition, z_start_mm: float = 0, thickness_mm: float = 0, priority: int = 10, consider_partial_volume: bool = False, adhere_to_deformation: bool = False)

TODO

class ParallelepipedStructure(global_settings: Settings, single_structure_settings: Optional[Settings] = None)

Bases: GeometricalStructure

Defines a parallelepiped which is defined by a start point and three edge vectors which originate from the start point. This structure currently does not implement partial volume effects. Example usage:

# single_structure_settings initialization structure = Settings()

structure[Tags.PRIORITY] = 9 structure[Tags.STRUCTURE_START_MM] = [25, 25, 25] structure[Tags.STRUCTURE_FIRST_EDGE_MM] = [5, 1, 1] structure[Tags.STRUCTURE_SECOND_EDGE_MM] = [1, 5, 1] structure[Tags.STRUCTURE_THIRD_EDGE_MM] = [1, 1, 5] structure[Tags.MOLECULE_COMPOSITION] = TISSUE_LIBRARY.muscle() structure[Tags.STRUCTURE_TYPE] = Tags.PARALLELEPIPED_STRUCTURE

get_enclosed_indices()

Gets indices of the voxels that are either entirely or partially occupied by the GeometricalStructure. :return: mask for a numpy array

get_params_from_settings(single_structure_settings)

Gets all the parameters required for the specific GeometricalStructure. :param single_structure_settings: Settings which describe the specific GeometricalStructure. :return: Tuple of parameters

to_settings()

Creates a Settings dictionary which contains all the parameters needed to create the same GeometricalStructure again. :return : A tuple containing the settings key and the needed entries

define_parallelepiped_structure_settings(start_mm: list, edge_a_mm: list, edge_b_mm: list, edge_c_mm: list, molecular_composition: MolecularComposition, priority: int = 10, consider_partial_volume: bool = False, adhere_to_deformation: bool = False)

TODO

class RectangularCuboidStructure(global_settings: Settings, single_structure_settings: Optional[Settings] = None)

Bases: GeometricalStructure

Defines a rectangular cuboid (box) which is defined by a start point its extent along the x-, y-, and z-axis. This structure implements partial volume effects. The box can be set to adhere to a deformation defined by the simpa.utils.deformation_manager. The start point of the box will then be shifted along the z-axis accordingly. Example usage:

# single_structure_settings initialization structure = Settings()

structure[Tags.PRIORITY] = 9 structure[Tags.STRUCTURE_START_MM] = [25, 25, 25] structure[Tags.STRUCTURE_X_EXTENT_MM] = 40 structure[Tags.STRUCTURE_Y_EXTENT_MM] = 50 structure[Tags.STRUCTURE_Z_EXTENT_MM] = 60 structure[Tags.MOLECULE_COMPOSITION] = TISSUE_LIBRARY.muscle() structure[Tags.CONSIDER_PARTIAL_VOLUME] = True structure[Tags.ADHERE_TO_DEFORMATION] = True structure[Tags.STRUCTURE_TYPE] = Tags.RECTANGULAR_CUBOID_STRUCTURE

get_enclosed_indices()

Gets indices of the voxels that are either entirely or partially occupied by the GeometricalStructure. :return: mask for a numpy array

get_params_from_settings(single_structure_settings)

Gets all the parameters required for the specific GeometricalStructure. :param single_structure_settings: Settings which describe the specific GeometricalStructure. :return: Tuple of parameters

to_settings()

Creates a Settings dictionary which contains all the parameters needed to create the same GeometricalStructure again. :return : A tuple containing the settings key and the needed entries

define_rectangular_cuboid_structure_settings(start_mm: list, extent_mm: Union[int, list], molecular_composition: MolecularComposition, priority: int = 10, consider_partial_volume: bool = False, adhere_to_deformation: bool = False)

TODO

class SphericalStructure(global_settings: Settings, single_structure_settings: Optional[Settings] = None)

Bases: GeometricalStructure

Defines a sphere which is defined by a start point and a radius. This structure implements partial volume effects. The sphere can be set to adhere to a deformation defined by the simpa.utils.deformation_manager. The start point of the sphere will then be shifted along the z-axis accordingly. Example usage:

# single_structure_settings initialization structure = Settings()

structure[Tags.PRIORITY] = 9 structure[Tags.STRUCTURE_START_MM] = [50, 50, 50] structure[Tags.STRUCTURE_RADIUS_MM] = 10 structure[Tags.MOLECULE_COMPOSITION] = TISSUE_LIBRARY.blood() structure[Tags.CONSIDER_PARTIAL_VOLUME] = True structure[Tags.ADHERE_TO_DEFORMATION] = True structure[Tags.STRUCTURE_TYPE] = Tags.SPHERICAL_STRUCTURE

get_enclosed_indices()

Gets indices of the voxels that are either entirely or partially occupied by the GeometricalStructure. :return: mask for a numpy array

get_params_from_settings(single_structure_settings)

Gets all the parameters required for the specific GeometricalStructure. :param single_structure_settings: Settings which describe the specific GeometricalStructure. :return: Tuple of parameters

to_settings()

Creates a Settings dictionary which contains all the parameters needed to create the same GeometricalStructure again. :return : A tuple containing the settings key and the needed entries

define_spherical_structure_settings(start_mm: list, molecular_composition: MolecularComposition, radius_mm: float = 1, priority: int = 10, consider_partial_volume: bool = False, adhere_to_deformation: bool = False)

TODO

class GeometricalStructure(global_settings: Settings, single_structure_settings: Optional[Settings] = None)

Bases: object

Base class for all model-based structures for ModelBasedVolumeCreator. A GeometricalStructure has an internal representation of its own geometry. This is represented by self.geometrical_volume which is a 3D array that defines for every voxel within the simulation volume if it is enclosed in the GeometricalStructure or if it is outside. Most of the GeometricalStructures implement a partial volume effect. So if a voxel has the value 1, it is completely enclosed by the GeometricalStructure. If a voxel has a value between 0 and 1, that fraction of the volume is occupied by the GeometricalStructure. If a voxel has the value 0, it is outside of the GeometricalStructure.

fill_internal_volume()

Fills self.geometrical_volume of the GeometricalStructure.

abstract get_enclosed_indices()

Gets indices of the voxels that are either entirely or partially occupied by the GeometricalStructure. :return: mask for a numpy array

abstract get_params_from_settings(single_structure_settings: Settings)

Gets all the parameters required for the specific GeometricalStructure. :param single_structure_settings: Settings which describe the specific GeometricalStructure. :return: Tuple of parameters

get_volume_fractions()

Get the volume fraction this structure takes per voxel.

properties_for_wavelength(settings, wavelength) → TissueProperties

Returns the values corresponding to each optical/acoustic property used in SIMPA. :param settings: The global settings that contains the info on the volume dimensions. :param wavelength: Wavelength of the queried properties :return: optical/acoustic properties

abstract to_settings() → Settings

Creates a Settings dictionary which contains all the parameters needed to create the same GeometricalStructure again. :return : A tuple containing the settings key and the needed entries

update_molecule_volume_fractions(single_structure_settings: Settings)

In particular cases, only molecule volume fractions are determined by tensors that expand the structure. This method allows the tensor to only have the size of the structure, with the rest of the volume filled with volume fractions of 0. In the case where the tensors defined are such that they fill the volume, they will be left. Later, when using priority_sorted_structures the volume used will be that within the boundaries in the shape. :param single_structure_settings: Settings which describe the specific GeometricalStructure.

class VesselStructure(global_settings: Settings, single_structure_settings: Optional[Settings] = None)

Bases: GeometricalStructure

Defines a vessel tree that is generated randomly in the simulation volume. The generation process begins at the start with a specified radius. The vessel grows roughly in the specified direction. The deviation is specified by the curvature factor. Furthermore, the radius of the vessel can vary depending on the specified radius variation factor. The bifurcation length defines how long a vessel can get until it will bifurcate. This structure implements partial volume effects. Example usage:

# single_structure_settings initialization structure_settings = Settings()

structure_settings[Tags.PRIORITY] = 10 structure_settings[Tags.STRUCTURE_START_MM] = [50, 0, 50] structure_settings[Tags.STRUCTURE_DIRECTION] = [0, 1, 0] structure_settings[Tags.STRUCTURE_RADIUS_MM] = 4 structure_settings[Tags.STRUCTURE_CURVATURE_FACTOR] = 0.05 structure_settings[Tags.STRUCTURE_RADIUS_VARIATION_FACTOR] = 1 structure_settings[Tags.STRUCTURE_BIFURCATION_LENGTH_MM] = 70 structure_settings[Tags.MOLECULE_COMPOSITION] = TISSUE_LIBRARY.blood() structure_settings[Tags.CONSIDER_PARTIAL_VOLUME] = True structure_settings[Tags.STRUCTURE_TYPE] = Tags.VESSEL_STRUCTURE

calculate_vessel_samples(position, direction, bifurcation_length, radius, radius_variation, volume_dimensions, curvature_factor)

fill_internal_volume()

Fills self.geometrical_volume of the GeometricalStructure.

get_enclosed_indices()

Gets indices of the voxels that are either entirely or partially occupied by the GeometricalStructure. :return: mask for a numpy array

get_params_from_settings(single_structure_settings)

Gets all the parameters required for the specific GeometricalStructure. :param single_structure_settings: Settings which describe the specific GeometricalStructure. :return: Tuple of parameters

to_settings()

Creates a Settings dictionary which contains all the parameters needed to create the same GeometricalStructure again. :return : A tuple containing the settings key and the needed entries

define_vessel_structure_settings(vessel_start_mm: list, vessel_direction_mm: list, molecular_composition: MolecularComposition, radius_mm: float = 2, curvature_factor: float = 0.05, radius_variation_factor: float = 1.0, bifurcation_length_mm: float = 7, priority: int = 10, consider_partial_volume: bool = False, adhere_to_deformation: bool = False)

TODO