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

One job: fit camera models and verify the results. OpenCV models when they work, spline-based distortion when they don't.

Why lensboy

Even for standard OpenCV models, lensboy gives you better calibrations than raw cv2.calibrateCamera (see model comparison notebook):

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

For cheap or wide-angle lenses where OpenCV's distortion model isn't enough, lensboy offers spline-based models that can capture arbitrary distortion patterns.

Lensboy also offers analysis tools to verify your calibration is actually good.

Quick example

import lensboy as lb

target_points, frames, image_indices = lb.extract_frames_from_charuco(board, imgs)

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

result.camera_model.save("camera.json")

Swap the config for a spline model — same API, more flexible:

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

Getting started

Read the calibration guide for a full walkthrough - calibrating a camera, verifying the results, and exporting for runtime use.

If you just want to see lensboy in action, see quickstart notebook.

Analysis tools

Plots for residuals, distortion, detection coverage, and model differencing. See the example notebooks.

Install

Full install, with analysis and plotting:

pip install lensboy[analysis]

Minimal install, for loading and using models:

pip install lensboy

Spline models

Spline models use B-spline grids instead of polynomial coefficients, so they can fit lenses that OpenCV's model can't. This approach is inspired by mrcal.

The calibrated model converts to a pinhole model with undistortion maps, so you can use it with any standard pinhole pipeline.