braincell.vis module

braincell.vis module#

braincell.vis is the visualization layer of BrainCell. It turns a Morphology (or any higher-level object that carries one) into static plots through matplotlib, interactive 3D through PyVista or Plotly, and publication-quality exports. The module is deliberately split into three layers:

  1. Scene builders (scene2d / scene3d) translate a morphology plus an overlay spec into backend-agnostic primitive tuples.

  2. Backends (backend_matplotlib, backend_pyvista, backend_plotly) render those primitives. Each backend advertises its supported scene kinds via a capability set.

  3. High-level entry points (plot2d, plot3d, plot_movie, plot_traces, morphometry plots) are the user-facing surface.

Optional dependencies (matplotlib, pyvista, plotly) are imported lazily inside the backend that uses them so the base install stays small.

Top-level plot entry points#

plot2d

plot3d

plot_movie

Render a time-varying colour-by-values animation over a morphology.

plot_traces

Plot time-series traces at selected morphology locations.

Morphometry and topology plots#

plot_dendrogram

Render a left-to-right dendrogram of the morphology.

plot_topology

Render a topology-only schematic (length-ignored) of the morphology.

plot_point_topology

Render a NodeTree as a topology-only graph.

plot_sholl

Plot a Sholl-intersection curve.

plot_branch_order_histogram

Bar chart of the number of branches per branch order.

Comparison helpers#

compare_morphologies

Render several morphologies side by side with a shared layout.

compare_values

Render the same morphology with multiple value overlays.

Interactivity hooks#

VisHooks

Bundle of interactive callbacks understood by the vis backends.

PickInfo

Payload delivered to a VisHooks callback.

Styling, themes and configuration#

theme

Temporarily override visualization defaults for the duration of a block.

publication_theme

Activate the PublicationTheme for the duration of a block.

configure_defaults

get_defaults

reset_defaults

set_defaults

save_figure

Save a vis backend return value to disk.

VisDefaults

PublicationTheme

Publication-quality styling preset for braincell.vis.

Scene primitives and overlays#

OverlaySpec

User-facing overlay request passed through plot2d / plot3d.

ValueSpec

Styling parameters for a color-by-values overlay.

Layout engine#

LayoutConfig

Configurable parameters for the 2D layout engine.

LayoutCache

Size-bounded LRU cache for layout-branch builder results.

Publication constants#

braincell.vis.PUBLICATION_BRANCH_TYPE_COLORS#

Publication-ready branch-type colour palette (RGB tuples keyed by branch type). High-contrast, print-friendly, and colour-blind safe; mirrors the keys of the default palette so the two presets can be diffed side by side.

braincell.vis.PUBLICATION_RC_PARAMS#

Matplotlib rcParams applied when the publication theme is active. Tuned for LaTeX-style output (serif font, thicker lines, no grid, tight margins) and 300 dpi raster export.