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