PyAIMS submodules API¶
This section documents soma.aims
/ soma.aimsalgo
submodules written in python.
SubModule: apctools
¶
.APC (commissure coordinates) IO and other tools

soma.aims.apctools.
apcFileTransform
(inAPCfilename, outAPCfilename, transform, outimagevoxelsize, imagefile=None)[source]¶ Transforms the coordinates of a .APC file points through a given transformation. It basically reads
inAPCfilename
, transforms its contents usingapcTransform()
, then writes the result tooutAPCfilename
.

soma.aims.apctools.
apcRead
(filename, imagefile=None)[source]¶ Read a .APC file  filename: string  imagefile: string
optional filename for the image file from which the AC/PC coordinates are taken from. Its header may be used to recover millimeters positions from voxels if they are not specified in the .APC file itself (for older versions of the .APC files)returns: dict
the contents of the file as a dictionary, keys being ‘ac’, ‘pc’, ‘ih’ for voxel coordinates, and ‘acmm’, ‘pcmm’, ‘ihmm’ for millimeters coordinates, and optionally ‘comment’.

soma.aims.apctools.
apcTransform
(apcdict, transform, outimagevoxelsize)[source]¶ Transforms coordinates of commissures points through a specified transformation
apcdict: dict
Commissures coordinates, as a dictionary with ‘ac’, ‘pc’, ‘ih’ keys for voxel coordinates, ‘acmm’, ‘pcmm’, ‘ihmm’ for millimeters coordinates
transform:
AffineTransformation3d
objectoutimagevoxelsize:
Coordinates are transformed in the
apcdict
dictionary, which is modified inplace.
SubModule: colormaphints
¶

soma.aims.colormaphints.
anatomicalColormaps
= [('BW LINEAR', (1.0, 1.0, 1.0)), ('BlueWhite', (0.0, 0.0, 1.0)), ('GreenWhitelinear', (0.0, 1.0, 0.0)), ('GreenWhiteexponential', (0.0, 1.0, 0.0))]¶ predefined list of colormaps suitable for anatomical volumes

soma.aims.colormaphints.
anatomicalFusionColormaps
= [('BW LINEARfusion', (1.0, 1.0, 1.0)), ('BlueWhitefusion', (0.0, 0.0, 1.0)), ('GreenWhitelinearfusion', (0.0, 1.0, 0.0))]¶ predefined list of colormaps suitable for fusionned anatomical volumes

soma.aims.colormaphints.
binaryColormaps
= [('BLUElfusion', (0.0, 0.0, 1.0)), ('GREENlfusion', (0.0, 1.0, 0.0)), ('REDlfusion', (1.0, 0.0, 0.0)), ('CYANlfusion', (0.0, 1.0, 1.0)), ('VIOLETlfusion', (1.0, 0.0, 1.0)), ('YELLOWlfusion', (1.0, 1.0, 0.0)), ('WHITElfusion', (1.0, 1.0, 1.0))]¶ predefined list of colormaps suitable for binary volumes

soma.aims.colormaphints.
binaryFusionColormaps
= [('BLUEufusion', (0.0, 0.0, 1.0)), ('GREENufusion', (0.0, 1.0, 0.0)), ('REDufusion', (1.0, 0.0, 0.0)), ('CYANufusion', (0.0, 1.0, 1.0)), ('VIOLETufusion', (1.0, 0.0, 1.0)), ('YELLOWufusion', (1.0, 1.0, 0.0)), ('Blackufusion', (1.0, 1.0, 1.0))]¶ predefined list of colormaps suitable for fusionned binary volumes

soma.aims.colormaphints.
checkVolume
(vol)[source]¶ Checks colormaprelated clues in a volume, and tries to determine whether it is an anatomical volume, a diffusion volume, a functional volume, or a labels volume. This is determined as “likelihoods” for each class (based on a pure empirical heurisrtic), based on, mainly, the histogram, voxel type, and voxel sizes.

soma.aims.colormaphints.
chooseColormaps
(vols)[source]¶ Automatically chooses distinc colormaps for a list of volumes
 returns: a list of colormaps names. They should be known from Anatomist.

soma.aims.colormaphints.
diffusionColormaps
= [('BW LINEAR', (1.0, 1.0, 1.0)), ('BlueWhite', (0.0, 0.0, 1.0)), ('GreenWhitelinear', (0.0, 1.0, 0.0)), ('GreenWhiteexponential', (0.0, 1.0, 0.0))]¶ predefined list of colormaps suitable for diffusion volumes

soma.aims.colormaphints.
diffusionFusionColormaps
= [('BW LINEARfusion', (1.0, 1.0, 1.0)), ('BlueWhitefusion', (0.0, 0.0, 1.0)), ('GreenWhitelinearfusion', (0.0, 1.0, 0.0))]¶ predefined list of colormaps suitable for fusionned diffusion volumes

soma.aims.colormaphints.
functionalColormaps
= [('RED TEMPERATURE', (1.0, 0.5, 0.0)), ('RAINBOW', (1.0, 0.0, 0.0)), ('BlueRed', (1.0, 0.0, 0.0)), ('actifret', (1.0, 1.0, 0.0)), ('Yellowred', (1.0, 1.0, 0.0))]¶ predefined list of colormaps suitable for functional volumes

soma.aims.colormaphints.
functionalFusionColormaps
= [('Rainbow1fusion', (1.0, 0.0, 0.0)), ('BlueRedfusion', (1.0, 0.0, 0.0)), ('Yellowredfusion', (1.0, 1.0, 0.0))]¶ predefined list of colormaps suitable for fusionned functional volumes

soma.aims.colormaphints.
labelsColormaps
= [('BlueRed', (1.0, 0.0, 0.0)), ('Talairach', (0.0, 0.0, 0.0))]¶ predefined list of colormaps suitable for labels volumes

soma.aims.colormaphints.
labelsFusionColormaps
= []¶ predefined list of colormaps suitable for fusionned labels volumes

soma.aims.colormaphints.
twotailColormaps
= [('tvalues100200100lfusion', (1.0, 0.0, 0.0)), ('tvalues100100100lfusion', (1.0, 0.0, 0.0))]¶ predefined list of colormaps suitable for twotail Tvalues volumes

soma.aims.colormaphints.
twotailFusionColormaps
= [('tvalues100200100', (1.0, 0.0, 0.0)), ('tvalues100100100', (1.0, 0.0, 0.0))]¶ predefined list of colormaps suitable for fusionned twotail Tvalues volumes
SubModule: filetools
¶
File functions
SubModule: fslTransformation
¶
FSL matrixes seem to transform from/to internal refs, like Aims but with a different convention:
 X: right > left
 Y: back > front
 Z: bottom > top
which appears to be Y and Z flipped compared to Aims

soma.aims.fslTransformation.
fslMatToTrm
(matfile, srcimage, dstimage)[source]¶ As far as I have understood:
A FSL transformation goes from the disk referential of the source image to the disk referential of the destination image.
BUT:
if the qform of an image (disk > “real world”) implies a flip (goes from a direct referential to an indirect one or the contrary), then a flip along X axis is inserted in the matrix, since FSL flirt doesn’t allow flipping.
SubModule: graph_comparison
¶

soma.aims.graph_comparison.
same_graphs
(ref_graph, test_graph, verbose=False)[source]¶ Compare two graphs and return if they are identical. This function is useful for testing and validation purposes. Graphs structure are compared, and vertices / edges attributes. AIMS objects inside attributes are not compared (meshes, bucket, volumes in sulci graphs for instance)
Parameters:  ref_graph (string or Graph object) – reference graph to be compared. A filename may be passed here: in this case the graph is read using aims.read() function.
 test_graph (string or Graph object) – test graph to be compared. A filename may be passed here: in this case the graph is read using aims.read() function.
 verbose (bool (optional, default: False)) – if True, messages are print on the standard output during comparison.
Returns: Return type: True if ref and test graphs are identical, or False otherwise.
SubModule: lazy_read_data
¶
This module provides wrappers for Aims readable data types which lazily load when they are used, and can release memory after they are used: LazyReadData
Specialized iterators can help parallelizing reading opertions, and perform it earlier (before they are really used) in an iteration: PreloadIterator
, PreloadList
.
A specialized version in aimsalgo handles resampling while loading: LazyResampleVolume
.

class
soma.aims.lazy_read_data.
LazyReadData
(data_or_filename, allocator_context=None, read_options=None, nops=0, reader=None, **kwargs)[source]¶ Bases:
object
LazyReadData is a data class proxy, which loads the underlying data when used, and is also able to unload it after a given number of operations to release memory.
If the data is used again after release, then it is loaded again.
The aim of this proxy is to carry data references in complex expressions or formulas, while allowing to lower the amount of memory needed to process the expression.
Ex: if we need to add 100 Volumes, the easy way to write it is:
volumes = [aims.read(f) for f in filenames] res = sum(volumes)
This expression,
sum(volumes)
uses a complete list of volumes, and thus needs the 100 volumes to be physically in mempry before the sum operation actually begins. However as the sum is performed sequentially, it should be possible to perform the same operation using only memory for 2 volumes.One solution would use iterators and yield to read data during the for loop, but it would not work in a more “handmade” expression like this one:
res = vol1 + vol2 + vol3  vol4 * vol5 + vol6 # etc.
LazyReadData offers a solution to process these expressions:
volumes = [LazyReadData(f, nops=1) for f in filenames] res = sum(volumes).data vol1 = LazyReadData(filenames[0], nops=1) # ... vol6 = LazyReadData(filename[5], nops=1) # etc. res = vol1 + vol2 + vol3  vol4 * vol5 + vol6 # etc. res = res.data # get actual Volume object
LazyReadData loads the underlying data from its filename whenever any attribute or method of the proxy is queried in the underlying data. Reading is done using aims.read(), thus only AIMS objects are supported, but on the other hand, all kinds of AIMS objects can work this way: volumes, meshes, textures, graphs, transformations, etc.
Without specifying the nops parameter, LazyReadData does not save so much memory: it just loads data whenever needed, but from this moment, keeps it in memory until the proxy is actually deleted. nops tells the proxy that, after this number of operations, the data will be released.
operations in this context are arithmetic operators (+, , *, /, pow). Other method calls are not counted.
Thus in order to optimize things, nops should be set to the number of times the object will be used in an expression. A kind of preparsing of the expression may be needed in order to automatize this.
Loading is done in a threadsafe manner (using a lock) so that two (or more) threads accessing data will not trigger several loads.
Specializing
Subclasses may override the
_lazy_read()
method to implement a different behavior or load additional data. This method should set self.data with the loaded data. This method returns the loaded data.Another way of specializing the load behavior is to provide a Reader object which could also be a specialized version of
soma.aims.Reader
.Parameters:  data_or_filename (str, Aims object, or LazyReadData) – a LazyReadData can be built from another one (copying its data, filename and other internals), or from a filename, or from an existing AIMS object.
 allocator_context (AllocatorContext) – passed to aims.read() when data is read.
 read_options (dict) – passed to aims.read() when data is read
 nops (int) – number of operations before data is unloaded. 0 means never released.
 reader (aims.Reader) – prebuilt Reader instance, used when more specific reader options are needed. Otherwise a standard reader will be used.
 kwargs (dict) – if data is an AIMS object, kwargs may include an additional ‘filename’ argument. The rest is passed to aims.read() when data is read.

class
soma.aims.lazy_read_data.
PreloadIterator
(iterable, npreload=4)[source]¶ Bases:
object
An iterator intended to be used to iterate over sequences of LazyReadData, which performs preiterations and preloads data before they get used in an actual iteration.
Idea:
When iterating over a list of LazyReadData, data is loaded when accessed, thus at the last moment, sequentially. As data loading can be efficiently threaded, the idea is to use threads to start preloading of a number of data which will be used later in the loop. This parallel loading idea is somewhat antinomic with the lazy loading data principle, so the PreloadIterator mixes both approaches. The number of preloaded data can be specified, the default is the number of processors in the machine. Each preload operation will run in a separate thread.
volumes = [LazyReadData(f, nops=1) for f in filenames] res = sum(PreloadIterator(volumes, npreload=8))
In the above example, 8 threads will be used to preload the next 8 items in the list from the current iterator position. As the iterator advances, more data preloads will be triggered.
Parameters:  iterable (iterable) – the iterable can be a list, a generator, or an iterator. It should iterate over items which are LazyReadData instances, because it will use their lazy loading mechanism and their threading locks.
 npreload (number of preloaded data / number of threads used to preload) –

class
soma.aims.lazy_read_data.
PreloadList
(iterable=None, npreload=4)[source]¶ Bases:
list
A list which provides a PreloadIterator to iterate over it.
volumes = PreloadList((LazyReadData(f, nops=1) for f in filenames), npreload=8) res = sum(volumes)
equivalent to:
volumes = [LazyReadData(f, nops=1) for f in filenames] res = sum(PreloadIterator(volumes, npreload=8))
SubModule: meshSplit
¶

soma.aims.meshSplit.
meshSplit
(mesh, tex, graph, tex_time_step=0)[source]¶ Splits a mesh into patches corresponding to a labels texture. Patches are organized into a graph.
The graph must preexist, and nodes will be inserted into it.

soma.aims.meshSplit.
meshSplit2
(mesh, tex, graph, voxel_size=None, tex_time_step=None)[source]¶ Split mesh according to texture patches
Compared to meshSplit, this version also adds buckets (voxels lists) in each graph node.
Parameters:  mesh (cortex mesh for example) –
 tex (aims.TimeTexture_S16) – texture of labels (parcellation of the mesh, labels between 1 and nb_labels, background = 0)
 graph (Graph) – the graph __syntax__ attribute should be: ‘roi’
 voxel_size ((optional)) – if a voxel size is given, a bucket will be built with the specified voxel size to follow the mesh. Otherwise there will be no bucket.
 tex_time_step (int (optional)) – time step to be used in the texture for regions split. default: 0
 Outputs –
  –
 None – modify the input graph: add vertex : submeshes (one per texture label) and associated buckets add vertex “others” : void
SubModule: pandas
¶
SubModule: spmnormalizationreader
¶

soma.aims.spmnormalizationreader.
readSpmNormalization
(matfilename, source=None, destref=None, srcref=None)[source]¶ Read a SPM *_sn.mat normalization file and converts it to an Aims AffineTransformation3d. The converted transformation has for source the AIMS referential of the source image, and for destination the template referential of the SPM .mat file. All coordinates are in millimeters.
The source image information may be provided either as its filename, its header object, or the image itself. It should carry the needed information: source volume storage_to_memory transformation matrix, voxel_size, etc. If None is passed as source (the default), then the source image name will be built from the .mat filename and will be read if found.
matfilename: string
file name of the *_sn.mat normalization file to reading
source: filename (string), or Volume
Volume
orAimsData
), or volume header (MappingType)file name of the *_sn.mat normalization file to reading
destref: string or UUID (
Uuid
)destination referential for the transformation. If not specified, none will be set. If provided as a symbolic name (‘TalairachMNI templateSPM’), it will be converted to an UUID string.
srcref: string or UUID
source referential for the transformation. If not specified, an attempt will be made to take it from the source image, otherwise it will not be set. If provided as a symbolic name (‘TalairachMNI templateSPM’), it will be converted to an UUID string.
returns:
AffineTransformation3d
objectthe converted transformation
SubModule: texturetools
¶

soma.aims.texturetools.
average_texture
(output, inputs)[source]¶ Create average gyri texture from a group of subject.

soma.aims.texturetools.
change_wrong_labels
(cc_label, label, gyri_tex, mesh_neighbors_vector, cc_tex_label)[source]¶ After a study of its neighbors, wrong label is replaced by the correct number.
Parameters:  cc_label (label of connected component in cc_tex_label) –
 label (label of associated vertices in gyri texture) –
 (aims time texture S16) (gyri_tex) –
 mesh_neighbors_vector (aims.SurfaceManip.surfaceNeighbours(mesh)) –
 cc_tex_label (texture representing connected components of label) –
Returns:  gyri_tex (aims time texture S16) (new gyri_tex texture,) – without isolated vertex.
 winner_label (the correct number.)

soma.aims.texturetools.
clean_gyri_texture
(mesh, gyri_tex)[source]¶ Cleaning a gyri texture by using connected components.
Parameters:  (aims time surface) (mesh) – white mesh associated to gyri_tex
 (aims time texture S16) (gyri_tex) – gyri texture as full FreeSurfer parcellation.
Returns: new gyri texture, without isolated vertex.
Return type: gyri_tex (aims time texture S16)

soma.aims.texturetools.
connectedComponents
(mesh, tex, areas_mode=0)[source]¶ Parameters:  mesh –
 tex (aimsTimeTexture_S16) – (one time step) labeled between 1 and LabelsNb, background = 0, ignored_vertex = 1.
 areas_mode – if = 1: computing area measures of the connected components, if = 0: no measure (by default).
Returns:  step_cc (connectedComponentTex: aimsTimeTexture_S16) – time step = LabelsNb, for each time step (label in the tex), texture of the connected components corresponding to this label (background = 1, and connected components = values between 1 and nb_cc).
 areas_measure (python dictionary) – areas_measures[label] = [16.5, 6.0] (numpy array) if label (in tex) has two connected Components 1 and 2 with area = 16.5 and 6.0 respectively, areas are in square mm

soma.aims.texturetools.
extractLabelsFromTexture
(tex, labels_list, new_label)[source]¶  inputs:
 tex: labeled texture ( from FreeSurfer or an other ) labels_list, new_label: you can overwrite numbers ( labels_list ) with your own number ( new_label )
 output:
 otex: labeled texture with merged regions only

soma.aims.texturetools.
find_wrong_labels
(mesh, gyriTex)[source]¶ Parameters:  mesh –
 gyriTex (gyri texture) –
Returns: wrong_labels – [cctex: connectedComponentTex: aimsTimeTexture_S16, time step = LabelsNb, for each time step (label in the tex), texture of the connected components corresponding to this label (background = 1, and connected components = values between 1 and ccNb) areas_measures = python dictionary, areas_measures[label] = [16.5, 6.0] (numpy array) if label (in tex) has two connected Components 1 and 2 with area = 16.5 and 6.0 respectively, areas are in square mm]
Return type: list of wrong labels

soma.aims.texturetools.
mergeLabelsFromTexture
(tex, labels_list, new_label)[source]¶  inputs:
 tex: labeled texture ( from FreeSurfer or an other ) labels_list, new_label: you can overwrite numbers ( labels_list ) with your own number ( new_label )
 ouput:
 otex: labeled texture with merged regions

soma.aims.texturetools.
meshDiceIndex
(mesh, texture1, texture2, timestep1=0, timestep2=0, labels_table1=None, labels_table2=None)[source]¶ DICE index calculation between two sets of regions defined by label textures on a common mesh. texture1, texture2: aims.TimeTexture instances, should be int (labels). timestep1, timestep2: timestep to use in texture1 and texture2. labels_table1, labels_table2: optional labels translation tables (dicts or arrays) to translate values of texture1 and/or texture2.
return

soma.aims.texturetools.
nomenclature_to_colormap
(hierarchy, labels_list, as_float=True, default_color=[0.3, 0.6, 1.0, 1.0])[source]¶ Make a colormap from labels and colors of a nomenclature (hierarchy), following a labels_list order.
Parameters:  hierarchy (Hierarchy object) – nomenclature
 labels_list (list of strings) – labels with order. The returned colormap will follow this ordering.
 as_float (bool (optional, default: True)) – if True, colors will be float values in the [01] range. If False, they will be int values in the [0255] range.
 default_color (list (4 floats) (optional)) – Color used for labels not found in the nomenclature. It is given as floats ([01] range).
Returns: colormap – array of colors (4 float values in [01] range)
Return type: numpy array

soma.aims.texturetools.
remove_non_principal_connected_components
(mesh, tex, trash_label)[source]¶ Keep only the largest connected component in each label, for a label texture.
Parameters:  mesh –
 tex (label texture (S16, int)) –
 trash_label (value to replace nonprincipal components) –
Returns: out_tex
Return type: label texture

soma.aims.texturetools.
vertex_texture_to_polygon_texture
(mesh, tex, allow_cut=False)[source]¶ Make a “polygon texture” from a vartexbased label texture. A polygon texture has a value for each polygon.
For a given polygon the value is taken as the majority of values on its vertices. If an absolute majority cannot be obtained, the mesh polygons may be cut to avoid losing precision. This is done if allow_cut is True.
When allow_cut is False, the returned value is the polygon texture. It may work on meshes of any polygon size (triangles, quads, segments…)
 When allow_cut is True, the returned value is a tuple:
 polygon texture
 new mesh with possibly split triangles
It only works for meshes of triangles.
SubModule: volumetools
¶
Volume functions

soma.aims.volumetools.
crop_volume
(vol, threshold=0, border=0)[source]¶ Crop the input volume, removing slices filled with values under a given threshold, and keeping a given border.
If no crop actually takes place, the input volume is returned without duplication. If crop is actually performed, then a view into the original volume is returned, sharing the same data block which is not copied.
Transformations in the header are adapted accordingly.
Parameters:  vol (aims Volume) – volume to be cropped
 threshold (volume value, optional) – Minimum value over which a slice cannot be cropped (is supposed to contain real data). The default is 0: only value <= 0 is croppable
 border (int, optional) – border around the cropped volume: the cropped volume is enlarged by twice this value in each direction, within the limits of the original volume (the bounding box always fits in the original volume). Values in the border are taken from the original volume, the border is not artificially filled with a constant value. The default is 0: no border
SubModule: aimsalgo.lazy_resample_volume
¶

class
soma.aimsalgo.lazy_resample_volume.
LazyResampleVolume
(data_or_filename, allocator_context=None, read_options=None, nops=0, reader=None, dtype=None, transform=None, dims=None, vox_size=(1.0, 1.0, 1.0, 1.0), resampling_order=1, default_value=0, **kwargs)[source]¶ Bases:
soma.aims.lazy_read_data.LazyReadData
A specialized version of aims.LazyReadData dedicated to Volumes, which can perform voxel type conversion and resampling to another space when reading data.
LazyResampleVolume is useful when operations have to be performed on several volumes which are not initially in the same space.
image_names = ['image%02d.nii' % i for i in range(10)] transf_names = ['transform%02d' % i for i in range(10)] rvols = [lazy_resample_volume.LazyResampleVolume( f, transform=t, nops=1, dims=(256, 256, 200, 1), vox_size=(1, 1, 1, 1), dtype='FLOAT') for f, t in zip(image_names, transf_names)] res = sum(rvols) / len(rvols)
Parameters:  data_or_filename (see LazyReadData) –
 allocator_context (see LazyReadData) –
 read_options (see LazyReadData) –
 nops (see LazyReadData) –
 reader (see LazyReadData) –
 dtype (str or type) – may specify a conversion to a specific voxel type
 transform (str or aims.AffineTransformation3d or list) – Transformations to be applied to the volume when it is read. May be an AffineTransformation3d instance, or a filename (.trm file), or a list of transformations / filenames to be combined (applied rioght to left, thus matrices are multiplied in the lefttoright order ).
 dims (list or tuple of int) – resampled volume dimensions in voxels
 vox_size (list or tuple of float) – resampled volume voxel sizes
 resampling_order (int) – interpolation order for the resampling
 default_value (data type) – default background value for the resampled volume
 kwargs (see LazyReadData) –
SubModule: aimsalgo.mesh_coordinates_sphere_resampling
¶

soma.aimsalgo.mesh_coordinates_sphere_resampling.
draw_sphere
(mesh, longitude, latitude)[source]¶ Draw a sphere
Parameters:  mesh ((AimsTimeSurface_3_VOID)) – a spherical triangulation of cortical hemisphere of the subject
 longitude ((TimeTexture_FLOAT)) – a longitude texture from HipHop mapping that go with the white_mesh of the subject. This texture indicates the spherical coordinates at each point.
 latitude ((TimeTexture_FLOAT)) – a latitude texture from HipHop mapping that go with the white_mesh of the subject. This texture indicates the spherical coordinates at each point.
Returns: sphere_mesh – a spherical triangulation of the subject of its cortical hemisphere, projected on a sphere
Return type:

soma.aimsalgo.mesh_coordinates_sphere_resampling.
polygon_average_sizes
(mesh)[source]¶ Return the average edge length for each triangle of a mesh
Used by refine_sphere_mesh() and sphere_mesh_from_distance_map()
Parameters:  mesh ((AimsTimeSurface_3_VOID)) – a mesh providing trianglar struture
 Return –
 lengths ((numpy array)) – average size for each polygon

soma.aimsalgo.mesh_coordinates_sphere_resampling.
polygon_max_sizes
(mesh)[source]¶ Return the max edge length for each triangle of a mesh
Used by refine_sphere_mesh() and sphere_mesh_from_distance_map()
Parameters:  mesh ((AimsTimeSurface_3_VOID)) – a mesh providing trianglar struture
 Return –
 lengths ((numpy array)) – average size for each polygon

soma.aimsalgo.mesh_coordinates_sphere_resampling.
refine_sphere_mesh
(init_sphere, avg_dist_texture, current_sphere, target_avg_dist, inversion=False, init_sphere_coords=None, current_sphere_coords=None, dist_texture_is_scaled=True)[source]¶ Adaptively refine polygons of a sphere mesh according to an average distance map (genrally calculated in a different space), and a target length.
This is one single step if the iterative sphere_mesh_from_distance_map().
Polygons where the average distance map value is “too high” are oversampled (divided in 4).
Parameters:  init_sphere ((AimsTimeSurface_3_VOID)) –
 avg_dist_texture ((TimeTexture_FLOAT)) –
 current_sphere ((AimsTimeSurface_3_VOID)) –
 target_avg_dist ((float)) –
 init_sphere_coords ((tuple of 2 textures) (optional)) –
 current_sphere_coords ((tuple of 2 textures) (optional)) –
Returns: refined_sphere
Return type:

soma.aimsalgo.mesh_coordinates_sphere_resampling.
resample_mesh_to_sphere
(mesh, sphere, longitude, latitude, inversion=False)[source]¶ Resample a mesh to the sphere.
Parameters:  mesh ((AimsTimeSurface_3_VOID)) – a spherical triangulation of cortical hemisphere of the subject
 sphere ((AimsTimeSurface_3_VOID)) – a sphere mesh with center 0. For example, a spherical mesh of size 100 located in standard BrainVISA directory can be used.
 longitude ((TimeTexture_FLOAT)) – a longitude texture from HipHop mapping that go with the white_mesh of the subject. This texture indicates the spherical coordinates at each point.
 latitude ((TimeTexture_FLOAT)) – a latitude texture from HipHop mapping that go with the white_mesh of the subject. This texture indicates the spherical coordinates at each point.
 inversion (bool) – if True, the longitude coord is inverted (useful for right hemisphere)
Returns: resampled
Return type:

soma.aimsalgo.mesh_coordinates_sphere_resampling.
resample_texture_to_sphere
(mesh, sphere, longitude, latitude, texture, interpolation='linear', inversion=False)[source]¶ Resample a mesh to the sphere.
Parameters:  mesh ((AimsTimeSurface_3_VOID)) – a spherical triangulation of cortical hemisphere of the subject
 sphere ((AimsTimeSurface_3_VOID)) – a sphere mesh with center 0. For example, a spherical mesh of size 100 located in standard BrainVISA directory can be used.
 longitude ((TimeTexture_FLOAT)) – a longitude texture from HipHop mapping that go with the white_mesh of the subject. This texture indicates the spherical coordinates at each point.
 latitude ((TimeTexture_FLOAT)) – a latitude texture from HipHop mapping that go with the white_mesh of the subject. This texture indicates the spherical coordinates at each point.
 interpolation (string or MeshInterpoler.InterpolationType enum) – resampling interpolation type: “linear” or “nearest_neighbour”
 inversion (bool) – if True, the longitude coord is inverted (useful for right hemisphere)
Returns: resampled
Return type: (same type as input texture)

soma.aimsalgo.mesh_coordinates_sphere_resampling.
sphere
(v, u)[source]¶ Generate a sphere from polar coordinates to spheric coordinates.
Parameters:

soma.aimsalgo.mesh_coordinates_sphere_resampling.
sphere_coordinates
(sphere, inversion=False)[source]¶ Compute spherical coordinates (longitude, latitude) on a sphere.
Parameters:  sphere ((AimsTimeSurface_3_VOID)) – a sphere mesh: vertices must be on a sphere with center 0.
 inversion (bool) – if True, the longitude coord is inverted (useful for right hemisphere)
Returns: (longitude, latitude)
Return type: tuple, each element being a TimeTexture_FLOAT

soma.aimsalgo.mesh_coordinates_sphere_resampling.
sphere_mesh_from_distance_map
(init_sphere, avg_dist_texture, target_avg_dist, inversion=False, dist_texture_is_scaled=True)[source]¶ Builds a sphere mesh with vertices density driven by an average distance map, coming with another initial sphere mesh, (genrally calculated in a different space), and a target length.
Starting from an icosahedron, this procedure iterates calls to refine_sphere_mesh() until the target_avg_dist criterion is reached everywhere on the mesh.
The initial avg_dist_texture can be (and, has better be) scaled according to the edges length of the init_sphere mesh polygons. In this case it is the ratio of post / pre deformation edges lengths.
Use case:  get an initial sphere mesh (typically an icosphere)  get subjects mesh (typically grey/white brain interfaces), which have
also coordinates maps (output of the Hip Hop toolbox for BrainVISA) resample subjects mesh to the initial sphere. Obtained meshes will be very inhomogen
 build a edges legth map from these subjects resampled meshes
 use sphere_mesh_from_distance_map to build an adapted template sphere
Parameters:  init_sphere ((AimsTimeSurface_3_VOID)) –
 avg_dist_texture ((TimeTexture_FLOAT)) –
 target_avg_dist ((float)) –
 dist_texture_is_scaled ((bool) (optional)) – If True, the avg_dist_texture is considered to be scaled according to the inital sphere triangles edges (see aims.SurfaceManip.meshEdgeLengthRatioTexture). Default: True
Returns: refined_sphere
Return type:

soma.aimsalgo.mesh_coordinates_sphere_resampling.
texture_by_polygon
(mesh, texture)[source]¶ Averages a texture (classically, by vertex) on polygons.
Used by refine_sphere_mesh() and sphere_mesh_from_distance_map()
Parameters:  mesh ((AimsTimeSurface_3_VOID)) – a mesh providing trianglar struture
 texture ((TimeTexture_FLOAT)) – texture data
Returns: poly_tex – texture averaged on polygons
Return type: (nupy array)
SubModule: aimsalgo.meshwatershedtools
¶
This modles features the following:
 generate a reduced profile by basins using the watershed algorithm
 merge the items if necessary (measured criteria validating the basins)
Main dependencies: PyAims library

soma.aimsalgo.meshwatershedtools.
watershedWithBasinsMerging
(tex, mesh, size_min=0, depth_min=0, tex_threshold=0.01, mode='and')[source]¶ Generate a texture of merged basins: watershed texture.
 The basins are merged according to two criteria:
 the size of basins
 the depth of basins
Parameters:  tex ((TimeTexture_S16)) – texture of boundaries between regions
 mesh ((aimsTimeSurface_3)) – associated mesh
 size_min ((int)) – number of basins > size_min
 depth_min ((float)) – number of basins > depth_min
 tex_threshold ((float)) – threshold on the input intensity texture
 mode ((str)) –
 two cases:
 and –> merge basins with its parent
 if size < k_size and depth < k_depth
 or –> merge basins with its parent
 if size < k_size or depth < k_depth
Returns: output_tex – watershed results according to the thresholds indicated by k_size and k_depth
Return type:
SubModule: aimsalgo.polyfit
¶
Fit a volume with a polynomial.
Inspired by Fitpoly.m, courtesy of Alexandre Vignaud.

soma.aimsalgo.polyfit.
apply_poly
(volume_like, coefs, mask=None, transformation=None)[source]¶ Calculate a polynomial over the domain of the supplied mask.
Return a numpy array the same size as the input mask.
transformation (optional) is the projective transformation from the volume to the referential in which the polynomial coefficients were calculated.
SubModule: aimsalgo.t1mapping
¶
Reconstruct magnetic resonance parametres.
This is mainly a reimplementation of scripts provided by Alexandre Vignaud, plus a few improvements functions (such as mask and B1 map holes filling).

class
soma.aimsalgo.t1mapping.
BAFIData
(amplitude_volume, phase_volume)[source]¶ Bases:
object
B1 map reconstruction class using the VFA (Variable Flip Angle) method.
Pass the BAFI data as two amplitudephase 4D AIMS volumes.
The last dimension of both arrays represents the different echos.

static
correctB0
(FA_map, FA_phase, B0_map, tau, echo_time)[source]¶ Apply B0 correction to a B1 map.
This is a reimplementation of correctB0.m, courtesy of Alexandre Vignaud.

fix_b1_map
(b1map, smooth_type='median', gaussian=False, output_median=False)[source]¶ Fix/improve the B1 map by filling holes, smoothing, and extending it a little bit spacially so as to use it on the complete whole brain.
Parameters:  b1map (volume) – the B1 map to be corrected, may be the output of self.make_flip_angle_map()
 smooth_type (str (optional)) – smoothing correction type. default: ‘median’ median: dilated:
 gaussian (float (optional)) – default: 0 (not applied) perform an additional gaussian filtering of given stdev
 output_median (bool (optional)) – if set, the output will be a tuple including a 2nd volume: the medianfiltered B1 map. Only valid if smooth_type is ‘median’.
Returns:  The corrected B1 map.
 If output_median is set, the return value is a tuple
 (corrected B1 map, medianfiltered B1 map)

make_B0_map
()[source]¶ Build a map of B0 in Hz from BAFI data.
Return the map as a numpy array.
This is a reimplementation of Phase2B0Map.m, courtesy of Alexandre Vignaud.

make_B1_map
(B0_correction=False)[source]¶ Build a map of B1 (in radians) from BAFI data.
Return a numpy array of complex type.
This is a reimplementation of BAFI2B1map.m, courtesy of Alexandre Vignaud.
 The method is Yarnykh’s (MRM 57:192200 (2007)) +
 Amadon ISMRM2008 (MAFI sequence: simultaneaous cartography of B0
and B1)

make_flip_angle_map
()[source]¶ Build a map of actual flip angle (in radians) from BAFI data.
This is a reimplementation of BAFI2FAmap.m (courtesy of Alexandre Vignaud) modified to return only the real flip angle (omitting the phase).
 The method is Yarnykh’s (MRM 57:192200 (2007)) +
 Amadon ISMRM2008 (MAFI sequence: simultaneaous cartography of B0
and B1)

static

class
soma.aimsalgo.t1mapping.
GREData2FlipAngles
(min_FA_volume, max_FA_volume)[source]¶ Bases:
object

soma.aimsalgo.t1mapping.
correct_bias
(biased_vol, b1map, dp_gre_low_contrast=None, field_threshold=None)[source]¶ Apply bias correction on biased_vol according to the B1 map, and possibly a GRE low contrast image.
Without dp_gre_low_contrast image:
\[unbiased\_vol = biased\_vol / b1map\](plus improvements)
With dp_gre_low_contrast image:
\[unbiased\_vol = biased\_vol / (lowpass(dp\_gre\_low\_contrast) * b1map)\](roughly)
\(lowpass\) is currently a gaussian filter with
sigma=8mm
.method: courtesy of Alexandre Vignaud.
ref: ISMRM abstract Mauconduit et al.
All input images are expected to contain transformation information to a common space in their header (1st transformation, normally to the scannerbased referential). They are thus not expected to have the same field of view or voxel size, all are resampled to the biased_vol space.
The returned value is a tuple containing 2 images: the corrected image, and the multiplicative correction field.
Parameters:  biased_vol (volume) – volume to be corrected
 b1map (volume) – B1 map as flip angles in degrees, generally returned by BAFIData.make_flip_angle_map. May be improved (holes filled, dilated) using BAFIData.fix_b1_map() which is generally better.
 dp_gre_low_contrast (volume (optional)) – GRE low contrast image
 field_threshold (float (optional)) – Threshold for the corrective field before inversion: the biased image will be divided by this field. To avoid too high values, field values under this threshold are clamped. Null values are masked out, so the threshold applies only to nonnull values. If not specified, the threshold is 100 if the dp_gre_low_contrast is not provided, and 3000 when dp_gre_low_contrast is used. If field_threshold is 0, then no thresholding is applied.
Returns:  unbiased_vol (volume) – according to the calculations explained above. The returned image has the same voxel type as the input one (althrough calculations are performed in float in the function), and the grey levels are roughly adjusted to the level of input data (unless it produces overflow, in which case the max value is adjusted to fit in the voxel type).
 field (volume) – The correction field applied to the image (multiplicatively)