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 subspectrum 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 subspectrum 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 subregions 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 xaxis in local coordinates (default=1cm).
 y_width (float) – The rectangular collection area’s width along the yaxis 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 xaxis in local coordinates.
Return type: float

y_width
¶ The rectangular collection area’s width along the yaxis 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 CCDlike 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 xwidth in metres (default=35mm).
 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 xwidth 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