Back to Adaptive Vision Library website

You are here: Start » Function Reference » Camera Calibration » CalibrateWorldPlane_Labeled

CalibrateWorldPlane_Labeled


Header:AVL.h
Namespace:avl

Finds the image to world plane transformation matrix using sparse world coordinate information, i.e. world coordinates are known for only a few points of the grid.

Syntax

C++
C#
 
void avl::CalibrateWorldPlane_Labeled
(
	const atl::Array<avl::AnnotatedPoint2D>& inImageGrid,
	const atl::Array<avl::AnnotatedPoint2D>& inLabeledWorldPoints,
	const atl::Optional<const avl::AnyCameraModel&>& inCameraModel,
	const atl::Optional<float>& inGridSpacing,
	float inGridThickness,
	bool inInvertedWorldY,
	avl::RectificationTransform& outTransform,
	atl::Optional< atl::Array<avl::AnnotatedPoint2D>& > outGridWorldPoints = atl::NIL,
	atl::Optional< atl::Conditional<float>& > outComputedGridSpacing = atl::NIL,
	atl::Optional< float& > outRmsImageError = atl::NIL,
	atl::Optional< float& > outRmsWorldError = atl::NIL,
	atl::Optional< float& > outMaxReprojectionError = atl::NIL,
	atl::Optional< atl::Array<avl::Segment2D>& > outReprojectionErrorSegments = atl::NIL
)

Parameters

Name Type Range Default Description
inImageGrid const Array<AnnotatedPoint2D>& Annotated calibration grid.
inLabeledWorldPoints const Array<AnnotatedPoint2D>& Sparse array of world coordinate points. Annotations need to correspond to those in the inImageGrid input.
inCameraModel const Optional<const AnyCameraModel&>& NIL For undistortion of inImageGrid. If not supplied, the filter will assume that grid came from undistorted image.
inGridSpacing const Optional<float>& 0.000001 - NIL World distance between grid indices. Used when spacing cannot be computed from supplied inLabeledWorldPoints.
inGridThickness float 0.0f The world plane will be shifted by given amount in direction perpendicular to the grid to compensate for grid thickness.
inInvertedWorldY bool False Set to true if world coordinate system has right-handed orientation, also known as mathematical or standard.
outTransform RectificationTransform&
outGridWorldPoints Optional< Array<AnnotatedPoint2D>& > NIL Array of world coordinates of the calibration grid points.
outComputedGridSpacing Optional< Conditional<float>& > NIL World distance between grid indices. NIL when there is no enough information to compute the spacing.
outRmsImageError Optional< float& > NIL RMS reprojection error of inImageGrid onto the image plane, in pixels. This is a partial error characterizing inaccuracies in perspective estimation, excluding the influence of world point labeling.
outRmsWorldError Optional< float& > NIL RMS reprojection error of inLabeledWorldPoints onto the world plane, in world units. This is a partial error characterizing inaccuracies with labeling of world coordinate system, excluding perspective estimation.
outMaxReprojectionError Optional< float& > NIL Maximum reprojection error of inImageGrid onto the image plane, in pixels. This is a partial error characterizing inaccuracies in perspective estimation, excluding the influence of world point labeling.
outReprojectionErrorSegments Optional< Array<Segment2D>& > NIL Array of segments connecting inImageGrid points to their reprojections. Note that these segments depict only inaccuracies in perspective estimation - excluding inaccuracies due to the world point labeling.

Optional Outputs

The computation of following outputs can be switched off by passing value atl::NIL to these parameters: outGridWorldPoints, outComputedGridSpacing, outRmsImageError, outRmsWorldError, 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. It is capable of using a sparse world coordinate information - a calibration grid for which only a few world plane coordinates are known.

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.

To uniquely define the outTransform, the algorithm requires at least four inImageGrid points (the affine relation requires at least three), and at least two inLabeledWorldPoints.

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

  • The outRmsImageError and outRmsWorldError could show if the error is due to the inImageGrid or inLabeledWorldPoints errors. 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 outRmsImageError and outMaxReprojectionError could be a sign of presence of outliers in inImageGrid 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 (excluding the errors due to incorrect world plane labeling).

Hints

  • Image to world plane coordinate transform can be obtained from as few as 4 image points (inImageGrid points), 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).
  • It is often assumed that calibration grid is perfect in terms of 2D world coordinates of its points. If such an assumption is made then 2 world coordinates are enough for labeling of grid world point coordinates (inLabeledWorldPoints).
  • The output reprojection errors are useful tool for assessing the feasibility of computed solution. Note, that the filter outputs two RMS metrics: outRmsImageError and outRmsWorldError. The outRmsImageError characterizes inaccuracies in perspective estimation, it is not influenced by world coordinate labeling. On the other hand, the outRmsWorldError characterizes inaccuracies with labeling of grid 2D world coordinate system, excluding perspective estimation. In order for a solution to be feasible, both these errors must be low.

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.

Errors

List of possible exceptions:

Error type Description
DomainError inGridSpacing needs to be positive

See Also

  • CalibrateWorldPlane_Default – Finds the image to world plane transformation matrix. World plane origin and axes are unspecified. Useful for image rectification or distance measurements.
  • CalibrateWorldPlane_OffgridOrigin – Finds the image to world plane transformation matrix, with world origin and axes specified in the image coordinates. Note that this is a filter for rather rarely seen special cases and it is usually better to use the CalibrateWorldPlane_Labeled filter.
  • CalibrateWorldPlane_Multigrid – Finds the image to world plane transformation matrix using multiple grids, using sparse world coordinate information.
  • CalibrateCamera_Pinhole – Finds the camera intrinsic parameters from the input arrays of annotated image coordinates. Uses pinhole camera model (perspective camera).
  • CalibrateCamera_Telecentric – Finds the telecentric camera intrinsic parameters from the input arrays of annotated image coordinates.
  • 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.