XMP sidecars and interchange

Imago keeps its catalog as the source of truth, and can also store each photo's metadata and develop settings in an XMP sidecar next to the original. Sidecars let edits travel with the files (backups, another Imago library, other tools), and let Imago pick up edits made elsewhere.

Sidecar files

What we write (standard namespaces, so other tools can read the metadata):

lc: is http://ns.imago.app/lc/1.0/.

Reading merges into the catalog with the sidecar winning for every field it states; fields it doesn't state are kept. The one exception is the capture time: a time embedded in the file (EXIF/IPTC) always wins; when the file has none, the sidecar's exif:DateTimeOriginal, else psd:DateCreated, else xmp:CreateDate (ISO 8601) is used — on import (it then also files a copied photo in its date folder) and by photo.readMetadataFromFile (undoable). xmp:Rating="-1" (the XMP convention for rejected) sets the reject flag. Develop settings come from lc:settings when present (exact); otherwise from the crs: fields below (approximate).

When foreign crs: settings are only partly transferable, library.import includes per-photo warnings in its report. Warnings identify unsupported profile names, saved Upright geometry that will be recalculated, and other unmapped adjustments; they do not change the source packet or become catalog edits.

Manual rereading and undo leave the JPEG original unchanged. Manual rereading also leaves sidecar files unchanged, even with automatic XMP writing on. With automatic XMP writing off (the default), undo/redo leave sidecars unchanged; with it enabled, subsequent edits and undo/redo can trigger the existing sidecar writer. photo.allMetadata uses its already loaded file bytes for embedded XMP, with an existing sidecar taking precedence.

Manual JPEG rereading uses the first standard XMP APP1 before the first SOS (scan) or EOI (end) marker. Scanning is limited to a 16 MiB header span, including SOI, segment headers and skipped payloads, and 4096 marker/fill steps after SOI. Non-APP1 payloads are skipped without loading them. Each APP1 payload must be complete and is at most 65,533 bytes. Header extraction succeeds for the first complete standard XMP packet within both limits, including a packet ending exactly at either limit; otherwise it fails without a whole-file fallback, including on I/O errors or an incomplete APP1 whose available bytes form parseable XMP. A valid JPEG with XMP beyond those limits therefore cannot be manually reread through this path. Extended XMP assembly and packets between scans are not supported by manual JPEG rereading.

Packet completeness is stricter than the shared best-effort JPEG extractor; it is not strict whole-JPEG validation. A complete early XMP packet can be returned without examining the remaining file. Import and photo.allMetadata retain their existing extraction paths. Command regressions in crates/engine/src/tests_xmp.rs cover metadata/undo and sidecar precedence, an over-nested XMP packet and a truncated APP1 without an XMP signature. Separate reader cases in sidecar::jpeg_header_tests use small counted readers and injected limits for span/step boundaries, complete versus truncated APP1, early stopping, short reads and I/O errors.

Saving into an existing sidecar

A sidecar may already hold another application's data — e.g. its crs: develop settings and xmpMM:History — often the only copy of those edits outside that application's catalog. Saving never drops it:

• Imago owns the properties in the table above: xmp:Rating, xmp:Label, dc:title, dc:description, dc:rights, dc:creator, dc:subject, Iptc4xmpCore:Location, Iptc4xmpCore:AltTextAccessibility, Iptc4xmpCore:ExtDescrAccessibility, psd:City/State/Country, xmpRights:Marked/UsageTerms/ WebStatement and everything in lc:. They are replaced on every save, and removed when Imago has no value (clearing a title in Imago clears it in the file). All of them are read back on import, so the library starts from what the sidecar said.
• The capture time (exif:DateTimeOriginal, psd:DateCreated) and GPS (exif:GPSLatitude, exif:GPSLongitude) are replaced only when Imago has a value; otherwise the file's stay.
• Everything else is kept byte for byte: other namespaces (crs:, xmpMM:, lr:hierarchicalSubject, unknown ones), xmp:CreatorTool, comments, the packet wrapper and padding. Imago's properties go into one rdf:Description of their own; owned properties written by another application (in attribute or element form) are removed from its description, which otherwise stays as it was.
• Ownership follows the namespace URI, not the prefix spelling. A foreign namespace bound to lc: or xmp: stays foreign: its properties are preserved and do not become Imago settings or ratings. Genuine namespace aliases remain interchangeable, including namespace declarations containing XML character references.
• A sidecar that can't be read as XMP (not well-formed, not UTF-8, no rdf:RDF) is first copied to <name>.xmp.bak-<date><time> (-1, -2… if taken — a backup is never overwritten), then replaced. A sidecar that can't be read at all (permissions) is left alone and the save fails.

Limits: Imago writes keywords to dc:subject only, so another application's lr:hierarchicalSubject is kept as it was and may still list keywords removed in Imago. Imago doesn't write crs:: the other application's develop settings stay as that application left them, next to Imago's own (lc:settings, which Imago reads first).

Shared names

With stem naming, IMG_0001.CR3 and IMG_0001.JPG map to the same IMG_0001.xmp. When two or more files in the library share a stem, the stem sidecar belongs to one of them — a raw first, otherwise the first by file name — and the others write and read <file>.xmp (IMG_0001.JPG.xmp), falling back to the stem sidecar for reading when they have none. So saving one photo never overwrites the other's metadata (Session::sidecar_naming).

An import ranks the files it is adding the same way, before they are catalogued: a TIFF or JPEG arriving beside a raw of its stem reads its own <file>.xmp and takes nothing from the raw's IMG_0001.xmp, whether it arrives with the raw or after it (issue #1905).

Face regions (MWG)

Imago reads face, pet, focus and barcode regions in the Metadata Working Group's region schema (mwg-rs:Regions, http://www.metadataworkinggroup.com/schemas/regions/), as a professional photo organizer, digiKam, Picasa and others write them, from sidecars and from XMP embedded in the file. Named faces become people in the People view (LR-LIB-PEOPLE in parity-checklist.md), and every region is drawn as a box in the loupe.

• Read only. Imago never writes mwg-rs:Regions; saving a sidecar keeps another application's regions byte for byte. Removing or resizing a box in the loupe changes the library only.
• Areas: stArea:x/y are the box's centre, w/h its size, normalized to the photo (stArea:unit="pixel" areas are divided by mwg-rs:AppliedToDimensions, and dropped without it). Boxes are clipped to the photo; one that misses it entirely, or has a non-finite, zero or negative size, is skipped (the rest of the list is kept).
• Orientation: regions are stored on the upright (EXIF-oriented) photo. A mwg-rs:Rotation of −π/2, +π/2 or ±π (how a professional photo organizer marks a box given in the sensor's frame for Exif orientation 6, 8 or 3) is turned back into the upright frame; MWG can't say "mirrored", so boxes on mirrored photos (orientations 2, 4, 5, 7) are taken as written. Boxes follow Imago's own Rotate Left/Right and flips.
• Re-reading: a sidecar that has mwg-rs:Regions — even with an empty list — replaces the photo's regions, so regions removed in another application go away here too. A sidecar without mwg-rs:Regions (an application that doesn't do regions) leaves the photo's regions as they are.

Reading crs: develop fields

Many raw developers store edits as crs: properties (`) in sidecars, in DNG files and in XMP presets. Imago reads the common ones and maps them to its own controls. We implemented this from the public XMP specification and by observing what each field does; no third-party code or preset files were used. Our pipeline renders differently, so values carry over but the look is approximate.

We read these fields; we never write them. Only fields in the packet are applied: the result is a partial settings object that gets merged like a preset, so everything else keeps its current or default value. Packets marked crs:AlreadyApplied="True" are skipped, because those pixels already contain the edit. Only process-version 2012+ field names are read (e.g. Exposure2012, not the older Exposure). crs:ProcessVersion itself numbers the other application's renderer and is ignored: the photo keeps Imago's own process, the latest for a newly imported photo (process-versions.md).

Values pass through our control specs, so anything outside our slider ranges gets clamped.

crs:CameraProfile is kept as the selected name in the photo's import warning and the active profile is left as it is: the name carries no rendering data and never selects an the vendor profile. Import reports such a profile as not applied (colours may differ from a professional photo organizer), except a professional photo organizer's default profiles (vendor Standard, vendor Color), which every sidecar names and which Imago's own starting look stands in for.

Profiles named by presets (Look, issue #1001). A preset keeps the profile it names (crs:Look: Name, Group, UUID, Amount; in .lrtemplate files the Look table) as profile.look in its settings. When the user has imported a profile of that name (profile.import; the name compared ignoring case and repeated spaces, the group breaking ties), applying the preset selects it at the look's amount (Amount 1 = 100 %). A professional photo organizer's basic profiles map to our own (vendor Color → Color, vendor Neutral, vendor Vivid, vendor Landscape, vendor Portrait, vendor Monochrome → Monochrome). Any other vendor … / Camera … profile and the numbered creative ones (Artistic 01, B&W 05, Modern 10, Vintage 02) can't be used here, and a third-party profile not imported yet leaves the photo's profile as it is; import reports either per preset (Profile “Name” (lrcat's own) / (not imported yet) in unmapped). References are resolved again whenever profiles are imported or deleted, so a pack's profiles and presets can come in either order. The look's embedded Parameters are not read.

Not mapped: camera profiles (CameraProfile; we have our own profile set), red eye, lens blur, process-version 2010 field names, and AI features. Local adjustments and spot removal are read as described below.

Spot removal

Heal and clone spots stored as crs:RetouchAreas (one structure per spot, a mask component inside) and the older crs:RetouchInfo list (one key = value, … line per spot; read on its own when it is all a packet has) become our spots (crates/engine/src/crs_masks.rs, spots). Implemented from the public data model and by observing what a sidecar written for a healed photo contains.

A spot whose mask is any other kind is reported as Spot: <kind>. Sizes are clamped to our spot range. A sidecar's spots replace the photo's, as its masks do.

Local corrections (masks)

Masks stored as crs: structures are read from sidecars, DNG-embedded XMP, XMP presets and .lrtemplate files (crates/engine/src/crs_masks.rs). Four containers hold them: MaskGroupBasedCorrections (current) and the older GradientBasedCorrections, CircularGradientBasedCorrections and PaintBasedCorrections. Each correction becomes one mask: CorrectionName → name, CorrectionAmount → Amount, inactive corrections are skipped.

Applying a preset adds its masks to the photo's own (masks the photo already has are not added twice), and the Amount slider scales them. A sidecar's masks replace the photo's, because a sidecar holds the whole edit. Components we can't carry over are listed in preset.import's unmapped as Mask: <kind>.

Local adjustment presets (mask effects)

mask.importEffects {path | paths, group?, dryRun?} (and preset.import, File ▸ Import Profiles & Presets…, drag & drop) reads these into the Masking panel's Effect menu (crates/engine/src/cmd/mask_effect_files.rs):

Groups: a file's folder (relative to the imported folder; names that only say "local adjustment presets" don't count) names its group, unless the file names one. A professional photo organizer users mark sections of the flat preset menu with divider presets: presets that set nothing, named like 10 ----- DETAIL ENHANCERS ----- 10 (a run of three or more -, =, _, *, #, ~, —, .). These become groups instead of effects: a preset whose name starts with a number goes to the divider with the largest number not above it (12 Sky under 10 ----- DETAIL ENHANCERS ----- 10 → Detail Enhancers); presets without a number keep their folder's group. An earlier import's divider effects are removed. Same-named effects are replaced (a star is kept).

Settings with no local slider here are listed per preset in unmapped (and the toast) and kept with the effect in extra (an .lceffect export carries them), but not applied: grain (Grain; Imago has no local grain), pointColors (Point Color: SrcHue/Sat/Lum, HueShift, SatScale, LumScale, RangeAmount, Hue/Sat/LumRange {LowerNone, LowerFull, UpperFull, UpperNone}; there is global Point Color only), toningLuminance. Zero values aren't listed (refineSaturation = 0 in most files). A professional photo organizer keeps brush size, feather, flow and density per brush, not in presets, so there is nothing to import for them; an effect saved here can carry them (brush).

Applying (mask.applyEffect {name, id? | ids? | all?, photos?: "selected"}) sets the sliders the effect carries — all of them for an imported preset (unnamed ones to 0, as a professional photo organizer does), or only the ones chosen when it was saved (mask.saveEffect {fields: "changed" | [..]}) — and Amount only if it carries it. The effect is remembered for the mask's kind: the next brush / linear / radial / … mask starts with it (mask.toolEffect).

Preset files

Imago ships no third-party presets. Its built-in presets are its own values (crates/engine/src/presets.rs).

Luminar looks (.lmp, .mplumpack)

preset.import (and drag & drop, File ▸ Import Profiles & Presets…) also reads Luminar looks: an .lmp file is an XML property list of adjustment layers (each with effects and named sliders, mostly on a −100..100 scale); newer looks may be a bundle folder Name.lmp/Contents/preset.lmp. An .mplumpack collection is a zip of .lmp files whose PresetsInfo.plist names the group (GroupName); the pack's file name is the fallback. Looks get their own name (Name) or their file / bundle name. The sliders with a clear counterpart are carried over; everything else (AI tools, Orton, glow, LUT layers, colour balance…) is listed in unmapped as Tool.Slider (e.g. OrtonFilter.Amount). Disabled layers are ignored, layer opacity scales the sliders (and fades curves toward a straight line), and layers with a blend mode other than Normal or with a mask are reported, not applied. Binary property lists are not read.

Profiles: 3D LUTs (.cube)

profile.import {paths} (File ▸ Import Profiles & Presets…, drag & drop) reads .cube 3D LUTs — single files, folders or .zip bundles — as creative profiles: they appear in the profile browser under their folder's (or zip's) name and take the Amount slider (0–200 %) like the built-in looks. The LUT is applied to the finished, display-encoded colour (trilinear; DOMAIN_MIN / DOMAIN_MAX honoured; 1D LUTs are not supported); photos with a LUT profile render on the CPU. A library on disk keeps a copy of each file in its Profiles/ folder. the vendor's own profile formats (.dcp, XMP camera/creative profiles with embedded tables) are deliberately not read.