lensboy 1.0.8

lensboy for camera calibrations

Camera calibration for vision engineers. Maximally powerful, minimally complex.

Supports OpenCV camera models and spline-based distortion models for lenses that OpenCV can't handle.

Quick example

import lensboy as lb

# detect calibration target in images (works with any target — charuco is just a built-in utility)
target_points, frames = lb.extract_frames_from_charuco(board, imgs)

# calibrate
result = lb.calibrate_camera(
    target_points, frames,
    camera_model_config=lb.OpenCVConfig(
        image_height=h, image_width=w, initial_focal_length=1000,
    ),
)

# save
result.optimized_camera_model.save("camera.json")

Need more accuracy? Just swap the config — same API, way more powerful:

result = lb.calibrate_camera(
    target_points, frames,
    camera_model_config=lb.PinholeSplinedConfig(
        image_height=h, image_width=w, initial_focal_length=1000,
    ),
)

Why lensboy

Even for standard OpenCV models, lensboy gives you better calibrations than raw cv2.calibrateCamera, as clearly demonstrated in the model comparison notebook. This is achieved mainly by two means:

• Automatic outlier filtering removes bad detections
• Target warp estimation compensates for non-flat calibration boards

For cheap or wide-angle lenses where OpenCV's polynomial distortion model isn't enough, lensboy offers spline-based distortion models that can capture arbitrary distortion patterns. This approach is inspired by mrcal, but lensboy is designed to be easier to use and trivial to install.

Lensboy also offers strong analysis tools to verify your calibration is actually good. These are demonstrated in the example notebooks.

Install

For calibration time, includes analysis and plotting tools:

pip install lensboy[analysis]

For loading and using the camera models:

pip install lensboy

Getting started

See the quickstart notebook for a full walkthrough covering both OpenCV and spline models.

Spline models

When OpenCV's polynomial distortion model can't fully capture your lens, switch to a spline model. These use B-spline grids instead of polynomial coefficients, and can capture arbitrary distortion patterns.

The calibrated spline model can be converted to a pinhole model with undistortion maps, so you can use it anywhere:

pinhole = spline_model.get_pinhole_model()
undistorted = pinhole.undistort(image)