visualization.coloring.scale#

Color Scale Module

This module contains the ColorScale class, which maps scalar values to colors and produces the matching 2D colorbar (matplotlib) or 3D scalar bar (VTK).

Kramer Harrison, 2026

Functions

collect_scales(*colorizers)

Gather the resolved scales to display from colorizers, skipping absent ones.

Classes

ColorScale([cmap, vmin, vmax, log, label])

Maps scalar values to colors through a colormap.
class ColorScale(cmap: str | Colormap = 'viridis', vmin: float | None = None, vmax: float | None = None, log: bool = False, label: str = '')[source]#

Maps scalar values to colors through a colormap.

Limits that are left as None are filled from the data by resolved(). Limits set by the user are always kept.

Parameters:

  • cmap (str | Colormap) – Matplotlib colormap or its name. Defaults to "viridis".

  • vmin (float | None) – Value mapped to the low end of the colormap.

  • vmax (float | None) – Value mapped to the high end of the colormap.

  • log (bool) – If True, values are mapped on a base-10 logarithmic axis.

  • label (str) – Colorbar / scalar bar title.

add_colorbar(fig: Figure, ax: Axes) → Colorbar[source]#

Add a colorbar for this scale to a matplotlib figure.

Parameters:

  • fig (Figure) – Figure that receives the colorbar.

  • ax (Axes) – Axes the colorbar steals space from.

Returns:

The new colorbar.

Return type:

Colorbar

Raises:

ValueError – If the scale is not resolved.

cmap: str | Colormap = 'viridis'#
label: str = ''#
log: bool = False#
resolved(values: ArrayLike) → ColorScale[source]#

Return a copy whose missing limits are filled from values.

Parameters:

values (ArrayLike) – Scalar values the scale will be applied to.

Returns:

A scale with both limits set.

Return type:

ColorScale

Raises:

ValueError – If values has no finite entry, or if log is set and any finite value or user limit is not positive.

scalar_bar_actor() → vtkScalarBarActor[source]#

Build a VTK scalar bar for this scale.

Returns:

Actor titled with label. Position and size are left to the caller.

Return type:

vtkScalarBarActor

Raises:

ValueError – If the scale is not resolved.

to_rgba(values: ArrayLike) → np.ndarray[source]#

Map values to RGBA rows.

Parameters:

values (ArrayLike) – Scalar values; any shape is flattened.

Returns:

Array of shape (N, 4). Entries that are not finite (or, for a log scale, not positive) give a row of NaN, which callers treat as “use the default color”.

Return type:

np.ndarray

Raises:

ValueError – If the scale is not resolved.

vmax: float | None = None#
vmin: float | None = None#
collect_scales(*colorizers: _HasScale | None) → list[ColorScale][source]#

Gather the resolved scales to display from colorizers, skipping absent ones.

Parameters:

*colorizers – Component and/or ray colorizers, or None.

Returns:

The scales of the colorizers that expose one, in order.

Return type:

list[ColorScale]