Robertleoj/lensboy

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.

Many of the techniques in this library were originally developed in mrcal.

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,
    ),
)

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,
    ),
)

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.

Runtime unproject LUTs

Iterative unprojection can be too slow for some applications. UnprojectLUT caches normalize_points() on a regular pixel grid so that per-pixel queries reduce to a bicubic interpolation. The cache is saved as a directory of metadata.json + xy_grid.npy, loadable from Python or from a small standalone C++ runtime in cpp_runtime/.

import lensboy as lb
from lensboy.analysis import compute_lut_error_heatmap

model = lb.OpenCV.load("camera.json")
lut = model.get_unproject_lut(pixel_stride=32)
lut.save("camera_lut/")

runtime_lut = lb.UnprojectLUT.load("camera_lut/")
rays, valid_mask = runtime_lut.normalize_points(pixel_coords)

heatmap = compute_lut_error_heatmap(runtime_lut, model)

See the unproject LUT guide for sizing, interpolation modes, the file format, and the C++ runtime. There is also a runnable Jupyter notebook.