Metadata-Version: 2.4
Name: opencv-chessboard-generator
Version: 1.1.1
Summary: Generate print-accurate checkerboard targets for OpenCV camera calibration
Author-email: Batuhan ÖKMEN <batuhanokmen@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/flavvesResearch/chessboard-calibration-generator
Project-URL: Bug Reports, https://github.com/flavvesResearch/chessboard-calibration-generator/issues
Project-URL: Source, https://github.com/flavvesResearch/chessboard-calibration-generator
Keywords: opencv,camera calibration,camera-calibration,checkerboard,chessboard,calibration target,calibration pattern,pattern generator,stereo calibration,intrinsic calibration,extrinsic calibration,computer vision,printable checkerboard,printable chessboard
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: Pillow>=9.0
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy<2.0,>=1.10; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Dynamic: license-file

# OpenCV Chessboard Generator

[![PyPI version](https://badge.fury.io/py/opencv-chessboard-generator.svg)](https://pypi.org/project/opencv-chessboard-generator/)
[![Python versions](https://img.shields.io/pypi/pyversions/opencv-chessboard-generator.svg)](https://pypi.org/project/opencv-chessboard-generator/)
[![CI](https://github.com/flavvesResearch/chessboard-calibration-generator/actions/workflows/ci.yml/badge.svg)](https://github.com/flavvesResearch/chessboard-calibration-generator/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

![Generated calibration checkerboard](https://raw.githubusercontent.com/flavvesResearch/chessboard-calibration-generator/main/docs/example-board.svg)

## Install

```bash
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:

```bash
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:

```bash
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.

```bash
# 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.

```bash
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:

```bash
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

```text
--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

```python
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:

```python
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:

```python
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:

```python
import cv2

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

## Development

```bash
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](LICENSE) © Batuhan ÖKMEN
