spectralbrain.viz.tracts3d#

Advanced 3D white-matter tractography visualization.

Library-native implementation of the neuro-tracts conventions: streamline rendering with direction-encoded (DEC) or scalar colouring, bundle-surface meshes with embedded scalar/spectral (HKS/WKS) overlays, glass-brain context, and multi-POV montages — all rendered offscreen with depth peeling and anti-aliasing, then composited into hybrid raster+vector publication panels.

Engine choice (mirrors neuro-tracts):

Colour policy: DEC RGB for orientation (x=L-R red, y=A-P green, z=I-S blue); perceptually-uniform sequential (Crameri batlow if cmcrameri present, else viridis) for FA/MD/HKS/density; diverging centred on zero for signed maps; robust 2-98% colour limits. Never jet/rainbow.

All heavy deps (FURY/DIPY, PyVista, nibabel, scikit-image, trimesh, cmcrameri) are imported lazily; the module imports cleanly without them and raises a clear message only when a path needs one.

Functions

add_glass_brain(plotter, brain_mask, affine, *)

Add a translucent glass-brain shell to a PyVista plotter for context.

compose_tract_panel(images, *[, titles, ...])

Composite rendered PNGs into a publication panel (hybrid raster+vector).

get_cmap([kind])

Perceptually-uniform colormap by role (sequential/diverging).

load_streamlines(path[, reference, to_space])

Load a .trk/.tck tractogram into world (RAS+ mm) coordinates.

mask_to_mesh(mask[, affine, level, ...])

Marching-cubes surface from a binary tract mask, mapped to world coords.

render_bundle_surface(vertices, faces, *[, ...])

Render a bundle surface mesh with an optional per-vertex scalar overlay.

render_streamlines(streamlines, *[, ...])

Render a streamline bundle offscreen (FURY) and snapshot to PNG.

robust_clim(values[, low, high, symmetric])

Robust colour limits from percentiles (optionally symmetric on zero).

spectral_overlay(vertices, faces[, kind, ...])

Compute an HKS/WKS per-vertex field on a bundle surface for overlay.

streamlines_multiview(streamlines, *[, ...])

Render one bundle from several canonical POVs and composite into a panel.
spectralbrain.viz.tracts3d.add_glass_brain(plotter, brain_mask, affine, *, opacity=0.12, color='#cccccc', level=0.5)[source]#

Add a translucent glass-brain shell to a PyVista plotter for context.

Parameters:
spectralbrain.viz.tracts3d.compose_tract_panel(images, *, titles=None, colorbar=None, ncols=None, panel_letters=True, out_path=None, dpi=300)[source]#

Composite rendered PNGs into a publication panel (hybrid raster+vector).

Parameters:

  • images (sequence of PNG paths)

  • titles (sequence of str, optional)

  • colorbar (dict, optional) – {"kind": "sequential"|"diverging", "clim": (lo, hi), "label": str} to draw a shared vector colorbar.

  • ncols (int, optional) – Columns (defaults to len(images) up to 4).

  • panel_letters (bool)

  • out_path (str | PathLike[str] | None)

  • dpi (int)

spectralbrain.viz.tracts3d.get_cmap(kind='sequential')[source]#

Perceptually-uniform colormap by role (sequential/diverging).

Parameters:

kind (str)

spectralbrain.viz.tracts3d.load_streamlines(path, reference=None, to_space='world')[source]#

Load a .trk/.tck tractogram into world (RAS+ mm) coordinates.

.tck (MRtrix) stores no affine and needs reference (a NIfTI). Returns (streamlines, affine).

Parameters:
spectralbrain.viz.tracts3d.mask_to_mesh(mask, affine=None, level=0.5, smooth_sigma=1.0, taubin_iter=25, raw=False)[source]#

Marching-cubes surface from a binary tract mask, mapped to world coords.

With raw=False (default) the surface is produced by the shared, open-surface-safe improvement pipeline (spectralbrain.io.meshing.volume_to_mesh() with closed=False): Gaussian field smoothing + Lewiner marching cubes + Taubin (shrink-free) smoothing, giving a clean surface suitable for spectral overlays. With raw=True a plain marching-cubes surface (no smoothing) is returned.

Bundle masks are open / branching, so closed=False is used: the surface is not forced watertight and components are not pruned. Returns (vertices, faces).

Parameters:
spectralbrain.viz.tracts3d.render_bundle_surface(vertices, faces, *, scalars=None, cmap=None, clim=None, symmetric=False, robust=True, view='oblique', bg='white', size=(1600, 1600), metallic=0.1, roughness=0.6, nan_color='#BDBDBD', out_path=None)[source]#

Render a bundle surface mesh with an optional per-vertex scalar overlay.

PyVista PBR render with depth peeling + SSAA. For signed maps (t, d, r) pass symmetric=True to centre a diverging colormap on zero. Returns the PNG.

Parameters:
Return type:

Path

spectralbrain.viz.tracts3d.render_streamlines(streamlines, *, color_by='orientation', scalars=None, tube=True, linewidth=0.4, cmap=None, clim=None, robust=True, view='oblique', n_max=20000, bg='white', size=(1600, 1600), out_path=None, random_state=0)[source]#

Render a streamline bundle offscreen (FURY) and snapshot to PNG.

Parameters:

  • streamlines (sequence of (N_i, 3) arrays)

  • color_by ({"orientation", "scalar"}) – "orientation" = DEC RGB (default); "scalar" colours each point by scalars with a perceptual colormap.

  • scalars (sequence of (N_i,) arrays, optional) – Per-point scalar values (required for color_by="scalar").

  • tube (bool) – Render as streamtubes (hero look) vs thin lines.

  • view (str) – Camera preset (see TRACT_VIEWS).

  • n_max (int) – Downsample whole-brain tractograms above this many streamlines.

  • linewidth (float)

  • cmap (Any)

  • clim (tuple | None)

  • robust (bool)

  • bg (str)

  • size (tuple[int, int])

  • out_path (str | PathLike[str] | None)

  • random_state (int)

Returns:

Path to the PNG.

Return type:

Path

spectralbrain.viz.tracts3d.robust_clim(values, low=2.0, high=98.0, symmetric=False)[source]#

Robust colour limits from percentiles (optionally symmetric on zero).

Parameters:
Return type:

tuple[float, float]

spectralbrain.viz.tracts3d.spectral_overlay(vertices, faces, kind='hks', n_eigen=100, t_index=30, laplacian_method='cotangent')[source]#

Compute an HKS/WKS per-vertex field on a bundle surface for overlay.

Uses SpectralBrain’s own LBO + descriptor machinery so the bundle surface is described with the same spectral vocabulary as cortical/hippocampal surfaces. The marching-cubes bundle surface is a clean 2-manifold, so the default cotangent Laplacian is appropriate; pass laplacian_method="robust" for non-manifold inputs (requires robust_laplacian). Returns a (V,) field.

Parameters:
Return type:

ndarray

spectralbrain.viz.tracts3d.streamlines_multiview(streamlines, *, views=('left', 'anterior', 'superior', 'oblique'), color_by='orientation', scalars=None, titles=None, colorbar=None, tube=True, bg='white', size=(1200, 1200), out_path=None, random_state=0)[source]#

Render one bundle from several canonical POVs and composite into a panel.

This is the multi-POV tract figure: each view is rendered offscreen, then all are assembled into a single hybrid raster+vector matplotlib figure with an optional shared colorbar. Returns (fig, png_paths).

Parameters: