3.1. Main Optical Classes

3.1.1. Optical Rays

class raysect.optical.ray.Ray

Bases: 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.

>>> from raysect.core import Point3D, Vector3D
>>> from raysect.optical import World, Ray
>>>
>>> world = World()
>>>
>>> ray = Ray(origin=Point3D(0, 0, -5),
>>>           direction=Vector3D(0, 0, 1),
>>>           min_wavelength=375,
>>>           max_wavelength=785,
>>>           bins=100)
>>>
>>> spectrum = ray.trace(world)
>>> spectrum
<raysect.optical.spectrum.Spectrum at 0x7f5b08b6e048>
bins

Number of spectral bins across wavelength range.

Return type:

int

copy(origin=None, direction=None)

Obtain a new Ray object with the same configuration settings.

Parameters:

  • origin (Point3D) – New Ray’s origin position.

  • direction (Vector3D) – New Ray’s direction.

Return type:

Ray

>>> from raysect.core import Point3D, Vector3D
>>> from raysect.optical import Ray
>>>
>>> ray = Ray(origin=Point3D(0, 0, -5),
>>>           direction=Vector3D(0, 0, 1),
>>>           min_wavelength=375,
>>>           max_wavelength=785,
>>>           bins=100)
>>>
>>> ray.copy()
Ray(Point3D(0.0, 0.0, -5.0), Vector3D(0.0, 0.0, 1.0), inf)
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

>>> from raysect.core import Point3D, Vector3D
>>> from raysect.optical import Ray
>>>
>>> ray = Ray(origin=Point3D(0, 0, -5),
>>>           direction=Vector3D(0, 0, 1),
>>>           min_wavelength=375,
>>>           max_wavelength=785,
>>>           bins=100)
>>>
>>> ray.new_spectrum()
<raysect.optical.spectrum.Spectrum at 0x7f5b08b6e1b0>
sample(world, count)

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:

Spectrum

>>> from raysect.core import Point3D, Vector3D
>>> from raysect.optical import World, Ray
>>>
>>> world = World()
>>>
>>> ray = Ray(origin=Point3D(0, 0, -5),
>>>           direction=Vector3D(0, 0, 1),
>>>           min_wavelength=375,
>>>           max_wavelength=785,
>>>           bins=100)
>>>
>>> ray.sample(world, 10)
<raysect.optical.spectrum.Spectrum at 0x7f5b08b6e318>
spawn_daughter(origin, direction)

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:

  • origin (Point3D) – A Point3D defining the ray origin.

  • direction (Vector3D) – A vector defining the ray direction.

Returns:

A daughter Ray object.

Return type:

Ray

trace(world, keep_alive=False)

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:

Spectrum

>>> from raysect.core import Point3D, Vector3D
>>> from raysect.optical import World, Ray
>>>
>>> world = World()
>>>
>>> ray = Ray(origin=Point3D(0, 0, -5),
>>>           direction=Vector3D(0, 0, 1),
>>>           min_wavelength=375,
>>>           max_wavelength=785,
>>>           bins=100)
>>>
>>> spectrum = ray.trace(world)
>>> spectrum
<raysect.optical.spectrum.Spectrum at 0x7f5b08b6e048>
wavelength_range

Upper and lower wavelength range.

Return type:

tuple

class raysect.optical.loggingray.LoggingRay

Bases: Ray

LoggingRay is a subclass of Ray that provides additional logging functionality.

A LoggingRay records all intersections it encounters during its path through the scene.

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.

Variables:

  • log (list[Intersection]) – List of intersections encountered by the ray.

  • path_vertices (list[Point3D]) – List of vertices defining the ray’s path.

>>> from raysect.core import Point3D, Vector3D
>>> from raysect.primitive import Box
>>> from raysect.optical import World
>>> from raysect.optical.material import NullMaterial
>>> from raysect.optical.loggingray import LoggingRay
>>>
>>> world = World()
>>> box = Box(Point3D(-1, -1, 0), Point3D(1, 1, 1),
>>>           material=NullMaterial(), parent=world)
>>>
>>> ray = LoggingRay(origin=Point3D(0, 0, -5),
>>>                  direction=Vector3D(0, 0, 1))
>>>
>>> ray.trace(world)
>>> ray.log
[Intersection(...), Intersection(...)]
>>>
>>> ray.path_vertices
[Point3D(0.0, 0.0, -5.0), Point3D(0.0, 0.0, 0.0), Point3D(0.0, 0.0, 1.0)]
copy(origin=None, direction=None)

Obtain a new LoggingRay object with the same configuration settings.

Parameters:

  • origin (Point3D) – New Ray’s origin position.

  • direction (Vector3D) – New Ray’s direction.

Return type:

LoggingRay

path_vertices

List of vertices defining the ray’s path.

The list includes the ray’s origin and all intersection points along its path.

Return type:

list[Point3D]

>>> ray = LoggingRay(Point3D(0, 0, 0), Vector3D(0, 0, 1))
>>> ray.path_vertices
[Point3D(0, 0, 0), Point3D(...), ... ]
spawn_daughter(origin, direction)

Obtain a new LoggingRay object with the same configuration settings.

Parameters:

  • origin (Point3D) – New Ray’s origin position.

  • direction (Vector3D) – New Ray’s direction.

Return type:

LoggingRay

trace(world, keep_alive=False)

Traces a single ray path through the world.

This method is responsible for tracing the ray through the scene, handling all interactions with the environment.

Parameters:

  • world (World) – World object defining the scene.

  • keep_alive (bool) – If true, disables Russian roulette termination of the ray.

Returns:

A Spectrum object.

Return type:

Spectrum

>>> world = World()
>>> ray = LoggingRay(origin=Point3D(0, 0, -5),
>>>                  direction=Vector3D(0, 0, 1))
>>> spectrum = ray.trace(world)

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 sub-classes exist to simplify SpectralFunction development.

see also: NumericallyIntegratedSF, InterpolatedSF, ConstantSF, Spectrum

average(min_wavelength, max_wavelength)

Average radiance over the requested spectral range (W/m^2/sr/nm).

Virtual method, to be implemented in child classes.

Parameters:

  • min_wavelength (float) – lower wavelength for calculation

  • max_wavelength (float) – upper wavelength for calculation

Return type:

float

>>> spectrum = ray.trace(world)
>>> spectrum.average(400, 700)
1.095030870970234
evaluate(wavelength)

Evaluate the spectral function f(wavelength)

Parameters:

wavelength (float) – Wavelength in nanometers.

Return type:

float

integrate(min_wavelength, max_wavelength)

Calculates the integrated radiance over the specified spectral range.

Virtual method, to be implemented in child classes.

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

>>> spectrum = ray.trace(world)
>>> spectrum.integrate(400, 700)
328.50926129107023
sample(min_wavelength, max_wavelength, bins)

Re-sample 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

>>> spectrum
<raysect.optical.spectrum.Spectrum at 0x7f56c22bd8b8>
>>> spectrum.min_wavelength, spectrum.max_wavelength
(375.0, 785.0)
>>> sub_spectrum = spectrum.sample(450, 550, 100)
class raysect.optical.spectrum.Spectrum

Bases: 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

>>> from raysect.optical import Spectrum
>>>
>>> spectrum = Spectrum(400, 720, 250)
clear()

Resets the sample values in the spectrum to zero.

copy()

Returns a copy of the spectrum.

Return type:

Spectrum

is_compatible(min_wavelength, max_wavelength, bins)

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

>>> spectrum = ray.trace(world)
>>> spectrum.is_zero()
False
new_spectrum()

Returns a new Spectrum compatible with the same spectral settings.

Return type:

Spectrum

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

>>> spectrum = ray.trace(world)
>>> spectrum.to_photons()
array([2.30744985e+17, 3.12842916e+17, ...])
total()

Calculates the total radiance integrated over the whole spectral range.

Returns radiance in W/m^2/str

Return type:

float

>>> spectrum = ray.trace(world)
>>> spectrum.total()
416.6978223103715
wavelengths

Wavelength array in nm

Return type:

ndarray

class raysect.optical.spectralfunction.NumericallyIntegratedSF

Bases: SpectralFunction

Numerically integrates a supplied function.

This abstract class provides an implementation of the integrate method that numerically integrates a supplied function (typically a non-integrable analytical function). The function to numerically integrate is supplied by sub-classing 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.

class raysect.optical.spectralfunction.InterpolatedSF

Bases: 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.

>>> from raysect.optical import InterpolatedSF
>>>
>>> # defining a set of spectral filters
>>> filter_red = InterpolatedSF([100, 650, 660, 670, 680, 800], [0, 0, 1, 1, 0, 0])
>>> filter_green = InterpolatedSF([100, 530, 540, 550, 560, 800], [0, 0, 1, 1, 0, 0])
>>> filter_blue = InterpolatedSF([100, 480, 490, 500, 510, 800], [0, 0, 1, 1, 0, 0])
class raysect.optical.spectralfunction.ConstantSF

Bases: SpectralFunction

Constant value spectral function

Parameters:

value (float) – Constant radiance value

>>> from raysect.optical import ConstantSF
>>>
>>> unity_spectral_function = ConstantSF(1.0)
raysect.optical.spectrum.photon_energy(wavelength)

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 375-785 nm

raysect.optical.colour.resample_ciexyz(min_wavelength, max_wavelength, bins)

Pre-calculates 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:

memoryview

raysect.optical.colour.spectrum_to_ciexyz(spectrum, resampled_xyz=None)

Calculates a tuple of CIE X, Y, Z values from an input spectrum

Parameters:

  • spectrum (Spectrum) – Spectrum to process

  • resampled_xyz (memoryview) – Pre-calculated XYZ sensitivity curves optimised for this spectral range (default=None).

Return type:

tuple

raysect.optical.colour.ciexyy_to_ciexyz(cx, cy, y)

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(x, y, z)

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 61966-2-1:1999. For more information see Wikipedia.

raysect.optical.colour.ciexyz_to_srgb(x, y, z)

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(r, g, b)

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

Bases: World

The root node of the optical scene-graph.

Inherits a lot of functionality and attributes from the core World object.

The world node tracks all primitives and observers in the world. It maintains acceleration structures to speed up the ray-tracing calculations. The particular acceleration algorithm used is selectable. The default acceleration structure is a kd-tree.

Parameters:

name – A string defining the node name.

build_importance(force=False)

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 scene-graph have an importance weighting.

Return type:

bool

important_direction_pdf(origin, direction)

Calculates the value of the PDF for the specified sample point and direction.

Parameters:

  • origin (Point3D) – The point from which to sample.

  • direction (Vector3D) – The sample direction.

Return type:

float

important_direction_sample(origin)

Get a sample direction of an important primitive.

Parameters:

origin (Point3D) – The point from which to sample.

Returns:

The vector along which to sample.

Return type:

Vector3D