visualization.coloring.components#

Component Coloring Module

This module contains the strategies that choose the face color of drawn components (lens elements, mirrors and standalone surfaces).

Kramer Harrison, 2026

Classes

ComponentColorizer()

Strategy that picks the face color of each drawn component.

ComponentRef(kind, surface_indices)

Identifies one drawn component by kind and position in optic.surfaces.

PropertyColorizer(value_fn[, scale, kinds])

Colors components by a scalar property mapped through a ColorScale.

ThemeColorizer()

Keeps the theme's default color for every component.

UniformColorizer(color)

Gives every component the same color.
class ComponentColorizer[source]#

Strategy that picks the face color of each drawn component.

abstractmethod color_for(ref: ComponentRef) → tuple[float, float, float, float] | None[source]#

Return the face color of a component.

Parameters:

ref (ComponentRef) – The component to color.

Returns:

Color, or None to keep the default color.

Return type:

RGBA | None

prepare(optic: Optic, refs: Sequence[ComponentRef]) → None[source]#

Hook called once per draw, before any color_for() call.

Parameters:

  • optic (Optic) – The system being drawn.

  • refs (Sequence[ComponentRef]) – Every component that will be drawn.

property scale: ColorScale | None#

Resolved scale to show as a colorbar, if any.

Type:

ColorScale | None

class ComponentRef(kind: Literal['lens_element', 'mirror', 'surface'], surface_indices: tuple[int, ...])[source]#

Identifies one drawn component by kind and position in optic.surfaces.

Variables:

  • kind (str) – "lens_element", "mirror" or "surface". A lens element is one glass body bounded by surfaces (k, k + 1), so a cemented doublet holds two elements. A mirror or standalone surface (object, image, paraxial, phase) is (k,).

  • surface_indices (tuple[int, ...]) – Positions in optic.surfaces (0 is the object surface).

kind: Literal['lens_element', 'mirror', 'surface']#
surface_indices: tuple[int, ...]#
class PropertyColorizer(value_fn: Callable[[Optic, ComponentRef], float | None], scale: ColorScale | None = None, kinds: tuple[ComponentKind, ...] = ('lens_element',))[source]#

Colors components by a scalar property mapped through a ColorScale.

Parameters:

  • value_fn (Callable[[Optic, ComponentRef], float | None]) – Property of a component. Returning None or NaN keeps the default color. Values may be Python floats, NumPy scalars or Torch tensors.

  • scale (ColorScale) – Value-to-color mapping. Unset limits are taken from the evaluated values.

  • kinds (tuple[str, ...]) – Component kinds to color; other kinds keep the default color.

color_for(ref: ComponentRef) → tuple[float, float, float, float] | None[source]#

Return the face color of a component.

Parameters:

ref (ComponentRef) – The component to color.

Returns:

Color, or None to keep the default color.

Return type:

RGBA | None

prepare(optic: Optic, refs: Sequence[ComponentRef]) → None[source]#

Hook called once per draw, before any color_for() call.

Parameters:

  • optic (Optic) – The system being drawn.

  • refs (Sequence[ComponentRef]) – Every component that will be drawn.

property scale: ColorScale | None#

Resolved scale to show as a colorbar, if any.

Type:

ColorScale | None

class ThemeColorizer[source]#

Keeps the theme’s default color for every component.

color_for(ref: ComponentRef) → tuple[float, float, float, float] | None[source]#

Return the face color of a component.

Parameters:

ref (ComponentRef) – The component to color.

Returns:

Color, or None to keep the default color.

Return type:

RGBA | None

prepare(optic: Optic, refs: Sequence[ComponentRef]) → None#

Hook called once per draw, before any color_for() call.

Parameters:

  • optic (Optic) – The system being drawn.

  • refs (Sequence[ComponentRef]) – Every component that will be drawn.

property scale: ColorScale | None#

Resolved scale to show as a colorbar, if any.

Type:

ColorScale | None

class UniformColorizer(color: ColorType)[source]#

Gives every component the same color.

Parameters:

color (ColorType) – Anything matplotlib.colors.to_rgba accepts.

color_for(ref: ComponentRef) → tuple[float, float, float, float] | None[source]#

Return the face color of a component.

Parameters:

ref (ComponentRef) – The component to color.

Returns:

Color, or None to keep the default color.

Return type:

RGBA | None

prepare(optic: Optic, refs: Sequence[ComponentRef]) → None#

Hook called once per draw, before any color_for() call.

Parameters:

  • optic (Optic) – The system being drawn.

  • refs (Sequence[ComponentRef]) – Every component that will be drawn.

property scale: ColorScale | None#

Resolved scale to show as a colorbar, if any.

Type:

ColorScale | None