Command-Line Interfaces

whippersnap1

CLI entry point for single-mesh snapshot and rotation video via snap1/snap_rotate.

Renders any triangular surface mesh from a chosen viewpoint and saves it as a PNG image. Alternatively, pass --rotate to produce a full 360° rotation video (MP4, WebM, or GIF).

The mesh can be a FreeSurfer binary surface (e.g. lh.white), an ASCII OFF file (mesh.off), a legacy ASCII VTK PolyData file (mesh.vtk), or an ASCII PLY file (mesh.ply).

Usage:

# FreeSurfer surface — lateral view with thickness overlay
whippersnap1 --mesh <subject_dir>/surf/lh.white \
    --overlay <subject_dir>/surf/lh.thickness \
    --bg-map  <subject_dir>/surf/lh.curv \
    --roi     <subject_dir>/label/lh.cortex.label \
    --view left --fthresh 1.5 --fmax 4.0 \
    -o snap1.png

# OFF / VTK / PLY mesh with a numpy-saved overlay
whippersnap1 --mesh mesh.off --overlay values.mgh -o snap1.png
whippersnap1 --mesh mesh.vtk -o snap1.png
whippersnap1 --mesh mesh.ply --overlay values.mgh -o snap1.png

# 360° rotation video
whippersnap1 --mesh <subject_dir>/surf/lh.white \
    --overlay <subject_dir>/surf/lh.thickness \
    --rotate --rotate-frames 72 --rotate-fps 24 \
    -o rotation.mp4

# Parcellation annotation
whippersnap1 --mesh <subject_dir>/surf/lh.white \
    --annot <subject_dir>/label/lh.aparc.annot \
    --view left -o snap_annot.png

See whippersnap1 --help for the full list of options. For four-view batch rendering use whippersnap4. For the interactive GUI use whippersnap.

whippersnappy.cli.whippersnap1.run()[source]

Command-line entry point for single-view snapshot or rotation video.

Parses command-line arguments, validates them, and calls either whippersnappy.snap1() (static snapshot) or whippersnappy.snap_rotate() (360° rotation video) depending on whether --rotate is passed. All input is read from sys.argv via argparse.

Raises:
FileNotFoundError

If the mesh file or any overlay/annotation/label file cannot be found.

RuntimeError

If the OpenGL context cannot be initialised.

ValueError

For invalid argument combinations.

Notes

Snapshot options (default mode):

  • --mesh — path to any triangular surface mesh: FreeSurfer binary (e.g. lh.white), ASCII OFF (.off), legacy ASCII VTK PolyData (.vtk), or ASCII PLY (.ply).

  • --overlay — per-vertex scalar overlay (e.g. lh.thickness or a .mgh file).

  • --annot — FreeSurfer .annot parcellation file.

  • --roi — FreeSurfer label file defining vertices to include in overlay coloring.

  • --bg-map — per-vertex scalar file whose sign controls light/dark background shading.

  • --view — camera direction: left, right, front, back, top, bottom (default: left).

  • --fthresh / --fmax — overlay threshold and saturation values.

  • --invert — invert the color scale.

  • --no-colorbar — suppress the color bar.

  • --caption — text label placed on the image.

  • --width / --height — output resolution in pixels (default: 700×500).

  • -o / --output — output file path (default: temp .png).

Rotation video options (pass --rotate):

  • --rotate-frames — number of frames for one full rotation (default: 72).

  • --rotate-fps — output frame rate (default: 24).

  • --rotate-start-view — starting camera direction (default: left).

  • -o — output path; extension controls format: .mp4, .webm, or .gif (GIF requires no ffmpeg).

whippersnap4

CLI entry point for four-view batch rendering via snap4.

Renders left and right hemisphere surfaces in lateral and medial views, stitches them into a single image and writes it to disk.

Usage:

whippersnap4 -lh <lh_overlay> -rh <rh_overlay> -sd <subject_dir> -o out.png
whippersnap4 --lh_annot <lh.annot> --rh_annot <rh.annot> -sd <subject_dir>

See whippersnap4 --help for the full list of options. For the interactive GUI use whippersnap.

whippersnappy.cli.whippersnap4.run()[source]

Command-line entry point for WhipperSnapPy four-view batch rendering.

Parses command-line arguments, validates them, and calls whippersnappy.snap4() to produce a four-view composed image.

Raises:
ValueError

For invalid or mutually exclusive argument combinations.

RuntimeError

If the OpenGL context cannot be initialised.

FileNotFoundError

If required surface files cannot be found.

Notes

Required:

  • -sd / --sdir — subject directory containing surf/ and label/ subdirectories.

  • One of the following (not both):

    • -lh / --lh_overlay and -rh / --rh_overlay — per-vertex scalar overlay files for left and right hemispheres (e.g. lh.thickness).

    • --lh_annot and --rh_annot — FreeSurfer .annot parcellation files for left and right hemispheres.

Output:

  • -o / --output_path — output image path (default: temp .png).

Overlay appearance:

  • --fthresh / --fmax — threshold and saturation values (auto-estimated if not set).

  • --invert — invert the color scale.

  • --no-colorbar — suppress the color bar.

  • -c / --caption — text label placed on the figure.

Rendering:

  • -s / --surf_name — surface basename (e.g. white); auto-detected if not provided.

  • --diffuse — use diffuse-only shading (no specular highlights).

  • --scale — geometry scale factor (default: 1.85).

  • --ambient — ambient light strength (default: 0.0).

  • --font — path to a TTF font file for captions.

whippersnap

Interactive GUI viewer for WhipperSnapPy.

Opens a live OpenGL window for any triangular surface mesh together with a Qt-based configuration panel that allows adjusting overlay thresholds at runtime.

Two input modes are supported:

General mode — pass any mesh file directly:

whippersnap --mesh mesh.off --overlay values.mgh
whippersnap --mesh lh.white --overlay lh.thickness --bg-map lh.curv

FreeSurfer shortcut — pass a subject directory and hemisphere; all FreeSurfer paths are derived automatically:

whippersnap -sd <subject_dir> --hemi lh --overlay lh.thickness
whippersnap -sd <subject_dir> --hemi rh --annot rh.aparc.annot

See whippersnap --help for the full list of options. For non-interactive four-view batch rendering use whippersnap4. For single-view non-interactive snapshots use whippersnap1.

class whippersnappy.cli.whippersnap.ViewState(rotation=<factory>, pan=<factory>, zoom=0.4, last_mouse_pos=None, left_button_down=False, right_button_down=False, middle_button_down=False)[source]

Mutable view parameters for the interactive render loop.

All mouse/keyboard interaction updates this object; the view matrix is recomputed from it each frame via compute_view_matrix().

Attributes

rotation

(np.ndarray) 4×4 float32 rotation matrix (identity = no rotation applied).

pan

(np.ndarray) (x, y) pan offset in normalised screen-space units.

zoom

(float) Z-translation contribution to the transform matrix.

last_mouse_pos

(np.ndarray or None) Last recorded mouse position in pixels; None when no button held.

left_button_down

(bool) Whether the left mouse button is currently pressed.

right_button_down

(bool) Whether the right mouse button is currently pressed.

middle_button_down

(bool) Whether the middle mouse button is currently pressed.
whippersnappy.cli.whippersnap.arcball_vector(x, y, width, height)[source]

Map a 2-D screen pixel to a point on the unit arcball sphere.

Parameters:
x, yfloat

Mouse position in pixels.

width, heightint

Window dimensions in pixels.

Returns:
np.ndarray

Unit 3-vector on (or clamped to) the arcball sphere.

whippersnappy.cli.whippersnap.arcball_rotation_matrix(v1, v2)[source]

Return a 4×4 rotation matrix that rotates unit vector v1 to v2.

Uses Rodrigues’ rotation formula in pure numpy. Returns identity when v1 and v2 are coincident.

Parameters:
v1, v2np.ndarray

Unit 3-vectors on the arcball sphere.

Returns:
np.ndarray

4×4 float32 rotation matrix.

whippersnappy.cli.whippersnap.compute_view_matrix(view_state, base_view)[source]

Return the transform uniform for the current ViewState.

Packs transl * rotation * base_view matching the snap_rotate convention.

Parameters:
view_stateViewState

Current interactive view state.

base_viewnp.ndarray

Fixed 4×4 orientation preset from get_view_matrices().

Returns:
np.ndarray

4×4 float32 matrix for the transform shader uniform.

whippersnappy.cli.whippersnap.show_window(mesh, overlay=None, annot=None, bg_map=None, roi=None, invert=False, specular=True, view=ViewType.LEFT, app=None, config_window=None)[source]

Start a live interactive OpenGL+Qt window for viewing a triangular mesh.

On macOS both GLFW/Cocoa and Qt require the main thread. This function creates a GLFW window, registers GLFW input callbacks, then hands control to a QTimer-driven render loop so GLFW polling and Qt event processing share the main thread.

Parameters:
meshstr or tuple of (array_like, array_like)

Path to any mesh file or a (vertices, faces) array tuple.

overlaystr, array_like, or None, optional

Per-vertex scalar overlay.

annotstr, tuple, or None, optional

FreeSurfer .annot file or (labels, ctab[, names]) tuple.

bg_mapstr, array_like, or None, optional

Per-vertex scalar file or array for background shading.

roistr, array_like, or None, optional

FreeSurfer label file or boolean array masking overlay coloring.

invertbool, optional

Invert the overlay color mapping. Default is False.

specularbool, optional

Enable specular highlights. Default is True.

viewViewType, optional

Initial camera view direction. Default is ViewType.LEFT.

appQApplication

The already-created QApplication instance.

config_windowConfigWindow

The already-created Qt configuration panel.

Raises:
RuntimeError

If the GLFW window or OpenGL context could not be created.

Notes

Mouse and keyboard interaction:

  • Left-drag — arcball rotation (view-relative, no gimbal lock).

  • Right-drag / Middle-drag — pan in screen space.

  • Scroll wheel — zoom in/out.

  • Arrow keys — rotate in 3° increments (faster while held).

  • R / double-click — reset view to initial preset.

  • S — save snapshot (opens a file-save dialog).

  • Q / ESC — quit.

whippersnappy.cli.whippersnap.run()[source]

Command-line entry point for the WhipperSnapPy interactive GUI.

Parses command-line arguments, validates them, then spawns the OpenGL viewer thread and launches the PyQt6 configuration window in the main thread.

Two mutually exclusive input modes are supported:

General mode — supply a mesh file directly with --mesh. Works with FreeSurfer binary surfaces, OFF, VTK, and PLY files.

FreeSurfer shortcut — supply -sd/--sdir and --hemi; the surface, curvature, and cortex-label paths are all derived automatically from the subject directory.

Raises:
RuntimeError

If PyQt6 is not installed (pip install 'whippersnappy[gui]').

ValueError

For invalid or mutually exclusive argument combinations.

Notes

General mode (--mesh required):

  • --mesh — path to any triangular mesh file (FreeSurfer binary, .off, .vtk, .ply).

  • --overlay — per-vertex scalar overlay file path or .mgh.

  • --annot — FreeSurfer .annot file.

  • --bg-map — per-vertex scalar file for background shading.

  • --roi — FreeSurfer label file or boolean mask for overlay region.

FreeSurfer shortcut (-sd/--sdir + --hemi required):

  • -sd / --sdir — subject directory containing surf/ and label/ subdirectories.

  • --hemi — hemisphere to display: lh or rh.

  • -lh / --lh_overlay or -rh / --rh_overlay — overlay for the respective hemisphere (shorthand; equivalent to --overlay).

  • --annot — annotation file (full path).

  • -s / --surf_name — surface basename (e.g. white); auto-detected if not provided.

  • --curv-name — curvature basename (default: curv).

  • --label-name — cortex label basename (default: cortex.label).

Common options (both modes):

  • --fthresh — overlay threshold (default: 2.0); adjustable live in the GUI.

  • --fmax — overlay saturation (default: 4.0); adjustable live in the GUI.

  • --invert — invert the color scale.

  • --diffuse — use diffuse-only shading (no specular highlights).

  • --view — initial camera view (default: left).

Requires pip install 'whippersnappy[gui]'. For non-interactive batch rendering use whippersnap4 or whippersnap1.