3.2. Observers

Observers describe the geometry of how rays will sample a scene, such as where rays are generated on the image plane and their path through a camera before sampling the rest of the scene. They also act as a manager class controlling other important settings such as the sampling properties of the camera (how many samples to obtain per pixel) and the wavelength range of the camera response.

All observers are derrived from a common base class which describes the common properties of all observers and the overall observing workflow.

class raysect.optical.observer.base.observer._ObserverBase

Observer base class.

This is an abstract class and cannot be used for observing.

Parameters:
  • parent (Node) – The parent node in the scenegraph. Observers will only observe items in the same scenegraph as them.
  • transform (AffineMatrix3D) – Affine matrix describing the location and orientation of this observer in the world.
  • name (str) – User friendly name for this observer.
  • render_engine (object) – A workflow manager for controlling whether tasks will be executed in serial, parallel or on a cluster (default=MulticoreEngine()).
  • spectral_rays (int) – The number of smaller sub-spectrum rays the full spectrum will be divided into (default=1).
  • spectral_bins (int) – The number of spectral samples over the wavelength range (default=15).
  • min_wavelength (float) – Lower wavelength bound for sampled spectral range (default=375nm).
  • max_wavelength (float) – Upper wavelength bound for sampled spectral range (default=740nm).
  • ray_extinction_prob (float) – Probability of ray extinction after every material intersection (default=0.01).
  • ray_extinction_min_depth (int) – Minimum number of paths before russian roulette style ray extinction (default=3).
  • ray_max_depth (int) – Maximum number of Ray paths before terminating Ray (default=500).
  • ray_importance_sampling (bool) – Toggle importance sampling behaviour (default=True).
  • ray_important_path_weight (float) – Relative weight of important path sampling (default=0.2).
  • quiet (bool) – When True, suppresses the printing of observer performance statistics and completion (default=False).
max_wavelength

Upper wavelength bound for sampled spectral range.

Return type:float
min_wavelength

Lower wavelength bound for sampled spectral range.

Return type:float
observe()

Ask this Camera to Observe its world.

ray_extinction_min_depth

Minimum number of paths before russian roulette style ray extinction.

Return type:int
ray_extinction_prob

Probability of ray extinction after every material intersection.

Return type:float
ray_important_path_weight

Relative weight of important path sampling.

Return type:float
ray_max_depth

Maximum number of Ray paths before terminating Ray.

Return type:int
spectral_bins

The number of spectral samples over the wavelength range.

Return type:int
spectral_rays

The number of smaller sub-spectrum rays the full spectrum will be divided into.

This setting is important for scenes with dispersive elements such as glass prisms. This setting allows the parent spectrum to be divided into N smaller sub-regions that will be individually sampled. This allows rays with different active wavelength ranges to take different paths when passing through materials wit different refractive indexes.

Note that the number of spectral rays cannot be greater than the number of spectral bins.

Return type:int

3.2.1. 0D Observers

class raysect.optical.observer.base.observer.Observer0D

Bases: raysect.optical.observer.base.observer._ObserverBase

0D observer base class.

This is an abstract class and cannot be used for observing.

Parameters:
  • pipelines (list) – A list of pipelines that will process the resulting spectra from this observer.
  • pixel_samples (int) – Number of samples to generate per pixel with one call to observe() (default=1000).
  • samples_per_task (int) – Minimum number of samples to request per task (default=250).
  • kwargs**kwargs from _ObserverBase.
_generate_rays()

Generate a list of Rays that sample over the etendue of the pixel.

This is a virtual method to be implemented by derived classes.

Runs during the observe() loop to generate the rays. Allows observers to customise how they launch rays.

This method must return a list of tuples, with each tuple containing a Ray object and a corresponding weighting, typically the projected area/direction cosine. In general the weight will be:

\[W = \frac{1}{2\pi} * \frac{1}{A} * \frac{1}{pdf_A} * \frac{1}{pdf_\Omega} * cos(\theta)\]

If the projected area weight is not required (due to the ray sampling algorithm taking the weighting into account in the distribution e.g. cosine weighted) then the weight should be set to 1.0.

The number of rays returned must be equal to ray_count otherwise pipeline statistics will be incorrectly calculated.

Parameters:
  • template (Ray) – The template ray from which all rays should be generated.
  • ray_count (int) – The number of rays to be generated.
Return list:

A list of tuples of (ray, weight)

pipelines

A list of pipelines to process the output spectra of these observations.

Return type:list
pixel_samples

The number of samples to take per pixel.

Return type:int
samples_per_task

Minimum number of samples to request per task.

For efficiency reasons this should not be set below 100 samples.

Return type:int
class raysect.optical.observer.nonimaging.fibreoptic.FibreOptic

Bases: raysect.optical.observer.base.observer.Observer0D

An optical fibre observer that samples rays from an acceptance cone and circular area at the fibre tip.

Rays are sampled over a circular area at the fibre tip and a conical solid angle defined by the acceptance_angle parameter.

Parameters:
  • pipelines (list) – The list of pipelines that will process the spectrum measured by this optical fibre (default=SpectralPipeline0D()).
  • acceptance_angle (float) – The angle in degrees between the z axis and the cone surface which defines the fibres solid angle sampling area.
  • radius (float) – The radius of the fibre tip in metres. This radius defines a circular area at the fibre tip which will be sampled over.
  • kwargs**kwargs from Observer0D and _ObserverBase
acceptance_angle

The angle in degrees between the z axis and the cone surface which defines the fibres solid angle sampling area.

Return type:float
collection_area

The fibre’s collection area in m^2.

Return type:float
etendue

The fibre’s etendue measured in units of per area per solid angle (m^-2 str^-1).

Return type:float
radius

The radius of the fibre tip in metres. This radius defines a circular area at the fibre tip which will be sampled over.

Return type:float
solid_angle

The fibre’s solid angle in steradians str.

Return type:float
class raysect.optical.observer.nonimaging.pixel.Pixel

Bases: raysect.optical.observer.base.observer.Observer0D

A pixel observer that samples rays from a hemisphere and rectangular area.

Parameters:
  • pipelines (list) – The list of pipelines that will process the spectrum measured by this pixel (default=SpectralPipeline0D()).
  • x_width (float) – The rectangular collection area’s width along the x-axis in local coordinates (default=1cm).
  • y_width (float) – The rectangular collection area’s width along the y-axis in local coordinates (default=1cm).
  • kwargs**kwargs from Observer0D and _ObserverBase
collection_area

The pixel’s collection area in m^2.

Return type:float
etendue

The pixel’s etendue measured in units of per area per solid angle (m^-2 str^-1).

Return type:float
solid_angle

The pixel’s solid angle in steradians str.

Return type:float
x_width

The rectangular collection area’s width along the x-axis in local coordinates.

Return type:float
y_width

The rectangular collection area’s width along the y-axis in local coordinates.

Return type:float
class raysect.optical.observer.nonimaging.sightline.SightLine

Bases: raysect.optical.observer.base.observer.Observer0D

A simple line of sight observer.

Fires a single ray oriented along the observer’s z axis in world space.

Parameters:
  • etendue (float) – Optional user specified etendue. Defaults to etendue=1.0 in which case the returned units will always be in radiance (W/m^2/str/nm)
  • pipelines (list) – The list of pipelines that will process the spectrum measured by this line of sight (default=SpectralPipeline0D()).
  • kwargs**kwargs and instance properties from Observer0D and _ObserverBase
etendue

User specified etendue (str^-1/m^-2)

If etendue=1.0 the spectral units will always be in radiance (W/m^2/str/nm)

Return type:float

3.2.2. 2D Observers

class raysect.optical.observer.base.observer.Observer2D

Bases: raysect.optical.observer.base.observer._ObserverBase

2D observer base class.

This is an abstract class and cannot be used for observing.

Parameters:
  • pixels (tuple) – A tuple of pixel dimensions for this observer, i.e. (512, 512).
  • frame_sampler (FrameSampler2D) – A frame sampler class.
  • pipelines (list) – A list of pipelines that will process the resulting spectra from this observer.
  • pixel_samples (int) – Number of samples to generate per pixel with one call to observe() (default=1000).
  • kwargs**kwargs from _ObserverBase.
_generate_rays()

Generate a list of Rays that sample over the etendue of the pixel.

This is a virtual method to be implemented by derived classes.

Runs during the observe() loop to generate the rays. Allows observers to customise how they launch rays.

This method must return a list of tuples, with each tuple containing a Ray object and a corresponding weighting, typically the projected area/direction cosine. In general the weight will be:

\[W = \frac{1}{2\pi} * \frac{1}{A} * \frac{1}{pdf_A} * \frac{1}{pdf_\Omega} * cos(\theta)\]

If the projected area weight is not required (due to the ray sampling algorithm taking the weighting into account in the distribution e.g. cosine weighted) then the weight should be set to 1.0.

The number of rays returned must be equal to ray_count otherwise pipeline statistics will be incorrectly calculated.

Parameters:
  • x (int) – Pixel x index.
  • y (int) – Pixel y index.
  • template (Ray) – The template ray from which all rays should be generated.
  • ray_count (int) – The number of rays to be generated.
Return list:

A list of tuples of (ray, weight)

frame_sampler

The FrameSampler2D class for this observer.

Return type:FrameSampler2D
pipelines

A list of pipelines to process the output spectra of these observations.

Return type:list
pixel_samples

The number of samples to take per pixel.

Return type:int
pixels

Tuple describing the pixel dimensions for this observer (nx, ny), i.e. (512, 512).

Return type:tuple
class raysect.optical.observer.imaging.pinhole.PinholeCamera

Bases: raysect.optical.observer.base.observer.Observer2D

An observer that models an idealised pinhole camera.

A simple camera that launches rays from the observer’s origin point over a specified field of view.

Parameters:
  • pixels (tuple) – A tuple of pixel dimensions for the camera, i.e. (512, 512).
  • fov (float) – The field of view of the camera in degrees (default=45 degrees).
  • etendue (float) – The etendue of each pixel (default=1.0)
  • frame_sampler (FrameSampler2D) – The frame sampling strategy, defaults to adaptive sampling (i.e. extra samples for noisier pixels).
  • pipelines (list) – The list of pipelines that will process the spectrum measured at each pixel by the camera (default=RGBPipeline2D()).
  • kwargs**kwargs and properties from Observer2D and _ObserverBase.
etendue

The etendue applied to each pixel.

If etendue=1.0 all spectral units are in radiance.

Return type:float
fov

The field of view of the camera in degrees.

Return type:float
class raysect.optical.observer.imaging.orthographic.OrthographicCamera

Bases: raysect.optical.observer.base.observer.Observer2D

A camera observing an orthogonal (orthographic) projection of the scene, avoiding perspective effects.

Parameters:
  • pixels (tuple) – A tuple of pixel dimensions for the camera, i.e. (512, 512).
  • width (double) – width of the orthographic area to observe in meters, the height is deduced from the ‘pixels’ attribute.
  • etendue (float) – The etendue of each pixel (default=1.0)
  • frame_sampler (FrameSampler2D) – The frame sampling strategy (default=FullFrameSampler2D()).
  • pipelines (list) – The list of pipelines that will process the spectrum measured at each pixel by the camera (default=RGBPipeline2D()).
  • kwargs**kwargs and properties from Observer2D and _ObserverBase.
etendue

The etendue applied to each pixel.

If etendue=1.0 all spectral units are in radiance.

Return type:float
width

The width of the orthographic area to observe in meters, the height is deduced from the ‘pixels’ attribute.

Return type:float
class raysect.optical.observer.imaging.ccd.CCDArray

Bases: raysect.optical.observer.base.observer.Observer2D

An observer that models an idealised CCD-like imaging sensor.

The CCD is a regular array of square pixels. Each pixel samples red, green and blue channels (behaves like a Foveon imaging sensor). The CCD sensor width is specified with the width parameter. The CCD height is calculated from the width and the number of vertical and horizontal pixels. The default width and sensor ratio approximates a 35mm camera sensor.

Parameters:
  • pixels (tuple) – A tuple of pixel dimensions for the camera (default=(512, 512)).
  • width (float) – The CCD sensor x-width in metres (default=35mm).
  • etendue (float) – The etendue of each pixel (default=1.0)
  • pipelines (list) – The list of pipelines that will process the spectrum measured at each pixel by the camera (default=RGBPipeline2D()).
  • kwargs**kwargs and properties from Observer2D and _ObserverBase.
width

The CCD sensor x-width in metres.

Return type:float
class raysect.optical.observer.imaging.vector.VectorCamera

Bases: raysect.optical.observer.base.observer.Observer2D

An observer that uses a specified set of pixel vectors.

A simple camera that uses calibrated vectors for each pixel to sample the scene. Arguments and attributes are inherited from the base Observer2D sensor class.

Parameters:
  • pixel_origins (np.ndarray) – Numpy array of Point3Ds describing the origin points of each pixel. Must have same shape as the pixel dimensions.
  • pixel_directions (np.ndarray) – Numpy array of Vector3Ds describing the sampling direction vectors of each pixel. Must have same shape as the pixel dimensions.
  • etendue (float) – The etendue of each pixel (default=1.0)
  • frame_sampler (FrameSampler2D) – The frame sampling strategy (default=FullFrameSampler2D()).
  • pipelines (list) – The list of pipelines that will process the spectrum measured at each pixel by the camera (default=RGBPipeline2D()).
  • kwargs**kwargs and properties from Observer2D and _ObserverBase.
etendue

The etendue applied to each pixel.

If etendue=1.0 all spectral units are in radiance.

Return type:float