Back to Adaptive Vision Studio website

You are here: Start » Filter Reference » Camera Calibration » CalibrateWorldPlane

CalibrateWorldPlane


Finds the image to world plane transformation matrix.

Name Type Description
inImagePoints Point2DArray Array of 2D points of the calibration pattern, in the picture.
inWorldPlanePoints Point2DArray Array of 2D points of the calibration pattern, in a given world coordinate plane.
inCameraModel AnyCameraModel* For undistortion of inImagePoints. If not supplied, the filter will assume undistorted inImagePoints.
inWorldPlaneOrigin Point2D* Override world plane origin. If set, the world plane specified by inWorldPlanePoints will be translated so that world plane origin will lie at the specified image point.
inWorldPlaneXAxis Point2D* Override world plane x axis direction. If set, the world plane specified by inWorldPlanePoints will be rotated so that world plane x axis will lie at the specified image point.
outTransform RectificationTransform
outRmsError Real RMS reprojection error, in pixels.
outMaxReprojectionError Real Maximum reprojection error, in pixels.
outReprojectionErrorSegments Segment2DArray Array of segments connecting input image points to reprojected world points.

Applications

Image to world coordinates transformations.

Description

The filter estimates the correspondence between the image plane and a "world plane" – a given planar surface in observed space. The image plane, and thus inImagePoints are assumed to be distorted, and to correct for the distortion the inCameraModel (calibration data) needs to be provided. The calculated result – outTransform contains all the information for transforming the distorted image plane to the world plane.

The inCameraModel is also used to define the type of the planar correspondence. For a standard projective camera (pinhole camera), the planar correspondence is a homography. If the inCameraModel is a telecentric camera, the planar correspondence is affine (as there are no perspective parameters in orthographic projection). If no inCameraModel is provided, the filter defaults to homography.

The homography requires at least four inImagePoints (and their inWorldPlanePoints correspondences). The affine relation requires at least three such pairs.

Grids detected by some filters such as DetectCalibrationGrid_Chessboard have random origin location. When using such grids as a source of inImagePoints and inWorldPlanePoints, the inWorldPlaneOrigin and inWorldPlaneXAxis can be used to set the origin and x axis direction for the world plane. Note that the origin and the axis direction does not need to lie on a grid point, it can be arbitrarily chosen.

The filter provides a few methods for judging the feasibility of calculated solution.

  • The outRmsError and outMaxReprojectionError. The main contributor to these values is the random noise in inImagePoints positions. Model mismatch (i.e. trying to calibrate a non-planar object, e.g. wavy surface) will also result in increased reprojection errors. Large difference between outRmsError and outMaxReprojectionError could be a sign of presence of outliers in input data.
  • The outReprojectionErrorSegments consists of segments connecting input image points to reprojected world points, and thus it can be readily used for visualization of per-point reprojection errors.

Hints

  • Image to world plane coordinate transform can be obtained from as few as 4 point correspondences, however high accuracy calculations need a considerable amount of high quality calibration points. The calibration plane should contain about hundred points, spanning whole area of interest. Take care of proper conditions when taking the calibration images: reduce vibrations that may yield motion blur, prevent reflections from the calibration surface (ideally use diffusion lighting).

Examples

Good case of image to world plane calibration using high amount of calibration points. Calibration resulted in RMS and maximum reprojection errors less than 1.0, as expected. The outReprojectionErrorSegments are not visible at that scale.

Example of a gross error. The RMS reprojection error is 17.6, max reprojection error is 91.2, source of these errors is clearly visible thanks to outReprojectionErrorSegments: the association of inImagePoints and inWorldPlanePoints is wrong.

Errors

This filter can throw an exception to report error. Read how to deal with errors in Error Handling.

List of possible exceptions:

Error type Description
DomainError Array inImagePoints and inWorldPlanePoints sizes differ

Complexity Level

This filter is available on Basic Complexity Level.

See Also

  • CalibrateCamera_Pinhole – Finds the camera intrinsic parameters from the input arrays of image and real-world coordinates. Uses pinhole camera model (perspective camera).
  • CalibrateCamera_Telecentric – Finds the telecentric camera intrinsic parameters from the input arrays of image and real-world coordinates.
  • CreateRectificationMap – Computes a spatial map for transforming distorted images to rectified images defined in world coordinates.