Skip to content

CalibrationPattern

CalibrationPattern describes the physical ChArUco board you printed and uses it to detect corners in images. Create one instance per board design and share it across your calibration and detection code.

Example

import cv2
from charucal import CalibrationPattern

pattern = CalibrationPattern(
    width=10,
    height=8,
    square_length=0.115,   # meters — measure your printed board
    marker_length=0.086,   # meters
    aruco_dict=cv2.aruco.DICT_4X4_100,
)

# Detect corners in a single image
grid = pattern.detect(image)   # returns a CalibrationGrid

Choosing the right ArUco dictionary

The dictionary must match the one used when you generated the board.

Dictionary Markers Recommended for
DICT_4X4_50 50 Small boards, few cameras
DICT_4X4_100 100 General use (default)
DICT_5X5_100 100 Larger boards, more robust detection
DICT_6X6_250 250 Very large boards

Pass the constant directly (cv2.aruco.DICT_4X4_100) or its integer value. The CLI also accepts the short string form (4X4_100).

Reference

CalibrationPattern 

CalibrationPattern(
    width: int,
    height: int,
    square_length: float,
    marker_length: float,
    aruco_dict: int,
)

Represents a calibration pattern.

Initialize the calibration pattern.

Parameters:

Name Type Description Default
width int

The width of the calibration pattern.

 required
height int

The height of the calibration pattern.

 required
square_length float

The length of the squares on the calibration pattern.

 required
marker_length float

The length of the markers on the calibration pattern.

 required
aruco_dict int

The dictionary for the calibration pattern.

 required

Methods:

Name Description
detect

Detect the ChArUco board in an image.
get_shape

Get the shape of the ChArUco board.
to_grid

Get the grid of the ChArUco board.

Attributes:

Name Type Description
width int

The width of the calibration pattern.
height int

The height of the calibration pattern.
board CharucoBoard

The calibration board.
detector CharucoDetector

The calibration pattern detector.
Source code in src/charucal/pattern.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def __init__(self, width: int, height: int, square_length: float, marker_length: float, aruco_dict: int) -> None:
    """Initialize the calibration pattern.

    :param width: The width of the calibration pattern.
    :param height: The height of the calibration pattern.
    :param square_length: The length of the squares on the calibration pattern.
    :param marker_length: The length of the markers on the calibration pattern.
    :param aruco_dict: The dictionary for the calibration pattern.
    """
    self.width = width
    self.height = height

    dictionary = cv2.aruco.getPredefinedDictionary(aruco_dict)
    self.board = cv2.aruco.CharucoBoard(self.get_shape(), square_length, marker_length, dictionary)
    self.detector = cv2.aruco.CharucoDetector(
        self.board,
        cv2.aruco.CharucoParameters(),
        cv2.aruco.DetectorParameters(),
    )

width instance-attribute 

width: int = width

The width of the calibration pattern.

height instance-attribute 

height: int = height

The height of the calibration pattern.

board instance-attribute 

board: CharucoBoard = CharucoBoard(
    get_shape(), square_length, marker_length, dictionary
)

The calibration board.

detector instance-attribute 

detector: CharucoDetector = CharucoDetector(
    board, CharucoParameters(), DetectorParameters()
)

The calibration pattern detector.

detect 

detect(image: NDArray[uint8]) -> CalibrationGrid

Detect the ChArUco board in an image.

Parameters:

Name Type Description Default
image NDArray[uint8]

The image to detect the ChArUco board in.

 required

Returns:

Type Description
CalibrationGrid

The corners and ids of the detected ChArUco board.
Source code in src/charucal/pattern.py 
53
54
55
56
57
58
59
60
61
62
63
def detect(self, image: npt.NDArray[np.uint8]) -> CalibrationGrid:
    """Detect the ChArUco board in an image.

    :param image: The image to detect the ChArUco board in.
    :return: The corners and ids of the detected ChArUco board.
    """
    charuco_corners, charuco_ids, _, _ = self.detector.detectBoard(image)
    if charuco_corners is None or charuco_ids is None:
        raise ValueError("Failed to detect ChArUco board")

    return CalibrationGrid.from_corners(self.get_shape(), charuco_corners, charuco_ids)

get_shape 

get_shape() -> tuple[int, int]

Get the shape of the ChArUco board.

Returns:

Type Description
tuple[int, int]

The shape of the ChArUco board.
Source code in src/charucal/pattern.py 
65
66
67
68
69
70
def get_shape(self) -> tuple[int, int]:
    """Get the shape of the ChArUco board.

    :return: The shape of the ChArUco board.
    """
    return self.width, self.height

to_grid 

to_grid() -> CalibrationGrid

Get the grid of the ChArUco board.

Returns:

Type Description
CalibrationGrid

The grid of the ChArUco board.
Source code in src/charucal/pattern.py 
72
73
74
75
76
77
78
79
80
def to_grid(self) -> CalibrationGrid:
    """Get the grid of the ChArUco board.

    :return: The grid of the ChArUco board.
    """
    shape = self.get_shape()
    length = self.board.getSquareLength()

    return CalibrationGrid.from_shape(shape, length)