Subject Viewer

This module implements high level data viewers. They handle all VTK, and data access operations. They are made of data managers which specialize on handling specific data types. They maintain its state, and specially important, support changing subject or coordinate systems while keeping the other parameters constant. In this way it is possible to compare two subjects.

These viewers are designed to be used as widgets it Qt applications. For that matter specific Widget wrappers exist for each of them. This wrappers can send PyQt signals on certain events, like picking the screen.

Full Viewers

These classes combine different data managers to create integrated visualizations.

class SubjectViewer(render_window_interactor, reader, widget)

A general viewer to show data on a particular subject

It provides access to

• Images
• fMRI Contours
• Segmentation reconstruction models
• Surface parcellations
• Tractographies
• Tracula Bundles

change_current_space(*args, **kwargs)

Changes the current coordinate system

Parameters:new_space (str) – New coordinate system

change_subject(new_subject)

Changes the subject associated to the viewer

Parameters:new_subject – new subject id

contours

Access to FmriContours

get_camera_parameters()

Gets current camera parameters

Returs:

focal_point, position, view_up

image

Access to ImageManager

models

Access to ModelManager

print_camera()

Logs information about the current camera position

Data is send to the current logger with info level

reset_camera(position)

resets the current camera to standard locations.

Parameters:position (int) –

• 0: initial 3d view
• 1: left
• 2: right
• 3: front
• 4: back
• 5: top
• 6: bottom

set_camera(focal_point, position, view_up)

Sets the camera position

Parameters:

• focal_point (tuple) – Focal point
• position (tuple) – Camera position
• view_up (tuple) – View up vector

set_contours_visibility(*args, **kwargs)

Toggle visibility of fMRI contours

Parameters:visible (bool) – If True contours will show, if False contours will be hidden,

set_fmri_contours_image(*args, **kwargs)

Sets the image to use for calculating fMRI contours

Parameters:

• paradigm (str) – Name of fMRI paradigm
• contrast (int) – Index (Matlab style) of desired contrast

show_cone()

Useful for testing

surface

Access to SurfaceManager

tractography

Access to TractographyManager

tracula

Access to TraculaManager

class fMRI_viewer(render_window_interactor, reader, widget)

A viewer for visualizaing fMRI data. It displays

• Images
• fMRI contours

change_contrast(*args, **kwargs)

Change contrast

Parameters:new_contrast (int) – Index of new contrast (starting at 1)

change_orientation(orientation_index)

Changes the orientation of the Image Plane Widget

Parameters:orientation_index (int) – 0 for x, 1 for y and 2 for z

change_paradigm(*args, **kwargs)

Change fMRI paradigm

Parameters:new_pdgm (str) – Must be one of the available fMRI paradigms

change_subject(*args, **kwargs)

Change subject associated to the plane

Parameters:new_subj – Id of new subject

contours

Access to FmriContours

current_coords()

Get cursor coordinates

Returns:A tuple of coordinates

get_camera_parameters()

Gets current camera parameters

Returs:

focal_point, position, view_up

image

Access to ImageManager

reset_camera(*args, **kwargs)

resets the current camera to standard locations.

Parameters:position (int) –

• 0: initial 3d view
• 1: left
• 2: right
• 3: front
• 4: back
• 5: top
• 6: bottom

set_all(*args, **kwargs)

Set subject, paradigm and contrast

Parameters:

• new_subject – Id of new subject
• new_pdgm (str) – New paradigm, must be one of the available fMRI paradigms
• new_contrast (int) – Index of new contrast (starting at 1)

set_camera(focal_point, position, view_up)

Sets the camera position

Parameters:

• focal_point (tuple) – Focal point
• position (tuple) – Camera position
• view_up (tuple) – View up vector

set_contour_opacity(*args, **kwargs)

Opacity for displaying the contours

Parameters:value (int) – A number from 0 to 100; where 0 is invisible and 100 is opaque

set_contour_value(*args, **kwargs)

Set value for the fMRI contours

Parameters:value (float) – The iso-contours will be calculated at this value

set_contour_visibility(*args, **kwargs)

Set visibility of contours

Parameters:value (bool) – If True show the contours, otherwise hide them

set_cursor_coords(*args, **kwargs)

Set coordinates for the cursor

Parameters:Coords (tuple) – New position for the cursor (in voxels)

update_view(*args, **kwargs)

Resets all elements in the view

class OrthogonalPlanesViewer(render_window_interactor, reader, widget)

A viewer with three orthogonal planes

It provides access to

• Images
• Surfaces
• A sphere

change_image_modality(*args, **kwargs)

Change image modality in all planes

See ImageManager.change_image_modality()

Parameters:

• image_class (str) – New image class (IMAGE, LABELS or FMRI)
• image_name (str) – New image name, for fMRI enter the paradigm here
• contrast (int) – If modality is fMRI the index of the contrast

change_space(*args, **kwargs)

Changes the current coordinate system

Parameters:new_space (str) – New coordinate system

change_subject(*args, **kwargs)

Changes the subject associated to the viewer

Parameters:new_subject – new subject id

cortex

Access to the surface manager

current_position()

Last picked position, either on the planes or on the surface

Returns:Coordinates of the last picked position

finish_initializing()

Finish viewer initialization, only call this after calling “show” on the widget or its parents

get_camera_parameters()

Gets current camera parameters

Returns:focal_point, position, view_up

get_current_slice()

Get current slices of all planes

Returns:A tuple with the current slice of each plane (x,y,z)

get_number_of_slices()

Get number of slices in each plane

Returns:A tuple with the image dimension

hide_image(*args, **kwargs)

Hide all planes

image_planes

Access to the image planes array

set_camera(focal_point, position, view_up)

Sets the camera position

Parameters:

• focal_point (tuple) – Focal point
• position (tuple) – Camera position
• view_up (tuple) – View up vector

show_image(*args, **kwargs)

Shows all planes

sphere

Access to the sphere

x_image

Access to the image manager perpendicular to x

y_image

Access to the image manager perpendicular to y

z_image

Access to the image manager perpendicular to z

class MeasurerViewer(render_window_interactor, reader, widget)

A viewer that allows the user to measure the distance between two points on images using a vtkMeasureWidget

change_image_modality(*args, **kwargs)

Change image modality in all planes

See ImageManager.change_image_modality()

Parameters:

• image_class (str) – New image class, must be FMRI, IMAGE, LABEL or DTI
• mod (str) – New modality name, for fMRI enter the paradigm here
• contrast (int) – If modality is fMRI the index of the contrast

change_space(*args, **kwargs)

Changes the current coordinate system

Parameters:new_space (str) – New coordinate system

change_subject(*args, **kwargs)

Changes the subject associated to the viewer

Parameters:new_subject – new subject id

distance

Current distance measured by the measure widget

emit_distance_changed_signal(caller, event)

Emit a Qt Signal through the associated widget

finish_initializing()

Finish viewer initialization, only call this after calling “show” on the widget or its parents

get_camera_parameters()

Gets current camera parameters

Returns:focal_point, position, view_up

get_current_slice()

Get current slices of all planes

Returns:A tuple with the current slice of each plane (x,y,z)

get_number_of_slices()

Get number of slices in each plane

Returns:A tuple with the image dimension

hide_image(*args, **kwargs)

Hide all planes

image_planes

Access to the image planes array

point1

Get coordinates of first measure point

point2

Get coordinates of second measure point

reset_camera(*args, **kwargs)

Resets camera to the initial position

reset_measure(*args, **kwargs)

Reset the measure widget, remove both points from the scene

set_camera(*args, **kwargs)

Sets the camera position

Parameters:

• focal_point (tuple) – Focal point
• position (tuple) – Camera position
• view_up (tuple) – View up vector

set_measure_axis(*args, **kwargs)

Set the measure plane to be perpendicular to the axis

Parameters:axis_str (str) – “axial”, “sagital” or “coronal”

set_measure_color(*args, **kwargs)

Set color of the measure widget

Parameters:

• r (int) – red
• g (int) – green
• b (int) – blue

set_points(*args, **kwargs)

Set coordinates for both points

Parameters:

• p1 (tuple) – First point coordinates
• p2 (tuple) – Second point coordinates

set_slice_coords(*args, **kwargs)

Move the measure plane perpendicularly

Parameters:coords (float) – New position across the axis perpendicular to the measure plane

show_image(*args, **kwargs)

Shows all planes

x_image

Access to the image manager perpendicular to x

y_image

Access to the image manager perpendicular to y

z_image

Access to the image manager perpendicular to z

Data Managers

Managing the visualization state is simplified by the data managers, which focus on specific data types.

class ImageManager(reader, ren, widget, interactor, initial_subj=None, initial_space='subject', picker=None)

Controls an ImagePlaneWidget

change_image_modality(*args, **kwargs)

Changes the modality of the current image;

In the case of fMRI modality should be fMRI and paradigm the name of the paradigm

Parameters:

• image_class (str) – New image class, may be one of ["image","label","dti","fmri"]
• image_name (str) – New image modality name. Use None if image_class is "dti", otherwise it should be inside the index of the given class. In case of FMRI the paradigm should be entered here See get()
• force_reload (bool) – if True, forces the plane to reload the image if it appears to be the same as before
• contrast (int) – contrast to show in case image_class is "fmri"

change_image_orientation(*args, **kwargs)

Changes the orientation of the current image

Parameters:orientation (int) – 0 for X, 1 for Y and 2 for Z

change_space(*args, **kwargs)

Change current coordinate system

new_space (str) : new coordinate system, see get()

change_subject(*args, **kwargs)

Change subject associated to the plane

Parameters:new_subject – Id of new subject

get_current_image_level()

Current level

Returns:Current level value

get_current_image_slice()

Get the index of the actual slice

Returns:The index of the current slice

get_current_image_window()

Current window

Returns:Current window value

get_number_of_image_slices()

Gets the number of slices in the current orientation

Returns:The number of available slicer for the current image and orientation

hide_image(*args, **kwargs)

Hide the plane widget

image_plane_widget

Get the vtkImagePlaneWidget

reset_window_level(*args, **kwargs)

Resets window and level to standard values

set_image_level(*args, **kwargs)

Changes level value

Parameters:new_level (float) – New level value

set_image_slice(*args, **kwargs)

Sets the image slice

Parameters:new_slice (int) – Number of the desired slice

set_image_window(*args, **kwargs)

Changes window value

Parameters:new_window (float) – New window value

show_image(*args, **kwargs)

Show the plane widget

class ModelManager(reader, ren, initial_subj=None, initial_space='subject')

A manager for segmented structure models

get_opacity()

Gets actual opacity

Returns:An integer from 0 to 100 indicating the current opacity percentage

get_scalar_metrics(metric_name)

Get an scalar metric from the current models

Parameters:metric_name (str) –

May be

• volume : Total volume occupied by all models
• area : Sum of superficial areas of all models
• fa_inside : Mean value of FA inside the current models
• md_inside : Mean value of MD inside the current models
• nfibers : Number of fibers that cross any of the current models
• lfibers : Mean length of fibers that cross any of the current models
• fa-fibers : Mean FA of fibers that cross any of the current models

Returns:Scalar value or nan if there was an error

reload_models(*args, **kwargs)

Reloads all models

Parameters:

• subj – Code for new subject, if None the subject is not changed
• space (str) – new coordinate system, if None the coordinates are not changed

set_color(*args, **kwargs)

Sets the color for displaying the models

Parameters:float_rgb_color (tuple) – An rgb value, if None the freesurfer lookuptable is used

set_models(*args, **kwargs)

Sets the currently shown models

Parameters:new_model_set (set) – An iterable of strings with names of valid models.

set_opacity(*args, **kwargs)

Opacity for displaying the models

Parameters:int_opacity (int) – A number from 0 to 100; where 0 is invisible and 100 is opaque

class TractographyManager(reader, ren, initial_subj=None, initial_space='subject')

A manager for tractography data

add_from_database(*args, **kwargs)

Add a bundle from the database

See braviz.readAndFilter.bundles_db

Parameters:b_id (int) – Bundle id in the database

change_color(*args, **kwargs)

Sets the coloring scheme for the rendered data.

Parameters:new_color (str) –

New coloring scheme, the following values are accepted

• bundle : A different color for each bundle
• orient : Color tractography based on local orientation
• rand : A different color for each line
• fa_p : Use FA values at each point and a lookuptable
• fa_l : Use mean fa of each line and a lookuptable
• md_p : Use MD values at each point and a lookuptable
• md_l : Use mean MD of each line and a lookuptable
• length: Use length of each line and a lookuptable
• aparc: Use the aparc label at each point and the freesurfer lookuptable
• wmparc: Use the wmparc label at each point and the freesurfer lookuptable

get_bundle_colors()

Get a set of colors for coloring each active bundle in a different color

Returns:A color palette with length equal to the number of active bundles

get_polydata(b_id)

Gets the polydata object associated to a database bundle.

The current subject, coordinate system and scalars are maintained

Parameters:b_id (int) – Bundle database id Returns:vtkPolyData from the requested bundle

get_scalar_from_db(scalar, bid)

Gets an scalar metric from an active database bundle

Parameters:

• scalar (str) –

  Scalar metric, available options are:

  • number : Number of lines
  • mean_length : Mean length of lines
  • mean_fa : Mean FA of the bundle
  • mean_md : Mean MD of the bundle
• bid (int) – Database id

Returns:

Scalar value or nan if there was an error

get_scalar_from_structs(scalar)

Gets an scalar metric from the active checkpoints bundle

see set_bundle_from_checkpoints()

Parameters:scalar (str) –

Scalar metric, available options are:

• number : Number of lines
• mean_length : Mean length of lines
• mean_fa : Mean FA of the bundle
• mean_md : Mean MD of the bundle

Returns:Scalar value or nan if there was an error

get_show_color_bar()

Status of the color bar

Returns:True if the color bar is active, False otherwise

hide_checkpoints_bundle(*args, **kwargs)

Hide the checkpoints bundle created with set_bundle_from_checkpoints()

hide_database_tract(*args, **kwargs)

Hides a bundle previously added from the database

Parameters:bid (int) – Bundle database id

set_active_db_tracts(*args, **kwargs)

Selects active database tracts

Parameters:new_set (list) – List of database ids

set_bundle_from_checkpoints(*args, **kwargs)

Creates a fiber bundle based on a list of structures

Parameters:

• checkpoints (list) – Structure model names list
• through_all (bool) – If True the bundle will contain lines that pass though all checkpoints, otherwise it will contain lines that pass through any checkpoint

set_current_space(*args, **kwargs)

Set current coordinate system

new_space (str) : new coordinate system, see get()

set_opacity(*args, **kwargs)

Sets opacity for the displayed bundles

Parameters:float_opacity (float) – From 0 to 1; where 0 is transparent and 1 is opaque

set_show_color_bar(*args, **kwargs)

Activates a vtk color bar

Parameters:value (bool) – If True the bar is activated, if False it is hidden

set_subject(*args, **kwargs)

Sets the subject associated to the manager

Parameters:subj – New subject

class TraculaManager(reader, ren, initial_subj=None, initial_space='subject')

A data manager for Tracula bundles

active_bundles

Gets the set of active bundles

Returns:A frozenSet of currently active bundles

reload_bundles(*args, **kwargs)

Reloads all bundles

Parameters:

• subj – Code for new subject, if None the subject is not changed
• space (str) – new coordinate system, if None the coordinates are not changed

set_bundles(*args, **kwargs)

Sets the currently shown bundles

Parameters:bundle_names (set) – An iterable of strings with names of tracula bundles.

set_opacity(*args, **kwargs)

Opacity for displaying the models

Parameters:int_opacity (int) – A number from 0 to 100; where 0 is invisible and 100 is opaque

class SurfaceManager(reader, ren, iren, initial_subj=None, initial_space='subject', picker=None, persistent_cone=False)

A data manager for freesurfer sufaces parcelations

get_last_picked_pos()

Coordinates of the last picked position

Returns:A tuple with the coordinates of the last pickedposition

hide_cone()

Hides the picking cone

pick_cone_actor

Access to the pick cone actor

set_hemispheres(*args, **kwargs)

Sets the active hemisphers

Parameters:

• left (bool) – If True the left hemisphere is activated, if False it is deactivated, if None it is unchanged
• right (bool) – If True the right hemisphere is activated, if False it is deactivated, if None it is unchanged

set_opacity(*args, **kwargs)

Opacity for displaying the surfaces

Parameters:int_opacity (int) – A number from 0 to 100; where 0 is invisible and 100 is opaque

set_scalars(*args, **kwargs)

Sets the current scalars to use for the surfaces

Parameters:scalars (str) – See braviz.readAndFilter.base_reader.BaseReader.get() for options

set_space(*args, **kwargs)

Change current coordinate system

new_space (str) : new coordinate system, see get()

set_subject(*args, **kwargs)

Change subject associated to the manager

Parameters:new_subject – Id of new subject

set_surface(*args, **kwargs)

Sets the current surface to display at both hemispheres

Parameters:surface (str) – See braviz.readAndFilter.base_reader.BaseReader.get() for options

show_color_bar(*args, **kwargs)

Activates a vtk color bar

Parameters:value (bool) – If True the bar is activated, if False it is hidden

class SphereProp(ren)

An sphere that can be added to any viewer to represent regions of interest

hide()

Hide the sphere

remove_from_renderer()

Remove the sphere from the renderer

set_center(ctr)

Set the center of the sphere

Parameters:ctr (tuple) – center

set_color(r, g, b)

Set color of the measure widget

Parameters:

• r (int) – red
• g (int) – green
• b (int) – blue

set_opacity(opac_int)

Opacity of the sphere

Parameters:opac_int (int) – A number from 0 to 100; where 0 is invisible and 100 is opaque

set_radius(r)

Set the radius of the sphere

Parameters:r (float) – Sphere radius

set_repr(rep)

Set representation of the sphere

Parameters:rep (str) – Options are "wireframe" or "surface"

show()

Show the sphere

class FmriContours(ren)

Display contours calculated over an fMRI statistic map.

actor

Get the contours actor

set_image(img)

Sets the statistical map

Parameters:img (vtkImageData) – Data used for contours generation

set_lut(lut)

Sets a lookup table for showing the contours

Notice the contour will always have the same vale, and therefore the same color. However the lut will reflect the changes in the contour value.

Parameters:lut (vtkScalarsToColors) – Table to generate contour color based on its value

set_value(value)

Sets the value at which contours are generated

Parameters:value (float) – Statistical value for creating contours

PyQt Widgets

These classes wrap the viewers so that they can be connected into Qt applications, in theory such classes could be built for other graphical interface libraries.

class QSubjectViewerWidget(reader, parent)

A Qt Widget that wraps SubjectViewer and lets it connect naturally to Qt Applications

initialize_widget()

Call this function after calling show on the widget or a parent

slice_change_handle(new_slice)

Emits a signal when the current image slice is changed on the vtkWidget

subject_viewer

Access to the underlying SubjectViewer

window_level_change_handle(window, level)

Emits a signal when window or level are changed by interacting in the vtkWidget

class QOrthogonalPlanesWidget(reader, parent)

A Qt Widget that wraps OrthogonalPlanesViewer and lets it connect naturally to Qt Applications

initialize_widget()

Call this function after calling show on the widget or a parent

orthogonal_viewer

Access to the underlying class:OrthogonalPlanesViewer

slice_change_handle(new_slice)

Emits a signal when the current image slice is changed on the vtkWidget

window_level_change_handle(window, level)

Emits a signal when window or level are changed by interacting in the vtkWidget

class QMeasurerWidget(reader, parent)

A Qt Widget that wraps MeasurerViewer and lets it connect naturally to Qt Applications

distance_changed_handle(distance)

Emits a signal the measured distance is changed in the vtkWidget

initialize_widget()

Call this function after calling show on the widget or a parent

orthogonal_viewer

Access to the underlying class:MeasurerViewer

slice_change_handle(new_slice)

Emits a signal when the current image slice is changed on the vtkWidget

window_level_change_handle(window, level)

Emits a signal when window or level are changed by interacting in the vtkWidget

class QFmriWidget(reader, parent)

A Qt Widget that wraps fMRI_viewer and lets it connect naturally to Qt Applications

cursor_move_handler(coordinates)

Emits a signal when the cursor is moved

initialize_widget()

Call this function after calling show on the widget or a parent

slice_change_handle(new_slice)

Emits a signal when the current image slice is changed on the vtkWidget

viewer

Access to the internal fMRI_viewer

window_level_change_handle(window, level)

Emits a signal when window or level are changed by interacting in the vtkWidget

Utilities

do_and_render(f)

Wraps drawing methods, adding an optional call to Render at the end.

It adds the skip_render kwarg argument, which if True will avoid the call to Render. This is useful to avoid repeated call renders when performing several draw operations.

requires the class to have the renderer accessible as self.ren

Parameters:f (function) – Function that changes vtk scene

class FilterArrows(parent=None, other_keys=())

A Qt event filter to prevent the main vtk widget from swallowing certain keys. By default this are the arrows, but additional keys can be added in the constructor.

class AdditionalCursors(ren)

An additional set of cursors to use when those included in vtkImageWidget are not flexible enough

get_coords()

Voxel coordinates of last picked position

Returns:Coordinates of last picked position in voxels

get_position()

Current position of the cursors

Returns:Coordinates of the last picked position (in mm)

hide()

Hide cursor

set_axis_coords(axis=None, coords=None)

Set position of the cursors

Parameters:

• axis (int) – Axis perpendicular to the cursor, 0 for x, 1 for y and 2 for z
• coords (tuple) – Position of the cursor in voxels

set_image(img)

Image to use as reference for the cursors

Parameters:img (vtkImageData) – The cursors will stick to this image

Examples