plotly_tools.make_brainsurf¶

plotly_tools.make_brainsurf(surfname, orientation=True, orientation_lines=True, orientation_labels=True, orientation_lw=2, orientation_lcolor='black', orientation_fsize=18, orientation_fcolor='black', shiny_srf=True, surf_opac=1.0, surf_color='Gainsboro', view=None)[source]¶

Create Plotly graph objects to render brain surfaces

Parameters:

Parameters:	surfname : string Name of brain surface dataset in associated HDF5 container (access the container with h5py and use h5py.File(‘brainsurf/brainsurf.h5’,’r’).keys() to see all available surfaces). orientation : bool Flag to control whether axes are rendered to illustrate the employed coordinate system. Use the orientation_* keywords for more fine-grained controls. orientation_lines : bool Flag to control whether axes illustrating the employed coordinate system are rendered (only relevant if orientation = True). To prevent standard Cartesian coordinate axes from being drawn on top of the brain’s coordinate axes, use the ‘scene’ item of the return dictionary in Plotly’s Layout directive, see Examples below for details. orientation_labels : bool Flag to control whether labels (“Anterior”, “Posterior”, “Inferior”, “Superior”, “Left”, “Right”) highlighting the employed coordinate system are rendered (only relevant if orientation = True). orientation_lw : float Line-width of axes illustrating the employed coordinate system (only relevant if both orientation = True and orientation_lines = True). orientation_lcolor : string String to set the color of axes lines. Check matplotlib.colors.cnames for supported colors (only relevant if both orientation = True and orientation_lines = True). orientation_fsize : int Font size of coordinate system labels (only relevant if both orientation = True and orientation_labels = True). orientation_fcolor : string String to set the color of axes labels. Check matplotlib.colors.cnames for supported colors (only relevant if both orientation = True and orientation_labels = True). shiny_srf : bool Flag that controls whether the rendered brain surface exhibits good or poor light reflection properties making the surface appear “glossy” (shiny_srf = True) or matte. surf_opac : float Sets the opacity of the brain surface using a value between 0.0 (fully transparent) and 1.0 (solid). surf_color : str String to set the color of the brain surface. Check matplotlib.colors.cnames for supported colors view : str Camera position. Available options are “Axial”, “Sagittal” and “Coronal”. If view is None Plotly’s default camera position will be selected.
Returns:	ply_dict : dict A dictionary containing at least the item ‘brain’ representing the generated Plotly Mesh3d object for rendering the brain surface respecting all provided optional arguments. If orientation = True the dictionary additionally contains the items ‘orientation_lines’ (a Plotly Scatter3d object representing coordinate system axes) and ‘orientation_labels’ (a Plotly Scatter3d object representing axes labels). If only one of the provided keyword arguments orientation_lines or orientation_labels was True, the output dictionary only contains the respective conform item. If ply_dict contains the item ‘orientation_lines’ and/or the keyword view was not None, ply_dict further contains the item ‘scene’ (a nested dictionary which can be forwarded to Plotly’s Layout directive to control the visibility of Plotly’s default axes and/or the initial camera position, see Examples below for details).

surfname : string

Name of brain surface dataset in associated HDF5 container (access the container with h5py and use h5py.File(‘brainsurf/brainsurf.h5’,’r’).keys() to see all available surfaces).

orientation : bool

Flag to control whether axes are rendered to illustrate the employed coordinate system. Use the orientation_* keywords for more fine-grained controls.

orientation_lines : bool

Flag to control whether axes illustrating the employed coordinate system are rendered (only relevant if orientation = True). To prevent standard Cartesian coordinate axes from being drawn on top of the brain’s coordinate axes, use the ‘scene’ item of the return dictionary in Plotly’s Layout directive, see Examples below for details.

orientation_labels : bool

Flag to control whether labels (“Anterior”, “Posterior”, “Inferior”, “Superior”, “Left”, “Right”) highlighting the employed coordinate system are rendered (only relevant if orientation = True).

orientation_lw : float

Line-width of axes illustrating the employed coordinate system (only relevant if both orientation = True and orientation_lines = True).

orientation_lcolor : string

String to set the color of axes lines. Check matplotlib.colors.cnames for supported colors (only relevant if both orientation = True and orientation_lines = True).

orientation_fsize : int

Font size of coordinate system labels (only relevant if both orientation = True and orientation_labels = True).

orientation_fcolor : string

String to set the color of axes labels. Check matplotlib.colors.cnames for supported colors (only relevant if both orientation = True and orientation_labels = True).

shiny_srf : bool

Flag that controls whether the rendered brain surface exhibits good or poor light reflection properties making the surface appear “glossy” (shiny_srf = True) or matte.

surf_opac : float

Sets the opacity of the brain surface using a value between 0.0 (fully transparent) and 1.0 (solid).

surf_color : str

String to set the color of the brain surface. Check matplotlib.colors.cnames for supported colors

view : str

Camera position. Available options are “Axial”, “Sagittal” and “Coronal”. If view is None Plotly’s default camera position will be selected.

Returns:

ply_dict : dict

A dictionary containing at least the item ‘brain’ representing the generated Plotly Mesh3d object for rendering the brain surface respecting all provided optional arguments. If orientation = True the dictionary additionally contains the items ‘orientation_lines’ (a Plotly Scatter3d object representing coordinate system axes) and ‘orientation_labels’ (a Plotly Scatter3d object representing axes labels). If only one of the provided keyword arguments orientation_lines or orientation_labels was True, the output dictionary only contains the respective conform item. If ply_dict contains the item ‘orientation_lines’ and/or the keyword view was not None, ply_dict further contains the item ‘scene’ (a nested dictionary which can be forwarded to Plotly’s Layout directive to control the visibility of Plotly’s default axes and/or the initial camera position, see Examples below for details).

See also

Plotly: A data analytics and visualization tool for generating interactive 2D and 3D graphs rendered with D3.js. More information available on its official website
D3.js: A JavaScript library for visualizing data with HTML, SVG, and CSS. More information available on its official website

Notes

None

Examples

The following command returns a dictionary of Plotly objects to render the BrainMesh_Ch2withCerebellum brain as fully opaque glossy surface and sets up the initial camera view point in axial position

>>> pyt_dict = pyt.make_brainsurf('BrainMesh_Ch2withCerebellum', view='Axial')

The generated objects can be subsequently used to create a HTML file for rendering the surface in a web-browser based on embedded JavaScript code that employs D3.js functionality

>>> import plotly.offline as po
>>> import plotly.graph_objs as go
>>> layout = go.Layout(scene=pyt_dict['scene'])
>>> fig = go.Figure(data=[pyt_dict['brain'],
                          pyt_dict['orientation_labels'], 
                          pyt_dict['orientation_lines']],
                    layout=layout)
>>> po.plot(fig, filename='brain.html')