OpenCV Chessboard Generator

Generate print-accurate checkerboard calibration targets for OpenCV camera, stereo, intrinsic, and extrinsic calibration.

Install

pip install opencv-chessboard-generator

OpenCV is not required to generate a target. The lightweight runtime dependencies are NumPy and Pillow.

Quick start

Create a vector PDF on A3 landscape paper:

opencv-chessboard-generator \
  --cols 9 \
  --rows 6 \
  --square-size 30 \
  --unit mm \
  --paper A3 \
  --orientation landscape \
  --format pdf \
  --output board.pdf

The shorter command alias works too:

chessboard-generator --help

--cols and --rows always describe inner corners, not squares. A target with 9 × 6 inner corners has 10 × 7 squares. With 30 mm squares, its active board area is 300 × 210 mm.

Running either command without arguments starts the interactive mode.

Output formats

The same physical board definition can be saved in three formats:

• PDF — exact vector geometry and a physical page size; preferred for printing.
• SVG — exact vector geometry with mm dimensions; ideal for editing or professional print workflows.
• PNG — includes DPI metadata. A warning reports any sub-pixel physical size difference caused by raster rounding.

# PNG with embedded 300 DPI metadata
opencv-chessboard-generator \
  --cols 9 --rows 6 --square-size 30 --unit mm \
  --dpi 300 --format png --output board.png

# Content-sized SVG
opencv-chessboard-generator \
  --cols 9 --rows 6 --square-size 30 --unit mm \
  --format svg --output board.svg

Supported units are mm, cm, and inch. The default border is always 10 mm. When --border is supplied, it uses the selected --unit.

Paper size and overflow protection

Supported page sizes are A4, A3, A2, Letter, Legal, and Custom. The generator checks the active board, physical border, and optional information strip before writing a file. It never silently scales a target.

opencv-chessboard-generator \
  --cols 9 --rows 6 --square-size 3 --unit cm \
  --border 1 \
  --paper A3 --orientation landscape \
  --format pdf --output board-a3.pdf

For custom paper, width and height use the selected unit:

opencv-chessboard-generator \
  --paper Custom --page-width 500 --page-height 350 \
  --orientation landscape --unit mm \
  --format svg --output custom-board.svg

If a target does not fit, the error includes both required and available dimensions. --allow-overflow is available for deliberate clipping, but no automatic shrinking is performed.

For A3 landscape with the default 10 mm border, a 9 × 6 inner-corner target with 30 mm squares fits safely (required size: 320 × 230 mm). The older 13 × 8 recommendation did not fit once its border was included and should not be used at that square size.

Useful options

--invert                 Make the top-left square black
--black-value 0          Set the dark grayscale value
--white-value 255        Set the light grayscale value
--color-mode L|RGB       Select grayscale or RGB PNG output
--show-info              Add a separate 18 mm information strip
--no-border              Omit the white border
--preview                 Open a local preview before saving
--no-preview              Skip preview in interactive mode
--allow-overflow         Permit deliberate page clipping

Run opencv-chessboard-generator --help for the complete reference.

Python API

from chessboard_generator import ChessboardGenerator

generator = ChessboardGenerator(
    rows=6,
    cols=9,
    square_size=30,
    unit="mm",
    border=10,
    dpi=300,
)

generator.save(
    "calibration-board.pdf",
    paper="A3",
    orientation="landscape",
)
generator.save("calibration-board.svg")
generator.save("calibration-board.png")

You can also define a custom page explicitly:

from chessboard_generator import ChessboardGenerator, PageSpec

page = PageSpec(width_mm=500, height_mm=350, orientation="landscape")
generator = ChessboardGenerator(rows=6, cols=9, square_size=30, unit="mm")
generator.save("custom.pdf", paper=page)

Compatibility with 1.0

The original centimetre-based constructor remains available for one deprecation cycle:

generator = ChessboardGenerator(
    rows=6,
    cols=9,
    square_size_cm=3.0,
    dpi=300,
)

square_size_cm, add_border_and_info(), and save(..., add_info=...) emit DeprecationWarning. New code should use square_size/unit, add_border(), and add_border.

Printing instructions

For accurate calibration:

1. Print at 100% or Actual Size.
2. Disable Fit to Page and Shrink Oversized Pages.
3. Measure several squares after printing, in both directions.
4. Mount the target on a flat, rigid surface.
5. Do not use a visibly warped or flexible target.

Türkçe: %100 veya Gerçek Boyut ile yazdırın; Sayfaya Sığdır ve otomatik küçültme seçeneklerini kapatın. Baskıdan sonra farklı bölgelerdeki kareleri cetvelle ölçün ve tahtayı düz, rijit bir yüzeye sabitleyin.

For OpenCV, keep the same inner-corner order:

import cv2

pattern_size = (9, 6)  # columns, rows
found, corners = cv2.findChessboardCorners(image, pattern_size)

Development

python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check .
python -m black --check .
python -m mypy chessboard_generator
python -m build
python -m twine check dist/*

Publishing is intentionally separate from CI. A single GitHub Actions workflow publishes only after a GitHub Release is marked as published and its tag matches the version in pyproject.toml.

License

MIT © Batuhan ÖKMEN