ValueSpec

Contents

ValueSpec#

class braintools.visualize.morphology.ValueSpec(values, cmap='viridis', vmin=None, vmax=None, norm=None, label=None, unit_label=None, show_colorbar=True, space=None)[source]#

Styling parameters for a color-by-values overlay.

Parameters:
  • values (ArrayLike) –

    Per-element scalar array. The number of elements is interpreted against the morphology:

    • n_branches — one scalar per branch (the whole branch is shaded with that single colour);

    • total segment count — one scalar per segment (matplotlib LineCollection / PolyCollection uses the corresponding per-segment colour);

    • total centerline-point count (segments + branches) — one scalar per polyline point (used directly as polydata.point_data).

    Values may carry brainunit units; the units are used to generate a default colourbar label when unit_label is unset. When several interpretations have the same length the first one listed wins, unless space names one explicitly.

  • cmap (str) – Matplotlib colormap name, forwarded to matplotlib.cm.ScalarMappable and PyVista add_mesh.

  • vmin (float | None) – Fixed colour-scale bounds. When either is None the missing bound is derived from the data range.

  • vmax (float | None) – Fixed colour-scale bounds. When either is None the missing bound is derived from the data range.

  • norm (Any | None) – Optional matplotlib Normalize-compatible object. Takes precedence over vmin/vmax for the 2D backend.

  • label (str | None) – Colourbar title. When None no title is drawn.

  • unit_label (str | None) – Optional unit string appended to label on the colourbar.

  • show_colorbar (bool) – Whether to render a colourbar alongside the scene (matplotlib only; PyVista always draws its own scalar bar when scalars are present).

  • space (str | None) – Explicit value space. None (default) infers it from the length as listed under values; an explicit space is checked against the morphology when the plot is built.

Raises:

ValueError – If space is not one of the morphology value spaces. Per-CV or per-solver-node arrays belong to plot_topology_graph(), or must be projected onto the morphology by the simulator first.