visualization.coloring.rays#

Ray Coloring Module

This module contains the strategies that choose the color of each drawn ray, and the data handed to them.

Kramer Harrison, 2026

Classes

RayBundleRef(field_index, field, ...)

Identifies one traced ray bundle.

RayColorizer()

Strategy that picks the color of each ray in a bundle.

TracedRays(x, y, z, intensity[, opd])

NumPy copies of the bundle just traced.

UniformRayColorizer(color)

Gives every ray the same color.
class RayBundleRef(field_index: int, field: tuple[float, float], wavelength_index: int, wavelength: float, num_fields: int, num_wavelengths: int, is_reference: bool)[source]#

Identifies one traced ray bundle.

Variables:

  • field_index (int) – Index among the drawn fields.

  • field (tuple[float, float]) – Field coordinates.

  • wavelength_index (int) – Index among the drawn wavelengths.

  • wavelength (float) – Wavelength in micrometers.

  • num_fields (int) – Number of drawn fields.

  • num_wavelengths (int) – Number of drawn wavelengths.

  • is_reference (bool) – True for chief/marginal reference rays.

field: tuple[float, float]#
field_index: int#
is_reference: bool#
num_fields: int#
num_wavelengths: int#
wavelength: float#
wavelength_index: int#
class RayColorizer[source]#

Strategy that picks the color of each ray in a bundle.

prepare(optic: Optic) → None[source]#

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

Parameters:

optic (Optic) – The system being drawn.

abstractmethod ray_colors(bundle: RayBundleRef, rays: TracedRays) → np.ndarray | None[source]#

Return per-ray colors for a bundle.

Parameters:
Returns:

RGBA array of shape (num_rays, 4), or None to keep the default bundle color. A row of NaN keeps the default color for that ray only.

Return type:

np.ndarray | None

property scale: ColorScale | None#

Resolved scale to show as a colorbar, if any.

Type:

ColorScale | None

class TracedRays(x: np.ndarray, y: np.ndarray, z: np.ndarray, intensity: np.ndarray, opd: np.ndarray | None = None)[source]#

NumPy copies of the bundle just traced.

Variables:

  • z (x, y,) – Global coordinates, shape (num_surfaces, num_rays).

  • intensity (np.ndarray) – Intensity at each surface, same shape.

  • opd (np.ndarray | None) – Optical path difference recorded at each surface, same shape, or None if the trace did not record it.

intensity: np.ndarray#
property num_rays: int#
opd: np.ndarray | None = None#
x: np.ndarray#
y: np.ndarray#
z: np.ndarray#
class UniformRayColorizer(color: ColorType)[source]#

Gives every ray the same color.

Parameters:

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

prepare(optic: Optic) → None#

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

Parameters:

optic (Optic) – The system being drawn.

ray_colors(bundle: RayBundleRef, rays: TracedRays) → np.ndarray | None[source]#

Return per-ray colors for a bundle.

Parameters:
Returns:

RGBA array of shape (num_rays, 4), or None to keep the default bundle color. A row of NaN keeps the default color for that ray only.

Return type:

np.ndarray | None

property scale: ColorScale | None#

Resolved scale to show as a colorbar, if any.

Type:

ColorScale | None