visbrain.objects.BrainObj

class visbrain.objects.BrainObj(name, vertices=None, faces=None, normals=None, lr_index=None, hemisphere='both', translucent=True, sulcus=False, invert_normals=False, transform=None, parent=None, verbose=None, _scale=1.0, **kw)[source][source]

Create a brain object.

Parameters
namestring

Name of the brain object. If brain is ‘B1’ or ‘B2’ or ‘B3’ use a default brain template. If name is ‘white’, ‘inflated’ or ‘sphere’ download the template (if needed). Otherwise, at least vertices and faces must be defined. The name parameter can also be the path to a file with one the following extensions :

  • By default, visbrain includes six human brain templates (‘B1’, ‘B2’, ‘B3’ and three coming from freesurfer ‘inflated’, ‘white’ and ‘sphere’). If name is one of those, the template is downloaded

  • x3d (XML files)

  • gii (Gifti files, require nibabel)

  • obj (wavefront files)

  • Freesurfer files. For example, you can provide ‘lf.inflated’ if you only want one hemisphere or [‘lh.inflated’, ‘rh.inflated’] for both

verticesarray_like | None

Mesh vertices to use for the brain. Must be an array of shape (n_vertices, 3).

facesarray_like | None

Mesh faces of shape (n_faces, 3).

normalsarray_like | None

Normals to each vertex. If None, the program will try to compute it. Must be an array with the same shape as vertices.

lr_indexarray_like | None

Left / Right index for hemispheres. Must be a vector of length n_vertices. This vector must be a boolean array where True refer to vertices that belong to the left hemisphere and False, the right hemisphere.

hemisphere{‘left’, ‘both’, ‘right’}

The hemisphere to plot.

translucentbool | True

Use translucent (True) or opaque (False) brain.

transformVisPy.visuals.transforms | None

VisPy transformation to set to the parent node.

parentVisPy.parent | None

Brain object parent.

verbosestring

Verbosity level.

kwdict | {}

Optional arguments are used to control the colorbar (See ColorbarObj).

Notes

List of supported shortcuts :

  • s : save the figure

  • <delete> : reset camera

Examples

>>> from visbrain.objects import BrainObj
>>> # Use one of default human brain template.
>>> b = BrainObj('white', hemisphere='right', translucent=False)
>>> b.preview()
>>> # Alternatively, you can also provide path to a file. For example :
>>> files = ['lh.inflated', 'rh.inflated']  # freesurfer files
>>> b2 = BrainObj(files)
>>> b2.preview(is_freesurfer_mesh_file,
)

Methods

__init__(self, name[, vertices, faces, …])

Init.

add_activation(self[, data, vertices, …])

Add activation to the brain template.

animate(self[, step, interval, iterations])

Animate the object.

clean(self)

Clean brain object.

copy(self)

Get a copy of the object.

describe_tree(self)

Tree description.

get_parcellates(self, file)

Get the list of supported parcellates names and index.

list(self[, file])

Get the list of all installed templates.

parcellize(self, file[, select, hemisphere, …])

Parcellize the brain surface using a .annot file.

preview(self[, bgcolor, axis, xyz, show, …])

Previsualize the result.

project_sources(self, s_obj[, project, …])

Project source’s activity or repartition onto the brain object.

record_animation(self, name[, n_pic, bgcolor])

Record an animated object and save as a *.gif file.

remove(self)

Remove a brain template.

render(self)

Render the canvas.

reset_camera(self)

Reset the camera.

rotate(self[, fixed, scale_factor, custom, …])

Rotate the brain using predefined rotations or a custom one.

save(self[, tmpfile])

Save the brain template (if not already saved).

screenshot(self, saveas[, print_size, dpi, …])

Take a screeshot of the scene.

set_data(self[, name, vertices, faces, …])

Load a brain template.

set_shortcuts_to_canvas(self, canvas)

Set shortcuts to a VisbrainCanvas.

slice(self[, xmin, xmax, ymin, ymax, zmin, zmax])

Take a slice of the brain.

to_dict(self)

Return a dictionary of all colorbar args.

to_kwargs(self[, addisminmax])

Return a dictionary for input arguments.

update(self)

Fonction to run when an update is needed.

update_from_dict(self, kwargs)

Update attributes from a dictionary.

add_activation(self, data=None, vertices=None, smoothing_steps=5, file=None, hemisphere=None, hide_under=None, n_contours=None, cmap='viridis', clim=None, vmin=None, vmax=None, under='gray', over='red')[source][source]

Add activation to the brain template.

This method can be used for :

  • Add activations to specific vertices (data and vertices)

  • Add an overlay (file input)

Parameters
dataarray_like | None

Vector array of data of shape (n_data,).

verticesarray_like | None

Vector array of vertex indices of shape (n_vtx). Must be an array of integers. If hemisphere is ‘left’ or ‘right’ indexation is done with respect to the specified hemisphere.

smoothing_stepsint | 20

Number of smoothing steps (smoothing is used if n_data < n_vtx). If None or 0, no smoothing is performed.

filestring | None

Full path to the overlay file. Can either be a nii.gz or gii file.

hemisphrere{None, ‘both’, ‘left’, ‘right’}

The hemisphere to use to add the overlay. If None, the method tries to infer the hemisphere from the file name.

hide_underfloat | None

Hide activations under a certain threshold.

n_contoursint | None

Display activations as contour.

cmapstring | ‘viridis’

The colormap to use.

climtuple | None

The colorbar limits. If None, (data.min(), data.max()) will be used instead.

vminfloat | None

Minimum threshold.

vmaxfloat | None

Maximum threshold.

understring/tuple/array_like | ‘gray’

The color to use for values under vmin.

overstring/tuple/array_like | ‘red’

The color to use for values over vmax.

alpha

Get the alpha value.

animate(self, step=1.0, interval='auto', iterations=-1)[source]

Animate the object.

Note that this method can only be used with 3D objects.

Parameters
stepfloat | 1.

Rotation step.

intervalfloat | ‘auto’

Time between events in seconds. The default is ‘auto’, which attempts to find the interval that matches the refresh rate of the current monitor. Currently this is simply 1/60.

iterationsint | -1

Number of iterations. Can be -1 for infinite.

camera

Get the camera value.

clean(self)[source][source]

Clean brain object.

cmap

Get the cmap value.

copy(self)[source]

Get a copy of the object.

data_folder

Get the data_folder value.

faces

Get the faces value.

get_parcellates(self, file)[source][source]

Get the list of supported parcellates names and index.

This method require the pandas and nibabel packages to be installed.

Parameters
filestring

Path to the .annot file.

hemisphere

Get the hemisphere value.

list(self, file=None)[source][source]

Get the list of all installed templates.

name

Get the name value.

normals

Get the normals value.

parcellize(self, file, select=None, hemisphere=None, data=None, cmap='viridis', clim=None, vmin=None, under='gray', vmax=None, over='red')[source][source]

Parcellize the brain surface using a .annot file.

This method require the nibabel package to be installed.

Parameters
filestring

Path to the .annot file.

selectarray_like | None

Select the structures to display. Use either a list a index or a list of structure’s names. If None, all structures are displayed.

hemispherestring | None

The hemisphere for the parcellation. If None, the hemisphere will be inferred from file name.

dataarray_like | None

Use data to be transformed into color for each parcellate.

cmapstring | ‘viridis’

The colormap to use.

climtuple | None

The colorbar limits. If None, (data.min(), data.max()) will be used instead.

vminfloat | None

Minimum threshold.

vmaxfloat | None

Maximum threshold.

understring/tuple/array_like | ‘gray’

The color to use for values under vmin.

overstring/tuple/array_like | ‘red’

The color to use for values over vmax.

parent

Get the parent value.

preview(self, bgcolor='black', axis=False, xyz=False, show=True, obj=None, size=(1200, 800), mpl=False, **kwargs)[source]

Previsualize the result.

Parameters
bgcolorarray_like/string/tuple | ‘black’

Background color for the preview.

axisbool | False

Add x and y axis with ticks.

xyzbool | False

Add an (x, y, z) axis to the scene.

objVisbrainObj | None

Pass a Visbrain object if you want to use the camera of an other object.

sizetuple | (1200, 800)

Default size of the window.

mplbool | False

Use Matplotlib to display the object. This result in a non interactive figure.

kwargsdict | {}

Optional arguments are passed to the VisbrainCanvas class.

project_sources(self, s_obj, project='modulation', radius=10.0, contribute=False, cmap='viridis', clim=None, vmin=None, under='black', vmax=None, over='red', mask_color=None, to_overlay=0)[source][source]

Project source’s activity or repartition onto the brain object.

Parameters
s_objSourceObj

The source object to project.

project{‘modulation’, ‘repartition’}

Project either the source’s data (‘modulation’) or get the number of contributing sources per vertex (‘repartition’).

radiusfloat

The radius under which activity is projected on vertices.

contribute: bool | False

Specify if sources contribute on both hemisphere.

cmapstring | ‘viridis’

The colormap to use.

climtuple | None

The colorbar limits. If None, (data.min(), data.max()) will be used instead.

vminfloat | None

Minimum threshold.

vmaxfloat | None

Maximum threshold.

understring/tuple/array_like | ‘gray’

The color to use for values under vmin.

overstring/tuple/array_like | ‘red’

The color to use for values over vmax.

mask_colorstring/tuple/array_like | ‘gray’

The color to use for the projection of masked sources. If None, the color of the masked sources is going to be used.

record_animation(self, name, n_pic=10, bgcolor=None)[source]

Record an animated object and save as a *.gif file.

Note that this method :

  • Can only be used with 3D objects.

  • Requires the python package imageio

Parameters
namestring

Name of the gif file (e.g ‘myfile.gif’)

n_picint | 10

Number of pictures to use to render the gif.

bgcolorstring, tuple, list | None

Background color.

remove(self)[source][source]

Remove a brain template.

render(self)[source]

Render the canvas.

Returns
imgarray_like

Array of shape (n_rows, n_columns, 4) where 4 describes the RGBA components.

reset_camera(self)[source][source]

Reset the camera.

rotate(self, fixed=None, scale_factor=None, custom=None, margin=1.08)[source][source]

Rotate the brain using predefined rotations or a custom one.

Parameters
fixedstr | ‘top’

Use a fixed rotation :

  • Top view : ‘axial_0’, ‘top’

  • Bottom view : ‘axial_1’, ‘bottom’

  • Left : ‘sagittal_0’, ‘left’

  • Right : ‘sagittal_1’, ‘right’

  • Front : ‘coronal_0’, ‘front’

  • Back : ‘coronal_1’, ‘back’

  • Side front-left : ‘side-fl’

  • Side front-right : ‘side-fr’

  • Side back-left : ‘side-bl’

  • Side back-right : ‘side-br’

customtuple | None

Custom rotation. This parameter must be a tuple of two floats respectively describing the (azimuth, elevation).

save(self, tmpfile=False)[source][source]

Save the brain template (if not already saved).

scale

Get the scale value.

screenshot(self, saveas, print_size=None, dpi=300.0, unit='centimeter', factor=None, region=None, autocrop=False, bgcolor=None, transparent=False, obj=None, line_width=1.0, **kwargs)[source]

Take a screeshot of the scene.

By default, the rendered canvas will have the size of your screen. The screenshot() method provides two ways to increase to exported image resolution :

  • Using print_size, unit and dpi inputs : specify the size of the image at a specific dpi level. For example, you might want to have an (10cm, 15cm) image at 300 dpi.

  • Using the factor input : multiply the default image size by this factor. For example, if you have a (1920, 1080) monitor and if factor is 2, the exported image should have a shape of (3840, 2160) pixels.

Parameters
saveasstr

The name of the file to be saved. This file must contains a extension like .png, .tiff, .jpg…

print_sizetuple | None

The desired print size. This argument should be used in association with the dpi and unit inputs. print_size describe should be a tuple of two floats describing (width, height) of the exported image for a specific dpi level. The final image might not have the exact desired size but will try instead to find a compromize regarding to the proportion of width/height of the original image.

dpifloat | 300.

Dots per inch for printing the image.

unit{‘centimeter’, ‘millimeter’, ‘pixel’, ‘inch’}

Unit of the printed size.

factorfloat | None

If you don’t want to use the print_size input, factor simply multiply the resolution of your screen.

regiontuple | None

Select a specific region. Must be a tuple of four integers each one describing (x_start, y_start, width, height).

autocropbool | False

Automaticaly crop the figure in order to have the smallest space between the brain and the border of the picture.

bgcolorarray_like/string | None

The background color of the image.

transparentbool | False

Specify if the exported figure have to contains a transparent background.

objVisbrainObj | None

Pass a Visbrain object if you want to use the camera of an other object for the sceen rendering.

kwargsdict | {}

Optional arguments are passed to the VisbrainCanvas class.

set_data(self, name=None, vertices=None, faces=None, normals=None, lr_index=None, hemisphere='both', invert_normals=False, sulcus=False)[source][source]

Load a brain template.

slice(self, xmin=None, xmax=None, ymin=None, ymax=None, zmin=None, zmax=None)[source][source]

Take a slice of the brain.

Parameters
xmin, xmaxfloat | None

Cut the mesh along the x-dimension.

ymin, ymaxfloat | None

Cut the mesh along the y-dimension.

zmin, zmaxfloat | None

Cut the mesh along the z-dimension.

transform

Get the transform value.

translucent

Get the translucent value.

vertices

Get the vertices value.

visible_obj

Get the visible_obj value.