3.1. Main Optical Classes¶
3.1.1. Optical Rays¶

class
raysect.optical.ray.
Ray
¶ Bases:
raysect.core.ray.Ray
Optical Ray class for optical applications, inherits from core Ray class.
Provides the trace(world) method.
Parameters:  origin (Point3D) – Point defining ray’s origin (default=Point3D(0, 0, 0))
 direction (Vector3D) – Vector defining ray’s direction (default=Vector3D(0, 0, 1))
 min_wavelength (float) – Lower wavelength bound for observed spectrum
 max_wavelength (float) – Upper wavelength bound for observed spectrum
 bins (int) – Number of samples to use over the spectral range
 max_distance (float) – The terminating distance of the ray
 extinction_prob (float) – Probability of path extinction at every material surface interaction (default=0.1)
 extinction_min_depth (int) – Minimum number of paths before triggering extinction probability (default=3)
 max_depth (int) – Maximum number of material interactions before terminating ray trajectory.
 importance_sampling (bool) – Toggles use of importance sampling for important primitives. See help documentation on importance sampling, (default=True).
 important_path_weight (float) – Weight to use for important paths when using importance sampling.

bins
¶ Number of spectral bins across wavelength range.
Return type: int

copy
()¶ Obtain a new Ray object with the same configuration settings.
Parameters: Return type:

extinction_min_depth
¶ Minimum number of paths before triggering extinction probability.
Return type: int

extinction_prob
¶ Probability of path extinction at every material surface interaction.
Return type: float

important_path_weight
¶ Weight to use for important paths when using importance sampling.
Return type: float

max_depth
¶ Maximum number of material interactions before terminating ray trajectory.
Return type: int

max_wavelength
¶ Upper bound on wavelength range.
Return type: float

min_wavelength
¶ Lower bound on wavelength range.
Return type: float

new_spectrum
()¶ Returns a new Spectrum compatible with the ray spectral settings.
Return type: Spectrum

sample
()¶ Samples the radiance directed along the ray direction.
This methods calls trace repeatedly to obtain a statistical sample of the radiance directed along the ray direction from the world. The count parameter specifies the number of samples to obtain. The mean spectrum accumulated from these samples is returned.
Parameters:  world (World) – World object defining the scene.
 count (int) – Number of samples to take.
Returns: The accumulated spectrum collected by the ray.
Return type:

spawn_daughter
()¶ Spawns a new daughter of the ray.
A daughter ray has the same spectral configuration as the source ray, however the ray depth is increased by 1.
Parameters: Returns: A daughter Ray object.
Return type:

trace
()¶ Traces a single ray path through the world.
Parameters:  world (World) – World object defining the scene.
 keep_alive (bool) – If true, disables Russian roulette termination of the ray.
Returns: The resulting Spectrum object collected by the ray.
Return type:

wavelength_range
¶ Upper and lower wavelength range.
Return type: tuple
3.1.2. Spectral Functions¶

class
raysect.optical.spectralfunction.
SpectralFunction
¶ SpectralFunction abstract base class.
A common interface for representing optical properties that are a function of wavelength. It provides methods for sampling, integrating and averaging a spectral function over specified wavelength ranges. The optical package uses SpectralFunctions to represent a number of different wavelength dependent optical properties, for example emission spectra, refractive indices and attenuation curves.
Deriving classes must implement the integrate method.
It is also recommended that subclasses implement __call__(). This should accept a single argument  wavelength  and return a single sample of the function at that wavelength. The units of wavelength are nanometers.
A number of utility subclasses exist to simplify SpectralFunction development.
see also: NumericallyIntegratedSF, InterpolatedSF, ConstantSF, Spectrum

average
()¶ Average radiance over the requested spectral range (W/m^2/sr/nm).
Parameters:  min_wavelength (float) – lower wavelength for calculation
 max_wavelength (float) – upper wavelength for calculation
Return type: float

sample
()¶ Resample the spectral function with a new wavelength range and resolution.
Parameters:  min_wavelength (float) – lower wavelength for calculation
 max_wavelength (float) – upper wavelength for calculation
 bins (int) – The number of spectral bins
Return type: ndarray


class
raysect.optical.spectrum.
Spectrum
¶ Bases:
raysect.optical.spectralfunction.SpectralFunction
A class for working with spectra.
Describes the distribution of light at each wavelength in units of radiance (W/m^2/str/nm). Spectral samples are regularly spaced over the wavelength range and lie in the centre of the wavelength bins.
Parameters:  min_wavelength (float) – Lower wavelength bound for this spectrum
 max_wavelength (float) – Upper wavelength bound for this spectrum
 bins (int) – Number of samples to use over the spectral range

average
()¶ Finds the average number of spectral samples over the specified wavelength range.
Parameters:  min_wavelength (float) – The minimum wavelength in nanometers
 max_wavelength (float) – The maximum wavelength in nanometers
Returns: Average radiance in W/m^2/str/nm
Return type: float

clear
()¶ Resets the sample values in the spectrum to zero.

integrate
()¶ Calculates the integrated radiance over the specified spectral range.
Parameters:  min_wavelength (float) – The minimum wavelength in nanometers
 max_wavelength (float) – The maximum wavelength in nanometers
Returns: Integrated radiance in W/m^2/str
Return type: float

is_compatible
()¶ Returns True if the stored samples are consistent with the specified wavelength range and sample size.
Parameters:  min_wavelength (float) – The minimum wavelength in nanometers
 max_wavelength (float) – The maximum wavelength in nanometers
 bins (int) – The number of bins.
Returns: True if the samples are compatible with the range/samples, False otherwise.
Return type: boolean

is_zero
()¶ Can be used to determine if all the samples are zero.
True if the spectrum is zero, False otherwise.
Return type: bool

new_spectrum
()¶ Returns a new Spectrum compatible with the same spectral settings.
Return type: Spectrum

sample
()¶ Resample this spectrum over a new spectral range.
Parameters:  min_wavelength (float) – The minimum wavelength in nanometers
 max_wavelength (float) – The maximum wavelength in nanometers
 bins (int) – The number of spectral bins.
Return type: ndarray

to_photons
()¶ Converts the spectrum sample array from radiance W/m^2/str/nm to Photons/s/m^2/str/nm and returns the data in a numpy array.
Return type: ndarray

total
()¶ Calculates the total radiance integrated over the whole spectral range.
Returns radiance in W/m^2/str
Return type: float

wavelengths
¶ Wavelength array in nm
Return type: ndarray

class
raysect.optical.spectralfunction.
NumericallyIntegratedSF
¶ Bases:
raysect.optical.spectralfunction.SpectralFunction
Numerically integrates a supplied function.
This abstract class provides an implementation of the integrate method that numerically integrates a supplied function (typically a nonintegrable analytical function). The function to numerically integrate is supplied by subclassing this class and implementing the function() method.
The function is numerically sampled at regular intervals. A sampling resolution may be specified in the class constructor (default: 1 sample/nm).
Parameters: sample_resolution (double) – The numerical sampling resolution in nanometers. 
function
()¶ Function to numerically integrate.
This is a virtual method and must be implemented through subclassing.
Parameters: wavelength (double) – Wavelength in nanometers. Returns: Function value at the specified wavelength.

integrate
()¶ Calculates the integrated radiance over the specified spectral range.
Parameters:  min_wavelength (float) – The minimum wavelength in nanometers
 max_wavelength (float) – The maximum wavelength in nanometers
Returns: Integrated radiance in W/m^2/str
Return type: float


class
raysect.optical.spectralfunction.
InterpolatedSF
¶ Bases:
raysect.optical.spectralfunction.SpectralFunction
Linearly interpolated spectral function.
Spectral function defined by samples of regular or irregular spacing, ends are extrapolated. You must set the ends to zero if you want the function to go to zero at the edges!
wavelengths and samples will be sorted during initialisation.
If normalise is set to True the data is rescaled so the integrated area of the spectral function over the full range of the input data is normalised to 1.0.
Parameters:  wavelengths (object) – 1D array of wavelengths in nanometers.
 samples (object) – 1D array of spectral samples.
 normalise (bool) – True/false toggle for whether to normalise the spectral function so its integral equals 1.

integrate
()¶ Calculates the integrated radiance over the specified spectral range.
Parameters:  min_wavelength (float) – The minimum wavelength in nanometers
 max_wavelength (float) – The maximum wavelength in nanometers
Returns: Integrated radiance in W/m^2/str
Return type: float

class
raysect.optical.spectralfunction.
ConstantSF
¶ Bases:
raysect.optical.spectralfunction.SpectralFunction
Constant value spectral function
Parameters: value (float) – Constant radiance value 
average
()¶ Average radiance over the requested spectral range (W/m^2/sr/nm).
Parameters:  min_wavelength (float) – lower wavelength for calculation
 max_wavelength (float) – upper wavelength for calculation
Return type: float

integrate
()¶ Calculates the integrated radiance over the specified spectral range.
Parameters:  min_wavelength (float) – The minimum wavelength in nanometers
 max_wavelength (float) – The maximum wavelength in nanometers
Returns: Integrated radiance in W/m^2/str
Return type: float

sample
()¶ Resample the spectral function with a new wavelength range and resolution.
Parameters:  min_wavelength (float) – lower wavelength for calculation
 max_wavelength (float) – upper wavelength for calculation
 bins (int) – The number of spectral bins
Return type: ndarray


raysect.optical.spectrum.
photon_energy
()¶ Returns the energy of a photon with the specified wavelength.
Parameters: wavelength (float) – Photon wavelength in nanometers. Returns: Photon energy in Joules. Return type: float
3.1.3. Colours¶
The CIE 1931 colour spaces define quantitatively the link between pure physical colours (i.e. wavelengths in the visible spectrum) and human perceivable colours. The mathematical relationships between the spectrum and perceivable colours are based on the sensitivity curves for the three different cone cells in the human eye. Raysect implements three X, Y, Z normalised spectral functions from the CIE 1931 Standard Colorimetric Observer. For more information see Wikipedia.

raysect.optical.colour.
ciexyz_x
¶ X spectral function from CIE 1931 Standard Colorimetric Observer (normalised)

raysect.optical.colour.
ciexyz_y
¶ Y spectral function from CIE 1931 Standard Colorimetric Observer (normalised)

raysect.optical.colour.
ciexyz_z
¶ Z spectral function from CIE 1931 Standard Colorimetric Observer (normalised)

raysect.optical.colour.
d65_white
¶ CIE D65 standard illuminant, normalised to 1.0 over visual range 375785 nm

raysect.optical.colour.
resample_ciexyz
()¶ Precalculates samples of XYZ sensitivity curves over desired spectral range.
Returns ndarray of shape [N, 3] where the last dimension (0, 1, 2) corresponds to (X, Y, Z).
Parameters:  min_wavelength (float) – Lower wavelength bound on spectrum
 max_wavelength (float) – Upper wavelength bound on spectrum
 bins (int) – Number of spectral bins in spectrum
Return type: ndarray

raysect.optical.colour.
spectrum_to_ciexyz
()¶ Calculates a tuple of CIE X, Y, Z values from an input spectrum
Parameters:  spectrum (Spectrum) – Spectrum to process
 resampled_xyz (ndarray) – Precalculated XYZ sensitivity curves optimised for this spectral range (default=None).
Return type: tuple

raysect.optical.colour.
ciexyy_to_ciexyz
()¶ Performs conversion from CIE xyY to CIE XYZ colour space
Returns a tuple of (X, Y, Z)
Parameters:  cx (float) – chromaticity x
 cy (float) – chromaticity y
 y (float) – tristimulus Y
Return type: tuple

raysect.optical.colour.
ciexyz_to_ciexyy
()¶ Performs conversion from CIE XYZ to CIE xyY colour space
Returns a tuple of (cx, cy, Y)
Parameters:  x (float) – tristimulus X
 y (float) – tristimulus y
 z (float) – tristimulus Z
Return type: tuple
Raysect also supports conversion of CIE colour space values to standard sRGB colour space as defined by HP and Microsoft in 1996 as per IEC 6196621:1999. For more information see Wikipedia.

raysect.optical.colour.
ciexyz_to_srgb
()¶ Convert CIE XYZ values to sRGB colour space.
x, y, z in range [0, 1] r, g, b in range [0, 1]
Parameters:  x (float) – tristimulus X
 y (float) – tristimulus y
 z (float) – tristimulus Z
Return type: tuple

raysect.optical.colour.
srgb_to_ciexyz
()¶ Convert sRGB values to CIE XYZ colour space.
r, g, b in range [0, 1] x, y, z in range [0, 1]
Parameters:  r (float) – Red value
 g (float) – Green value
 b (float) – Blue value
Return type: tuple
3.1.4. Optical Scenegraph¶

class
raysect.optical.scenegraph.world.
World
¶ The root node of the optical scenegraph.
The world node tracks all primitives and observers in the world. It maintains acceleration structures to speed up the raytracing calculations. The particular acceleration algorithm used is selectable. The default acceleration structure is a kdtree.
Parameters: name – A string defining the node name. 
build_importance
()¶ This method manually triggers a rebuild of the importance manager object.
If the importance manager object is already in a consistent state this method will do nothing unless the force keyword option is set to True.
Parameters: force (bint) – If set to True, forces rebuilding of acceleration structure.

has_important_primitives
()¶ Returns true if any primitives in this scenegraph have an importance weighting.
Return type: bool

important_direction_pdf
()¶ Calculates the value of the PDF for the specified sample point and direction.
Parameters: Return type: float


class
raysect.optical.scenegraph.world.
ImportanceManager
¶ Specialist class for managing sampling of important primitives.

has_primitives
()¶ Returns true if any primitives in this scenegraph have an importance weighting.
Return type: bool

pdf
()¶ Calculates the value of the PDF for the specified sample point and direction.
Parameters: Return type: float
