shamo.core.fem.fem.FEM¶

class shamo.core.fem.fem.FEM(name, parent_path, **kwargs)[source]¶

Bases: shamo.core.objects.dir.ObjDir

A finite element model.

Parameters

namestr: The name of the model.
parent_pathstr, byte or os.PathLike: The path to the parent directory of the model.

Methods

`add_circle_sensor_on`	Add a circle sensor on a surface.
`add_circle_sensors_from_tsv_on`	Add multiple circle sensors to the mesh from a TSV file.
`add_circle_sensors_on`	Add multiple circle sensors to the mesh.
`add_point_sensor`	Add a point sensor to the mesh.
`add_point_sensor_in`
`add_point_sensor_on`
`add_point_sensors`	Add multiple point sensors to the mesh.
`add_point_sensors_from_tsv`	Add multiple point sensors to the mesh from a TSV file.
`add_point_sensors_from_tsv_in`
`add_point_sensors_from_tsv_on`
`add_point_sensors_in`
`add_point_sensors_on`
`add_rect_sensor_on`	Add a rectangular sensor on a surface.
`clear`
`copy`
`field_from_array`	Add a field to the mesh from an array.
`field_from_elems`	Add a field to the mesh from element data.
`field_from_nii`	Add a field to the mesh from a NIFTI image.
`fromkeys`	Create a new dictionary with keys from iterable and values set to value.
`get`	Return the value for key if key is in the dictionary, else default.
`get_relative_path`	Return the relative path from the object to a file or directory.
`items`
`keys`
`load`	Load an object from a JSON file.
`mesh_from_array`	Generate a MSH file from a labelled array.
`mesh_from_fem`	Generate a mesh from an existing FEM by merging tissues.
`mesh_from_masks`	Generate a MSH file from multiple binary masks.
`mesh_from_nii`	Generate a MSH file from a labelled NIFTI file.
`mesh_from_niis`	Generate a MSH file from multiple binary masks.
`mesh_from_surfaces`	Generate a mesh from a series of surface meshes.
`pop`	If key is not found, d is returned if given, otherwise KeyError is raised
`popitem`	Remove and return a (key, value) pair as a 2-tuple.
`save`	Save the object to a JSON file.
`setdefault`	Insert key with a value of default if key is not in the dictionary.
`update`	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
`values`

Attributes

`affine`	Return the affine matrix of the NIFTI file.
`json_path`	Return the path to the object JSON file.
`mesh_params`	Return the parameters used to produce the mesh.
`mesh_path`	Return the path to the MSH file.
`name`	Return the name of the object.
`nii_path`	Return the path to the NIFTI file.
`parent_path`	Return the path to the parent directory of the object.
`path`	Return the path to the object directory.
`sensors`	Return the sensors of the model.
`shape`	Return the shape of the NIFTI file.
`tissues`	Return the tissues of the model.

add_circle_sensor_on(name, coords, tissue, radius)[source]¶

Add a circle sensor on a surface.

Parameters

namestr: The name of the sensor.
coordstuple [float, float, float]: The coordinates of the sensor in the subject space.
tissuestr: The name of the tissue the sensor must be added on.
radiusfloat: The radius of the sensor [m].

Raises

ValueError: If a sensor with name name already exists. If the coordinates are not a 3D location. If the tissue tissue does not exist in the model.
TypeError: If the argument coords is not of the right type.

add_circle_sensors_from_tsv_on(tsv_path, tissue, radius)[source]¶

Add multiple circle sensors to the mesh from a TSV file.

Parameters

tsv_pathstr, byte or os.PathLike: The path to the TSV file.
tissuestr: The name of the tissue the sensor is on.
radiusfloat: The radius of the sensor [m].

add_circle_sensors_on(coords, tissue, radius)[source]¶

Add multiple circle sensors to the mesh.

Parameters

coordsMapping [str, Iterable [float]]: The coordinates of the sensor.
tissuestr: The name of the tissue the sensor is on.
radiusfloat: The radius of the sensor [m].

add_point_sensor(name, coords, tissue, dim)[source]¶

Add a point sensor to the mesh.

Parameters

namestr: The name of the sensor.
coordsIterable [float] or numpy.ndarray: The coordinates of the sensor.
tissuestr: The name of the tissue the sensor is on/in.
dimint: If set to 2, the sensor is added on the surface of the tissue. If set to 3, it is placed inside the tissue.

Raises

TypeError: If argument coords is neither an Iterable or a numpy.ndarray. If argument dim is not an int.
ValueError: If argument name refers to an existing sensor. If argument coords is not a proper 3D coordinate. If argument tissue refers to a non existing tissue.

add_point_sensors(coords, tissue, dim)[source]¶

Add multiple point sensors to the mesh.

Parameters

coordsMapping [str, Iterable [float]]: The coordinates of the sensor.
tissuestr: The name of the tissue the sensor is on/in.
dimint: If set to 2, the sensor is added on the surface of the tissue. If set to 3, it is placed inside the tissue.

Raises

TypeError: If argument coords is not a Mapping of coordinates. If argument dim is not an int.
ValueError: If argument tissue refers to a non existing tissue.

add_point_sensors_from_tsv(tsv_path, tissue, dim)[source]¶

Add multiple point sensors to the mesh from a TSV file.

Parameters

tsv_pathstr, byte or os.PathLike: The path to the TSV file.
tissuestr: The name of the tissue the sensor is on/in.
dimint: If set to 2, the sensor is added on the surface of the tissue. If set to 3, it is placed inside the tissue.

Raises

TypeError: If argument coords is not a Mapping of coordinates. If argument dim is not an int.
ValueError: If argument tissue refers to a non existing tissue.

add_rect_sensor_on(name, coords, axis, tissue, shape)[source]¶

Add a rectangular sensor on a surface.

Parameters

namestr: The name of the sensor.
coordstuple [float, float, float]: The coordinates of the center of the sensor in the subject space. It corresponds to the origin of the plane used to model the sensor.
axistuple [Iterable [float]]: The eigen vectors of the plane. the first is used for the width and the second for the height of the rectangle.
tissuestr: The name of the tissue the sensor must be added on.
shapetuple [float, float]: The width and height of the rectangle [m].

Raises

ValueError: If a sensor with name name already exists. If the coordinates are not a 3D location. If the tissue tissue does not exist in the model.
TypeError: If the argument coords is not of the right type.

property affine¶

Return the affine matrix of the NIFTI file.

Returns

numpy.ndarray: The affine matrix of the NIFTI file.

clear() → None. Remove all items from D.¶

copy() → a shallow copy of D¶

field_from_array(name, field, affine, tissue, fill_val, formula='1', nearest=True, resize=True)[source]¶

Add a field to the mesh from an array.

Parameters

namestr: The name of the field. In the mesh, it will be added as ‘{tissue}_{name}’.
fieldnumpy.ndarray: The field values.
affinenumpy.ndarray: The affine matrix of the field.
tissuestr: The tissue in which the field must be added.
fill_valnp.ndarray or Iterable: The value to add in elements of the tissue that are not in elems_tags.
formulastr, optional: The formula linking the field to a physical property. The default value is ‘1’.
nearestbool, optional: If set to True, no interpolation is performed. Otherwise, a linear interpolation is used. The default value is True.
resizebool, optional: If set to True, the affine matrix is converted from [mm] to [m]. The default is True.

Raises

TypeError: If argument field is not a numpy.ndarray. If argument affine is not a numpy.ndarray.
ValueError: If argument field is not a 3D or 4D array containing a scalar, vector or tensor field. If argument affine is neither a (3, 4) nor a (4, 4) array.
KeyError: If argument tissue does not correspond to a tissue of the mesh.

See also

FEM.field_from_array

field_from_elems(name, tissue, elems_tags, elems_vals, fill_val=None, formula='1')[source]¶

Add a field to the mesh from element data.

Parameters

namestr: The name of the field. In the mesh, it will be added as ‘{tissue}_{name}’.
tissuestr: The tissue in which the field must be added.
elems_tagsnp.ndarray or Iterable [int]: The tags of the elements in which the value is available.
elems_valsnp.ndarray or Iterable: The values of the field on the corresponding elements.
fill_valnp.ndarray or Iterable: The value to add in elements of the tissue that are not in elems_tags.
formulastr: The formula linking the field to a physical property.

Raises

KeyError: If argument tissue does not correspond to a tissue of the mesh. If argument name refers to an already existing field.
TypeError: If argument elems_tags is neither a numpy.ndarray or a Iterable of int. If argument elems_vals is neither a numpy.ndarray or a Iterable. If argument fill_val is neither a numpy.ndarray or a Iterable.
ValueError: If argument elems_vals does not contain a scalar, vector or tensor field. If argument fill_val does not correspond to the values in elems_vals.

field_from_nii(name, nii_path, tissue, fill_val, formula='1', nearest=True, resize=True)[source]¶

Add a field to the mesh from a NIFTI image.

Parameters

namestr: The name of the field. In the mesh, it will be added as ‘{tissue}_{name}’.
nii_pathstr, byte or os.PathLike: The path to the NIFTI file containing the field.
tissuestr: The tissue in which the field must be added.
fill_valnp.ndarray or Iterable: The value to add in elements of the tissue that are not in elems_tags.
formulastr, optional: The formula linking the field to a physical property. The default value is ‘1’.
nearestbool, optional: If set to True, no interpolation is performed. Otherwise, a linear interpolation is used. The default value is True.
resizebool, optional: If set to True, the affine matrix is converted from [mm] to [m]. The default is True.

Raises

TypeError: If argument nii_path is not a str, byte or os.PathLike.

See also

FEM.field_from_array

fromkeys(iterable, value=None, /)¶: Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)¶: Return the value for key if key is in the dictionary, else default.

get_relative_path(path)¶

Return the relative path from the object to a file or directory.

Parameters

pathstr, byte or os.PathLike: The path to the file or directory to compute the relative path for.

Returns

pathlib.Path: The relative path to the file or directory.

items() → a set-like object providing a view on D’s items¶

property json_path¶

Return the path to the object JSON file.

Returns

pathlib.Path: The path to the object JSON file.

keys() → a set-like object providing a view on D’s keys¶

classmethod load(json_path)¶

Load an object from a JSON file.

Parameters

json_pathstr, byte or os.PathLike: The path to the JSON file containing the object data.

Raises

TypeError: If argument json_path is not a str, byte or os.PathLike.

mesh_from_array(labels, affine, tissues, **kwargs)[source]¶

Generate a MSH file from a labelled array.

Parameters

labelsnumpy.ndarray: A labelled array corresponding to a multi-segments image. The array must contain int labels starting from 0 (air) without skipping a number.
affinenumpy.ndarray: The affine matrix of the volume.
tissuesiterable [str]: The names of the tissues in the same order as the labels.

Other Parameters

lloydbool, optional: For more information, refer to the documentation of pygalmesh.
odtbool, optional: For more information, refer to the documentation of pygalmesh.
perturbbool, optional: For more information, refer to the documentation of pygalmesh.
exudebool, optional: For more information, refer to the documentation of pygalmesh.
max_edge_size_at_feature_edges: float, optional: For more information, refer to the documentation of pygalmesh.
min_facet_angle: float, optional: For more information, refer to the documentation of pygalmesh.
max_radius_surface_delaunay_ball: float, optional: For more information, refer to the documentation of pygalmesh.
max_cell_circumradius: float, optional: For more information, refer to the documentation of pygalmesh.
max_facet_distance: float, optional: For more information, refer to the documentation of pygalmesh.
max_circumradius_edge_ratio: float, optional: For more information, refer to the documentation of pygalmesh.
seedint, optional: For more information, refer to the documentation of pygalmesh.

Raises

TypeError: If argument ‘labels’ is not a numpy.ndarray. If argument ‘affine’ is not a numpy.ndarray. If an element of argument ‘tissues’ is not a str.
ValueError: If argument ‘labels’ is not a 3D array. If argument ‘affine’ is neither a (3, 4) nor a (4, 4) array. If argument ‘tissues’ does not contain as many elements as there are labels in ‘labels’.

See also

pygalmesh.generate_from_array

mesh_from_fem(fem_path, merges)[source]¶

Generate a mesh from an existing FEM by merging tissues.

Parameters

fem_pathstr, byte or os.PathLike: The path to the original model.
mergesdict [str, list [str]]: The merges to perform. Each value contains the names of the tissues to merge into a tissue named with the key.

Notes

This method removes the fields contained in the tissues that are part of a merge and edit the tissue the sensors are placed in/on.

mesh_from_masks(masks, affine, **kwargs)[source]¶

Generate a MSH file from multiple binary masks.

Parameters

maskMapping [str, numpy.ndarray]: A mapping from the names of the tissues to the corresponding binary masks.
affinenumpy.ndarray: The affine matrix of the volume.

Other Parameters

lloydbool, optional: For more information, refer to the documentation of pygalmesh.
odtbool, optional: For more information, refer to the documentation of pygalmesh.
perturbbool, optional: For more information, refer to the documentation of pygalmesh.
exudebool, optional: For more information, refer to the documentation of pygalmesh.
max_edge_size_at_feature_edges: float, optional: For more information, refer to the documentation of pygalmesh.
min_facet_angle: float, optional: For more information, refer to the documentation of pygalmesh.
max_radius_surface_delaunay_ball: float, optional: For more information, refer to the documentation of pygalmesh.
max_cell_circumradius: float, optional: For more information, refer to the documentation of pygalmesh.
max_facet_distance: float, optional: For more information, refer to the documentation of pygalmesh.
max_circumradius_edge_ratio: float, optional: For more information, refer to the documentation of pygalmesh.
seedint, optional: For more information, refer to the documentation of pygalmesh.

Raises

TypeError: If argument masks is not a mapping from str to numpy.ndarray.
ValueError: If the masks in ‘masks’ are not all of the same shape.

See also

FEM.mesh_from_array
pygalmesh.generate_from_array

mesh_from_nii(nii_path, tissues, **kwargs)[source]¶

Generate a MSH file from a labelled NIFTI file.

Parameters

nii_pathstr, byte or os.PathLike: The path to the NIFTI file containing the labelled volume.
tissuesiterable [str]: The names of the tissues in the same order as the labels.

Other Parameters

lloydbool, optional: For more information, refer to the documentation of pygalmesh.
odtbool, optional: For more information, refer to the documentation of pygalmesh.
perturbbool, optional: For more information, refer to the documentation of pygalmesh.
exudebool, optional: For more information, refer to the documentation of pygalmesh.
max_edge_size_at_feature_edges: float, optional: For more information, refer to the documentation of pygalmesh.
min_facet_angle: float, optional: For more information, refer to the documentation of pygalmesh.
max_radius_surface_delaunay_ball: float, optional: For more information, refer to the documentation of pygalmesh.
max_cell_circumradius: float, optional: For more information, refer to the documentation of pygalmesh.
max_facet_distance: float, optional: For more information, refer to the documentation of pygalmesh.
max_circumradius_edge_ratio: float, optional: For more information, refer to the documentation of pygalmesh.
seedint, optional: For more information, refer to the documentation of pygalmesh.

Raises

TypeError: If argument nii_path is not a str, byte or os.PathLike.

See also

FEM.mesh_from_array
pygalmesh.generate_from_array

mesh_from_niis(niis, **kwargs)[source]¶

Generate a MSH file from multiple binary masks.

Parameters

niisMapping [str, str, byte or os.PathLike]: A mapping from the names of the tissues to the path to the corresponding NIFTI binary masks.

Other Parameters

lloydbool, optional: For more information, refer to the documentation of pygalmesh.
odtbool, optional: For more information, refer to the documentation of pygalmesh.
perturbbool, optional: For more information, refer to the documentation of pygalmesh.
exudebool, optional: For more information, refer to the documentation of pygalmesh.
max_edge_size_at_feature_edges: float, optional: For more information, refer to the documentation of pygalmesh.
min_facet_angle: float, optional: For more information, refer to the documentation of pygalmesh.
max_radius_surface_delaunay_ball: float, optional: For more information, refer to the documentation of pygalmesh.
max_cell_circumradius: float, optional: For more information, refer to the documentation of pygalmesh.
max_facet_distance: float, optional: For more information, refer to the documentation of pygalmesh.
max_circumradius_edge_ratio: float, optional: For more information, refer to the documentation of pygalmesh.
seedint, optional: For more information, refer to the documentation of pygalmesh.

Raises

TypeError: If argument niis is not a mapping from str to str, byte or os.PathLike.

See also

FEM.mesh_from_masks
FEM.mesh_from_array
pygalmesh.generate_from_array

mesh_from_surfaces(tissues, structure, lc=0.0)[source]¶

Generate a mesh from a series of surface meshes.

Parameters

tissuesdict [str, str | byte | os.PathLike]: A dictionary containing the names of the tissues as keys and the path leading to the corresponding surface mesh as values.
structurelist [str | list]: A tree structure defined as a nested list defining the way surfaces contain each other.
lcfloat | dict [str, float], optional: The characteristic length of the mesh elements. If set to 0, it is infered from the size of the surface elements. If a float value is used, the same size is set for the whole volume. If a dictionary is provided, it must contain the name of the tissues (or default) as keys and the corresponding characteristic length as values. (The default is 0.0)

Raises

ValueError: If argument lc is a dictionary, does not contain all the tissues and have no default key.

property mesh_params¶

Return the parameters used to produce the mesh.

Returns

dict [str, float]: The parameters used to produce the mesh.

property mesh_path¶

Return the path to the MSH file.

Returns

pathlib.Path: The path to the MSH file.

property name¶

Return the name of the object.

Returns

str: The name of the object.

property nii_path¶

Return the path to the NIFTI file.

Returns

pathlib.Path: The path to the NIFTI file.

property parent_path¶

Return the path to the parent directory of the object.

Returns

pathlib.Path: The path to the parent directory of the object.

property path¶

Return the path to the object directory.

Returns

pathlib.Path: The path to the object directory.

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If key is not found, d is returned if given, otherwise KeyError is raised

popitem(/)¶

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

save(exist_ok=True)¶

Save the object to a JSON file.

Parameters

exist_okbool, optional: If set to True, any already existing object is overriden. Otherwise, if the object already exists, a FileExistsError. The default is True.

Raises

FileExistsError: If exist_ok is set to False and the object already exists.
TypeError: If any of the keys/values to be stored is not a str, int, float, bool or None.

property sensors¶

Return the sensors of the model.

Returns

dict [str, shamo.fem.SensorABC]: The sensors of the model.

setdefault(key, default=None, /)¶

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

property shape¶

Return the shape of the NIFTI file.

Returns

numpy.ndarray: The shape of the NIFTI file.

property tissues¶

Return the tissues of the model.

Returns

dict [str, shamo.fem.Tissue]: The tissues of the model.

update([E, ]**F) → None. Update D from dict/iterable E and F.¶: If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D’s values¶