Documentation 0.16.0. > API Reference > viz

viz

fetch_viz_icons() Download icons for fury
optional_package(name[, trip_msg]) Return package-like thing and module setup for package name
read_viz_icons([style, fname]) Read specific icon from specific style.

Module: viz.app

Horizon(tractograms, images, cluster, …[, …])

Methods
Streamlines alias of nibabel.streamlines.array_sequence.ArraySequence
apply_shader(hz, actor)
build_label(text[, font_size, bold]) Simple utility function to build labels
horizon(tractograms, images, cluster, …[, …]) Highly interactive visualization - invert the Horizon!
length Euclidean length of streamlines
optional_package(name[, trip_msg]) Return package-like thing and module setup for package name
qbx_and_merge(streamlines, thresholds[, …]) Run QuickBundlesX and then run again on the centroids of the last layer
setup_module()
slicer_panel(renderer[, data, affine, …]) Slicer panel with slicer included

Module: viz.panel

build_label(text[, font_size, bold]) Simple utility function to build labels
optional_package(name[, trip_msg]) Return package-like thing and module setup for package name
setup_module()
slicer_panel(renderer[, data, affine, …]) Slicer panel with slicer included

Module: viz.projections

Visualization tools for 2D projections of 3D functions on the sphere, such as ODFs.

doctest_skip_parser(func) Decorator replaces custom skip test markup in doctests.
optional_package(name[, trip_msg]) Return package-like thing and module setup for package name
setup_module()
sph_project(vertices, val[, ax, vmin, vmax, …]) Draw a signal on a 2D projection of the sphere.

Module: viz.regtools

draw_lattice_2d(nrows, ncols, delta) Create a regular lattice of nrows x ncols squares.
optional_package(name[, trip_msg]) Return package-like thing and module setup for package name
overlay_images(img0, img1[, title0, …]) Plot two images one on top of the other using red and green channels.
overlay_slices(L, R[, slice_index, …]) Plot three overlaid slices from the given volumes.
plot_2d_diffeomorphic_map(mapping[, delta, …]) Draw the effect of warping a regular lattice by a diffeomorphic map.
plot_slices(V[, slice_indices, fname]) Plot 3 slices from the given volume: 1 sagital, 1 coronal and 1 axial
setup_module()
simple_plot(file_name, title, x, y, xlabel, …) Saves the simple plot with given x and y values

fetch_viz_icons

dipy.viz.fetch_viz_icons()

Download icons for fury

optional_package

dipy.viz.optional_package(name, trip_msg=None)

Return package-like thing and module setup for package name

Parameters:
name : str

package name

trip_msg : None or str

message to give when someone tries to use the return package, but we could not import it, and have returned a TripWire object instead. Default message if None.
Returns:
pkg_like : module or TripWire instance

If we can import the package, return it. Otherwise return an object raising an error when accessed

have_pkg : bool

True if import for package was successful, false otherwise

module_setup : function

callable usually set as setup_module in calling namespace, to allow skipping tests.

read_viz_icons

dipy.viz.read_viz_icons(style='icomoon', fname='infinity.png')

Read specific icon from specific style.

Parameters:
style : str

Current icon style. Default is icomoon.

fname : str

Filename of icon. This should be found in folder HOME/.fury/style/. Default is infinity.png.
Returns:
path : str

Complete path of icon.

Horizon

class dipy.viz.app.Horizon(tractograms, images, cluster, cluster_thr, random_colors, length_lt, length_gt, clusters_lt, clusters_gt, world_coords=True, interactive=True, out_png='tmp.png')

Bases: object

Methods

build_scene  
build_show  
__init__(tractograms, images, cluster, cluster_thr, random_colors, length_lt, length_gt, clusters_lt, clusters_gt, world_coords=True, interactive=True, out_png='tmp.png')

Highly interactive visualization - invert the Horizon!

Parameters:
tractograms : sequence

Sequence of Streamlines objects

images : sequence of tuples

Each tuple contains data and affine

cluster : bool

Enable QuickBundlesX clustering

cluster_thr : float

Distance threshold used for clustering

random_colors : bool
length_lt : float
length_gt : float
clusters_lt : int
clusters_gt : int
world_coords : bool
interactive : bool
out_png : string

References

[Horizon_ISMRM19]Garyfallidis E., M-A. Cote, B.Q. Chandio, S. Fadnavis, J. Guaje, R. Aggarwal, E. St-Onge, K.S. Juneja, S. Koudoro, D. Reagan, DIPY Horizon: fast, modular, unified and adaptive visualization, Proceedings of: International Society of Magnetic Resonance in Medicine (ISMRM), Montreal, Canada, 2019.
build_scene()
build_show(scene)

Streamlines

dipy.viz.app.Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

apply_shader

dipy.viz.app.apply_shader(hz, actor)

build_label

dipy.viz.app.build_label(text, font_size=18, bold=False)

Simple utility function to build labels

Parameters:
text : str
font_size : int
bold : bool
Returns:
label : TextBlock2D

horizon

dipy.viz.app.horizon(tractograms, images, cluster, cluster_thr, random_colors, length_lt, length_gt, clusters_lt, clusters_gt, world_coords=True, interactive=True, out_png='tmp.png')

Highly interactive visualization - invert the Horizon!

Parameters:
tractograms : sequence

Sequence of Streamlines objects

images : sequence of tuples

Each tuple contains data and affine

cluster : bool

Enable QuickBundlesX clustering

cluster_thr : float

Distance threshold used for clustering

random_colors : bool
length_lt : float
length_gt : float
clusters_lt : int
clusters_gt : int
world_coords : bool
interactive : bool
out_png : string

References

[Horizon_ISMRM19]Garyfallidis E., M-A. Cote, B.Q. Chandio, S. Fadnavis, J. Guaje, R. Aggarwal, E. St-Onge, K.S. Juneja, S. Koudoro, D. Reagan, DIPY Horizon: fast, modular, unified and adaptive visualization, Proceedings of: International Society of Magnetic Resonance in Medicine (ISMRM), Montreal, Canada, 2019.

length

dipy.viz.app.length()

Euclidean length of streamlines

Length is in mm only if streamlines are expressed in world coordinates.

Parameters:
streamlines : ndarray or a list or dipy.tracking.Streamlines

If ndarray, must have shape (N,3) where N is the number of points of the streamline. If list, each item must be ndarray shape (Ni,3) where Ni is the number of points of streamline i. If dipy.tracking.Streamlines, its common_shape must be 3.
Returns:
lengths : scalar or ndarray shape (N,)

If there is only one streamline, a scalar representing the length of the streamline. If there are several streamlines, ndarray containing the length of every streamline.

Examples

>>> from dipy.tracking.streamline import length
>>> import numpy as np
>>> streamline = np.array([[1, 1, 1], [2, 3, 4], [0, 0, 0]])
>>> expected_length = np.sqrt([1+2**2+3**2, 2**2+3**2+4**2]).sum()
>>> length(streamline) == expected_length
True
>>> streamlines = [streamline, np.vstack([streamline, streamline[::-1]])]
>>> expected_lengths = [expected_length, 2*expected_length]
>>> lengths = [length(streamlines[0]), length(streamlines[1])]
>>> np.allclose(lengths, expected_lengths)
True
>>> length([])
0.0
>>> length(np.array([[1, 2, 3]]))
0.0

optional_package

dipy.viz.app.optional_package(name, trip_msg=None)

Return package-like thing and module setup for package name

Parameters:
name : str

package name

trip_msg : None or str

message to give when someone tries to use the return package, but we could not import it, and have returned a TripWire object instead. Default message if None.
Returns:
pkg_like : module or TripWire instance

If we can import the package, return it. Otherwise return an object raising an error when accessed

have_pkg : bool

True if import for package was successful, false otherwise

module_setup : function

callable usually set as setup_module in calling namespace, to allow skipping tests.

qbx_and_merge

dipy.viz.app.qbx_and_merge(streamlines, thresholds, nb_pts=20, select_randomly=None, rng=None, verbose=True)

Run QuickBundlesX and then run again on the centroids of the last layer

Running again QuickBundles at a layer has the effect of merging some of the clusters that maybe originally devided because of branching. This function help obtain a result at a QuickBundles quality but with QuickBundlesX speed. The merging phase has low cost because it is applied only on the centroids rather than the entire dataset.

Parameters:
streamlines : Streamlines
thresholds : sequence

List of distance thresholds for QuickBundlesX.

nb_pts : int

Number of points for discretizing each streamline

select_randomly : int

Randomly select a specific number of streamlines. If None all the streamlines are used.

rng : RandomState

If None then RandomState is initialized internally.

verbose : bool

If True print information in stdout.
Returns:
clusters : obj

Contains the clusters of the last layer of QuickBundlesX after merging.

References

[Garyfallidis12]Garyfallidis E. et al., QuickBundles a method for tractography simplification, Frontiers in Neuroscience, vol 6, no 175, 2012.
[Garyfallidis16]Garyfallidis E. et al. QuickBundlesX: Sequential clustering of millions of streamlines in multiple levels of detail at record execution time. Proceedings of the, International Society of Magnetic Resonance in Medicine (ISMRM). Singapore, 4187, 2016.

setup_module

dipy.viz.app.setup_module()

slicer_panel

dipy.viz.app.slicer_panel(renderer, data=None, affine=None, world_coords=False)

Slicer panel with slicer included

Parameters:
renderer : Renderer
data : 3d ndarray
affine : 4x4 ndarray
world_coords : bool

If True then the affine is applied.
Returns:
panel : Panel

build_label

dipy.viz.panel.build_label(text, font_size=18, bold=False)

Simple utility function to build labels

Parameters:
text : str
font_size : int
bold : bool
Returns:
label : TextBlock2D

optional_package

dipy.viz.panel.optional_package(name, trip_msg=None)

Return package-like thing and module setup for package name

Parameters:
name : str

package name

trip_msg : None or str

message to give when someone tries to use the return package, but we could not import it, and have returned a TripWire object instead. Default message if None.
Returns:
pkg_like : module or TripWire instance

If we can import the package, return it. Otherwise return an object raising an error when accessed

have_pkg : bool

True if import for package was successful, false otherwise

module_setup : function

callable usually set as setup_module in calling namespace, to allow skipping tests.

setup_module

dipy.viz.panel.setup_module()

slicer_panel

dipy.viz.panel.slicer_panel(renderer, data=None, affine=None, world_coords=False)

Slicer panel with slicer included

Parameters:
renderer : Renderer
data : 3d ndarray
affine : 4x4 ndarray
world_coords : bool

If True then the affine is applied.
Returns:
panel : Panel

doctest_skip_parser

dipy.viz.projections.doctest_skip_parser(func)

Decorator replaces custom skip test markup in doctests.

Say a function has a docstring:

>>> something # skip if not HAVE_AMODULE
>>> something + else
>>> something # skip if HAVE_BMODULE

This decorator will evaluate the expresssion after skip if. If this evaluates to True, then the comment is replaced by # doctest: +SKIP. If False, then the comment is just removed. The expression is evaluated in the globals scope of func.

For example, if the module global HAVE_AMODULE is False, and module global HAVE_BMODULE is False, the returned function will have docstring:

>>> something 
>>> something + else
>>> something

optional_package

dipy.viz.projections.optional_package(name, trip_msg=None)

Return package-like thing and module setup for package name

Parameters:
name : str

package name

trip_msg : None or str

message to give when someone tries to use the return package, but we could not import it, and have returned a TripWire object instead. Default message if None.
Returns:
pkg_like : module or TripWire instance

If we can import the package, return it. Otherwise return an object raising an error when accessed

have_pkg : bool

True if import for package was successful, false otherwise

module_setup : function

callable usually set as setup_module in calling namespace, to allow skipping tests.

setup_module

dipy.viz.projections.setup_module()

sph_project

dipy.viz.projections.sph_project(vertices, val, ax=None, vmin=None, vmax=None, cmap=None, cbar=True, tri=False, boundary=False, **basemap_args)

Draw a signal on a 2D projection of the sphere.

Parameters:
vertices : (N,3) ndarray

unit vector points of the sphere

val: (N) ndarray

Function values.

ax : mpl axis, optional

If specified, draw onto this existing axis instead.

vmin, vmax : floats

Values to cut the z

cmap : mpl colormap
cbar: Whether to add the color-bar to the figure
triang : Whether to display the plot triangulated as a pseudo-color plot.
boundary : Whether to draw the boundary around the projection
in a black line
Returns:
ax : axis

Matplotlib figure axis

Examples

>>> from dipy.data import get_sphere
>>> verts = get_sphere('symmetric724').vertices
>>> ax = sph_project(verts.T, np.random.rand(len(verts.T)))

draw_lattice_2d

dipy.viz.regtools.draw_lattice_2d(nrows, ncols, delta)

Create a regular lattice of nrows x ncols squares.

Creates an image (2D array) of a regular lattice of nrows x ncols squares. The size of each square is delta x delta pixels (not counting the separation lines). The lines are one pixel width.

Parameters:
nrows : int

the number of squares to be drawn vertically

ncols : int

the number of squares to be drawn horizontally

delta : int

the size of each square of the grid. Each square is delta x delta pixels
Returns:
lattice : array, shape (R, C)

the image (2D array) of the segular lattice. The shape (R, C) of the array is given by R = 1 + (delta + 1) * nrows C = 1 + (delta + 1) * ncols

optional_package

dipy.viz.regtools.optional_package(name, trip_msg=None)

Return package-like thing and module setup for package name

Parameters:
name : str

package name

trip_msg : None or str

message to give when someone tries to use the return package, but we could not import it, and have returned a TripWire object instead. Default message if None.
Returns:
pkg_like : module or TripWire instance

If we can import the package, return it. Otherwise return an object raising an error when accessed

have_pkg : bool

True if import for package was successful, false otherwise

module_setup : function

callable usually set as setup_module in calling namespace, to allow skipping tests.

overlay_images

dipy.viz.regtools.overlay_images(img0, img1, title0='', title_mid='', title1='', fname=None)

Plot two images one on top of the other using red and green channels.

Creates a figure containing three images: the first image to the left plotted on the red channel of a color image, the second to the right plotted on the green channel of a color image and the two given images on top of each other using the red channel for the first image and the green channel for the second one. It is assumed that both images have the same shape. The intended use of this function is to visually assess the quality of a registration result.

Parameters:
img0 : array, shape(R, C)

the image to be plotted on the red channel, to the left of the figure

img1 : array, shape(R, C)

the image to be plotted on the green channel, to the right of the figure

title0 : string (optional)

the title to be written on top of the image to the left. By default, no title is displayed.

title_mid : string (optional)

the title to be written on top of the middle image. By default, no title is displayed.

title1 : string (optional)

the title to be written on top of the image to the right. By default, no title is displayed.

fname : string (optional)

the file name to write the resulting figure. If None (default), the image is not saved.

overlay_slices

dipy.viz.regtools.overlay_slices(L, R, slice_index=None, slice_type=1, ltitle='Left', rtitle='Right', fname=None)

Plot three overlaid slices from the given volumes.

Creates a figure containing three images: the gray scale k-th slice of the first volume (L) to the left, where k=slice_index, the k-th slice of the second volume (R) to the right and the k-th slices of the two given images on top of each other using the red channel for the first volume and the green channel for the second one. It is assumed that both volumes have the same shape. The intended use of this function is to visually assess the quality of a registration result.

Parameters:
L : array, shape (S, R, C)

the first volume to extract the slice from, plottet to the left

R : array, shape (S, R, C)

the second volume to extract the slice from, plotted to the right

slice_index : int (optional)

the index of the slices (along the axis given by slice_type) to be overlaid. If None, the slice along the specified axis is used

slice_type : int (optional)

the type of slice to be extracted: 0=sagital, 1=coronal (default), 2=axial.

ltitle : string (optional)

the string to be written as title of the left image. By default, no title is displayed.

rtitle : string (optional)

the string to be written as title of the right image. By default, no title is displayed.

fname : string (optional)

the name of the file to write the image to. If None (default), the figure is not saved to disk.

plot_2d_diffeomorphic_map

dipy.viz.regtools.plot_2d_diffeomorphic_map(mapping, delta=10, fname=None, direct_grid_shape=None, direct_grid2world=-1, inverse_grid_shape=None, inverse_grid2world=-1, show_figure=True)

Draw the effect of warping a regular lattice by a diffeomorphic map.

Draws a diffeomorphic map by showing the effect of the deformation on a regular grid. The resulting figure contains two images: the direct transformation is plotted to the left, and the inverse transformation is plotted to the right.

Parameters:
mapping : DiffeomorphicMap object

the diffeomorphic map to be drawn

delta : int, optional

the size (in pixels) of the squares of the regular lattice to be used to plot the warping effects. Each square will be delta x delta pixels. By default, the size will be 10 pixels.

fname : string, optional

the name of the file the figure will be written to. If None (default), the figure will not be saved to disk.

direct_grid_shape : tuple, shape (2,), optional

the shape of the grid image after being deformed by the direct transformation. By default, the shape of the deformed grid is the same as the grid of the displacement field, which is by default equal to the shape of the fixed image. In other words, the resulting deformed grid (deformed by the direct transformation) will normally have the same shape as the fixed image.

direct_grid2world : array, shape (3, 3), optional

the affine transformation mapping the direct grid’s coordinates to physical space. By default, this transformation will correspond to the image-to-world transformation corresponding to the default direct_grid_shape (in general, if users specify a direct_grid_shape, they should also specify direct_grid2world).

inverse_grid_shape : tuple, shape (2,), optional

the shape of the grid image after being deformed by the inverse transformation. By default, the shape of the deformed grid under the inverse transform is the same as the image used as “moving” when the diffeomorphic map was generated by a registration algorithm (so it corresponds to the effect of warping the static image towards the moving).

inverse_grid2world : array, shape (3, 3), optional

the affine transformation mapping inverse grid’s coordinates to physical space. By default, this transformation will correspond to the image-to-world transformation corresponding to the default inverse_grid_shape (in general, if users specify an inverse_grid_shape, they should also specify inverse_grid2world).

show_figure : bool, optional

if True (default), the deformed grids will be ploted using matplotlib, else the grids are just returned
Returns:
warped_forward : array

Image with grid showing the effect of transforming the moving image to the static image. Shape will be direct_grid_shape if specified, otherwise the shape of the static image.

warped_backward : array

Image with grid showing the effect of transforming the static image to the moving image. Shape will be inverse_grid_shape if specified, otherwise the shape of the moving image.

plot_slices

dipy.viz.regtools.plot_slices(V, slice_indices=None, fname=None)

Plot 3 slices from the given volume: 1 sagital, 1 coronal and 1 axial

Creates a figure showing the axial, coronal and sagital slices at the requested positions of the given volume. The requested slices are specified by slice_indices.

Parameters:
V : array, shape (S, R, C)

the 3D volume to extract the slices from

slice_indices : array, shape (3,) (optional)

the indices of the sagital (slice_indices[0]), coronal (slice_indices[1]) and axial (slice_indices[2]) slices to be displayed. If None, the middle slices along each direction are displayed.

fname : string (optional)

the name of the file to save the figure to. If None (default), the figure is not saved to disk.

setup_module

dipy.viz.regtools.setup_module()

simple_plot

dipy.viz.regtools.simple_plot(file_name, title, x, y, xlabel, ylabel)

Saves the simple plot with given x and y values

Parameters:
file_name : string

file name for saving the plot

title : string

title of the plot

x : integer list

x-axis values to be ploted

y : integer list

y-axis values to be ploted

xlabel : string

label for x-axis

ylable : string

label for y-axis