GitCorner

Code

ossartcraftlightcraft๐ŸŒ
5a24289898fd
//! Lens correction profiles: distortion, transverse chromatic aberration (TCA) and vignetting.
//!
//! - [`model`]: the radial models (distortion poly3 / poly5 / PTLens, TCA linear / poly3, vignetting `pa`), and the
//!   least-squares conversion to the DNG opcode polynomials (`WarpRectilinear`, `FixVignetteRadial`) the pipeline
//!   already applies in its single geometry resample.
//! - [`LensDb`]: profiles read from lensfun-format XML files in a directory the user supplies. The lensfun database
//!   is CC-BY-SA; it is never bundled with the code or the binary, only read at run time from where the user put it.
//! - [`LensDb::find_camera`] / [`LensDb::find_lens`]: identification from EXIF make / model / lens model strings,
//!   with mount and crop-factor handling.
//! - [`Profile::correction`]: the profile at a shot's focal length (and aperture / distance for vignetting),
//!   interpolated between calibrated points, expressed as [`lightcraft_develop::EmbeddedLens`] for a given image.
//!
//! Sources: the lensfun database format and model formulas as described in lensfun's published documentation
//! (database file format and lens calibration pages; no lensfun code was read), Panorama Tools' distortion model
//! (a, b, c) as documented by the PanoTools wiki, Adobe DNG specification 1.6 (opcodes `WarpRectilinear`,
//! `FixVignetteRadial`). Interpolation and fitting: own design.
#![forbid(unsafe_code)]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]

pub mod model;
mod xml;

use std::path::Path;

use lightcraft_develop::{EmbeddedLens, EmbeddedVignette, EmbeddedWarp};
use lightcraft_geom::Point;
pub use model::{Distortion, Tca, Vignetting};

/// Largest database file read (lensfun's biggest file is well under 1 MB).
const MAX_FILE_BYTES: u64 = 16 << 20;
/// Most files read from one directory.
const MAX_FILES: usize = 2000;
/// Most bytes of lens names that profiles may copy per parsed document (each calibration owns a copy): a real
/// database copies about a megabyte.
const MAX_PROFILE_COPY_BYTES: usize = 32 << 20;
/// What one copied name costs besides its bytes: the `String` slot in its `Vec` and the allocator's header and rounding.
const NAME_ALLOCATION: usize = std::mem::size_of::<String>() + 32;
/// Largest radial error (half-diagonal units) accepted when converting a distortion to the DNG polynomial.
pub const MAX_WARP_ERROR: f64 = 0.001;
/// Largest relative error accepted when converting vignetting to the DNG polynomial.
pub const MAX_VIGNETTE_ERROR: f64 = 0.01;

#[derive(Debug, Clone, PartialEq)]
pub enum Error {
    Io(String),
    Xml(String),
    TooLarge,
}

impl std::fmt::Display for Error {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Error::Io(e) => write!(f, "lens database: {e}"),
            Error::Xml(e) => write!(f, "lens database: invalid XML: {e}"),
            Error::TooLarge => write!(f, "lens database: file too large or too deeply nested"),
        }
    }
}

impl std::error::Error for Error {}

/// A camera body: what is needed to pick lenses (mount) and scale profiles (crop factor).
#[derive(Clone, Debug, PartialEq)]
pub struct Camera {
    pub maker: String,
    pub model: String,
    pub mount: String,
    /// Sensor crop relative to 35 mm; missing or invalid XML remains unknown.
    pub crop_factor: Option<f64>,
}

/// One calibrated vignetting point.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct VignettingPoint {
    pub focal: f64,
    pub aperture: f64,
    /// Focus distance, metres (lensfun uses 1000 for infinity).
    pub distance: f64,
    pub model: Vignetting,
}

/// A lens profile: names, mounts, the calibration frame and the calibrated points.
#[derive(Clone, Debug, PartialEq)]
pub struct Profile {
    pub maker: String,
    /// Every name the lens goes by (EXIF variants, translations).
    pub models: Vec<String>,
    pub mounts: Vec<String>,
    /// Crop factor of the calibration frame; missing or invalid XML remains unknown.
    pub crop_factor: Option<f64>,
    /// Long / short side of the calibration frame.
    pub aspect_ratio: f64,
    /// False for fisheye and other non-rectilinear projections: distortion is then not applied.
    pub rectilinear: bool,
    /// Sorted by focal length.
    pub distortion: Vec<(f64, Distortion)>,
    pub tca: Vec<(f64, Tca)>,
    pub vignetting: Vec<VignettingPoint>,
}

/// The shot a correction is wanted for.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Shot {
    /// Focal length, mm.
    pub focal: f64,
    pub aperture: Option<f64>,
    /// Focus distance, metres.
    pub distance: Option<f64>,
    /// Crop factor of the recorded frame: the camera's (from [`LensDb::find_camera`]), or larger when the camera
    /// recorded a crop of its sensor; the profile's own when unknown.
    pub crop_factor: Option<f64>,
    /// Image size in pixels (the frame the correction is expressed for; the optical centre is its centre).
    pub width: f64,
    pub height: f64,
}

/// A set of lens and camera profiles.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct LensDb {
    pub cameras: Vec<Camera>,
    pub lenses: Vec<Profile>,
}

impl LensDb {
    /// Read every `*.xml` file in `dir` (lensfun database format). Unreadable or invalid files are skipped and
    /// reported in the second value; only a directory that can't be listed is an error.
    pub fn load_dir(dir: &Path) -> Result<(LensDb, Vec<(String, Error)>), Error> {
        let mut entries: Vec<_> = std::fs::read_dir(dir)
            .map_err(|e| Error::Io(format!("{}: {e}", dir.display())))?
            .flatten()
            .map(|e| e.path())
            .filter(|p| p.extension().is_some_and(|x| x.eq_ignore_ascii_case("xml")))
            .collect();
        entries.sort();
        entries.truncate(MAX_FILES);
        let mut db = LensDb::default();
        let mut errors = Vec::new();
        for path in entries {
            let name = path.display().to_string();
            match read_capped(&path).and_then(|s| LensDb::parse(&s)) {
                Ok(part) => db.extend(part),
                Err(e) => errors.push((name, e)),
            }
        }
        Ok((db, errors))
    }

    /// Parse one lensfun-format XML document.
    pub fn parse(xml: &str) -> Result<LensDb, Error> {
        let root = xml::parse(xml)?;
        if root.name != "lensdatabase" {
            return Err(Error::Xml("no <lensdatabase> element".into()));
        }
        let cameras = root.children("camera").filter_map(camera).collect();
        let mut budget = MAX_PROFILE_COPY_BYTES;
        let lenses = root.children("lens").flat_map(|n| lens(n, &mut budget)).collect();
        Ok(LensDb { cameras, lenses })
    }

    pub fn extend(&mut self, other: LensDb) {
        self.cameras.extend(other.cameras);
        self.lenses.extend(other.lenses);
    }

    pub fn is_empty(&self) -> bool {
        self.cameras.is_empty() && self.lenses.is_empty()
    }

    /// The camera with this EXIF make and model.
    pub fn find_camera(&self, make: &str, model: &str) -> Option<&Camera> {
        let mk = tokens(make);
        let raw = tokens(model);
        let md = strip_maker(raw.clone(), &mk);
        if md.is_empty() {
            return None;
        }
        self.cameras.iter().find(|c| {
            let cm = tokens(&c.maker);
            // with no EXIF make, the model may still start with the maker's word
            let md = if mk.is_empty() { strip_maker(raw.clone(), &cm) } else { md.clone() };
            maker_matches(&cm, &mk) && strip_maker(tokens(&c.model), &cm) == md
        })
    }

    /// The best profile for an EXIF lens model (and lens make, when the file has one), preferring lenses for the
    /// camera's mount. `None` when no name is a convincing match.
    pub fn find_lens(&self, lens_make: Option<&str>, lens_model: &str, camera: Option<&Camera>) -> Option<&Profile> {
        self.best_lens(lens_make, lens_model, camera, |_| true).or_else(|| self.find_fixed_lens(&tokens(lens_model), camera?))
    }

    /// [`find_lens`](Self::find_lens) among the profiles one of whose names is exactly `name`
    /// ([`Profile::names_exactly`]), for names that carry no maker, such as [`spec_name`]s: another maker's lens with
    /// the same specification scores as high, and must neither win nor, by coming first, hide the profile named so.
    pub fn find_lens_named(&self, lens_make: Option<&str>, name: &str, camera: Option<&Camera>) -> Option<&Profile> {
        self.best_lens(lens_make, name, camera, |l| l.names_exactly(name))
    }

    fn best_lens(&self, lens_make: Option<&str>, lens_model: &str, camera: Option<&Camera>, eligible: impl Fn(&Profile) -> bool) -> Option<&Profile> {
        let exif = tokens(lens_model);
        if exif.is_empty() {
            return None;
        }
        let make = lens_make.map(tokens).unwrap_or_default();
        let mut best: Option<(f64, &Profile)> = None;
        for lens in self.lenses.iter().filter(|l| eligible(l)) {
            let maker = tokens(&lens.maker);
            if !make.is_empty() && !maker.is_empty() && !maker_matches(&maker, &make) {
                continue;
            }
            let mut score = lens.models.iter().map(|m| name_score(&tokens(m), &exif, &maker)).fold(0.0, f64::max);
            if let Some(cam) = camera
                && !lens.mounts.is_empty()
                && !lens.mounts.iter().any(|m| m.eq_ignore_ascii_case(&cam.mount))
            {
                score *= 0.8;
            }
            if score >= 0.6 && best.is_none_or(|(s, b)| score > s || (score == s && b.crop_factor.is_none() && lens.crop_factor.is_some())) {
                best = Some((score, lens));
            }
        }
        best.map(|(_, l)| l)
    }

    /// Compact cameras with a built-in lens: lensfun names the lens after the camera and gives it the camera's own
    /// mount, while EXIF reports only a focal / aperture range ("6.0-72.0 mm f/2.7-3.5"). Match by mount, then by
    /// how much of the calibrated focal range lies inside the EXIF focal range.
    fn find_fixed_lens(&self, exif: &[String], cam: &Camera) -> Option<&Profile> {
        if cam.mount.is_empty() {
            return None;
        }
        let cands: Vec<&Profile> = self
            .lenses
            .iter()
            .filter(|l| l.mounts.iter().any(|m| m.eq_ignore_ascii_case(&cam.mount)))
            .filter(|l| !l.models.iter().any(|m| tokens(m).iter().any(|t| t == "mm")))
            .collect();
        // an interchangeable mount has many lenses; a built-in lens has one or a few profiles
        if cands.is_empty() || cands.len() > MAX_FIXED_CANDIDATES {
            return None;
        }
        let Some((lo, hi)) = exif_focal_range(exif) else {
            return (cands.len() == 1).then(|| cands[0]);
        };
        let (lo, hi) = (lo * 0.9, hi * 1.1);
        if !lo.is_finite() || !hi.is_finite() {
            return None;
        }
        let mut best: Option<(f64, &Profile)> = None;
        for p in cands {
            let focals: Vec<f64> =
                p.distortion.iter().map(|d| d.0).chain(p.tca.iter().map(|t| t.0)).chain(p.vignetting.iter().map(|v| v.focal)).collect();
            if focals.is_empty() {
                continue;
            }
            let score = focals.iter().filter(|f| (lo..=hi).contains(*f)).count() as f64 / focals.len() as f64;
            if score > 0.0 && best.is_none_or(|(s, b)| score > s || (score == s && b.crop_factor.is_none() && p.crop_factor.is_some())) {
                best = Some((score, p));
            }
        }
        best.map(|(_, p)| p)
    }
}

/// Most profiles a camera's mount may have for it to count as a built-in-lens mount.
const MAX_FIXED_CANDIDATES: usize = 4;

/// Drop the maker's words from a model name ("Canon PowerShot S5 IS" โ†’ "powershot s5 is").
fn strip_maker(model: Vec<String>, maker: &[String]) -> Vec<String> {
    let first = maker.first();
    let stripped: Vec<String> = model.iter().filter(|t| Some(*t) != first).cloned().collect();
    if stripped.is_empty() { model } else { stripped }
}

/// The numbers before the first "mm" in tokenised EXIF lens text: (shortest, longest) focal length.
fn exif_focal_range(exif: &[String]) -> Option<(f64, f64)> {
    let end = exif.iter().position(|t| t == "mm")?;
    let nums: Vec<f64> = exif.get(..end)?.iter().filter_map(|t| t.parse::<f64>().ok()).filter(|v| v.is_finite() && *v > 0.0).collect();
    let lo = nums.iter().copied().fold(f64::INFINITY, f64::min);
    let hi = nums.iter().copied().fold(0.0, f64::max);
    (lo.is_finite() && hi > 0.0).then_some((lo, hi))
}

fn read_capped(path: &Path) -> Result<String, Error> {
    use std::io::Read;
    let io = |e: std::io::Error| Error::Io(e.to_string());
    // the pathname is checked before opening (opening a FIFO for reading blocks until a writer appears), then the
    // opened file again: a link or FIFO swapped in after the pathname check is refused too
    if !std::fs::metadata(path).map_err(io)?.is_file() {
        return Err(Error::Io(format!("{}: not a regular file", path.display())));
    }
    let file = std::fs::File::open(path).map_err(io)?;
    let meta = file.metadata().map_err(io)?;
    if !meta.is_file() {
        return Err(Error::Io(format!("{}: not a regular file", path.display())));
    }
    if meta.len() > MAX_FILE_BYTES {
        return Err(Error::TooLarge);
    }
    let mut bytes = Vec::new();
    file.take(MAX_FILE_BYTES + 1).read_to_end(&mut bytes).map_err(io)?;
    if bytes.len() as u64 > MAX_FILE_BYTES {
        return Err(Error::TooLarge);
    }
    Ok(String::from_utf8_lossy(&bytes).into_owned())
}

/// Lower-case word tokens; letters and digits are split ("24-105mm" โ†’ 24, 105, mm), decimals kept ("2.8").
fn tokens(s: &str) -> Vec<String> {
    let mut out: Vec<String> = Vec::new();
    let mut cur = String::new();
    let mut prev_digit: Option<bool> = None;
    for c in s.chars().flat_map(char::to_lowercase) {
        let digit = c.is_ascii_digit() || (c == '.' && prev_digit == Some(true));
        if c.is_alphanumeric() || digit {
            if prev_digit.is_some_and(|p| p != digit) && !cur.is_empty() {
                out.push(std::mem::take(&mut cur));
            }
            cur.push(c);
            prev_digit = Some(digit);
        } else {
            if !cur.is_empty() {
                out.push(std::mem::take(&mut cur));
            }
            prev_digit = None;
        }
    }
    if !cur.is_empty() {
        out.push(cur);
    }
    for t in &mut out {
        // "4.0" and "4" are the same aperture
        if t.contains('.') && t.starts_with(|c: char| c.is_ascii_digit()) {
            let trimmed = t.trim_end_matches('0').trim_end_matches('.');
            *t = trimmed.to_string();
        }
    }
    out.retain(|t| !t.is_empty());
    out
}

fn is_number(t: &str) -> bool {
    t.starts_with(|c: char| c.is_ascii_digit())
}

/// Makers match when one's first word appears in the other ("NIKON CORPORATION" / "Nikon").
fn maker_matches(a: &[String], b: &[String]) -> bool {
    match (a.first(), b.first()) {
        (Some(x), Some(y)) => b.contains(x) || a.contains(y),
        _ => true,
    }
}

/// How well a database name matches the EXIF name, 0..1. Every number in the database name (focal lengths,
/// apertures) must appear in the EXIF name and vice versa; the maker's words are ignored on both sides (EXIF
/// often omits them). Extra EXIF words only lower the score; they name a different lens only when they mark
/// a teleconverter, a different optical system than the bare lens.
fn name_score(db: &[String], exif: &[String], maker: &[String]) -> f64 {
    let db: Vec<&String> = db.iter().filter(|t| !maker.contains(t)).collect();
    let exif: Vec<&String> = exif.iter().filter(|t| !maker.contains(t)).collect();
    if db.is_empty() || exif.is_empty() {
        return 0.0;
    }
    if db.iter().any(|t| is_number(t) && !exif.contains(t)) || exif.iter().any(|t| is_number(t) && !db.contains(t)) {
        return 0.0;
    }
    // A teleconverter combo is a different optical system from the bare lens:
    // reject it whichever side carries the marker, independent of which tokens
    // the names drop or add.
    let db_tc = db.iter().any(|t| is_teleconverter_marker(t.as_str()));
    let exif_tc = exif.iter().any(|t| is_teleconverter_marker(t.as_str()));
    if db_tc != exif_tc {
        return 0.0;
    }
    let common = db.iter().filter(|t| exif.contains(t)).count() as f64;
    common / db.len().max(exif.len()) as f64
}

/// Teleconverter markers in a lens name. A name carrying one names a different
/// optical system than the bare lens, so a match whose sides disagree on the
/// marker is rejected before scoring. Converter factors such as `1.4x`
/// tokenise into a number the base profile lacks, so the numeric check above
/// already rejects them.
fn is_teleconverter_marker(t: &str) -> bool {
    t == "tc" || t == "teleconverter"
}

fn camera(n: &xml::Node) -> Option<Camera> {
    Some(Camera {
        maker: xml::kid_text(n, "maker")?,
        model: xml::kid_text(n, "model")?,
        mount: xml::kid_text(n, "mount").unwrap_or_default(),
        crop_factor: crop_of(xml::kid_text(n, "cropfactor").as_deref()),
    })
}

fn crop_of(s: Option<&str>) -> Option<f64> {
    s.and_then(|v| v.trim().parse::<f64>().ok()).filter(|v| v.is_finite() && (0.05..=20.0).contains(v))
}

fn aspect_of(s: Option<&str>) -> Option<f64> {
    let s = s?.trim();
    let v = match s.split_once(':') {
        Some((a, b)) => a.trim().parse::<f64>().ok()? / b.trim().parse::<f64>().ok()?,
        None => s.parse::<f64>().ok()?,
    };
    let v = if v < 1.0 { 1.0 / v } else { v };
    (v.is_finite() && (1.0..=10.0).contains(&v)).then_some(v)
}

fn positive(v: Option<f64>) -> Option<f64> {
    v.filter(|v| *v > 0.0 && *v < 1e6)
}

/// One `<lens>` element โ†’ one profile per `<calibration>` (newer files give each its own crop factor and aspect).
fn lens(n: &xml::Node, copy_budget: &mut usize) -> Vec<Profile> {
    let Some(maker) = xml::kid_text(n, "maker") else { return Vec::new() };
    let models: Vec<String> = n.children("model").map(|m| m.text().trim().to_string()).filter(|m| !m.is_empty()).collect();
    if models.is_empty() {
        return Vec::new();
    }
    let crop = crop_of(xml::kid_text(n, "cropfactor").as_deref());
    let aspect = aspect_of(xml::kid_text(n, "aspect-ratio").as_deref()).unwrap_or(1.5);
    let rectilinear = xml::kid_text(n, "type").is_none_or(|t| t.eq_ignore_ascii_case("rectilinear"));
    let mounts = n.children("mount").map(|m| m.text().trim().to_string()).filter(|m| !m.is_empty()).collect::<Vec<_>>();
    // every kept calibration owns a copy of the lens's names, charged to the document's shared copy budget (the
    // strings' own allocations count, not only their bytes): when it can't cover another copy, the rest are left out
    let meta_bytes = std::mem::size_of::<Profile>()
        + NAME_ALLOCATION
        + maker.len()
        + models.iter().chain(&mounts).map(|m| m.len() + NAME_ALLOCATION).sum::<usize>();
    let mut out = Vec::new();
    for cal in n.children("calibration") {
        if *copy_budget < meta_bytes {
            break;
        }
        let mut p = Profile {
            maker: String::new(),
            models: Vec::new(),
            mounts: Vec::new(),
            // Only an omitted override inherits; an explicit invalid value remains unknown.
            crop_factor: match cal.attr("cropfactor") {
                Some(value) => crop_of(Some(value)),
                None => crop,
            },
            aspect_ratio: aspect_of(cal.attr("aspect-ratio")).unwrap_or(aspect),
            rectilinear,
            distortion: Vec::new(),
            tca: Vec::new(),
            vignetting: Vec::new(),
        };
        for c in cal.elements() {
            let Some(focal) = positive(xml::num(c, "focal")) else { continue };
            let k = |name: &str| xml::num(c, name).unwrap_or(0.0);
            match (c.name.as_str(), c.attr("model")) {
                ("distortion", Some("poly3")) => p.distortion.push((focal, Distortion::Poly3 { k1: k("k1") })),
                ("distortion", Some("poly5")) => p.distortion.push((focal, Distortion::Poly5 { k1: k("k1"), k2: k("k2") })),
                ("distortion", Some("ptlens")) => p.distortion.push((focal, Distortion::PtLens { a: k("a"), b: k("b"), c: k("c") })),
                ("tca", Some("linear")) => {
                    let one = |name: &str| xml::num(c, name).unwrap_or(1.0);
                    p.tca.push((focal, Tca::Linear { kr: one("kr"), kb: one("kb") }));
                }
                ("tca", Some("poly3")) => {
                    let one = |name: &str| xml::num(c, name).unwrap_or(1.0);
                    p.tca.push((focal, Tca::Poly3 { vr: one("vr"), vb: one("vb"), cr: k("cr"), cb: k("cb"), br: k("br"), bb: k("bb") }));
                }
                ("vignetting", Some("pa")) => {
                    let (Some(aperture), distance) = (positive(xml::num(c, "aperture")), positive(xml::num(c, "distance")).unwrap_or(1000.0)) else {
                        continue;
                    };
                    let model = Vignetting { k1: k("k1"), k2: k("k2"), k3: k("k3") };
                    p.vignetting.push(VignettingPoint { focal, aperture, distance, model });
                }
                _ => {}
            }
        }
        // a calibration with nothing to apply is dropped before its names are copied or charged
        if p.distortion.is_empty() && p.tca.is_empty() && p.vignetting.is_empty() {
            continue;
        }
        *copy_budget -= meta_bytes;
        p.maker = maker.to_string();
        p.models = models.clone();
        p.mounts = mounts.clone();
        p.distortion.sort_by(|a, b| a.0.total_cmp(&b.0));
        p.tca.sort_by(|a, b| a.0.total_cmp(&b.0));
        out.push(p);
    }
    out
}

/// Linear interpolation weights in a sorted key list: the bracketing indices and the weight of the upper one.
fn bracket(keys: &[f64], x: f64) -> Option<(usize, usize, f64)> {
    let last = keys.len().checked_sub(1)?;
    let hi = keys.iter().position(|&k| k >= x).unwrap_or(last);
    let lo = hi.saturating_sub(1);
    let (a, b) = (keys.get(lo).copied()?, keys.get(hi).copied()?);
    if x <= a || b <= a {
        return Some((lo, lo, 0.0));
    }
    if x >= b {
        return Some((hi, hi, 0.0));
    }
    Some((lo, hi, (x - a) / (b - a)))
}

/// A value interpolated in focal length between calibrated points, by evaluating both neighbours.
fn by_focal<T: Copy>(points: &[(f64, T)], focal: f64, eval: impl Fn(&T) -> f64) -> Option<f64> {
    let keys: Vec<f64> = points.iter().map(|p| p.0).collect();
    let (lo, hi, t) = bracket(&keys, focal)?;
    let (a, b) = (eval(&points.get(lo)?.1), eval(&points.get(hi)?.1));
    Some(a + (b - a) * t)
}

/// A lens name built from a lens specification (min / max focal length, f-number at each), for files that name
/// no lens model, only its specification (Nikon DSLRs' maker note): "24-70mm f/2.8", "18-55mm f/3.5-5.6",
/// "85mm f/1.8". Such a name says nothing about the maker, so [`Profile::names_exactly`] must confirm a match.
pub fn spec_name(spec: [f64; 4]) -> String {
    fn num(v: f64) -> String {
        let t = format!("{v:.1}");
        t.trim_end_matches('0').trim_end_matches('.').to_string()
    }
    fn range(a: f64, b: f64) -> String {
        if (a - b).abs() < 0.05 { num(a) } else { format!("{}-{}", num(a), num(b)) }
    }
    format!("{}mm f/{}", range(spec[0], spec[1]), range(spec[2], spec[3]))
}

impl Profile {
    /// Whether one of the profile's names is exactly `name` (same words and numbers, ignoring case and
    /// punctuation): the check for names that carry no maker, such as [`spec_name`]s, where the best partial match
    /// could be another maker's lens with the same focal range. The maker's words count too, so "Samyang 85mm f/1.4"
    /// is not "85mm f/1.4"; only a name given for the purpose (a user's alias) matches.
    pub fn names_exactly(&self, name: &str) -> bool {
        let want = tokens(name);
        !want.is_empty() && self.models.iter().any(|m| tokens(m) == want)
    }

    /// Distortion ratio `r_d / r_u` at lensfun radius `r` for `focal` (1 when the profile has none).
    pub fn distortion_ratio(&self, focal: f64, r: f64) -> f64 {
        if !self.rectilinear {
            return 1.0;
        }
        by_focal(&self.distortion, focal, |d| d.ratio(r)).unwrap_or(1.0)
    }

    /// TCA ratio for channel `ch` at lensfun radius `r` for `focal`.
    pub fn tca_ratio(&self, focal: f64, ch: usize, r: f64) -> f64 {
        by_focal(&self.tca, focal, |t| t.ratio(ch, r)).unwrap_or(1.0)
    }

    /// Vignetting attenuation at radius `r` (half-diagonal units): linear in focal length, in stops of aperture and
    /// in 1 / distance between the calibrated points.
    pub fn vignetting_attenuation(&self, focal: f64, aperture: Option<f64>, distance: Option<f64>, r: f64) -> Option<f64> {
        let mut focals: Vec<f64> = self.vignetting.iter().map(|v| v.focal).collect();
        focals.sort_by(f64::total_cmp);
        focals.dedup();
        let (lo, hi, t) = bracket(&focals, focal)?;
        let at = |f: f64| -> Option<f64> {
            let pts: Vec<&VignettingPoint> = self.vignetting.iter().filter(|v| v.focal == f).collect();
            // the calibrated distance nearest the shot's (in 1/d; infinity when unknown)
            let inv = |d: f64| 1.0 / d.max(0.01);
            let want = distance.map_or(0.0, inv);
            let near = pts.iter().map(|v| v.distance).min_by(|a, b| (inv(*a) - want).abs().total_cmp(&(inv(*b) - want).abs()))?;
            let mut at_d: Vec<&&VignettingPoint> = pts.iter().filter(|v| v.distance == near).collect();
            at_d.sort_by(|a, b| a.aperture.total_cmp(&b.aperture));
            let stops: Vec<f64> = at_d.iter().map(|v| v.aperture.log2()).collect();
            // unknown aperture: the widest calibrated one (the strongest falloff)
            let n = aperture.filter(|a| *a > 0.0).map_or(stops.first().copied()?, f64::log2);
            let (i, j, u) = bracket(&stops, n)?;
            let (a, b) = (at_d.get(i)?.model.attenuation(r), at_d.get(j)?.model.attenuation(r));
            Some(a + (b - a) * u)
        };
        let (a, b) = (at(*focals.get(lo)?)?, at(*focals.get(hi)?)?);
        Some(a + (b - a) * t)
    }

    /// The correction for `shot`, as the DNG opcode polynomials the pipeline applies, centred on the image.
    /// Distortion and TCA are combined per plane (R, G, B); a model the polynomial can't follow closely
    /// ([`MAX_WARP_ERROR`], [`MAX_VIGNETTE_ERROR`]) or that would fold the image is left out.
    /// An unknown or invalid calibration crop factor cannot be converted.
    pub fn correction(&self, shot: &Shot) -> Option<EmbeddedLens> {
        let (w, h) = (shot.width, shot.height);
        if !(w >= 2.0 && h >= 2.0 && w.is_finite() && h.is_finite() && shot.focal.is_finite() && shot.focal > 0.0) {
            return None;
        }
        let calibration_crop = self.crop_factor.filter(|c| c.is_finite() && (0.05..=20.0).contains(c))?;
        let cam = shot.crop_factor.filter(|c| c.is_finite() && *c > 0.0).unwrap_or(calibration_crop);
        // DNG radius (1 = image half diagonal) โ†’ lensfun radii
        let to_vig = calibration_crop / cam;
        let to_dist = to_vig * (1.0 + self.aspect_ratio * self.aspect_ratio).sqrt();
        let center = Point::new(0.5, 0.5);
        let radius = w.hypot(h) / 2.0 / w.max(h);
        let f = shot.focal;
        let mut lens = EmbeddedLens::default();
        let has_dist = self.rectilinear && !self.distortion.is_empty();
        if has_dist || !self.tca.is_empty() {
            let plane = |ch: usize| -> Option<[f64; 6]> {
                let ratio = |r: f64| {
                    let rl = r * to_dist;
                    let d = self.distortion_ratio(f, rl);
                    d * self.tca_ratio(f, ch, rl * d)
                };
                let (k, err) = model::fit_even4(ratio)?;
                (err <= MAX_WARP_ERROR).then_some([k[0], k[1], k[2], k[3], 0.0, 0.0])
            };
            if let (Some(r), Some(g), Some(b)) = (plane(0), plane(1), plane(2)) {
                lens.warp = Some(EmbeddedWarp { planes: [r, g, b], center, radius });
            }
        }
        if !self.vignetting.is_empty() {
            let att = |r: f64| self.vignetting_attenuation(f, shot.aperture, shot.distance, r * to_vig).unwrap_or(1.0);
            if let Some((k, err)) = model::fit_gain5(|r| 1.0 / att(r).max(0.05))
                && err <= MAX_VIGNETTE_ERROR
            {
                lens.vignette = Some(EmbeddedVignette { k, center, radius });
            }
        }
        (lens.warp.is_some() || lens.vignette.is_some()).then_some(lens)
    }
}

#[cfg(test)]
mod tests;