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