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

CalibrateWorldPlane_Multigrid

Header:	FIL.h
Namespace:	fil
Module:	Calibration

Finds the image to world plane transformation parameters using multiple grids, using sparse world coordinate information.

Applications: Covers cases where a single grid spanning whole working area on a world plane is not feasible. Also useful when high accuracy is desired.

Syntax

void fil::CalibrateWorldPlane_Multigrid
(
	const ftl::Array<ftl::Array<fil::AnnotatedPoint2D> >& inImageGrids,
	const ftl::Array<ftl::Array<fil::AnnotatedPoint2D> >& inLabeledWorldPoints,
	const ftl::Optional<const fil::AnyCameraModel&>& inCameraModel,
	const ftl::Optional<float>& inGridSpacing,
	float inGridThickness,
	bool inInvertedWorldY,
	fil::RectificationTransform& outTransform,
	ftl::Optional< ftl::Array<ftl::Array<fil::AnnotatedPoint2D> >& > outGridWorldPoints = ftl::NIL,
	ftl::Optional< ftl::Conditional<float>& > outComputedGridSpacing = ftl::NIL,
	ftl::Optional< float& > outRmsImageError = ftl::NIL,
	ftl::Optional< float& > outRmsWorldError = ftl::NIL,
	ftl::Optional< ftl::Array<float>& > outMaxReprojectionErrors = ftl::NIL,
	ftl::Optional< ftl::Array<ftl::Array<fil::Segment2D> >& > outReprojectionErrorSegments = ftl::NIL,
	ftl::Optional< ftl::Array<float>& > outGridRotations = ftl::NIL,
	ftl::Optional< ftl::Array<fil::Vector2D>& > outGridTranslations = ftl::NIL
)

Parameters

Name	Type	Range	Default	Description
inImageGrids	const Array<Array<AnnotatedPoint2D> >&			Array of annotated calibration grids.
inLabeledWorldPoints	const Array<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 inGridImagePoints. If not supplied, the filter will assume that grids came from undistorted images.
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<Array<AnnotatedPoint2D> >& >		NIL	For each grid: 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 inImageGrids 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 inLabeledGridIds onto the world plane, in world units. This is a partial error characterizing inaccuracies with labeling of world coordinate system, excluding perspective estimation.
outMaxReprojectionErrors	Optional< Array<float>& >		NIL	For each grid: Maximum reprojection error of inImageGrids 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<Array<Segment2D> >& >		NIL	For each grid: 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.
outGridRotations	Optional< Array<float>& >		NIL	Grids' rotations on the world plane.
outGridTranslations	Optional< Array<Vector2D>& >		NIL	Grids' positions on the world plane.

Optional Outputs

The computation of following outputs can be switched off by passing value ftl::NIL to these parameters: outGridWorldPoints, outComputedGridSpacing, outRmsImageError, outRmsWorldError, outMaxReprojectionErrors, outReprojectionErrorSegments, outGridRotations, outGridTranslations.

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 multiple grids with sparse world coordinate information - i.e. grids for which only a few world plane coordinates are known.

The image plane, and thus inImageGrids 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.

Currently, only pinhole camera model is supported, so the planar correspondence used is a homography.

For each grid, the algorithm requires at least four inImageGrids points. At least two inLabeledWorldPoints (in total, among all grids) are required to uniquely determine the outTransform.

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 inImageGrids 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 outMaxReprojectionErrors could be a sign of presence of outliers in inImageGrids 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 (inImageGrids 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).
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.

Errors

List of possible exceptions:

Error type	Description
DomainError	Array inImageGrids and inLabeledWorldPoints sizes differ
DomainError	inGridSpacing needs to be positive