Ray Casting

While the calcam.Calibration class can provide information about the camera line-of-sight geometry based on a calibration, it is often necessary to also know where these sight lines intersect with a surface in the CAD model. For example for infrared thermography cameras, the mapping of image pixels to positions on the physical surfaces (of the CAD model) is usually of most interest. The function calcam.raycast_sightlines() is provided for this purpose; it determines the 3D coordinates where the given pixels’ sight-lines intersect the CAD model. Results of these calculations are represented by the calcam.RayData class. Both of these are documented on this page. For examples of usage, see the Examples page.

calcam.raycast_sightlines(calibration, cadmodel, x=None, y=None, exclusion_radius=0.0, binning=1, coords='Display', verbose=True, intersecting_only=False, force_subview=None, status_callback=None, calc_normals=False)

Ray cast camera sight-lines to determine where they intersect the given CAD model.

Parameters

  • calibration (calcam.Calibration) – Calibration whose sight-lines to raycast.

  • cadmodel (calcam.CADModel) – CAD model to check intersection with.

  • x (array-like) – x and y image pixel coordinates for which to cast sight-lines. If not specified, one ray is cast at the centre of every detector pixel. x and y must be the same shape.

  • y (array-like) – x and y image pixel coordinates for which to cast sight-lines. If not specified, one ray is cast at the centre of every detector pixel. x and y must be the same shape.

  • exclusion_radius (float) – Distance from camera pupil (in meters) over which to ignore ray intersections with CAD surfaces. This is useful for views involving mirrors and/or prisms where unfolding the optical path results in the virtual pupil location falling behind nearby CAD surfaces. Setting a sufficient exclusion radius will cause the rays to be launched from the other side of these surfaces so they intersect the correct surfaces present in the image.

  • binning (int) – If not explicitly providing x and y image coordinates, pixel binning for ray casting. This specifies NxN binning, i.e. for a value of 2, one ray is cast at the centre of every 2x2 cluster of pixels.

  • coords (str) – Either Display or Original. If specifying x and y coordinates, specifies whether the input x and y are in original or display coords. Otherwise, specifies the orientation of the returned data.

  • intersecting_only (bool) – If set to True, the ray end coordinates and length for sight-lines which do not intersect with the CAD model (i.e. sight lines which “escape” through holes in the model) are set to NaN. This is useful if you are only interested in sight-lines which intersect with CAD model surfaces.

  • force_subview (int) – If specified, forces use of the camera model from this index of sub-view in the calibration. Otherwise, sub-views are chosen according to the sub-view mask in the calibration.

  • verbose (bool) – Whether to print status updates during ray casting (depreciated in favour of status_callback)

  • status_callback (callable) – Callable which takes a single argument to be called with status updates. The argument will either be a string for textual status updates or a float from 0 to 1 specifying the progress of the calculation. If set to None, no status updates are issued. For backwards compatibility, if set to None but verbose is set to True, status_callback will be set such that status updates go to stdout.

  • calc_normals (bool) – Whether to calculate the normal vectors of the CAD model where the sight-lines intersect it. Not turned on by default because it seems to add around 80% extra calculation time, so best used only if actyally needed.

Returns

Object containing the results.

Return type

calcam.RayData

class calcam.RayData(filename=None)

Class representing ray casting results.

Objects of this class are returned by calcam.raycast_sightlines(). It can also be used to save and load ray cast results to disk.

Parameters

filename (str) – File name of netCDF file containing saved RayData to load. If not given, an empty RayData object is created.

get_model_normals(x=None, y=None, im_position_tol=1, coords='Display')

Get the 3D unit normal vectors of the CAD model surface where the camera sight-lines hit the model. Only available if calc_normals = True was given when running raycast_sightlines().

Parameters

  • x (array-like) – Image pixel coordinates at which to get the model normals. If not specified, the end coordinates of all casted sight lines will be returned.

  • y (array-like) – Image pixel coordinates at which to get the model normals. If not specified, the end coordinates of all casted sight lines will be returned.

  • im_position_tol (float) – If x and y are specified but no sight-line was cast at exactly the input coordinates, the nearest casted sight-line will be returned instead provided the pixel coordinates wre within this many pixels of the requested coordinates.

  • coords (str) – Either Display or Coords, specifies what orientation the input x and y correspond to or orientation of the returned array.

Returns

An array containing the normal vectors of the CAD model surface where each sight line intersects the CAD model. If x and y coordinates were given either to this function or to calcam.raycast_sightlines(), the shape of this array is the same as the input x and y arrays with an additional dimension added which contains the [X,Y,Z] components of the normals. Otherwise the shape is (h x w x 3) where w and h are the image width and height (in display coords).

Return type

np.ndarray

get_ray_directions(x=None, y=None, im_position_tol=1, coords='Display')

Get unit vectors specifying the sight-line directions. Note that ray casting is not required to get this information: see calcam.Calibration.get_los_direction() for the same functionality, however this can be useful if you have the RayData but not calcam.Calibration object loaded when doing the analysis.

Parameters

  • x (array-like) – x and y pixel coordinates at which to get the ray directions. If not specified, the ray directions of every sight-line are returned.

  • y (array-like) – x and y pixel coordinates at which to get the ray directions. If not specified, the ray directions of every sight-line are returned.

  • im_position_tol (float) – If x and y are specified but no sight-line was cast at exactly the input coordinates, the nearest casted sight-line will be returned instead provided the pixel coordinates wre within this many pixels of the requested coordinates.

  • coords (str) – Either Display or Original, specifies what orientation the input x and y correspond to or orientation of the returned array.

Returns

Array containing the sight-line directions. If the ray cast was for the full detector and x and y are not specified, the array shape will be (h x w x 3) where w nd h are the image width and height. Otherwise it will be the same shape as the input x and y coordinates plus an extra dimension.

Return type

np.ndarray

get_ray_end(x=None, y=None, im_position_tol=1, coords='Display')

Get the 3D x,y,z coordinates where the casted rays / sightlines intersect the CAD model.

Parameters

  • x (array-like) – Image pixel coordinates at which to get the sight-line end coordinates. If not specified, the end coordinates of all casted sight lines will be returned.

  • y (array-like) – Image pixel coordinates at which to get the sight-line end coordinates. If not specified, the end coordinates of all casted sight lines will be returned.

  • im_position_tol (float) – If x and y are specified but no sight-line was cast at exactly the input coordinates, the nearest casted sight-line will be returned instead provided the pixel coordinates wre within this many pixels of the requested coordinates.

  • coords (str) – Either Display or Coords, specifies what orientation the input x and y correspond to or orientation of the returned array.

Returns

An array containing the 3D coordinates, in metres, of the points where each sight line intersects the CAD model. If x and y coordinates were given either to this function or to calcam.raycast_sightlines(), the shape of this array is the same as the input x and y arrays with an additional dimension added which contains the [X,Y,Z] 3D coordinates. Otherwise the shape is (h x w x 3) where w and h are the image width and height (in display coords).

Return type

np.ndarray

get_ray_lengths(x=None, y=None, im_position_tol=1, coords='Display')

Get the sight-line lengths either of all casted sight-lines or at the specified image coordinates.

Parameters

  • x (array-like) – Image pixel coordinates at which to get the sight-line lengths. If not specified, the lengths of all casted sight lines will be returned.

  • y (array-like) – Image pixel coordinates at which to get the sight-line lengths. If not specified, the lengths of all casted sight lines will be returned.

  • im_position_tol (float) – If x and y are specified but no sight-line was cast at exactly the input coordinates, the nearest casted sight-line will be returned instead provided the pixel coordinates wre within this many pixels of the requested coordinates.

  • coords (str) – Either Display or Coords, specifies what orientation the input x and y correspond to or orientation of the returned array.

Returns

Array containing the sight-line lengths. If the ray cast was for the full detector and x and y are not specified, the array shape will be (h x w) where w nd h are the image width and height. Otherwise it will be the same shape as the input x and y coordinates.

Return type

np.ndarray

get_ray_start(x=None, y=None, im_position_tol=1, coords='Display')

Get the 3D x,y,z coordinates of the “start” of the casted rays / sightlines.

Parameters

  • x (array-like) – Image pixel coordinates at which to get the sight-line start coordinates. If not specified, the start coordinates of all casted sight lines will be returned.

  • y (array-like) – Image pixel coordinates at which to get the sight-line start coordinates. If not specified, the start coordinates of all casted sight lines will be returned.

  • im_position_tol (float) – If x and y are specified but no sight-line was cast at exactly the input coordinates, the nearest casted sight-line will be returned instead provided the pixel coordinates wre within this many pixels of the requested coordinates.

  • coords (str) – Either Display or Coords, specifies what orientation the input x and y correspond to or orientation of the returned array.

Returns

An array containing the 3D coordinates, in metres, of the start of each sight line (i.e. camera pupil position). If x and y coordinates were given either to this function or to calcam.raycast_sightlines(), the shape of this array is the same as the input x and y arrays with an additional dimension added which contains the [X,Y,Z] 3D coordinates. Otherwise the shape is (h x w x 3) where w and h are the image width and height (in display coords).

Return type

np.ndarray

history

Human readable description of where the raydata came from.

Type

str

save(filename)

Save the RayData to a netCDF file.

Parameters

filename (str) – File name to save to.

set_detector_window(window)

Adjust the raydata to apply to a different detector region for than was used to perform the original raycast. Useful for example if a CMOS camera has been calibrated over the full frame, but you now want to use this calibration for data which has been cropped.

Calling this function with None as the single argument sets the raydata back to its “native” state. Otherwise, call with a 4 element tuple specifying the left,top,width and height of the detector window.

Detector window coordinates must always be in original coordinates.

Parameters

window (tuple or list) – A 4-element tuple or list of integers defining the detector window coordinates (Left,Top,Width,Height)