estimateCheckerboardCorners3d

(To be removed) Estimate world frame coordinates of checkerboard corner points in image

estimateCheckerboardCorners3d function will be removed in a future release. Use the estimateBoardCornersCamera function instead. (since R2026a)

Syntax

boardCorners = estimateCheckerboardCorners3d(I,cameraIntrinsic,checkerSize)

[boardCorners,boardSize] = estimateCheckerboardCorners3d(I,cameraIntrinsic,checkerSize)

[boardCorners,boardSize,imagesUsed] = estimateCheckerboardCorners3d(imageFileNames,cameraIntrinsic,checkerSize)

[___] = estimateCheckerboardCorners3d(imageArray,cameraIntrinsic,checkerSize)

[___] = estimateCheckerboardCorners3d(___,Name,Value)

Description

boardCorners = estimateCheckerboardCorners3d(I,cameraIntrinsic,checkerSize) estimates the world frame coordinates of the corner points of a checkerboard in an image, I, by using the camera intrinsic parameters cameraIntrinsic and the size of the checkerboard squares checkerSize.

[boardCorners,boardSize] = estimateCheckerboardCorners3d(I,cameraIntrinsic,checkerSize) additionally returns the checkerboard size boardSize.

[boardCorners,boardSize,imagesUsed] = estimateCheckerboardCorners3d(imageFileNames,cameraIntrinsic,checkerSize) estimates the world frame coordinates of the corner points of a checkerboard from a set of image files, imageFileNames. The function returns a logical vector that indicates in which images it detected a checkerboard, imagesUsed, in addition to output arguments from previous syntaxes.

[___] = estimateCheckerboardCorners3d(imageArray,cameraIntrinsic,checkerSize) estimates the world frame coordinates of the corner points of a checkerboard from an array of images, imageArray.

[___] = estimateCheckerboardCorners3d(___,Name,Value) specifies options using one or more name-value pair arguments in addition to any combination of arguments from previous syntaxes. For example, 'MinCornerMetric',0.2 sets the threshold for the checkerboard corner metric to 0.2.

Input Arguments

I — Raw distorted image for detection

H-by-W-by-C array

Raw distorted image for detection, specified as an H-by-W-by-C array where:

• H — Height of the image in pixels

• W — Width of the image in pixels

• C — Number of color channels

Data Types: single | double | int16 | uint8 | uint16

imageFileNames — Image file names

character vector | cell array of character vectors

Image file names, specified as a character vector or cell array of character vectors. If specifying more than one file name, you must use a cell array of character vectors.

Data Types: char | cell

imageArray — Set of raw distorted images

H-by-W-by-C-by-N array

Set of raw distorted images, specified as an H-by-W-by-C-by-N array where:

• H — Height of the tallest image in the array

• W — Width of the widest image in the array

• C — Number of color channels

• N — Number of images in the array

Data Types: single | double | int16 | uint8 | uint16

cameraIntrinsic — Camera intrinsic parameters

cameraIntrinsics object

Camera intrinsic parameters, specified as a cameraIntrinsics object.

checkerSize — Size of checkerboard square

scalar

Size of a checkerboard square, specified as a scalar in millimeters. This value specifies the length of each side of a checkerboard square.

Data Types: single | double

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'MinCornerMetric',0.2 sets the threshold for the checkerboard corner metric to 0.2.

Padding — Padding along each side of checkerboard

[0 0 0 0] (default) | four-element row vector

Padding along each side of checkerboard, specified as the comma-separated pair consisting of 'Padding' and a four-element row vector of nonnegative values in millimeters.

The figure shows how the elements of the vector pad the sides.

Checkerboard Padding

Data Types: single | double

MinCornerMetric — Threshold for checkerboard corner metric

0.15 (default) | nonnegative scalar

Threshold for the checkerboard corner metric, specified as the comma-separated pair consisting of 'MinCornerMetric' and a nonnegative scalar. Using a higher threshold value can reduce the number of false detections in a noisy or highly textured image.

Data Types: single | double

ShowProgressBar — Display function progress

false (default) | true

Display function progress in a progress bar, specified as the comma-separated pair consisting of 'ShowProgressBar' and a logical false or true.

Data Types: logical

Output Arguments

boardCorners — Estimated location of checkerboard corners in the camera frame

4-by-3 matrix | 4-by-3-by-P array

Estimated location of checkerboard corners in the camera frame, returned as a 4-by-3 matrix or 4-by-3-by-P array. For one image, the function returns the 3-D world frame coordinates of the four checkerboard corners. Each row represents the x-, y- , z-axis coordinates of a corner point in meters. For multiple images, the coordinates are returned as a 4-by-3-by-P array, where P is the number of images in which a checkerboard was detected.

boardSize — Checkerboard size

two-element row vector

Checkerboard size, returned as a two-element row vector. The elements represent the width and length of the checkerboard respectively, in millimeters. The function calculates the size of the checkerboard by multiplying the size of the checkerboard squares, checkerSize, by the number of detected squares along a side.

imagesUsed — Pattern detection

N-by-1 logical vector

Pattern detection, returned as an N-by-1 logical vector, where N is the number of images. The function returns 1 (true) if corners are successfully detected in an image, and 0 (false) if no corners are detected.

The function estimates the checkerboard corners based on a successful detection of the keypoints. If any step in the detection process fails, the function does not return corners for that image, and the corresponding value in the logical vector is false.

Limitations

• Partial detection of checkerboard is not supported.

Algorithms

The algorithm first detects the checkerboard keypoints in the image and undistorts them using the provided camera intrinsics input. It then generates world points based on the checkerboard pattern dimensions. Using the undistorted image keypoints, generated world points, and camera intrinsics, the algorithm estimates the camera extrinsics. The board corners are estimated by extending from the origin keypoint according to the board size and padding. Finally, these board corners are transformed from the world coordinate frame to the camera coordinate frame using the estimated extrinsics.

Version History

Introduced in R2020b

R2026a: To be removed

The estimateCheckerboardCorners3d function will be removed in a future release. Use the estimateBoardCornersCamera function instead.