plot3d¶

3D plotting for WhipperSnapPy using pythreejs (Three.js) for Jupyter.

This module provides interactive 3D brain visualization for Jupyter notebooks using Three.js/WebGL. It works in all Jupyter environments (browser, JupyterLab, Colab, VS Code).

Unlike the desktop GUI (whippersnap command), this renders entirely in the browser via WebGL and is designed for notebook environments.

Usage:

from whippersnappy import plot3d
viewer = plot3d(mesh='path/to/lh.white', bg_map='path/to/lh.curv')
display(viewer)

Dependencies:: pythreejs, ipywidgets, numpy

whippersnappy.plot3d.plot3d(mesh, overlay=None, annot=None, bg_map=None, roi=None, minval=None, maxval=None, invert=False, scale=1.85, color_mode=None, width=800, height=800, ambient=0.1)[source]¶

Create an interactive 3D notebook viewer using pythreejs (Three.js).

This function prepares geometry and color information (via whippersnappy.geometry.prepare_geometry()) and constructs a pythreejs renderer and controls wrapped in an ipywidgets.VBox for display inside a Jupyter notebook.

The mesh can be any triangular surface — not just brain surfaces. Supported file formats: FreeSurfer binary surface (e.g. lh.white), ASCII OFF (.off), legacy ASCII VTK PolyData (.vtk), ASCII PLY (.ply), or a (vertices, faces) numpy array tuple.

Parameters:

meshstr or tuple of (array_like, array_like): Path to a mesh file (FreeSurfer binary, .off, .vtk, or .ply) or a (vertices, faces) tuple.
overlaystr, array_like, or None, optional: Path to a per-vertex scalar file, or a (N,) array of per-vertex scalar values.
annotstr, tuple, or None, optional: Path to a FreeSurfer .annot file, or a (labels, ctab) / (labels, ctab, names) tuple for categorical labeling.
bg_mapstr, array_like, or None, optional: Path to a per-vertex scalar file or a (N,) array used as grayscale background shading for non-overlay regions.
roistr, array_like, or None, optional: Path to a FreeSurfer label file or a (N,) boolean array to restrict overlay coloring to a subset of vertices.
minval, maxvalfloat or None, optional: Threshold and saturation values used for color mapping. If None, sensible defaults are chosen automatically.
invertbool, optional: If True, invert the overlay color map. Default is False.
scalefloat, optional: Global geometry scale applied during preparation. Default is 1.85.
color_modeColorSelection or None, optional: Which sign of overlay values to color (BOTH/POSITIVE/NEGATIVE). If None, defaults to ColorSelection.BOTH.
width, heightint, optional: Canvas dimensions for the generated renderer. Default is 800.
ambientfloat, optional: Ambient lighting strength passed to the Three.js shader. Default is 0.1.

Returns:

ipywidgets.VBox: A widget containing the pythreejs Renderer and a small info panel.

Raises:

ValueError, FileNotFoundError: Errors from prepare_geometry() are propagated (for example shape mismatches between overlay and mesh vertex count).

Examples

In a Jupyter notebook:

from whippersnappy import plot3d
from IPython.display import display

# FreeSurfer surface
viewer = plot3d('lh.white', overlay='lh.thickness', bg_map='lh.curv')
display(viewer)

# Any triangular mesh via OFF / VTK / PLY
viewer = plot3d('mesh.off', overlay='values.mgh')
display(viewer)

# Array inputs
import numpy as np
v = np.random.randn(500, 3).astype(np.float32)
f = np.zeros((1, 3), dtype=np.uint32)
viewer = plot3d((v, f))
display(viewer)

whippersnappy.plot3d.create_threejs_mesh_with_custom_shaders(vertices, faces, colors, normals, ambient=0.1)[source]¶

Create a pythreejs.Mesh using custom shader material and buffers.

The function builds a BufferGeometry with position, color and normal attributes, attaches an index buffer, and creates a ShaderMaterial using the WebGL shader snippets returned by get_webgl_shaders().

Parameters:

verticesnumpy.ndarray: Array of shape (N, 3) with vertex positions (float32).
facesnumpy.ndarray: Integer face index array shape (M, 3) or flattened (3*M,) dtype uint32.
colorsnumpy.ndarray: Array of shape (N, 3) with per-vertex RGB colors (float32).
normalsnumpy.ndarray: Array of shape (N, 3) with per-vertex normals (float32).
ambientfloat, optional, default 0.1: Ambient lighting strength for the shader (passed to Three.js uniform).

Returns:

pythreejs.Mesh: Mesh object ready to be inserted into a pythreejs.Scene.