pynibs.roi package

Submodules

pynibs.roi.roi module

Functions that operate on region of interest (ROI) data.

pynibs.roi.roi.clean_roi(img, vox_thres=0.5, fn_out=None)

Remove values < vox thres from image.

Parameters:

• img (str or nibabel.nifti1.Nifti1Image) –

• vox_thres (float, optional) –

• fn_out (str) –

Returns:

• img_thres (nibabel.nifti1.Nifti1Image)

• img_thres (<file>) – If fn_out is specified, thresholded image is saved here

pynibs.roi.roi.create_refine_spherical_roi(center, radius, final_tissues_nii, out_fn, target_size=0.5, outside_size=None, outside_factor=3, out_spher_fn=None, tissue_types=None, verbose=False)

Create a spherical roi nifti for simnibs 4 refinement. Only tissue types accoring to _tissue_types will be refined.

Use the resulting output file as input for –sizing_field in SimNIBS-4/simnibs/cli/meshmesh.py

Parameters:

• center (list of float) – Center of spherical ROI in mm

• radius (float) – Radius of spherical ROI in mm

• final_tissues_nii (string or nib.nifti1.Nifti1Image) – final_tissues.nii.gz to create roi for.

• out_fn (str) – Final output filename

• target_size (float, default = 0.5) – Target element size of refined areas in mm (?)

• outside_size (float, default = None) – Element size outside of target size.

• outside_factor (float, default = None) – Distance factor to define the ‘outside’ area: oudsidefactor * radius -> outside

• out_spher_fn (str, optional) – Output filename of orignal, raw spherical ROI

• tissue_types (list of float, default = [1,2,3]) – Which tissue types to refine. Defaults to WM, GM, CSF

• verbose (bool, optional, default=False) – Print additional information

pynibs.roi.roi.determine_element_idx_in_mesh(fname, msh, points, compute_baricentric=False)

Finds the tetrahedron that contains each of the described points using a stochastic walk algorithm. Implemented from Devillers et al. (2002) [1]

Parameters:

• msh (pynibs.mesh.mesh_struct.TetrahedraLinear) –

• fname (str or None) – Filename of saved .txt file containing the element indices (no data is saved when fname=None or fname=’’)

• points (np.ndarray (N, 3) or list of np.ndarray) – List of points to be queried

• compute_baricentric (bool) – Wether or not to compute baricentric coordinates of the points

Returns:

• th_with_points (np.ndarray) – List with the tetrahedron that contains each point. If the point is outside the mesh, the value will be -1

• baricentric (np.ndarray [n, 4](if compute_baricentric == True)) – Baricentric coordinates of point. If the point is outside, a list of zeros

Notes

[1]

Devillers, Olivier, Sylvain Pion, and Monique Teillaud. “Walking in a triangulation.” International Journal of Foundations of Computer Science 13.02 (2002): 181-199.

pynibs.roi.roi.elem_workhorse(chunk, points_out, P1_all, P2_all, P3_all, P4_all, N_points_total, N_CPU)

Parameters:

• chunk (np.ndarray) – Indices of points the CPU thread is computing the element indices for

• points_out (np.ndarray of float) – (N_points, 3) Coordinates of points, the tetrahedra indices are computed for

• P1_all (np.ndarray of float) –

• (N_tet –

• tetrahedra (3) Coordinates of first point of) –

• P2_all (np.ndarray of float) – (N_tet, 3) Coordinates of second point of tetrahedra

• P3_all (np.ndarray of float) – (N_tet, 3) Coordinates of third point of tetrahedra

• P4_all (np.ndarray of float) – (N_tet, 3) Coordinates of fourth point of tetrahedra

• N_points_total (int) – Total number of points

• N_CPU (int) – Number of CPU cores to use

Returns:

tet_idx_local

Return type:

np.ndarray of int (N_points,)

pynibs.roi.roi.get_mask(areas, fn_annot, fn_inflated_fs, fn_out)

Determine freesurfer average mask .overlay file, which is needed to generate subject specific ROIs.

Parameters:

• areas (list of str) – Brodmann areas (e.g. [‘Brodmann.6’, ‘Brodmann.4’, ‘Brodmann.3’, ‘Brodmann.1’])

• fn_annot (str) – Annotation file of freesurfer (e.g. ‘FREESURFER_DIR/fsaverage/label/lh.PALS_B12_Brodmann.annot’)

• fn_inflated_fs (str) – Inflated surface of freesurfer average (e.g. ‘FREESURFER_DIR/fsaverage/surf/lh.inflated’)

• fn_out (str) – Filename of .overlay file of freesurfer mask

Returns:

<File> – fn_out.overlay file of freesurfer mask

Return type:

.overlay file

pynibs.roi.roi.get_sphere_in_nii(center, radius, nii=None, out_fn=None, thresh_by_nii=True, val_in=1, val_out=0, outside_val=0, outside_radius=inf)

Computes a spherical ROI for a given Nifti image (defaults to SimNIBS MNI T1 tissue). The ROI area is defined in nifti coordinates. By default, everything inside the ROI is set to 1, areas outside = 0. The ROI is further thresholded by the nifti. A nib.Nifti image is returned and optionally saved.

Parameters:

• center (array-like) – X, Y, Z coordinates in nifti space

• radius (float) – radius of sphere

• nii (string or nib.nifti1.Nifti1Image, optional) – The nifti image to work with.

• out_fn (string, optional) – If provided, sphere ROI image is saved here

• outside_val (float, default = None) – Value outside of outside_radius.

• outside_radius (float, default = None) – Distance factor to define the ‘outside’ area: oudsidefactor * radius -> outside

• thresh_by_nii (bool, optional) – Mask sphere by nii != 0

• val_in (float, optional) – Value within ROI

• val_out (float, optional) – Value outside ROI

Returns:

• sphere_img (nib.nifti1.Nifti1Image)

• sphere_img (<file>, optional)

Raises:

ValueError – If the final ROI is empty.

pynibs.roi.roi.load_roi_surface_obj_from_hdf5(fname)

pynibs.roi.roi.make_GM_WM_surface(gm_surf_fname, wm_surf_fname, mesh_folder, midlayer_surf_fname=None, delta=0.5, x_roi=None, y_roi=None, z_roi=None, layer=1, fn_mask=None, refine=False)

Generating a surface between WM and GM in a distance of delta 0…1 for ROI, given by freesurfer mask or coordinates.

Parameters:

• gm_surf_fname (str or list of str) – Filename(s) of GM surface generated by freesurfer (lh and/or rh) (e.g. in mri2msh: fs_ID/surf/lh.pial)

• wm_surf_fname (str or list of str) – Filename(s) of WM surface generated by freesurfer (lh and/or rh) (e.g. in mri2msh: fs_ID/surf/lh.white)

• mesh_folder (str) – Path of mesh (parent directory)

• midlayer_surf_fname (str or list of str) – filename(s) of midlayer surface generated by headreco (lh and/or rh) (e.g. in headreco: fs_ID/surf/lh.central) (after conversion)

• m2m_mat_fname ([defunct]) – Filename of mri2msh transformation matrix (e.g. in mri2msh: m2m_ProbandID/MNI2conform_6DOF.mat)

• delta (float) –

  Distance parameter where surface is generated 0…1 (default: 0.5)

  • 0 -> WM surface

  • 1 -> GM surface

• x_roi (list of float or None) – Region of interest [Xmin, Xmax], whole X range if empty [0,0] or None (left - right)

• y_roi (list of float or None) – Region of interest [Ymin, Ymax], whole Y range if empty [0,0] or None (anterior - posterior)

• z_roi (list of float or None) – Region of interest [Zmin, Zmax], whole Z range if empty [0,0] or None (inferior - superior)

• layer (int) –

  Define the number of layers:

  • 1: one layer

  • 3: additionally upper and lower layers are generated around the central midlayer

• fn_mask (string or None) – Filename for freesurfer mask. If given, this is used instead of *_ROIs

• refine (bool, optional, default: False) – Refine ROI by splitting elements

Returns:

• if layer == 3

• surface_points_upper (np.ndarray of float) – (N_points, 3) Coordinates (x, y, z) of surface + epsilon (in GM surface direction)

• surface_points_middle (np.ndarray of float) – (N_points, 3) Coordinates (x, y, z) of surface

• surface_points_lower (np.ndarray of float) – (N_points, 3) Coordinates (x, y, z) of surface - epsilon (in WM surface direction)

• connectivity (np.ndarray of int) – (N_tri x 3) Connectivity of triangles (indexation starts at 0!)

• else

• surface_points_middle (np.ndarray of float) – (N_points, 3) Coordinates (x, y, z) of surface

• connectivity (np.ndarray of int) – (N_tri x 3) Connectivity of triangles (indexation starts at 0!)

Example

make_GM_WM_surface(self, gm_surf_fname, wm_surf_fname, delta, X_ROI, Y_ROI, Z_ROI)
make_GM_WM_surface(self, gm_surf_fname, wm_surf_fname, delta, mask_fn, layer=3)

pynibs.roi.roi.nii2msh(mesh, m2m_dir, nii, out_folder, hem, out_fsaverage=False, roi_name='ROI')

Transform a nifti ROI image to subject space .mgh file.

Parameters:

• mesh (simnibs.Mesh or str) –

• m2m_dir (str) –

• nii (nibabel.nifti1.Nifti1Image or str) –

• out_folder (str) –

• hem (str) – ‘lh’ or ‘rh’

• out_fsaverage (bool) –

• roi_name (str) – How to name the ROI

Returns:

roi – f”{out_folder}/{hem}.mesh.central.{roi_name}”

Return type:

file

pynibs.roi.roi.read_roi_from_mesh_hdf5(fname, roi_id=None)

Loading and initializing RegionOfInterestSurface object/s from .hdf5 mesh file.

Parameters:

• fname (str) – Filename (incl. path) of .hdf5 mesh file, e.g. from subject.fn_mesh_hdf5

• roi_id (str, optional) – Which ROI to return. If empty: return all as list.

Returns:

RegionOfInterestSurface – RegionOfInterestSurface

Return type:

pynibs.roi.RegionOfInterestSurface or list of pynibs.roi.RegionOfInterestSurface

pynibs.roi.roi_structs module

Classes to cope with cortical region of interests (ROIs).

class pynibs.roi.roi_structs.CorticalLayer(create_key, layer_id, volumetric_mesh=None, roi=None, depth=None, path=None, surface=None, id=None)

Bases: object

class Settings

Bases: object

GRID_POINTS_PER_MM = 1.5

NUM_TRIANGLE_SMOOTHING_STEPS = 30

ROI_SIZE_OFFSET = 5

TAG_GRAY_MATTER_SURF = 1002

TAG_GRAY_MATTER_VOL = 2

TAG_WHITE_MATTER_SURF = 1001

TAG_WHITE_MATTER_VOL = 1

classmethod create_in_bbox(layer_id, bbox, depth, volmesh)

Factory method for constructing a CorticalLayer-object within a region-of-interest and a specified cortical depth.

Parameters:

• layer_id (str) – Identifier of the layer.

• bbox (List[float]) – List of bounding values around the ROI box: [x_min, x_max, y_min, y_max, z_min, z_max].

• depth (float) – Normalized distance of the layer from gray matter surface. Provide values in the open interval (0,1).

• volmesh (simnibs.Msh) – The tetrahedral volume mesh, in which the layer should be generated.

classmethod create_in_roi(layer_id, roi, depth, volmesh)

Factory method for constructing a CorticalLayer-object within a region-of-interest and a specified cortical depth.

Parameters:

• layer_id (str) – Identifier of the layer.

• roi (pynibs.RegionOfInterestSurface) – RegionOfInterestSurface.

• depth (float) – Normalized distance of the layer from gray matter surface. Provide values in the open interval (0,1).

• volmesh (simnibs.Msh) – The tetrahedral volume mesh, in which the layer should be generated.

static crop_mesh_with_box(mesh, roi, keep_elements=False)

Returns the cropped mesh with all points that are inside the region of interest

Parameters:

• keep_elements (bool, default = False) – If True, keeps elements with at least one point in roi, else removes them.

• mesh (simnibs.Msh) – The mesh that is supposed to be cropped.

• roi (List[float]) – The bounding box of the region of interest which the mesh should be cropped to. [x-min, x-max, y-min, y-max, z-min, z-max].

Returns:

mesh_cropped – The cropped mesh.

Return type:

simnibs.Msh

static crop_mesh_with_surface(mesh, roi, keep_elements=False, radius=3)

Returns the cropped mesh with all points that are close to the surface of interest

Parameters:

• keep_elements (bool, default = False) – If True, keeps elements with at least one point in roi, else removes them.

• mesh (simnibs.Msh) – The mesh that is supposed to be cropped.

• roi (RegionOfInterestSurface instance) – RegionOfInterestSurface.

• radius (float, default = 3) – Search radius of mesh elements around ROI nodes.

Returns:

mesh_cropped – The cropped mesh.

Return type:

simnibs.Msh

generate_layer(depth, roi)

Create the geometry of the layer at the specified depth using marching cubes.

Parameters:

• depth (float) – The depth below the GM surface at which the layer should be generated; in [0,1].

• roi (RegionOfInterestSurface instance) – RegionOfInterestSurface.

get_evenly_spaced_element_subset(elements_per_square_mm)

Subsample the surface representation of the ayer.

Parameters:

elements_per_square_mm (float) – Number of triangles per mm^2 in the layer.

Returns:

selected elements – List of indices of selected elements as a result of the subsampling.

Return type:

Typing.List[int]

get_smoothed_normals()

Computed the smoothed normals of the surface representation of this layer.

Note: For the later stages, we don’t want a smoothed surface, but smooth normals in order to maintain the location of the cells, but orient them more smoothly. Therefore, we use smoothed normals, e.g. for the computation of the theta angle, but do not smooth the entire layer surface.

Returns:

normals – The tetrahedral volume mesh, in which the layer should be generated.

Return type:

np.ndarray

classmethod init_from_file(layer_id, fn)

Factory method for constructing a CorticalLayer-object from a file.

Parameters:

• layer_id (str) – Identifier of the layer.

• fn (str) – File path to a region of interest surfe (e.g. midlayer).

classmethod init_from_surface(layer_id, surf)

Factory method for constructing a CorticalLayer-object from a Simnibs-surface object.

Parameters:

• layer_id (str) – Identifier of the layer.

• surf (simnibs.Msh) – The surface representation of an already existing layer (e.g. midlayer).

remove_unconnected_surfaces()

Remove elements small unconnected element-clusters from this layer.

static roi_bbox_from_points(points, offset=0)

Find the minimal bounding box around the provided points.

Parameters:

• points (simnibs.Msh) – The tetrahedral volume mesh, in which the layer should be generated.

• offset (float) – Normalized distance of the layer from gray matter surface. Provide values in the open interval (0,1).

Returns:

bounding_box – List of bounding values around the provided points: [x_min, x_max, y_min, y_max, z_min, z_max].

Return type:

List[float]

save(fn)

Save the current surface representation of this CorticalLayer instance at the specified location.

Parameters:

fn (str) – Target file name of the surface-file of this layer.

class pynibs.roi.roi_structs.RegionOfInterestSurface

Bases: object

Region of interest (surface).

node_coord_up

(N_points, 3) Coordinates (x,y,z) of upper surface nodes.

Type:

np.ndarray

node_coord_mid

(N_points, 3) Coordinates (x,y,z) of middle surface nodes.

Type:

np.ndarray

node_coord_low

(N_points, 3) Coordinates (x,y,z) of lower surface nodes.

Type:

np.ndarray

node_number_list

(N_points, 3) Connectivity matrix of triangles.

Type:

np.ndarray

delta

Distance parameter between WM and GM (0 -> WM, 1 -> GM).

Type:

float

tet_idx_tri_center_up

Tetrahedra indices of TetrahedraLinear object instance where the center points of the triangles of the upper surface are.

Type:

np.ndarray [N_points]

tet_idx_tri_center_mid

Tetrahedra indices of TetrahedraLinear object instance where the center points of the triangles of the middle surface are.

Type:

np.ndarray [N_points]

tet_idx_tri_center_low

Tetrahedra indices of TetrahedraLinear object instance where the center points of the triangles of the lower surface are.

Type:

np.ndarray [N_points]

tet_idx_node_coord_mid

(N_tri,) Tetrahedra indices of TetrahedraLinear object instance where the nodes of the middle surface are.

Type:

np.ndarray

tri_center_coord_up

(N_tri, 3) Coordinates of roi triangle center of upper surface

Type:

np.ndarray

tri_center_coord_mid

(N_tri, 3) Coordinates of roi triangle center of middle surface

Type:

np.ndarray

tri_center_coord_low

(N_tri, 3) Coordinates of roi triangle center of lower surface

Type:

np.ndarray

fn_mask

Filename for surface mask in subject space. .mgh file or freesurfer surface file.

Type:

string

fn_mask_avg

Filename for .mgh mask in fsaverage space. Absolute path or relative to mesh folder.

Type:

string

fn_mask_nii

Filename for .nii or .nii.gz mask. Absolute path or relative to mesh folder.

Type:

string

X_ROI

Region of interest [Xmin, Xmax], whole X range if empty [0,0] or None (left - right)

Type:

list of float

Y_ROI

Region of interest [Ymin, Ymax], whole Y range if empty [0,0] or None (anterior - posterior)

Type:

list of float

Z_ROI

Region of interest [Zmin, Zmax], whole Z range if empty [0,0] or None (inferior - superior)

Type:

list of float

template

‘MNI’, ‘fsaverage’, ‘subject’

Type:

str

center

Center coordinates for spherical ROI in self.template space

Type:

list of float

radius

Radius in [mm] for spherical ROI

Type:

float

gm_surf_fname

Filename(s) of GM surface generated by freesurfer (lh and/or rh) (e.g. in mri2msh: …/fs_ID/surf/lh.pial)

Type:

str or list of str

wm_surf_fname

Filename(s) of WM surface generated by freesurfer (lh and/or rh) (e.g. in mri2msh: …/fs_ID/surf/lh.white)

Type:

str or list of str

layer

Define the number of layers:

• 1: one layer

• 3: additionally upper and lower layers are generated around the central midlayer

Type:

int

decimate(fraction=0.075)

Subsample ROI surface based on a decimation factor and return element indices. (no Freesurfer surfaces associated with the ROI surface required)

Parameters:

fraction (float, default: .075) – Multiplied by the total number of ROI elements determines (approximately) the number of remaining ROI elements after decimation.

Returns:

ele_idx – [approx. fraction * n_ele] Element indices of the subsampled surface; sorted.

Return type:

np.ndarray of float

determine_element_idx_in_mesh(msh)

Determines tetrahedra indices of msh where the triangle center points of upper, middle and lower surface and the nodes of middle surface are

Parameters:

msh (pynibs.mesh.mesh_struct.TetrahedraLinear) – TetrahedraLinear object.

Returns:

• RegionOfInterestSurface.tet_idx_tri_center_up (np.ndarray) – (N_points) Tetrahedra indices of TetrahedraLinear object instance where the center points of the triangles of the upper surface are.

• RegionOfInterestSurface.tet_idx_tri_center_mid (np.ndarray) – (N_points) Tetrahedra indices of TetrahedraLinear object instance where the center points of the triangles of the middle surface are.

• RegionOfInterestSurface.tet_idx_tri_center_low (np.ndarray) – (N_points) Tetrahedra indices of TetrahedraLinear object instance where the center points of the triangles of the lower surface are.

• RegionOfInterestSurface.tet_idx_node_coord_mid (np.ndarray) – (N_tri) Tetrahedra indices of TetrahedraLinear object instance where the nodes of the middle surface are.

generate_cortical_laminae(head_model_mesh, bbox=None, laminae=(0.06, 0.4, 0.55, 0.65, 0.85), layer_ids=('L1', 'L23', 'L4', 'L5', 'L6'))

Create the cortical layering with the provided laminar depths.

Defaults to the standard depths of the laminae in the neo-cortex from layer I to VI from “Simulation of transcranial magnetic stimulation in head model with morphologically-realistic cortical neurons”, Aberra et al., https://doi.org/10.1016/j.brs.2019.10.002

Parameters:

• head_model_mesh (simnibs.Msh) – The head model volume mesh. Inside the GM compartment of this mesh, the layering will be generated.

• bbox (np.ndarray, optional) – Bounding coordinates of the region of interest. Optional, if the mid-layer surface is already existing (and can thus be used to determine the bounding coordinates).

• laminae (list of float or tuple of float, default: (0.06, 0.4, 0.55, 0.65, 0.85)) – List of depths of the individual to-be created lamiae.

• layer_ids (List[str], default: ("L1", "L23", "L4", "L5", "L6")) – List of layer identifiers.

make_GM_WM_surface(gm_surf_fname=None, wm_surf_fname=None, midlayer_surf_fname=None, mesh_folder=None, delta=0.5, x_roi=None, y_roi=None, z_roi=None, layer=1, fn_mask=None, refine=False)

Generating a surface between WM and GM in a distance of delta 0…1 for ROI, given by Freesurfer mask or coordinates.

Parameters:

• gm_surf_fname (str or list of str) – Filename(s) of GM FreeSurfer surface(s) (lh and/or rh). Either relative to mesh_folder (fs_ID/surf/lh.pial) or absolute (/full/path/to/lh.pial)

• wm_surf_fname (str or list of str) – Filename(s) of WM FreeSurfer surface(s) (lh and/or rh) Either relative to mesh_folder (fs_ID/surf/lh.white) or absolute (/full/path/to/lh.white)

• midlayer_surf_fname (str or list of str) – Filename(s) of midlayer surface (lh and/or rh) Either relative to mesh_folder (fs_ID/surf/lh.central) or absolute (/full/path/to/lh.central)

• mesh_folder (str) – Root folder of mesh, Needed if paths above are given relative, or refine=True

• m2m_mat_fname ([defunct]) – Filename of mri2msh transformation matrix (e.g. in mri2msh: …/m2m_ProbandID/MNI2conform_6DOF.mat)

• delta (float) –

  Distance parameter where surface is generated 0…1 (default: 0.5)

  • 0 -> WM surface

  • 1 -> GM surface

• x_roi (list of float) – Region of interest [Xmin, Xmax], whole X range if empty [0,0] or None (left - right)

• y_roi (list of float) – Region of interest [Ymin, Ymax], whole Y range if empty [0,0] or None (anterior - posterior)

• z_roi (list of float) – Region of interest [Zmin, Zmax], whole Z range if empty [0,0] or None (inferior - superior)

• layer (int) –

  Define the number of layers:

  • 1: one layer

  • 3: additionally upper and lower layers are generated around the central midlayer

• fn_mask (str) – Filename for FreeSurfer .mgh mask.

• refine (bool, optional, default: False) – Refine ROI by splitting elements

Returns:

• node_coord_up (np.ndarray of float [N_roi_points x 3]) – Node coordinates (x, y, z) of upper epsilon layer of ROI surface

• node_coord_mid (np.ndarray of float [N_roi_points x 3]) – Node coordinates (x, y, z) of ROI surface

• node_coord_low (np.ndarray of float [N_roi_points x 3]) – Node coordinates (x, y, z) of lower epsilon layer of ROI surface

• node_number_list (np.ndarray of int [N_roi_tri x 3]) – Connectivity matrix of intermediate surface layer triangles

• delta (float) – Distance parameter where surface is generated 0…1 (default: 0.5)

  • 0 -> WM surface

  • 1 -> GM surface

• tri_center_coord_up (np.ndarray of float [N_roi_tri x 3]) – Coordinates (x, y, z) of triangle center of upper epsilon layer of ROI surface

• tri_center_coord_mid (np.ndarray of float [N_roi_tri x 3]) – Coordinates (x, y, z) of triangle center of ROI surface

• tri_center_coord_low (np.ndarray of float [N_roi_tri x 3]) – Coordinates (x, y, z) of triangle center of lower epsilon layer of ROI surface

• fn_mask (str) – Filename for freesurfer mask. If given, this is used instead of *_ROIs

• X_ROI (list of float) – Region of interest [Xmin, Xmax], whole X range if empty [0,0] or None (left - right)

• Y_ROI (list of float) – Region of interest [Ymin, Ymax], whole Y range if empty [0,0] or None (anterior - posterior)

• Z_ROI (list of float) – Region of interest [Zmin, Zmax], whole Z range if empty [0,0] or None (inferior - superior)

Example

make_GM_WM_surface(self, gm_surf_fname, wm_surf_fname, delta, X_ROI, Y_ROI, Z_ROI)
make_GM_WM_surface(self, gm_surf_fname, wm_surf_fname, delta, mask_fn, layer=3)

project_on_midlayer(target, verbose=False)

Project a coordinate on the nearest midlayer node

Parameters:

• target (np.ndarray) – Coordinate to project as (3,) array

• verbose (bool) – Print some verbosity information. Default: False

Returns:

target_proj – Node coordinate of nearest midlayer node.

Return type:

np.ndarray

subsample(dist=10, fn_sphere=None)

Subsample ROI surface based on a spacing and return element indices (Freesurfer surfaces associatd with the ROI surface required)

Parameters:

• dist (float) – Distance in mm the subsampled points lie apart.

• fn_sphere (str) – Name of ?.sphere file (freesurfer).

Returns:

ele_idx – (n_ele) Element indices of the subsampled surface.

Return type:

ndarray of float

class pynibs.roi.roi_structs.RegionOfInterestVolume

Bases: object

Region of interest (volume) class

node_coord

(N_points, 3) Coordinates (x,y,z) of ROI tetrahedra nodes.

Type:

np.ndarray

tet_node_number_list

(N_tet_roi, 3) Connectivity matrix of ROI tetrahedra.

Type:

np.ndarray

tri_node_number_list

(N_tri_roi, 3) Connectivity matrix of ROI tetrahedra.

Type:

np.ndarray

tet_idx_node_coord

(N_points) Tetrahedra indices of TetrahedraLinear object instance where the ROI nodes are.

Type:

np.ndarray

tet_idx_tetrahedra_center

(N_tet_roi) Tetrahedra indices of TetrahedraLinear object instance where the center points of the ROI tetrahedra are.

Type:

np.ndarray

tet_idx_triangle_center

(N_tri_roi) Tetrahedra indices of TetrahedraLinear object instance where the center points of the ROI triangle are. If the ROI is directly generated from the msh instance using “make_roi_volume_from_msh”, these indices are the triangle indices of the head mesh since the ROI mesh and the head mesh are overlapping. If the ROI mesh is not the same as the head mesh, the triangle center of the ROI mesh are always lying in a tetrahedra of the head mesh (these indices are given in this case).

Type:

np.ndarray

make_roi_volume_from_msh(msh, volume_type='box', x_roi=None, y_roi=None, z_roi=None)

Generate region of interest (volume) and extract nodes, triangles and tetrahedra from msh instance.

Parameters:

• msh (pynibs.mesh.mesh_struct.TetrahedraLinear) – Mesh object instance of type TetrahedraLinear

• volume_type (str) – Type of ROI (‘box’ or ‘sphere’)

• x_roi (list of float) –

  • type = ‘box’: [Xmin, Xmax] (in mm), whole X range if empty [0,0] or None (left - right)

  • type = ‘sphere’: origin [x,y,z]

• y_roi (list of float) –

  • type = ‘box’: [Ymin, Ymax] (in mm), whole Y range if empty [0,0] or None (anterior - posterior)

  • type = ‘sphere’: radius (in mm)

• z_roi (list of float) –

  • type = ‘box’: [Zmin, Zmax] (in mm), whole Z range if empty [0,0] or None (inferior - superior)

  • type = ‘sphere’: None

Returns:

• RegionOfInterestVolume.node_coord (np.ndarray [N_points x 3]) – Coordinates (x,y,z) of ROI tetrahedra nodes

• RegionOfInterestVolume.tet_node_number_list (np.ndarray [N_tet_roi x 3]) – Connectivity matrix of ROI tetrahedra

• RegionOfInterestVolume.tri_node_number_list (np.ndarray [N_tri_roi x 3]) – Connectivity matrix of ROI tetrahedra

• RegionOfInterestVolume.tet_idx_node_coord (np.ndarray [N_points]) – Tetrahedra indices of TetrahedraLinear object instance where the ROI nodes are lying in

• RegionOfInterestVolume.tet_idx_tetrahedra_center (np.ndarray [N_tet_roi]) – Tetrahedra indices of TetrahedraLinear object instance where the center points of the ROI tetrahedra are lying in

• RegionOfInterestVolume.tet_idx_triangle_center (np.ndarray [N_tri_roi]) – Tetrahedra indices of TetrahedraLinear object instance where the center points of the ROI triangle are . If the ROI is directly generated from the msh instance using “make_roi_volume_from_msh”, these

  indices are the triangle indices of the head mesh since the ROI mesh and the head mesh are overlapping. If the ROI mesh is not the same as the head mesh, the triangle center of the ROI mesh are always. a tetrahedra of the head mesh (these indices are given in this case)