Database-driven lens corrections with bundled lensfun calibration data

Author: kipcole9

.gitignore

@@ -10,14 +10,53 @@
 # Where third-party dependencies like ExDoc output generated docs.
 /doc/
 
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
+
 # If the VM crashes, it generates a dump, let's ignore it too.
 erl_crash.dump
 
 # Also ignore archive artifacts (built via "mix archive.build").
 *.ez
 
 # Ignore package tarball (built via "mix hex.build").
-image_lens_correction-*.tar
+image-*.tar
 
 # Temporary files, for example, from tests.
 /tmp/
+
+# Validation error images
+/test/support/images/did_not_match
+
+# Mac metadata
+.DS_Store
+
+# Minio
+.minio.sys/
+
+# Performance result images
+test/perf/*.png
+test/perf/*.jpeg
+
+# Local .iex.exs
+.iex.exs
+
+# ML model
+*.pt
+*.onnx
+
+# ASDF
+.tool-versions
+
+# Mise
+mise.toml
+
+# Don't add the lensfun DTD to the repo
+lensfun-database.dtd
+
+# Failed tests
+test/support/did_not_match/
+
+# Claude
+CLAUDE.md
+.claude

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## ImageLensCorrection 0.1.0
+
+This is the initial release of `ImageLensCorrection`, a lens-correction companion package for [`:image`](https://hex.pm/packages/image).
+
+### Features
+
+* **Radial distortion correction** for the lensfun `:ptlens`, `:poly3` and `:poly5` models. Each model is inverted per pixel via six iterations of Newton's method evaluated as `libvips` arithmetic on the radius image — no per-pixel branching, no NIF callouts. Standalone entry points `Image.LensCorrection.radial_distortion_correction/4`, `Image.LensCorrection.poly3_correction/2` and `Image.LensCorrection.poly5_correction/3`, plus `Image.LensCorrection.apply_distortion/2` for the lensfun-shaped `%{model:, terms:}` map.
+
+* **Vignetting correction** via the lensfun `:pa` model, inverted analytically. `Image.LensCorrection.vignette_correction/4` takes raw `k1, k2, k3`; `Image.LensCorrection.apply_vignetting/2` accepts the interpolated map.
+
+* **Lateral chromatic aberration (TCA) correction** via the lensfun `:linear` and `:poly3` models. `Image.LensCorrection.Tca` decomposes the input into bands, remaps the red and blue channels per channel, leaves green as the reference, and rejoins. RGBA inputs preserve their alpha channel.
+
+* **Geometric projection** between `:rectilinear`, `:fisheye` and `:equirectangular` projections, plus a `Image.LensCorrection.Geometry.focal_length_in_pixels/3` helper that derives the pixel focal length from the focal length in millimetres, the camera's crop factor and the image's diagonal.
+
+* **EXIF-driven correction pipeline** — `Image.LensFun.Correct.correct/2` reads the camera and lens identification, focal length, aperture and (where available) focus distance from the input image's EXIF metadata, looks the lens up in the bundled lensfun database, interpolates the calibration to the image's focal length and aperture, rescales coefficients to the camera's crop factor and applies all enabled corrections in one pipeline. Every parameter is overridable via options for images that lack EXIF metadata.
+
+* **Bundled lensfun database** — `priv/lensfun/lensfun.etf` (~5 MB) covers 1013 camera bodies and 1459 lens calibration sets across the lensfun XML database. Decoded once into a `:persistent_term` cache on first use. Rebuildable from a lensfun checkout via `Image.LensFun.Importer.import/1`.
+
+* **Database lookup primitives** — `Image.LensFun.find_lens/3` (case-insensitive maker matching, fuzzy substring fallback for the model, optional crop-factor narrowing), `Image.LensFun.find_camera/2`, `Image.LensFun.interpolate_distortion/2` (Catmull-Rom Hermite spline matching lensfun's `lfLens::InterpolateDistortion`), `Image.LensFun.interpolate_vignetting/4` (inverse-distance weighting over focal length, aperture and focus distance with `p = 3.5`, matching lensfun's `lfLens::InterpolateVignetting`), `Image.LensFun.interpolate_tca/2`, and `Image.LensFun.metrics_from_exif_and_options/2` for unified EXIF + options metric resolution.
+
+* **Coefficient rescaling** — `Image.LensCorrection.rescale_coefficients/4` implements lensfun's `rescale_polynomial_coefficients` so calibration coefficients can be applied to images captured on a different sensor than the one the lens was calibrated against.
+
+* **Database lens search** — `Image.LensFun.search_lenses/2` performs free-form, word-by-word, case-insensitive lookup across the bundled database with `:maker`, `:limit` and `:has` (capability) filters.
+
+### Notes
+
+* The Adobe Camera Model (`acm`) variants of the lensfun distortion, vignetting and TCA models are not supported. As of the current lensfun release no calibration record in the upstream XML database uses `acm`, and upstream lensfun itself does not implement reverse ACM correction. `apply_distortion/2`, `apply_vignetting/2` and `Tca.apply_tca/2` return a clear `{:error, {:unsupported_*_model, ...}}` tuple if given an ACM map.

LICENSE.md

@@ -0,0 +1,28 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Kip Cole
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+## Bundled lensfun calibration data
+
+The Erlang term file `priv/lensfun/lensfun.etf` is generated from the
+[lensfun](https://github.com/lensfun/lensfun) project's XML calibration
+database. That database is distributed under the
+[Creative Commons Attribution-ShareAlike 3.0 Unported License](https://creativecommons.org/licenses/by-sa/3.0/).
+
+The lensfun reference C library is licensed under LGPL v3. This
+package does not link to or distribute that library; it re-implements
+the calibration math in Elixir.

README.md

@@ -1,11 +1,30 @@
 # ImageLensCorrection
 
-**TODO: Add description**
+`ImageLensCorrection` provides corrections for the four most common camera-lens defects — radial (barrel/pincushion) distortion, vignetting, lateral chromatic aberration (TCA), and geometric projection — for images created or processed with the [`:image`](https://hex.pm/packages/image) library. Calibration coefficients come from the [`lensfun`](https://github.com/lensfun/lensfun) project's community-maintained database, which is bundled with the package as a compact ~5 MB Erlang term file covering 1000+ camera bodies and 1400+ lenses.
+
+Corrections are evaluated as `libvips` arithmetic expressions on top of `Vix`, so every correction stays inside the Vix pipeline; no external C library is required at runtime.
+
+Documentation can be found at <https://hexdocs.pm/image_lens_correction>.
+
+## Features
+
+* **Radial distortion correction** — implements the lensfun `:ptlens`, `:poly3` and `:poly5` models, all inverted per pixel via Newton's method evaluated as `libvips` arithmetic.
+
+* **Vignetting correction** — implements the lensfun `:pa` model `Cd = Cs * (1 + k1*r² + k2*r⁴ + k3*r⁶)`, inverted analytically.
+
+* **Lateral chromatic aberration (TCA)** — implements the lensfun `:linear` and `:poly3` TCA models. The image is decomposed into bands, red and blue are remapped per channel via `mapim`, green is taken as the reference, and RGBA inputs preserve their alpha channel.
+
+* **Geometric projection** — converts between `:rectilinear`, `:fisheye` and `:equirectangular` projections.
+
+* **EXIF-driven, one-call correction** — `Image.LensFun.Correct.correct/2` reads camera and lens metadata from the image's EXIF tags, looks the lens up in the bundled database, interpolates the calibration to the image's focal length and aperture, rescales coefficients to the camera's crop factor, and applies the requested corrections in one pipeline. Every EXIF tag is overridable via options for images that lack metadata.
+
+* **Database lookup primitives** — `Image.LensFun.find_lens/3`, `Image.LensFun.find_camera/2`, `Image.LensFun.interpolate_distortion/2`, `Image.LensFun.interpolate_vignetting/4` and `Image.LensFun.interpolate_tca/2` for direct programmatic access to the bundled calibration data, with case-insensitive maker matching, fuzzy-substring lens-model matching and crop-factor-narrowing.
+
+* **Bundled calibration database** — `priv/lensfun/lensfun.etf` is generated from the lensfun XML database at build time and decoded once into a `:persistent_term` cache on first use.
 
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `image_lens_correction` to your list of dependencies in `mix.exs`:
+The package can be installed by adding `image_lens_correction` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
@@ -15,7 +34,94 @@ def deps do
 end
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at <https://hexdocs.pm/image_lens_correction>.
+## Usage
+
+### One-shot correction from EXIF
+
+For an image whose EXIF metadata identifies the camera and lens, all available corrections (distortion, vignetting and TCA) can be applied with a single call:
+
+```elixir
+{:ok, image}     = Image.open("photo.jpg")
+{:ok, corrected} = Image.LensFun.Correct.correct(image)
+```
+
+For an image without complete EXIF metadata, supply the missing parameters as options. Every parameter that `correct/2` reads from EXIF is overridable:
+
+```elixir
+{:ok, corrected} =
+  Image.LensFun.Correct.correct(image,
+    make: "Canon",
+    model: "Canon EOS 5D Mark III",
+    lens_make: "Canon",
+    lens_model: "Canon EF 100mm f/2.8 Macro USM",
+    focal_length: 100.0,
+    aperture: 5.6
+  )
+```
+
+The `:corrections` option selects which corrections to run; the default is `[:distortion, :vignetting, :tca]`. Projection conversion is opt-in (since it changes the field of view) via `corrections: [:projection]` and an optional `:target_projection`.
+
+### Direct correction with explicit coefficients
+
+When you have your own calibration data — or you're experimenting — each model is exposed as a standalone function that takes raw coefficients in the Hugin coordinate convention (`r = 1` at the half short-edge for distortion / TCA / projection, `r = 1` at the corner for vignetting):
+
+```elixir
+# ptlens distortion (Hugin form)
+{:ok, image} = Image.LensCorrection.radial_distortion_correction(image, -0.0077, 0.087, 0.0)
+
+# poly3 distortion
+{:ok, image} = Image.LensCorrection.poly3_correction(image, -0.005)
+
+# poly5 distortion
+{:ok, image} = Image.LensCorrection.poly5_correction(image, -0.005, 0.001)
+
+# Vignetting (Adobe Camera Model "pa")
+{:ok, image} = Image.LensCorrection.vignette_correction(image, -0.2764, -1.26031, 0.7727)
+
+# Linear TCA
+{:ok, image} = Image.LensCorrection.Tca.linear_tca_correction(image, 1.0004, 1.0002)
+
+# Fisheye → rectilinear
+focal = Image.LensCorrection.Geometry.focal_length_in_pixels(8.0, 1.5, 5000.0)
+{:ok, image} = Image.LensCorrection.Geometry.fisheye_to_rectilinear(image, focal)
+```
+
+### Database lookup
+
+```elixir
+# Find a lens (case-insensitive maker, fuzzy-substring model)
+{:ok, lens} = Image.LensFun.find_lens("Canon", "Canon EF 100mm f/2.8 Macro USM")
+
+# Interpolate the calibration to a specific focal length
+{:ok, distortion} = Image.LensFun.interpolate_distortion(lens, 100.0)
+
+# Vignetting needs focal length, aperture and focus distance
+{:ok, vignetting} = Image.LensFun.interpolate_vignetting(lens, 100.0, 5.6, 1000.0)
+
+# TCA needs focal length only
+{:ok, tca} = Image.LensFun.interpolate_tca(lens, 100.0)
+
+# Apply the result
+{:ok, image} = Image.LensCorrection.apply_distortion(image, distortion)
+{:ok, image} = Image.LensCorrection.apply_vignetting(image, vignetting)
+{:ok, image} = Image.LensCorrection.Tca.apply_tca(image, tca)
+```
+
+## Background
+
+The lens defects this library corrects, the mathematical models it uses, and the relationship to the upstream lensfun project are described in detail in the [Lens corrections guide](guides/lens_corrections.md).
+
+## Rebuilding the bundled database
+
+```sh
+git clone https://github.com/lensfun/lensfun ../lensfun
+mix run -e 'Image.LensFun.Importer.import()'
+```
+
+## Attribution
+
+This library re-implements the calibration math and bundles a snapshot of the calibration data from [the lensfun project](https://github.com/lensfun/lensfun). Lens calibration data is distributed under [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/); the lensfun reference C library is LGPL v3 (this library does not link to or distribute it).
+
+## License
 
+`ImageLensCorrection` is licensed under the [Apache 2.0 License](LICENSE.md).