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 subviews, which subview 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 subviews, which subview 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 subview.
Returns: Camera roll in degrees. Positive angles correspond to a clockwise roll of the camera i.e. anticlockwise 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 subviews, specifies which subview 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 subviews, which subview index to return the field of view for.
 fullchip (bool) – For calibrations with multiple subviews, setting this to True will return the field of view defined by the camaera model of the specified subview, as if that subview covered the whole image.
Returns: 2element 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
orOriginal
, 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 sightlines in 3D space.
Can be used together with
get_pupilpos()
to obtain a full description of the camera’s sightline geometry.Parameters:  x,y (sequence of floats) – Image pixel coordinates at which to get the sightline 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
orOriginal
, 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 subview index. If not given, the correct subview(s) will be chosen automatically.
Returns: Array of sightline 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 sightline 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,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
orOriginal
, specifies whether the provided x and y are in display or original coordinates.  subview (int) – Which subview to get the pupil position for. Only required for calibrations with more than 1 subview.
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
orOriginal
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 undistortion. This can be useful if you need to calculate point undistortion 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 subviews, what subview 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 realworld 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
orOriginal
, 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 subview, so for images without multuiple subviews 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 4element 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 subviews if the requested detector region goes outside the original calibration i.e. the outside the defined subview 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) – 3element 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) – 3element 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) – 3element 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) – Humanreadable 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 undistorted, where N is the number of colour channels.
 coords (str) – Either
Display
orOriginal
, 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