Back to FabImage Library website

You are here: Start » Function Reference » Computer Vision » Camera Calibration » CalibrateWorldPlane_Default

CalibrateWorldPlane_Default


Header: FIL.h
Namespace: fil
Module: Calibration

Finds the image to world plane transformation parameters from world plane calibration grid. World plane origin and axes are unspecified.

Applications: Useful for cases where the position of world plane origin is not important, e.g. distance measurements on a world plane, or image rectification for perspective removal.

Syntax

C++
C#
 
void fil::CalibrateWorldPlane_Default
(
	const ftl::Array<fil::AnnotatedPoint2D>& inImageGrid,
	const ftl::Optional<const fil::AnyCameraModel&>& inCameraModel,
	float inGridSpacing,
	float inGridThickness,
	fil::RectificationTransform& outTransform,
	ftl::Optional<float&> outRmsError = ftl::NIL,
	ftl::Optional<float&> outMaxReprojectionError = ftl::NIL,
	ftl::Optional<ftl::Array<fil::Segment2D>&> outReprojectionErrorSegments = ftl::NIL
)

Parameters

Name Type Range Default Description
Input value inImageGrid const Array<AnnotatedPoint2D>& Annotated calibration grid
Input value inCameraModel const Optional<const AnyCameraModel&>& NIL For undistortion of inImageGrid. If not supplied, the filter will assume that grid came from undistorted image.
Input value inGridSpacing float 0.000001 - 1.0f Real-world distance between adjacent grid points.
Input value inGridThickness float 0.0f The world plane will be shifted by given amount in direction perpendicular to the grid to compensate for grid thickness.
Output value outTransform RectificationTransform&
Output value outRmsError Optional<float&> NIL RMS reprojection error, in pixels.
Output value outMaxReprojectionError Optional<float&> NIL Maximum reprojection error, in pixels.
Output value outReprojectionErrorSegments Optional<Array<Segment2D>&> NIL Array of segments connecting input image points to grid reprojections.

Optional Outputs

The computation of following outputs can be switched off by passing value ftl::NIL to these parameters: outRmsError, outMaxReprojectionError, outReprojectionErrorSegments.

Read more about Optional Outputs.

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 inImageGrid points 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 inImageGrid points. The affine relation requires at least three.

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 inImageGrid points 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 image points and their grid coordinates in inImageGrid is wrong.

Errors

List of possible exceptions:

Error type Description
DomainError inGridSpacing needs to be positive

See Also

  • CalibrateWorldPlane_Labeled – Finds the image to world plane transformation parameters using sparse world coordinate information, i.e. world coordinates are known for only a few points of the grid.
  • CalibrateWorldPlane_Multigrid – Finds the image to world plane transformation parameters using multiple grids, using sparse world coordinate information.
  • CalibrateWorldPlane_Manual – Finds the image to world plane transformation parameters. Image and their corresponding world points are directly specified (no grid needed).
  • CalibrateCamera_Pinhole – Finds the camera intrinsic parameters from calibration grids. Uses pinhole camera model (perspective camera).
  • CreateRectificationMap_PixelUnits – Computes a spatial map for transforming distorted images to rectified images defined in world coordinate plane. Defines the output geometry in pixels.
  • CreateRectificationMap_WorldUnits – Computes a spatial map for transforming distorted images to rectified images defined in world coordinate plane. Defines the output geometry in world units.