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 sensitivity 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.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
  • sensitivity (float) – Optional user specified sensitivity. Defaults to sensitivity=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

>>> from raysect.optical import World
>>> from raysect.optical.observer import SightLine, PowerPipeline0D
>>>
>>> world = World()
>>> power = PowerPipeline0D(accumulate=False)
>>> los = SightLine([power], min_wavelength=400, max_wavelength=720,
                    parent=world, transform=rotate(0, 0, 0)*translate(0, 0, -1))
>>> los.observe()
sensitivity

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

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

Return type

float

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

>>> from raysect.optical.observer import FibreOptic, RadiancePipeline0D, PowerPipeline0D
>>>
>>> power = PowerPipeline0D()
>>> radiance = RadiancePipeline0D()
>>> fibre = FibreOptic([power, radiance], acceptance_angle=10, radius=0.0005,
                        spectral_bins=500, pixel_samples=1000,
                        transform=translate(0, 0, -5), parent=world)
>>> fibre.observe()
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

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

sensitivity

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

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

>>> from raysect.optical import World
>>> from raysect.optical.observer import Pixel, PowerPipeline0D
>>>
>>> world = World()
>>> power = PowerPipeline0D(accumulate=False)
>>> observing_plane = Pixel([power], x_width=2.0, y_width=2.0,
                            min_wavelength=400, max_wavelength=720,
                            spectral_bins=1, pixel_samples=250,
                            parent=world, transform=rotate(0, 0, 0)*translate(0, 0, -1))
>>> observing_plane.observe()
collection_area

The pixel’s collection area in m^2.

Return type

float

sensitivity

The pixel’s sensitivity 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.targetted_pixel.TargettedPixel

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

A pixel observer that preferentially targets rays towards a given list of primitives.

The targetted pixel takes a list of target primitives. The observer targets the bounding sphere that encompasses a target primitive. Therefore, for best performance, the target primitives should be split up such that their surfaces are closely wrapped by the bounding sphere.

The sampling algorithm fires a proportion of rays at the targets, and a portion sampled from the full hemisphere. The proportion that is fired towards the targets is controlled with the targetted_path_prob attribute. By default this attribute is set to 0.9, i.e. 90% of the rays are fired towards the targets.

Parameters
  • targets (list) – The list of primitives for targeted sampling.

  • targetted_path_prob (float) – The probability of sampling a targeted primitive VS sampling over the whole hemisphere.

  • 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

>>> from raysect.optical.observer import TargettedPixel, PowerPipeline0D
>>>
>>> # set-up scenegraph
>>> world = World()
>>> emitter = Sphere(radius=sphere_radius, parent=world)
>>> emitter.material = UnityVolumeEmitter()
>>>
>>> # setup targetted pixel observer
>>> targetted_pipeline = PowerPipeline0D(name="Targeted Pixel Observer")
>>> targetted_pixel = TargettedPixel(parent=world, targets=[emitter],
>>>                                  pixel_samples=250, pipelines=[targetted_pipeline])
>>> targetted_pixel.observe()
collection_area

The pixel’s collection area in m^2.

Return type

float

sensitivity

The pixel’s sensitivity 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

targets

The list of primitives this pixel will target for sampling.

Return type

list

targetted_path_prob

The probability that an individual sample will be fired at a target instead of a sample from the whole hemisphere.

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.mesh_pixel.MeshPixel

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

Uses a supplied mesh surface as a pixel.

Warning

Users must be careful when using this camera to not double count radiance. For example, if you have a concave mesh its possible for two surfaces to see the same emission. In cases like this, the mesh should have an absorbing surface to prevent double counting.

This observer samples over the surface defined by a triangular mesh. At each point on the surface the incoming radiance over a hemisphere is sampled.

A mesh surface offset can be set to ensure sample don’t collide with a coincident primitive. When set, the surface offset specifies the distance along the surface normal that the ray launch origin is shifted.

Parameters
  • mesh (Mesh) – The mesh instance to use for observations.

  • surface_offset (float) – The offset from the mesh surface (default=0).

  • pipelines (list) – The list of pipelines that will process the spectrum measured by this pixel (default=SpectralPowerPipeline0D()).

  • kwargs**kwargs from Observer0D and _ObserverBase

>>> from raysect.primitive import Mesh
>>> from raysect.optical import World
>>> from raysect.optical.material import AbsorbingSurface
>>> from raysect.optical.observer import MeshPixel, PowerPipeline0D
>>>
>>> world = World()
>>>
>>> mesh = Mesh.from_file("my_mesh.rsm", material=AbsorbingSurface(), parent=world)
>>>
>>> power = PowerPipeline0D(accumulate=False)
>>> observer = MeshPixel(mesh, pipelines=[power], parent=world,
>>>                      min_wavelength=400, max_wavelength=750,
>>>                      spectral_bins=1, pixel_samples=10000, surface_offset=1E-6)
>>> observer.observe()
collection_area

The pixel’s collection area in m^2.

Return type

float

sensitivity

The pixel’s sensitivity 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

3.2.2. 1D Observers

class raysect.optical.observer.base.observer.Observer1D

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

1D observer base class.

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

Parameters
  • pixels (int) – The number of pixels for this observer, i.e. 512.

  • frame_sampler (FrameSampler1D) – 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 sensitivity 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
  • pixel (int) – Pixel 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 FrameSampler1D class for this observer.

Return type

FrameSampler1D

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

The number of pixels for this observer, i.e. 512.

Return type

int

class raysect.optical.observer.nonimaging.mesh_camera.MeshCamera

Bases: raysect.optical.observer.base.observer.Observer1D

Uses a supplied mesh surface as a linear camera.

Warning

Users must be careful when using this camera to not double count radiance. For example, if you have a concave mesh its possible for two surfaces to see the same emission. In cases like this, the mesh should have an absorbing surface to prevent double counting.

This observer samples over each triangle or a triangular mesh. At each point on the surface the incoming radiance over a hemisphere is sampled. The pixel id corresponds to the triangle id in the mesh.

A mesh surface offset can be set to ensure samples don’t collide with a coincident primitive. When set, the surface offset specifies the distance along the surface normal that the ray launch origin is shifted.

Parameters
  • mesh (Mesh) – The Mesh object to use as the sampling surface.

  • surface_offset (float) – The offset from the mesh surface (default=0).

  • pipelines (list) – The list of pipelines that will process the spectrum measured by this observer (default=PowerPipeline1D()).

  • kwargs**kwargs from Observer1D and _ObserverBase

>>> from raysect.primitive import Mesh
>>> from raysect.optical import World
>>> from raysect.optical.material import AbsorbingSurface
>>> from raysect.optical.observer import MeshCamera, PowerPipeline1D, MonoAdaptiveSampler1D
>>>
>>> world = World()
>>>
>>> mesh = Mesh.from_file("my_mesh.rsm", material=AbsorbingSurface(), parent=world)
>>>
>>> power = PowerPipeline1D()
>>> sampler = MonoAdaptiveSampler1D(power, fraction=0.2, ratio=25.0, min_samples=1000, cutoff=0.1)
>>> camera = MeshCamera(mesh,
                        surface_offset=1e-6,  # launch rays 1mm off surface to avoid intersection with absorbing mesh
                        pipelines=[power],
                        frame_sampler=sampler,
                        parent=world,
                        spectral_bins=1,
                        min_wavelength=400,
                        max_wavelength=740,
                        pixel_samples=250)
>>> camera.observe()
collection_area()

The mesh camera’s collection area in m^2.

Return type

float

sensitivity()

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

Return type

float

solid_angle()

The solid angle observed at each mesh triangle in steradians str.

Return type

float

3.2.3. 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 sensitivity 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).

  • sensitivity (float) – The sensitivity 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.

>>> from raysect.core import translate
>>> from raysect.optical import World
>>> from raysect.optical.observer import PinholeCamera, PowerPipeline2D
>>>
>>> power = PowerPipeline2D(display_unsaturated_fraction=0.96, name="Unfiltered")
>>>
>>> camera = PinholeCamera((512, 512), parent=world, pipelines=[power])
>>> camera.transform = translate(0, 0, -3.3)
>>> camera.pixel_samples = 250
>>> camera.spectral_bins = 15
>>>
>>> camera.observe()
fov

The field of view of the camera in degrees.

Return type

float

pixels

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

Return type

tuple

sensitivity

The sensitivity applied to each pixel.

If sensitivity=1.0 all spectral units are in radiance.

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.

  • sensitivity (float) – The sensitivity 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.

pixels

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

Return type

tuple

sensitivity

The sensitivity applied to each pixel.

If sensitivity=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).

  • 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.

pixels
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.

  • sensitivity (float) – The sensitivity 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.

sensitivity

The sensitivity applied to each pixel.

If sensitivity=1.0 all spectral units are in radiance.

Return type

float