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_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.