luxar.colormaps

Colormap resolution and built-in colormap registry.

Colormap (CLUT) support for Luxar.

Provides named colormaps for mapping scalar data to RGB colors. Built-in colormaps include microscopy linear ramps, perceptually uniform maps, and diverging maps. Custom colormaps can be provided as numpy arrays or resolved from matplotlib/colorcet if installed.

Usage:

from luxar.colormaps import resolve_colormap, BUILTIN_COLORMAP_NAMES

# Get a built-in colormap as (256, 3) uint8
lut = resolve_colormap("viridis")

# Use matplotlib/colorcet name (if installed)
lut = resolve_colormap("cividis")

# Use a custom numpy array
lut = resolve_colormap(my_array)  # shape (N, 3), resampled to 256
luxar.colormaps.resolve_colormap(colormap: str | NDArray[uint8] | NDArray[float32] | NDArray[float64]) → NDArray[uint8][source]

Resolve a colormap name or array to a (256, 3) uint8 LUT.

Parameters:

colormap (str or ndarray) –

  • String: tries built-in names, then matplotlib, then colorcet.

  • ndarray of shape (N, 3): resampled to (256, 3) uint8.

Returns:

Colormap LUT of shape (256, 3).

Return type:

NDArray[np.uint8]

Raises:

  • ValueError – If the name is not found in any source.

  • TypeError – If the input is not a string or array.

luxar.colormaps.scalars_to_colors(scalars: NDArray, colormap: str | NDArray, vmin: float | None = None, vmax: float | None = None) → NDArray[float32][source]

Map a scalar array to per-element RGB via a colormap LUT.

Replicates the viewer’s render-time normalisation so baked colours match what a scalar-driven node would display to within one LUT cell: normalise scalars to [0, 1] over [vmin, vmax], clamp, index a (256, 3) LUT with nearest rounding. (The viewer samples the LUT texture with linear filtering, so interior colours can differ by up to half a LUT cell — sub- perceptual; a constant gamma on the node is also not baked, see callers.)

Parameters:

  • scalars (array, shape (N,)) – Scalar values.

  • colormap (str or (M, 3) array) – Colormap name (built-in / matplotlib / colorcet) or an explicit LUT, resolved via luxar.colormaps.resolve_colormap().

  • vmin (float, optional) – Normalisation bounds. Default to scalars min/max — matching the scalar_data_range the writer records for render-time normalisation.

  • vmax (float, optional) – Normalisation bounds. Default to scalars min/max — matching the scalar_data_range the writer records for render-time normalisation.

Returns:

Per-element RGB. (Float, not uint8, to avoid a round-trip through the downstream integer-colour normalisation.)

Return type:

(N, 3) float32 in [0, 1]