class visbrain.objects.VolumeObj(name, vol=None, hdr=None, method='mip', threshold=0.0, cmap='OpaqueGrays', select=None, transform=None, parent=None, preload=True, verbose=None, **kw)[source][source]

Create a 3-D volume object.


Name of the volume object. If name is ‘brodmann’, ‘aal’ or ‘talairach’ a predefined volume object is used and vol, index and label are ignored. The name input can also be the path to an nii.gz file.


The volume to use. Should be a 3-d array.

hdrarray_like | None

Matrix transformation to apply. hdr should be a (4, 4) array.

method{‘mip’, ‘translucent’, ‘additive’, ‘iso’}

Volume rendering method. Default is ‘mip’.

thresholdfloat | 0.

Threshold value for iso rendering method.

cmap{‘OpaqueGrays’, ‘TransFire’, ‘OpaqueFire’, ‘TransGrays’}

Colormap to use.

selectlist | None

Select some structures in the volume.

transformVisPy.visuals.transforms | None

VisPy transformation to set to the parent node.

parentVisPy.parent | None

Volume object parent.

kwdict | {}

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


List of supported shortcuts :

  • s : save the figure

  • <delete> : reset camera


>>> from visbrain.objects import VolumeObj
>>> select = [4, 6]  # select Brodmann area 4 and 6
>>> v = VolumeObj('brodmann', method='iso', select=select)
>>> v.preview(axis=True)


__init__(self, name[, vol, hdr, method, …])


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

Animate the object.


Get a copy of the object.


Tree description.

extract_activity(self, xyz[, radius])

Extract activity of a volume around (x, y, z) points.

list(self[, file])

Get the list of installed volumes.

pos_to_slice(self, pos[, axis, hdr])

Return the slice from position.

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

Previsualize the result.

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

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


Remove the volume template.


Render the canvas.

save(self[, tmpfile])

Save the volume template.

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

Take a screeshot of the scene.

set_data(self, vol[, hdr, threshold, cmap, …])

Set data to the volume.

set_shortcuts_to_canvas(self, canvas)

Set shortcuts to a VisbrainCanvas.

slice_to_pos(self, sl[, axis, hdr])

Return the position from slice in the volume space.


Return a dictionary of all colorbar args.

to_kwargs(self[, addisminmax])

Return a dictionary for input arguments.


Update the volume.

update_from_dict(self, kwargs)

Update attributes from a dictionary.

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

Animate the object.

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

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.

property cmap

Get the cmap value.


Get a copy of the object.

property data_folder

Get the data_folder value.

extract_activity(self, xyz, radius=2.0)[source][source]

Extract activity of a volume around (x, y, z) points.


Array of (x, y, z) coordinates of shape (n_sources, 3)

radiusfloat | 2.

Radius of the sphere around each point.


Activity array of shape (n_sources,)

list(self, file=None)[source]

Get the list of installed volumes.

property method

Get the method value.

property name

Get the name value.

property parent

Get the parent value.

pos_to_slice(self, pos, axis=None, hdr=None)[source]

Return the slice from position.

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

Previsualize the result.

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.

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


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 the volume template.


Render the canvas.


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

save(self, tmpfile=False)[source]

Save the volume template.

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.


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, vol, hdr=None, threshold=None, cmap=None, method=None, select=None)[source][source]

Set data to the volume.

slice_to_pos(self, sl, axis=None, hdr=None)[source]

Return the position from slice in the volume space.

property threshold

Get the threshold value.

property transform

Get the transform value.

property visible_obj

Get the visible_obj value.