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.

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.

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