The Calibration Class

Once you have created a calibration using the Calcam GUI tools, the starting point to interact with the calibration results programatically is the calcam.Calibration class, which is documented on this page. For examples of usage, see the Examples page.

class calcam.Calibration(load_filename=None, cal_type=None)

Class representing a camera view calibration.

A complete Calibration object contains the camera image which was calibrated (if any), the point pairs used for fitting (if applicable), the camera model parameters, and metadata about each of these.

If instantiated with the name of a .ccc file to load, the resulting object represents the calibration contained in that file. If no file name is given, an empty calibration object of a specified type is created.

Parameters
  • load_filename (str) – File name of the calibration to load. If not given, an “empty” calibration object is created.

  • cal_type (str) – Required only if load_file is not specified i.e. creating an empty calibration object. Must be one of “fit”, “alignment” or “virtual”. If load_file is provided, this is ignored.

get_cam_matrix(subview=None)

Get the camera matrix.

Parameters

subview (int) – For calibrations with multiple sub-views, which sub-view index to return the camera matrix for.

Returns

3x3 camera matrix.

Return type

np.matrix

get_cam_roll(subview=None, centre='optical')

Get the camera roll. This is the angle between the projection of the lab +Z axis in the image and the vertical “up” direction on the detector.

Parameters
  • subview (int) – For calibrations with multiple sub-views, which sub-view index to return the camera roll for.

  • centre (str) – At what image position to measure the “camera roll”. ‘optical’ - at the optical axis (default); ‘detector’ - at the detector centre; or ‘subview’ - at the centre of the relevant sub-view.

Returns

Camera roll in degrees. Positive angles correspond to a clockwise roll of the camera i.e. anti-clockwise roll of the image.

Return type

float

get_cam_to_lab_rotation(subview=None)

Get a 3D rotation matrix which will rotate a point in the camera coordinate system (see Calcam theory documentation) in to the lab coordinate system’s orientation.

Parameters

subview (int) – For calibrations with multiple sub-views, specifies which sub-view to return the rotation matrix for.

Returns

3x3 rotation matrix.

Return type

np.matrix

get_fov(subview=None, fullchip=False)

Get the camera field of view.

Parameters
  • subview (int) – For calibrations with multiple sub-views, which sub-view index to return the field of view for.

  • fullchip (bool) – For calibrations with multiple sub-views, setting this to True will return the field of view defined by the camaera model of the specified sub-view, as if that sub-view covered the whole image.

Returns

2-element tuple containing the full angles of the horizontal and vertical fields of view (h_fov,v_fov) in degrees.

Return type

tuple

get_image(coords='Display')

Get the image which was calibrated.

Parameters

coords (str) – Either Display or Original, what orientation to return the image.

Returns

If the calibration contains an image: returns image data array with shape (h x w x n) where n is the number of colour channels in the image. If the calibration does not contain an image, returns None.

Return type

np.ndarray or NoneType

get_los_direction(x=None, y=None, coords='Display', subview=None)

Get unit vectors representing the directions of the camera’s sight-lines in 3D space.

Can be used together with get_pupilpos() to obtain a full description of the camera’s sight-line geometry.

Parameters
  • x (sequence of floats) – Image pixel coordinates at which to get the sight-line directions. x and y must be the same shape. If not specified, the line of sight direction at the centre of every detector pixel is returned.

  • y (sequence of floats) – Image pixel coordinates at which to get the sight-line directions. x and y must be the same shape. If not specified, the line of sight direction at the centre of every detector pixel is returned.

  • coords (str) – Either Display or Original, specifies which image orientation the provided x and y inputs and/or shape of the returned array correspond to.

  • subview (int) – If specified, forces the use of the camera model from the specified sub-view index. If not given, the correct sub-view(s) will be chosen automatically.

Returns

Array of sight-line vectors. If specifying x_pixels and y_pixels, the output array will be the same shape as the input arrays but with an extra dimension added. The extra dimension contains the [X,Y,Z] components of the sight-line vectors. If not specifying x_pixels and y_pixels, the output array shape will be (h x w x 3) where w and h are the image width and height in pixels.

Return type

np.ndarray

get_pupilpos(x=None, y=None, coords='display', subview=None)

Get the camera pupil position in 3D space.

Can be used together with get_los_direction() to obtain a full description of the camera’s sight line geometry.

Parameters
  • x (float or numpy.ndarray) – For calibrations with more than one subview, get the pupil position(s) corresponding to these given image pixel coordinates.

  • y (float or numpy.ndarray) – For calibrations with more than one subview, get the pupil position(s) corresponding to these given image pixel coordinates.

  • coords (str) – Only used if x and y are also given. Either Display or Original, specifies whether the provided x and y are in display or original coordinates.

  • subview (int) – Which sub-view to get the pupil position for. Only required for calibrations with more than 1 sub-view.

Returns

Camera pupil position in 3D space. If not specifying x or y inputs, this will be a 3 element array containing the [X,Y,Z] coordinates of the pupil position in metres. If using x and y inputs, the output array will be the same shape as the x and y input arrays with an additional dimension added; the X, Y and Z components are then given along the new new array dimension.

Return type

np.ndarray

get_raysect_camera(coords='Display', binning=1)

Get a RaySect observer corresponding to the calibrated camera.

Parameters

coords (str) – Either Display or Original specifying the orientation of the raysect camera.

Returns

RaySect camera object.

Return type

raysect.optical.observer.imaging.VectorCamera

get_undistort_coeffs(radial_terms=None, include_tangential=None, subview=None)

Get a set of parameters which can be used to analytically calculate image coordinate un-distortion. This can be useful if you need to calculate point un-distortion faster than the usual numerical method. This fits a model of the form of the perspective distortion model but with coordinate vectors \((x_n, y_n)\) and \((x_d,y_d)\) interchanged. Which coefficients are included can be set by optional input arguments; by default the same terms which were enabled in the calibration fit are also included in this fit. Note: this function does not work with fisheye calibrations.

Parameters
  • radial_terms (int) – Number of terms to include in the radial distortion model, can be in the range 1 - 3. If < 3, higher order coefficients are set to 0. If not provided, uses the same number of terms as the calibration fit.

  • include_tangential (bool) – Whether to include the tangential distortion coefficients p1 and p2. If not given, uses the same option as was used in the calibration.

  • subview (int) – For calibrations with multiple sub-views, what sub-view to get the parameters for.

Returns

A dictionary containing the fitted coeffcients. Radial distortion coefficients are in keys: ‘k1’, ‘k2’ and ‘k3’; tangential coefficients are in keys ‘p1’ and ‘p2’. An additional key ‘rms_error’ gives the RMS fit error, in pixels, which indicates how well these fitted parameters reproduce the full numerical distortion inversion.

Return type

dict

project_points(points_3d, coords='display', check_occlusion_with=None, fill_value=nan, occlusion_tol=0.001)

Get the image coordinates corresponding to given real-world 3D coordinates.

Optionally can also check whether the 3D points are hidden from the camera’s view by part of the CAD model being in the way.

Parameters
  • points_3d – 3D point coordinates, in metres, to project on to the image. Can be EITHER an Nx3 array, where N is the number of 3D points and each row gives [X,Y,Z] for a 3D point, or a sequence of 3 element sequences, where each 3 element array specifies a 3D point.

  • coords (str) – Either Display or Original, specifies which image orientation the returned image coordinates should correspond to.

  • check_occlusion_with (calcam.CADModel or calcam.RayData) – If provided and fill_value is not None, for each 3D point the function will check if the point is hidden from the camera’s view by part of the provided CAD model. If a point is hidden its returned image coordinates are set to fill_value. Note: if using a RayData onject, always use Raydata resulting from a raycast of the complete detector, or else project_points will be incredibly slow.

  • fill_value (float) – For any 3D points not visible to the camera, the returned image coordinates will be set equal to this value. If set to None, image coordinates will be returned for every 3D point even if the point is outside the camera’s field of view or hidden from view.

  • occlusion_tol (float) – Tolerance (in mrtres) to use to check point occlusion. Try increasing this value if having trouble with points being wrongly detected as occluded.

Returns

A list of Nx2 NumPY arrays containing the image coordinates of the given 3D points (N is the number of input 3D points). Each NumPY array corresponds to a single sub-view, so for images without multuiple sub-views this will return a single element list containing an Nx2 array. Each row of the NumPY arrays contains the [X,Y] image coordinates of the corresponding input point. If fill_value is not None, points not visible to the camera have their coordinates set to [fill_value, fill_value].

Return type

list of np.ndarray

set_detector_window(window, bounds_error='warn')

Adjust the calibration to apply to a different detector region for than was used to perform the calibration. 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 windiw=`None` sets the calibration 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 (sequence) – Either None or a 4-element sequence of integers defining the detector window coordinates (Left,Top,Width,Height). This MUST be specified in ‘original’ detector coordinates (i.e. before any image rotation, flips etc).

  • bounds_error (str) – How to handle the case for calibrations with multiple sub-views if the requested detector region goes outside the original calibration i.e. the outside the defined sub-view map. ‘except’ will raise an exception, ‘warn’ will raise a warning and ‘silent’ will not alert the user at all. If ‘warn’ or ‘silent’, only pixels within the original calibrated area will be usable. Default is ‘warn’.

set_extrinsics(campos, upvec=None, camtar=None, view_dir=None, cam_roll=None, src=None)

Manually set the camera extrinsic parameters. Only applicable for synthetic or manual alignment type calibrations.

Parameters
  • campos (sequence) – 3-element sequence specifying the camera position (X,Y,Z) in metres.

  • view_dir (sequence) – 3D vector [X,Y,Z] specifying the camera view direction. Either view_dir or camtar must be given; if both are given then view_dir is used.

  • camtar (sequence) – 3-element sequence specifying a point in 3D space where the camera is pointed to. Either camtar or view_dir must be given; if both are given then view_dir is used.

  • upvec (sequence) – 3-element sequence specifying the camera up vector. Either upvec or cam_roll must be given; if both are given then upvec is used. upvec must be orthogonal to the viewing direction.

  • cam_roll (float) – Camera roll in degrees. This is the angle between the lab +Z axis and the camera’s “view up” direction. Either cam_roll or upvec must be given; if both are given the upvec is used.

  • src (str) – Human-readable string describing where these extrinsics come from, for data provenance. If not given, basic information like current username, hostname and time are used.

undistort_image(image, coords='display')

Correct lens distortion a given image from the calibrated camera, to give an image with a pure perspective projection.

Parameters
  • image (np.ndarray) – (h x w x N) array containing the image to be un-distorted, where N is the number of colour channels.

  • coords (str) – Either Display or Original, specifies which orientation the input image is in.

Returns

Image data array the same shape as the input array containing the corrected image.

Return type

np.ndarray