snap

Snapshot (static rendering) API for WhipperSnapPy.

whippersnappy.snap.snap1(mesh, outpath=None, overlay=None, annot=None, bg_map=None, roi=None, view=ViewType.LEFT, viewmat=None, width=700, height=500, fthresh=None, fmax=None, caption=None, caption_x=None, caption_y=None, caption_scale=1, invert=False, colorbar=True, colorbar_x=None, colorbar_y=None, colorbar_scale=1, orientation=OrientationType.HORIZONTAL, color_mode=ColorSelection.BOTH, font_file=None, specular=True, brain_scale=1.5, ambient=0.0)

Render a single static snapshot of a surface mesh.

This function opens an OpenGL context, uploads the provided surface geometry and colors (overlay or annotation), renders the scene for a single view, captures the framebuffer, and returns a PIL Image. When outpath is provided the image is also written to disk.

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 where vertices is (N, 3) float and faces is (M, 3) int.

outpathstr or None, optional

When provided, the resulting image is saved to this path.

overlaystr, array_like, or None, optional

Overlay file path (.mgh or FreeSurfer morph) or a (N,) array of per-vertex scalar values. If None, coloring falls back to background shading / annotation.

annotstr, tuple, or None, optional

Path to a FreeSurfer .annot file or a (labels, ctab) / (labels, ctab, names) tuple with per-vertex labels.

bg_mapstr, array_like, or None, optional

Path to a per-vertex scalar file or a (N,) array whose sign determines light/dark background shading for non-overlay vertices.

roistr, array_like, or None, optional

Path to a FreeSurfer label file or a (N,) boolean array. Vertices with True receive overlay coloring; others fall back to bg_map shading.

viewViewType, optional

Which pre-defined view to render (left, right, front, …). Default is ViewType.LEFT.

viewmat4x4 matrix-like, optional

Optional view matrix to override the pre-defined view.

width, heightint, optional

Output canvas size in pixels. Defaults to (700×500).

fthresh, fmaxfloat or None, optional

Threshold and saturation values for overlay coloring.

caption, caption_x, caption_y, caption_scalestr/float, optional

Caption text and layout parameters.

invertbool, optional

Invert the color scale. Default is False.

colorbarbool, optional

If True, render a colorbar when an overlay is present. Default is True.

colorbar_x, colorbar_y, colorbar_scalefloat, optional

Colorbar positioning and scale. Scale defaults to 1.

orientationOrientationType, optional

Colorbar orientation (HORIZONTAL/VERTICAL). Default is OrientationType.HORIZONTAL.

color_modeColorSelection, optional

Which sign of overlay to color (POSITIVE/NEGATIVE/BOTH). Default is ColorSelection.BOTH.

font_filestr or None, optional

Path to a TTF font for captions; fallback to bundled font if None.

specularbool, optional

Enable specular highlights. Default is True.

brain_scalefloat, optional

Scale factor applied when preparing the geometry. Default is 1.5.

ambientfloat, optional

Ambient lighting strength for shader. Default is 0.0.

Returns:

PIL.Image.Image

Rendered snapshot as a PIL Image.

Raises:

RuntimeError

If the OpenGL/GLFW context cannot be initialized.

ValueError

If the overlay contains no values to display for the chosen color_mode.

FileNotFoundError

If a required file cannot be found.

Examples

FreeSurfer surface with overlay:

>>> from whippersnappy import snap1
>>> img = snap1('lh.white', overlay='lh.thickness',
...             bg_map='lh.curv', roi='lh.cortex.label')
>>> img.save('/tmp/lh.png')

Array inputs (any triangular mesh):

>>> import numpy as np
>>> v = np.random.randn(100, 3).astype(np.float32)
>>> f = np.array([[0, 1, 2]], dtype=np.uint32)
>>> img = snap1((v, f))

OFF / VTK / PLY file:

>>> img = snap1('mesh.off', overlay='values.mgh')

whippersnappy.snap.snap4(lh_overlay=None, rh_overlay=None, lh_annot=None, rh_annot=None, fthresh=None, fmax=None, sdir=None, caption=None, invert=False, roi_name='cortex.label', surfname=None, bg_map_name='curv', colorbar=True, outpath=None, font_file=None, specular=True, ambient=0.0, brain_scale=1.85, color_mode=ColorSelection.BOTH)

Render four snapshot views (left/right hemispheres, lateral/medial).

This convenience function renders four views (lateral/medial for each hemisphere), stitches them together into a single PIL Image and returns it (and saves it to outpath when provided). It is typically used to produce publication-ready overview figures composed from both hemispheres.

Parameters:

lh_overlay, rh_overlaystr, array_like, or None

Left/right hemisphere overlay — either a file path (FreeSurfer morph or .mgh) or a per-vertex scalar array. Typically provided as a pair for a coherent two-hemisphere color scale.

lh_annot, rh_annotstr, tuple, or None

Left/right hemisphere annotation — either a path to a .annot file or a (labels, ctab) / (labels, ctab, names) tuple. Cannot be combined with lh_overlay/rh_overlay.

fthresh, fmaxfloat or None

Threshold and saturation for overlay coloring. Auto-estimated when None.

sdirstr or None

Subject directory containing surf/ and label/ subdirectories. Falls back to $SUBJECTS_DIR when None.

captionstr or None

Caption string to place on the final image.

invertbool, optional

Invert color scale. Default is False.

roi_namestr, optional

Basename of the label file used to restrict overlay coloring (default 'cortex.label'). The full path is constructed as <sdir>/label/<hemi>.<roi_name>.

surfnamestr or None, optional

Surface basename to load (e.g. 'white'); auto-detected when None.

bg_map_namestr, optional

Basename of the curvature/morph file used for background shading (default 'curv'). The full path is constructed as <sdir>/surf/<hemi>.<bg_map_name>.

colorbarbool, optional

Whether to draw a colorbar on the composed image. Default is True.

outpathstr or None, optional

If provided, save composed image to this path.

font_filestr or None, optional

Path to a font to use for captions.

specularbool, optional

Enable/disable specular highlights in the renderer. Default is True.

ambientfloat, optional

Ambient lighting strength. Default is 0.

brain_scalefloat, optional

Scaling factor passed to geometry preparation. Default is 1.85.

color_modeColorSelection, optional

Which sign of overlay to color (POSITIVE/NEGATIVE/BOTH). Default is ColorSelection.BOTH.

Returns:

PIL.Image.Image

Composed image of the four views.

Raises:

ValueError

For invalid argument combinations or when required overlay values are absent.

FileNotFoundError

When required surface files are not found.

Examples

>>> from whippersnappy import snap4
>>> img = snap4(
...     lh_overlay='fsaverage/surf/lh.thickness',
...     rh_overlay='fsaverage/surf/rh.thickness',
...     sdir='./fsaverage'
... )
>>> img.save('/tmp/whippersnappy_overview.png')

whippersnappy.snap.snap_rotate(mesh, outpath, n_frames=72, fps=24, width=700, height=500, overlay=None, bg_map=None, annot=None, roi=None, fthresh=None, fmax=None, invert=False, specular=True, ambient=0.0, brain_scale=1.5, start_view=ViewType.LEFT, color_mode=ColorSelection.BOTH)

Render a rotating 360° video of a surface mesh.

Rotates the view around the vertical (Y) axis in n_frames equal steps, captures each frame via OpenGL, and encodes the result into a video file. An animated GIF can be produced by passing an outpath ending in .gif; in that case imageio-ffmpeg is not required.

The mesh can be any triangular surface — not just brain surfaces. Supported file formats: FreeSurfer binary surface, 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.

outpathstr

Destination file path. The extension controls the output format:

• .mp4 — H.264 MP4 (recommended, requires imageio-ffmpeg).

• .webm — VP9 WebM (requires imageio-ffmpeg).

• .gif — animated GIF (no ffmpeg required, but larger file).

n_framesint, optional

Number of frames for a full 360° rotation. Default is 72 (one frame every 5°).

fpsint, optional

Output frame rate in frames per second. Default is 24.

width, heightint, optional

Render resolution in pixels. Defaults are 700 and 500.

overlaystr, array_like, or None, optional

Per-vertex overlay file path or array (e.g. thickness).

bg_mapstr, array_like, or None, optional

Curvature/morph file path or array for background shading.

annotstr, tuple, or None, optional

FreeSurfer .annot file path or (labels, ctab) tuple.

roistr, array_like, or None, optional

Label file path or boolean array to restrict overlay coloring.

fthreshfloat or None, optional

Overlay threshold value.

fmaxfloat or None, optional

Overlay saturation value.

invertbool, optional

Invert the overlay color scale. Default is False.

specularbool, optional

Enable specular highlights. Default is True.

ambientfloat, optional

Ambient lighting strength. Default is 0.0.

brain_scalefloat, optional

Geometry scale factor. Default is 1.5.

start_viewViewType, optional

Pre-defined view to start the rotation from. Default is ViewType.LEFT.

color_modeColorSelection, optional

Which overlay sign to color (POSITIVE/NEGATIVE/BOTH). Default is ColorSelection.BOTH.

Returns:

str

The resolved outpath that was written.

Raises:

ImportError

If imageio or imageio-ffmpeg is not installed and a video format (.mp4, .webm) was requested.

RuntimeError

If the OpenGL context cannot be initialised.

ValueError

If the overlay contains no values for the chosen color mode.

Examples

>>> from whippersnappy import snap_rotate
>>> snap_rotate(
...     'fsaverage/surf/lh.white',
...     '/tmp/rotation.mp4',
...     overlay='fsaverage/surf/lh.thickness',
... )
'/tmp/rotation.mp4'