detectPatternPoints

R2026b

Detect keypoints of calibration pattern in images from multiple cameras

Since R2025a

collapse all in page

Syntax

imagePoints = detectPatternPoints(imageFileNames,"charuco-board",patternDims,markerFamily,checkerSize,markerSize)
imagePoints = detectPatternPoints(imageFileNames,"aprilgrid",patternDims,tagFamily)
imagePoints = detectPatternPoints(imageFileNames,"checkerboard",patternDims)
imagePoints = detectPatternPoints(imageFileNames,"circle-grid-asymmetric",patternDims)
imagePoints = detectPatternPoints(imageFileNames,patternDetector,numKeyPoints)
imagePoints = detectPatternPoints(___,Name=Value)

Description

Natively Supported Patterns

imagePoints = detectPatternPoints(imageFileNames,"charuco-board",patternDims,markerFamily,checkerSize,markerSize) detects the keypoints of a ChArUco board calibration pattern in images imageFileNames, with dimensions specified by patternDims, markerFamily, and checkerSize.

Note

To use the detectPatternPoints function, first install the related features using the installMultiSensorCalibrationTools function.

example

imagePoints = detectPatternPoints(imageFileNames,"aprilgrid",patternDims,tagFamily) detects the keypoints of an AprilGrid calibration pattern in images imageFileNames, with dimensions specified by patternDims.

imagePoints = detectPatternPoints(imageFileNames,"checkerboard",patternDims) detects the keypoints of a fully visible checkerboard calibration pattern in images imageFileNames, with dimensions specified by patternDims. The values of the elements of patternDims must not be equal.

imagePoints = detectPatternPoints(imageFileNames,"circle-grid-asymmetric",patternDims) detects keypoints of a circle grid calibration pattern in images imageFileNames, with dimensions specified by patternDims.

Custom Pattern Detector

imagePoints = detectPatternPoints(imageFileNames,patternDetector,numKeyPoints) detects the specified number of uniquely detectable keypoints numKeyPoints of a custom calibration pattern that can be detected in an image using the specified detector function patternDetector.

Optional Arguments

imagePoints = detectPatternPoints(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, Verbose=true displays the progress of the detection process.

Examples

collapse all

This example uses:

Open Live Script

Download the calibration images.

calibImagesURL = "https://www.mathworks.com/supportfiles/vision/data/overlapping-cameras-aprilgrid-with-intrinsics.zip";
calibImagesDir = fullfile(pwd,"overlapping-cameras-aprilgrid-with-intrinsics");
calibImagesZip = fullfile(pwd,"overlapping-cameras-aprilgrid-with-intrinsics.zip");
if ~exist(calibImagesZip,"file")
    disp("Downloading calibration images (51 MB)...")
    websave(calibImagesZip,calibImagesURL);
end
if ~exist(calibImagesDir,"dir")
    unzip(calibImagesZip,calibImagesDir)
end

Specify calibration image filenames for each camera.

numCameras = 6;
camDirPrefix = "Cam00";
imageFiles = cell(1,numCameras);
for i = 1:numCameras
    camDir = fullfile(calibImagesDir,camDirPrefix+i);
    imds = imageDatastore(camDir);
    imageFiles{i} = imds.Files;
end
imageFiles = [imageFiles{:}];

Define the AprilGrid properties.

patternDims = [6 6];
tagFamily = "tag36h11";

Detect the key points of the AprilGrid in the calibration images.

imagePoints = detectPatternPoints(imageFiles, "aprilgrid", ...
    patternDims,tagFamily);
[==================================================] 100%
Elapsed time: 00:00:23
Estimated time remaining: 00:00:00

Display the detected keypoints of the AprilGrid in the first two acquisitions for three of the six cameras.

tiledlayout(2,3,TileSpacing="compact",Padding="compact");
for acqIdx = 1:2
    for camIdx = 1:3
        nexttile
        imshow(imageFiles{acqIdx,camIdx})
        title("Camera " + camIdx + "| Acquisition " + acqIdx)
        hold on
        plot(imagePoints(:,1,acqIdx,camIdx),imagePoints(:,2,acqIdx,camIdx), ...
            "ro",MarkerSize=3)
    end
end

Figure contains 6 axes objects. Hidden axes object 1 with title Camera 1| Acquisition 1 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Hidden axes object 2 with title Camera 2| Acquisition 1 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Hidden axes object 3 with title Camera 3| Acquisition 1 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Hidden axes object 4 with title Camera 1| Acquisition 2 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Hidden axes object 5 with title Camera 2| Acquisition 2 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Hidden axes object 6 with title Camera 3| Acquisition 2 contains 2 objects of type image, line. One or more of the lines displays its values using only markers

This example uses:

Open Live Script

Estimate the relative position and orientation of six cameras with overlapping fields of view by using calibration images that contain a single ChArUco board.

Download the calibration images.

calibImagesURL = "https://www.mathworks.com/supportfiles/vision/data/overlapping-cameras-charuco-with-intrinsics.zip";
calibImagesDir = fullfile(pwd,"overlapping-cameras-charuco-with-intrinsics");
calibImagesZip = fullfile(pwd,"overlapping-cameras-charuco-with-intrinsics.zip");
if ~exist(calibImagesZip,"file")
    disp("Downloading calibration images (50 MB)...")
    websave(calibImagesZip,calibImagesURL);
end
if ~exist(calibImagesDir,"dir")
    unzip(calibImagesZip,calibImagesDir)
end

Specify calibration image filenames for each camera.

numCameras = 6;
camDirPrefix = "Cam00";
imageFiles = cell(1,numCameras);
for i = 1:numCameras
    camDir = fullfile(calibImagesDir,camDirPrefix+i);
    imds = imageDatastore(camDir);
    imageFiles{i} = imds.Files;
end
imageFiles = [imageFiles{:}];

Define the ChArUco board properties. Specify checker size and marker size in centimeters.

checkerSize = 9.15; % in cm
markerSize = 6.8;   % in cm
markerFamily = "DICT_6X6_1000";
patternDims = [5 5];
numKeyPoints = prod(patternDims-1);
minMarkerId = 144;

Detect the key points of the ChArUco board in the calibration images.

imagePoints = detectPatternPoints(imageFiles,"charuco-board",patternDims, ...
    markerFamily,checkerSize,markerSize,MinMarkerID=minMarkerId);
[==================================================] 100%
Elapsed time: 00:00:03
Estimated time remaining: 00:00:00

Generate the world points for the pattern.

worldPoints = patternWorldPoints("charuco-board",patternDims,checkerSize);

Load the intrinsic parameters of the six cameras. These parameters have been estimated using the Using the Single Camera Calibrator App.

intrinsics = cell(numCameras,1);
for i = 1:numCameras
    camDir = fullfile(calibImagesDir,camDirPrefix+i);
    intrinsics{i} = load(fullfile(camDir,"intrinsics"+i)).intrinsics;
end

Perform multi-camera calibration.

params = estimateMultiCameraParameters(imagePoints,worldPoints,intrinsics,WorldUnits="cm");

Visualize the calibration accuracy.

figure(Position=[100,100,1000,400])
showReprojectionErrors(params)

Figure contains 3 axes objects. Axes object 1 with title Mean Reprojection Error per Image, xlabel Acquisition, ylabel Camera contains an object of type patch. Axes object 2 with title Mean Reprojection Error per Acquisition, xlabel Acquisition, ylabel Mean Error in Pixels contains 2 objects of type bar, line. This object represents Overall Mean Error: 0.28 pixels. Axes object 3 with title Mean Reprojection Error per Camera, xlabel Camera, ylabel Mean Error in Pixels contains 2 objects of type bar, line.

Visualize the camera extrinsic parameters.

figure
showExtrinsics(params)
view(2)

Figure contains an axes object. The axes object with title Extrinsic Parameters Visualization, xlabel X (cm), ylabel Z (cm) contains 58 objects of type patch, text, line.

Input Arguments

collapse all

Filenames of the camera calibration patterns, specified as a numAcquisitions-by-numCameras string or cell array. numAcquisitions is the number of calibration pattern acquisitions for each camera, and numCameras is the number of cameras.

Organize your calibration data into folders that contain synchronized images for each camera, ensuring that the filenames are consistent across all camera folders. This arrangement aligns images from different cameras that correspond to the same scene or subject. By using identical filenames in the folder for each camera, you can ensure that the images are properly synchronized.

Pattern dimensions, specified as a two-element vector that represents the number of checker boxes or circles along the rows (dim1) and columns (dim2) of the pattern. For an AprilGrid pattern, ensure that the pattern is oriented with the origin at the top-left as you count the rows and columns. For more information on patterns, see Calibration Patterns.

ArUco marker family, specified as one of these options:

  • "DICT_ARUCO_ORIGINAL"

  • "DICT_4X4_1000"

  • "DICT_5X5_1000"

  • "DICT_6X6_1000"

  • "DICT_7X7_1000"

ChArUco board checker box side length, specified as a scalar in world units, such as millimeters or inches. You must specify checkerSize and markerSize in the same world units, and checkerSize must be a larger value than markerSize.

Size of ArUco marker, specified as a positive integer. This value sets the length of one side of a square ArUco marker in world units such as millimeters, centimeters, meters, or inches. The value of checkerSize must be greater than the value of markerSize.

AprilTag family, specified as "tag36h11", "tag25h9", or "tag16h5".

Custom pattern detector, specified as a function handle with this syntax:

[imagePoints,hasDetected] = patternDetector(filename).

Input

  • filename — Name of the image to be processed, specified as a string scalar or character vector.

Output

  • imagePoints — Coordinates of the detected keypoints in the image, returned as a numKeyPoints-by-2 matrix. N is the number of keypoints.

  • hasDetected — Logical that indicates whether the function detected the pattern, returned as true when the function detects the pattern and false when it does not.

Number of keypoints that can be detected in the custom pattern, specified as a positive integer.

Name-Value Arguments

collapse all

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.

Example: detectPatternPoints(imageFileNames,"circle-grid-asymmetric",patternDims,Verbose=1) enables progress display to the screen.

Display detection progress information in the Command Window, specified as a numeric or logical 1 (true) or 0 (false). Set Verbose to true to display progress information.

Minimum marker ID of the pattern to detect, specified as a non-negative integer. This argument applies only to ChArUco and AprilGrid patterns.

Since R2026b

Option to perform computations in parallel using a parallel pool of workers, specified as one of these values:

  • "off" — Run in serial on the MATLAB client.

  • "auto" — Use a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, run in serial on the MATLAB client.

  • "on" — Use a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, throw an error.

If you do not have a parallel pool open and automatic pool creation is enabled, MATLAB opens a pool using the default cluster profile. Using parallel computing requires Parallel Computing Toolbox™. For more information, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).

Data Types: char | string

Output Arguments

collapse all

Image coordinates for the keypoints found in each image, returned as a numKeyPoints-by-2-by-numAcquisitions-by-numCameras matrix. numKeyPoints is the number of keypoints found for each image. numAcquisitions is the number of acquisitions with respect to the camera, and numCameras is the number of cameras. For example, imagePoints(:,:,i,j) contains the points from camera j when the pattern is located at the ith acquisition. For images in which a camera does not detect a pattern, the corresponding keypoint values are NaNs.

Extended Capabilities

expand all

Version History

Introduced in R2025a

expand all

See Also

Apps

Objects

Functions

Topics