Lensfun: a shared database of lens profiles for correcting distortion and vignetting

What Lensfun is: a profile database and the maths to use it

The stated goal of the project is to provide an open source database of photographic lenses and their characteristics. That sounds like a data file with a search function, and it is more than that. The library provides a way to read the database and search for specific things in it, and it also provides a set of algorithms for correcting images based on detailed knowledge of lens properties.

The corrections it currently handles are distortion, transversal chromatic aberration, also called lateral chromatic aberration, and vignetting. Distortion is the geometric bending of straight lines toward the frame edges. Lateral chromatic aberration is the colour fringing that appears away from the centre because the lens focuses different wavelengths at different distances. Vignetting is the darkening of the frame corners. All three are lens-specific, which is exactly why a database of lens characteristics is the input the algorithms need.

The interface is defined both in C++ style and in plain C, and the C interface is a wrapper around the C++ classes. That dual interface is the practical reason to care about the library at all. A modern image application is C++ and can use the classes directly, but the applications shipped in the package and third-party tools in the Unix world are often C, and a C wrapper lets them share the same database and the same corrections without binding to a C++ ABI.

The project page is at lensfun.github.io and the code lives on GitHub under the lensfun organisation.

Where the data came from: PTLens, a commercial detour and an XML rewrite

The history in the README explains more about the project's character than any feature list would.

There was an earlier effort in the same direction, and the README links it, a project called PTLens hosted at epaperpress.com. Its author eventually took the commercial route, and the database froze at the last public stage. The current Lensfun database grew on the basement of that earlier database, with the PTLens author giving permission for it, while the code was rewritten from scratch and the database converted to a totally new XML-based format.

That origin story explains two things you can see in the repository. First, the data lineage is acknowledged rather than hidden, and the credits list Tom Niemann as the provider of the original open-source ptlens database, with the suggestion for an open-source lens database credited to Pablo d'Angelo. The mathematics and knowledge behind the panorama and lens tooling come from the PanoTools team, a list of names the README credits individually.

Second, the XML-based format is a deliberate design decision rather than an accident of the era. GLib is used for the XML parsing, and xmllint is listed among the build tools specifically to test the validity of the database XML. A database that people are expected to extend by contributing profiles has to be diffable and mergeable, and XML with a validating parser is a reasonable way to get there.

The code itself is credited to Andrew Zabolotny, and the README ends with thanks to the many people sending profiles for the database, which is how a community profile database is actually populated.

Building it with CMake, and what you need installed first

The build system is CMake, and the README lists the tools required to configure and build successfully.

The list is short but real. CMake is the build system itself. Doxygen generates the library documentation. GLib above version 2.26 is used for low-level I/O and XML parsing, and GLib above version 2.40 is needed to build the unit tests with the GLib test framework. libpng is required to build and run the example implementation, and xmllint is used to test the database XML validity.

The sequence is a standard out-of-source CMake build. You enter the root folder and create a build directory:

cd lensfun
mkdir build

Then you enter the build directory and configure:

cd build
cmake ../

After that it is make and make install as usual:

make
make install

The README then notes that you may want to use ldconfig to add the necessary symlinks so that programs can find and use Lensfun once it is installed.

The configuration options are worth reading before a first build. CMAKE_BUILD_TYPE selects debug or release. INSTALL_HELPER_SCRIPTS controls whether various helper scripts get installed, and CMAKE_INSTALL_PREFIX sets the install prefix. BUILD_STATIC chooses a static or shared library, BUILD_TESTS controls the test programs, BUILD_LENSTOOL builds the Lensfun reference implementation, BUILD_FOR_SSE and BUILD_FOR_SSE2 enable the SIMD optimisations, and BUILD_DOC builds the documentation. There are also CPACK_BINARY_DEB and CPACK_BINARY_RPM options for producing packages, though the README says that path is not extensively tested.

One practical warning is worth repeating: running cmake again does not reset options to their defaults, so a clean reconfiguration means deleting the files in the build folder.

Three licences in one package, and they do not say the same thing

The licensing section is the most consequential part of the README for anyone planning to ship this in a product, and it splits the package into parts with genuinely different terms.

The libraries under libs/ are licensed under the GNU Lesser General Public License version 3, with the text in COPYING.LESSER. The documentation files, including the ones autogenerated with Doxygen, are covered by the same LGPL version 3.

The applications under apps/ are licensed under the GNU General Public License version 3, with the text in COPYING. This is the arrangement that lets a dynamic-linking library be used inside proprietary software while the applications that ship with it remain copyleft. If you link against the library, the LGPL terms apply to the library, and the distinction matters when you decide whether to ship your own tools alongside it.

The test programs under tests/ and the tools under tools/ are put into the public domain unless explicitly specified otherwise in the header of the source files. The README's wording is precise about where the exception applies, which is a header comment rather than a general rule, so it is worth checking a specific file rather than assuming.

The lens database under data/ is licensed separately again, under Creative Commons Attribution-Share Alike 3.0, with the text in data/COPYING.CC-BY-SA_3.0. This is the part that surprises people. The database is a data set contributed by many people and it carries a share-alike obligation, so redistributing a derived database carries requirements that the LGPL on the code does not. You can read the terms at the Creative Commons link given in the README, and the licence file in the repository is the authoritative copy.

The data directory, the update script and the reference implementation

The source package is organised so that each kind of file has a home, and the top level of the repository shows the shape.

Under data/ sits the lens database itself, in the XML format the project settled on. Under libs/ are the libraries, under apps/ the applications, under tests/ the test programs and under tools/ the tools that are in the public domain. include/ holds the public headers, cmake/ the build modules, and docs/ the documentation sources. Two directory names, berlios-archive/ and sourceforge-archive/, show where the project lived before it moved to GitHub, which is a reminder that this codebase predates the current hosting arrangements.

Two applications are named in the README and worth knowing about.

The first is the reference implementation, controlled by the BUILD_LENSTOOL option and referred to as the Lensfun reference implementation. It is the program that demonstrates what the library can do, and because it is under the GPL rather than the LGPL, it is also the part of the package you should treat most carefully if you plan to reuse its code in something of your own.

The second is apps/lensfun-update-data, the script that pulls in new profiles from the network, and it has a dependency that is easy to miss. The README notes that Certificate Authorities' certificates have to be available on the system in order to run it. On a minimal container image or a system with an outdated CA bundle, that script will fail on TLS verification rather than on anything specific to Lensfun.

For reference, the end-user documentation can be built locally with make docs, and it is also published online at the manual URL given in the README, where the site is rebuilt every night from Git so it tracks the current state of the library.

Limits: three correction types, an old release tag and a data set you do not control

The scope of the library is stated plainly in the README and it is narrower than the word lens correction implies. Right now Lensfun is designed to correct distortion, transversal chromatic aberration and vignetting. It does not mention other corrections that a commercial raw converter might offer, and the phrasing leaves no room for reading more into it.

The release history is the second limit. The tagged versions are v0.3.4 from 2023-07-12, its release candidate v0.3.4-RC1 from 2023-01-01, and v0.3.3 from 2022-02-22. Meanwhile the last push to the repository was on 2026-10-19 and the continuous integration badges cover Linux, macOS, MSYS2 and Windows, so the code is still being worked on and tested across four environments. The gap between an active master branch and a three-year-old tag is the situation you get with a library that is consumed as a system package more often than from a release tarball. Anyone needing a reproducible build should pin a commit rather than assume the tag is current.

The third limit is the one that comes with the data. The database is a community artefact: profiles are sent in by users, and the README thanks the people sending profiles. That means coverage is uneven in a way the software cannot fix, and it means the database carries a share-alike licence that a project depending on it inherits in part. A lens you own may simply not be in there, and if it is, its parameters were measured by a stranger rather than by the manufacturer.

For the same reason, the library is not a substitute for calibration. It applies a model of a lens to a file, and a model is only as good as the data behind it and the distance between that lens and the one being corrected.

Lensfun against built-in correction in an image editor and against the commercial route

Two comparisons matter, and they sit on different axes.

The first is against the lens correction built into a photo application or raw converter. Those tools ship their own tables of lens profiles, usually tied to the versions of the software that include them, and they correct with no library dependency at all. The difference in approach is ownership. An application's built-in correction is tuned to that application's pipeline and its own profile format, and it is updated when the application is updated. Lensfun is a shared, system-level component with a database and an API that several applications can point at, which means a correction applied in one tool matches a correction applied in another.

That shared property also cuts the other way. Because the database is open and XML, you can add a profile for a lens that no one has submitted and keep it in your own tree. An application's built-in table gives you no such route unless the vendor accepts the profile. And because the library is LGPL with a separate GPL for the shipped tools, you can build your own application around the library and choose your own licence for it.

The second comparison is against the commercial route the README describes. The predecessor project, PTLens, took its database commercial and the open data froze at the last public stage. That history is the clearest argument for the open model: a lens database is a corpus that grows through contributions, and a corpus that stops growing stops matching the cameras and lenses actually in use. Lensfun's answer is to keep the data open under a share-alike licence and the code LGPL, so the corpus can be extended and the corrections can be applied by any program.

The honest limit on that argument is the same as before. An open corpus is only as good as its coverage and its accuracy, and it is maintained by people measuring lenses with their own equipment. The commercial route can commission proper measurements; the open route relies on the community. Which one you want is a question about your tolerance for a wrong correction, not about the licence.

Editorial conclusion

Adopt Lensfun when you are writing image processing software that needs lens distortion, chromatic aberration and vignetting correction against a shared, community-maintained profile database rather than a private table of lens data. Do not expect a stable release train, since the newest tag is v0.3.4 from 2023-07-12 while development has continued into 2026, so pin a commit if you need reproducibility. Verify first that the specific lens you care about has a profile in the data directory, that your build links GLib, and that you have read the three separate licences covering the libraries, the applications and the database.

Frequently asked questions

Official sources

1. lensfun/lensfun on GitHub
2. License: LGPL-3.0
3. Project website
4. README
5. Releases