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.
1 maintainer
Metadata
1 maintainer
Release files for lensboy 4.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 14.5 MB
Release files / lensboy-4.0.3-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | lensboy-4.0.3-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.14 CPython 3.14 free-threading Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
5a7b91c3a809dc5cb95b257d4a62807caf72312e1e0bb1415f1180c88d81ecf6
|
|
BLAKE2b-256 checksum How to use checksums |
3f7311937f96f52d537ddbccdbe42a9dafedd43590bfca83ae788fa554b57a39
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / lensboy-4.0.3-cp314-cp314t-macosx_15_0_arm64.whl
| Download URL | lensboy-4.0.3-cp314-cp314t-macosx_15_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.14 CPython 3.14 free-threading macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
4d3ecf250dbc19dc358bc04495514e5e18d4c9d3e1c89fd0f56d48e92d596f0b
|
|
BLAKE2b-256 checksum How to use checksums |
8deaceaccf06a45aa62f8c8595cd67df207cd696eab25c8a9253b2828853d8c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / lensboy-4.0.3-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | lensboy-4.0.3-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.14 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
0671908486fefe4d56a58e28711fafee0213baa024fa8803a942d41bf942be51
|
|
BLAKE2b-256 checksum How to use checksums |
f43e9396d48a66bb683d975627526d45a641a9c2f4ab087c5b610779cdb2915d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / lensboy-4.0.3-cp314-cp314-macosx_15_0_arm64.whl
| Download URL | lensboy-4.0.3-cp314-cp314-macosx_15_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.14 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
90e9f8a3baf2e35fb097ea52b7c3b8c0465d0ce008c27579b19cb1ff3c7e80a4
|
|
BLAKE2b-256 checksum How to use checksums |
1770186d1b18313d3ae419c860ee67948901c65ab6d21016100c89f2b092d96c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / lensboy-4.0.3-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | lensboy-4.0.3-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
599832910a15b280dafd742e9b4c7177245ba2e390625c0edabaa3926493554d
|
|
BLAKE2b-256 checksum How to use checksums |
96ecb191cf845a8891c913ffd1ab9b2367d4ae5119fbdcfafb6f5912693e4d56
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / lensboy-4.0.3-cp313-cp313-macosx_15_0_arm64.whl
| Download URL | lensboy-4.0.3-cp313-cp313-macosx_15_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.13 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
79d16832e74c0a9840b9576cc3bfc77140a5b7cb492dcf423829ed9ff3f7615b
|
|
BLAKE2b-256 checksum How to use checksums |
e0ef8861fd36f7d3cdda1ed870de3f13ac1c456c517f6bfe1ff99242674f8549
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / lensboy-4.0.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | lensboy-4.0.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
f908cb5fefa9207a0e4f2bbd10791a615856dcede8ddb0a2ab54e56e768c6575
|
|
BLAKE2b-256 checksum How to use checksums |
b920d8b99879d4840398fe04a2d10706197d95f44dd0476688e7804e85d0f50e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / lensboy-4.0.3-cp312-cp312-macosx_15_0_arm64.whl
| Download URL | lensboy-4.0.3-cp312-cp312-macosx_15_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.12 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
fd0ec588b40acccbe1c0f4222b219d550833c4dd9bdece66c1bf5c4bad7a80b8
|
|
BLAKE2b-256 checksum How to use checksums |
955977b14bd920d21075c89788ed061521fba66da64b9492bd3fdb4b69a2f6d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / lensboy-4.0.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | lensboy-4.0.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
8a1944e2e5ad7aa1192f147f4ed458d9fd2d7055ebf44d4a6a6f9b1dc090f9eb
|
|
BLAKE2b-256 checksum How to use checksums |
0f0d45f02cbb1ca31da4329c7dc9c5d636c0980802ba80f4c931146bbf0baf59
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / lensboy-4.0.3-cp311-cp311-macosx_15_0_arm64.whl
| Download URL | lensboy-4.0.3-cp311-cp311-macosx_15_0_arm64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.11 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
f6221d0edcebcc2bfcfbaf5fd72ae1bbe20c8966ea644540a7e2d274b938d865
|
|
BLAKE2b-256 checksum How to use checksums |
a9e2bca8f4f70aba2b779f4b645861461684907b4db4d517d1c2d4c9dd787340
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logSecurity for lensboy 4.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 10 files in this release have been uploaded with provenance metadata.
Attestation for lensboy-4.0.3-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
