lensboy

PyPI Python License

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.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for robertleoj from gravatar.com robertleoj

Credits

Author: Robert Leo

Requires

Python >=3.11

Provides Extra

analysis

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

lensboy-4.0.3-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.14tmanylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

lensboy-4.0.3-cp314-cp314t-macosx_15_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.14tmacOS 15.0+ ARM64

lensboy-4.0.3-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

lensboy-4.0.3-cp314-cp314-macosx_15_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.14macOS 15.0+ ARM64

lensboy-4.0.3-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

lensboy-4.0.3-cp313-cp313-macosx_15_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.13macOS 15.0+ ARM64

lensboy-4.0.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

lensboy-4.0.3-cp312-cp312-macosx_15_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.12macOS 15.0+ ARM64

lensboy-4.0.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

lensboy-4.0.3-cp311-cp311-macosx_15_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.11macOS 15.0+ ARM64

File details

Details for the file lensboy-4.0.3-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for lensboy-4.0.3-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5a7b91c3a809dc5cb95b257d4a62807caf72312e1e0bb1415f1180c88d81ecf6
MD5 72081a22aab29152b167fe51a0dfaf98
BLAKE2b-256 3f7311937f96f52d537ddbccdbe42a9dafedd43590bfca83ae788fa554b57a39

See more details on using hashes here.

Provenance

The following attestation bundles were made for lensboy-4.0.3-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on Robertleoj/lensboy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lensboy-4.0.3-cp314-cp314t-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for lensboy-4.0.3-cp314-cp314t-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 4d3ecf250dbc19dc358bc04495514e5e18d4c9d3e1c89fd0f56d48e92d596f0b
MD5 993879c283afb1e73643adc90f30e0e1
BLAKE2b-256 8deaceaccf06a45aa62f8c8595cd67df207cd696eab25c8a9253b2828853d8c0

See more details on using hashes here.

Provenance

The following attestation bundles were made for lensboy-4.0.3-cp314-cp314t-macosx_15_0_arm64.whl:

Publisher: wheels.yml on Robertleoj/lensboy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lensboy-4.0.3-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for lensboy-4.0.3-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 0671908486fefe4d56a58e28711fafee0213baa024fa8803a942d41bf942be51
MD5 048b63e945a520643117c8d47f4ee159
BLAKE2b-256 f43e9396d48a66bb683d975627526d45a641a9c2f4ab087c5b610779cdb2915d

See more details on using hashes here.

Provenance

The following attestation bundles were made for lensboy-4.0.3-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on Robertleoj/lensboy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lensboy-4.0.3-cp314-cp314-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for lensboy-4.0.3-cp314-cp314-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 90e9f8a3baf2e35fb097ea52b7c3b8c0465d0ce008c27579b19cb1ff3c7e80a4
MD5 53e54301e9c36290ad147eda9240c443
BLAKE2b-256 1770186d1b18313d3ae419c860ee67948901c65ab6d21016100c89f2b092d96c

See more details on using hashes here.

Provenance

The following attestation bundles were made for lensboy-4.0.3-cp314-cp314-macosx_15_0_arm64.whl:

Publisher: wheels.yml on Robertleoj/lensboy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lensboy-4.0.3-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for lensboy-4.0.3-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 599832910a15b280dafd742e9b4c7177245ba2e390625c0edabaa3926493554d
MD5 5145f49228f867d3fa7ea8f0b3ba9680
BLAKE2b-256 96ecb191cf845a8891c913ffd1ab9b2367d4ae5119fbdcfafb6f5912693e4d56

See more details on using hashes here.

Provenance

The following attestation bundles were made for lensboy-4.0.3-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on Robertleoj/lensboy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lensboy-4.0.3-cp313-cp313-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for lensboy-4.0.3-cp313-cp313-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 79d16832e74c0a9840b9576cc3bfc77140a5b7cb492dcf423829ed9ff3f7615b
MD5 bafdbe8e67bbe4f36c79d2a6a449d3f1
BLAKE2b-256 e0ef8861fd36f7d3cdda1ed870de3f13ac1c456c517f6bfe1ff99242674f8549

See more details on using hashes here.

Provenance

The following attestation bundles were made for lensboy-4.0.3-cp313-cp313-macosx_15_0_arm64.whl:

Publisher: wheels.yml on Robertleoj/lensboy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lensboy-4.0.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for lensboy-4.0.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f908cb5fefa9207a0e4f2bbd10791a615856dcede8ddb0a2ab54e56e768c6575
MD5 c1c2bc1f6680ee5527c06437d1c2f817
BLAKE2b-256 b920d8b99879d4840398fe04a2d10706197d95f44dd0476688e7804e85d0f50e

See more details on using hashes here.

Provenance

The following attestation bundles were made for lensboy-4.0.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on Robertleoj/lensboy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lensboy-4.0.3-cp312-cp312-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for lensboy-4.0.3-cp312-cp312-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 fd0ec588b40acccbe1c0f4222b219d550833c4dd9bdece66c1bf5c4bad7a80b8
MD5 0fae70d3ac2115eca57d870cafc6231d
BLAKE2b-256 955977b14bd920d21075c89788ed061521fba66da64b9492bd3fdb4b69a2f6d0

See more details on using hashes here.

Provenance

The following attestation bundles were made for lensboy-4.0.3-cp312-cp312-macosx_15_0_arm64.whl:

Publisher: wheels.yml on Robertleoj/lensboy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lensboy-4.0.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for lensboy-4.0.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 8a1944e2e5ad7aa1192f147f4ed458d9fd2d7055ebf44d4a6a6f9b1dc090f9eb
MD5 a993aa3bc0cec175800e33b4c68411a7
BLAKE2b-256 0f0d45f02cbb1ca31da4329c7dc9c5d636c0980802ba80f4c931146bbf0baf59

See more details on using hashes here.

Provenance

The following attestation bundles were made for lensboy-4.0.3-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on Robertleoj/lensboy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file lensboy-4.0.3-cp311-cp311-macosx_15_0_arm64.whl.

File metadata

File hashes

Hashes for lensboy-4.0.3-cp311-cp311-macosx_15_0_arm64.whl
Algorithm Hash digest
SHA256 f6221d0edcebcc2bfcfbaf5fd72ae1bbe20c8966ea644540a7e2d274b938d865
MD5 5843e1b891c09b3c578d737370582c80
BLAKE2b-256 a9e2bca8f4f70aba2b779f4b645861461684907b4db4d517d1c2d4c9dd787340

See more details on using hashes here.

Provenance

The following attestation bundles were made for lensboy-4.0.3-cp311-cp311-macosx_15_0_arm64.whl:

Publisher: wheels.yml on Robertleoj/lensboy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

4.0.3 This release

10 files

4.0.2

10 files

4.0.1

10 files

4.0.0

10 files

3.1.0

10 files

3.0.1

10 files

3.0.0

10 files

2.1.5

10 files

2.1.4

6 files

2.1.3

6 files

2.1.2

6 files

2.1.1

6 files

2.1.0

6 files

2.0.0

6 files

1.1.4

6 files

1.1.3

6 files

1.1.2

6 files

1.1.1

6 files

1.1.0

6 files

1.0.8

6 files

1.0.7

6 files

1.0.6

6 files

1.0.5

6 files

1.0.4

6 files

1.0.3

6 files

1.0.2

6 files

1.0.1

6 files

1.0.0

6 files

0.0.1

6 files

0.0.0

6 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page