mirror of
https://github.com/storytold/lightcraft.git
synced 2026-11-22 02:12:32 +01:00
101 lines
8.2 KiB
Markdown
101 lines
8.2 KiB
Markdown
# Lens profiles from a lens database
|
|
|
|
Raws that carry no lens correction of their own (DNG `OpcodeList3`, or a camera correction a raw reader converts,
|
|
see [sony-lens-corrections.md](sony-lens-corrections.md) and [nikon-lens-corrections.md](nikon-lens-corrections.md)) are corrected from a **lens database in the lensfun
|
|
XML format**. The app does not ship any lens database: lensfun's data is licensed CC BY-SA 3.0 and is downloaded at
|
|
run time, never bundled and never committed. Adobe LCP profiles are never used.
|
|
|
|
## Setup: one click
|
|
|
|
1. Nothing is downloaded without the user's click. On the first launch the desktop app asks once: "Download lens
|
|
profiles? LightCraft can correct distortion and vignetting for many lenses using the open lens database
|
|
(lensfun, about N MB)", with **Download** and **Not Now** (N is the pinned files' sizes added up). Not Now (or
|
|
Esc) downloads nothing and the app doesn't ask again; Settings ▸ General ▸ Lens profiles has **Download Lens
|
|
Database** and a switch that turns the offer back on. The answer is kept with the app's settings (`ui.json`,
|
|
`lensDatabase`: `ask` / `accepted` / `declined`; a value it can't read asks again), and
|
|
`lensfun_download::fetch_on_start` is the one place that decides. After a yes, a start that finds the database
|
|
missing or from an older pin downloads it again (an interrupted download resumes).
|
|
Download fetches lensfun's `data/db` (56 XML files, about 5 MB) into the app's data folder
|
|
(`<config dir>/lensfun`, beside the face and denoise models; see `crates/engine/src/config.rs`), with a row in
|
|
the activity stack (its ✕ stops it). The files are pinned to one lensfun commit by name,
|
|
size and SHA-256 (`crates/engine/src/lensfun_download.rs`); a file that differs is thrown away. A later build with
|
|
a newer pin replaces them once. The files are staged in `<config dir>/lensfun.download`, `SOURCE.txt` (the commit
|
|
and the licence) is written there last, and the staged folder then replaces the old one as a whole: until it is
|
|
in place the previous complete database is used, and if the swap fails it is put back. The app's folder is read
|
|
only when it has `SOURCE.txt`, and a folder whose pinned files are missing or cut short is downloaded again.
|
|
The CLI (`render`, `merge`, `snapshot`) and the headless MCP server read this folder too, but never ask and never
|
|
fetch on their own; `lens.downloadDatabase` fetches it on request from any of them.
|
|
2. By default the files come from lensfun's GitHub repository at the pinned commit. `LIGHTCRAFT_LENSFUN_URL` lists
|
|
other places serving the same files (base URLs, tried first), e.g. a copy on LightCraft's own server.
|
|
3. `LIGHTCRAFT_LENSFUN_DIR` points at a database of your own instead (lensfun's `data/db`, or a Linux
|
|
distribution's `/usr/share/lensfun/version_1/`); then the app doesn't offer the download, and that folder is read
|
|
even after `lens.downloadDatabase` fetches the app's own copy.
|
|
|
|
When the database arrives (or changes), every library raw without a profile whose lens it knows is read again in the
|
|
background and gets its profile; a photo still as imported gets the correction switched on, as import would, and an
|
|
edited one keeps its settings. When a download replaced the database's files, the raws whose profile came from the
|
|
old database are read again too (they get the new profile, or lose one it no longer gives), and so are raws whose
|
|
file named no lens at import. Ticking **Enable Lens Corrections** on a photo without a profile looks it up again
|
|
too. `library.refreshLensProfiles` (`all: true` for the wider pass), `lens.downloadDatabase` (which also selects the
|
|
downloaded folder) and `lens.databaseStatus` do the same for agents.
|
|
|
|
A database profile is pinned to the photo: every render (fresh decode, cached preview, thumbnail, export) uses the
|
|
profile the catalog holds, never one a decode looked up in a newer database, and the profile is part of the render
|
|
and thumbnail cache keys, so a changed profile never shows an old cached render. A file's own correction comes from
|
|
the file as before.
|
|
|
|
The Optics panel says which profile is loaded: "Profile: from the file", "Profile: <lens> (lens database)", or
|
|
"No lens profile found for <lens>". A profile is never copied between photos: presets, Copy / Paste, Sync and Auto
|
|
Sync carry Enable Lens Corrections and its amounts, and each photo keeps the profile of its own lens
|
|
(`crates/engine/src/tests/lens_refresh.rs`).
|
|
|
|
Files are read once per folder and again after a download. Invalid files are skipped with a warning in the log.
|
|
Each read logs the folder, whether it is the download or `LIGHTCRAFT_LENSFUN_DIR`, and how many lenses and cameras
|
|
it holds; a folder that is missing or holds no lenses is logged as a warning (#2511). The app's own folder before a
|
|
download has finished is not read, and says so at info level, since that is the state before the first download.
|
|
|
|
## What is applied
|
|
|
|
The lens is identified from EXIF: camera make / model (for the mount and crop factor; the 35 mm equivalent focal
|
|
length is used when the camera isn't listed or its crop factor is unknown) and the lens model string. Lens names match on their words; every
|
|
number (focal lengths, apertures) in the database name must appear in the EXIF name, and the lens maker must agree
|
|
when the file names one.
|
|
|
|
Some cameras record no lens model at all, only the lens specification: Nikon DSLRs write the lens's focal range and
|
|
maximum apertures in their maker note (tag `0x0084`) and no Exif `LensModel`, whatever lens is mounted. For such a
|
|
file the lens is looked up by a name built from the specification, `24-70mm f/2.8` (`18-55mm f/3.5-5.6`,
|
|
`85mm f/1.8`), and a profile is used only when one of its names is exactly that (ignoring case and punctuation).
|
|
The specification fits every maker's lens with that range (a Nikkor, a Sigma, a Tamron), so neither a partial match
|
|
nor a name with a maker in it ("Samyang 85mm f/1.4" for "85mm f/1.4") is taken; a database that should correct such
|
|
files names its profile that way, e.g. a lensfun entry with an extra `<model>24-70mm f/2.8</model>` for the one
|
|
24-70 f/2.8 the photographer owns. lensfun's own database has no such names, so it doesn't correct these files.
|
|
|
|
| Correction | Models | Interpolated over |
|
|
|---|---|---|
|
|
| Distortion | `poly3`, `poly5`, `ptlens` | focal length |
|
|
| Lateral CA (TCA) | `linear`, `poly3` | focal length |
|
|
| Vignetting | `pa` | focal length, aperture (in stops), focus distance (nearest calibrated, by 1/d; infinity when unknown) |
|
|
|
|
Fisheye and other non-rectilinear lenses get no distortion correction. The profile is converted by least squares
|
|
into the DNG `WarpRectilinear` / `FixVignetteRadial` polynomials, so it goes through the same path as embedded
|
|
corrections: **Enable Profile Corrections** and its Distortion / Vignetting amounts, the CPU and GPU geometry
|
|
stage (one resample), orientation handling and DNG export. A conversion whose radial error exceeds 0.001 of the
|
|
half diagonal, or that would fold the image, is not applied.
|
|
|
|
Normalisation follows lensfun's documentation: distortion and TCA radii are 1 at half the shorter side of the
|
|
calibration frame (its `cropfactor` and `aspect-ratio`), vignetting radii 1 at its corner; the optical centre is
|
|
the image centre (lensfun's `<center>` offsets are not read). Missing or invalid crop factors remain unknown;
|
|
only finite values from 0.05 through 20 are accepted. A calibration inherits the lens's crop factor only when its
|
|
`cropfactor` attribute is omitted; an explicit invalid override remains unknown. Profiles with an unknown
|
|
calibration crop factor are not applied. An explicit crop factor of 1 still means full frame.
|
|
On exact lookup-score ties, both named and built-in fixed-lens matching prefer a known calibration crop; a higher
|
|
match score still wins even when its crop is unknown.
|
|
|
|
## Limits
|
|
|
|
- Only raws: rendered images (JPEG, HEIF, TIFF) are often already corrected in camera.
|
|
- The focus distance is not read from maker notes yet: vignetting uses the farthest calibrated distance.
|
|
- No manual make / model picker and no choice between sources (in the file, lens database, an own calibration)
|
|
yet; matching is automatic, the file's own correction wins.
|
|
- Not yet validated against real photos and another renderer; the tests use synthetic profiles and grids.
|