Module spectrum

Optional module implementing the traversal of the human visual gamut.

This module reflects a somewhat unsatisfactory compromise between what’s possible in Rust and what’s necessary for PyO3. In particular, PyO3 requires monomorphic enums/structs with monomorphic method implementations and does not support generic anything. The PyO3 guide justifies this restriction with the fact that the Rust compiler produces monomorphic code only. While correct, PyO3 complicates matters significantly by not supporting trait methods, its #[pymethods] macro disallowing item-level macros, and its error checking ignoring #[cfg] attributes. The impact is noticeable: Whereas Rust code might get by with four different implementations of SpectralDistribution’s methods, Python integration necessitates another three.

The SpectralDistribution trait defines an interface for mapping a fixed, nanometer-aligned range of wavelengths at 1nm resolution to values. With wavelengths restricted to integral nanometers, the interfaces uses usize for their representation. Meanwhile, values are represented by an associated type, which is Float for illuminants and [Float; 3] for observers.

This module includes the following implementations of the trait:

• Observer is a table-driven implementation of SpectralDistribution<Value=[Float;3]>.
• TabularDistribution is a table-driven implementation of SpectralDistribution<Value=Float>.
• FixedDistribution is an implementation of SpectralDistribution<Value=Float> with a fixed value.
• Illuminant is an implementation of SpectralDistribution<Value=Float> that wraps a Box<dyn SpectralDistribution<Value=Float> + Send + Sync>.
• IlluminatedObserver is a table-driven implementation of SpectralDistribution<Value=[Float;3]>. Its data is the result of the per-wavelength multiplication of a SpectralDistribution<Value=Float> and a SpectralDistribution<Value=[Float;3]>, i.e., an illuminant and an observer.

To play nice with PyO3 and Python, Observer and IlluminatedObserver reimplement all but one trait method in their impl blocks. Illuminant does the same, but is only defined if the pyffi feature is enabled. It makes two different trait implementations appear as the same type type in Python and allows instances to be passed back to Rust.

Using the above trait implementations, this module exports the following concrete illuminants and observers, with data directly sourced from the CIE.

• CIE_ILLUMINANT_D50 approximates daylight near sunrise and sunset.
• CIE_ILLUMINANT_D65 approximates daylight around noon.
• CIE_ILLUMINANT_E has equal energy.
• CIE_OBSERVER_2DEG_1931 is the 1931 2º color matching function.
• CIE_OBSERVER_10DEG_1964 is the 1964 10º color matching function.

A submodule provides std_observer::x(), std_observer::y(), and std_observer::z() as analytical approximations for the 1931 2º observer. As such, all three functions accept floating point arguments for wavelengths.

Finally, SpectrumTraversal is an iterator for tracing the spectral locus or the human visual gamut. It is instantiated with IlluminatedObserver::visual_gamut. In Python, the constructor accepts &Illuminant and &Observer arguments only, which makes it monomorphic. While that is insufficient for generally overcoming PyO3’s prohibition against polymorphic anything, in this particular case it suffices because spectrum traversal’s constructors do not retain their inputs and instead keep the result of premultiplying the two spectral distributions. In other words, the rest of SpectrumTraversal’s implementation is strictly monomophic itself.

Modules

std_observer

Free-standing functions related to the CIE standard observer.

Structs

FixedDistribution

A spectral distribution with a fixed floating point value.

Illuminant

An illuminant at nanometer resolution. Python only!

IlluminatedObserver

An illuminated observer at nanometer resolution.

Observer

A standard observer at nanometer resolution.

SpectrumTraversal

An iterator tracing the visual gamut.

TabularDistribution

A table-driven spectral distribution over floating point values.

Constants

ONE_NANOMETER

A convenient constant for 1nm.

Statics

CIE_ILLUMINANT_D50

The CIE D50 standard illuminant at 1nm resolution.

CIE_ILLUMINANT_D65

The CIE D65 standard illuminant at 1nm resolution.

CIE_ILLUMINANT_E

The CIE standard illuminant E at 1nm resolution.

CIE_OBSERVER_2DEG_1931

The CIE 1931 2º standard observer at 1nm resolution.

CIE_OBSERVER_10DEG_1964

The CIE 1964 10º standard observer at 1nm resolution.

Traits

SpectralDistribution

A spectral distribution at nanometer resolution.