lightcraft/docs/raw-preview-reads.md

Reading a raw's preview without reading the raw

A grid thumbnail and a loupe preview of an unedited raw both show the camera's embedded JPEG, not a decode of the sensor data. That JPEG lives near the start of the file, but the rest of the file is the sensor data — for a 24 MP Fuji RAF, 50 of 56 MB. Until this change the preview loader called std::fs::read on the whole file and threw the sensor data away, so every preview paid for bytes nobody looked at.

That is free on a local SSD and expensive on a network share, which is where photographers keep libraries. Measured on one real file (DSCF9492.RAF, 56.5 MB) over a GVFS/SMB share on Wi-Fi:

	read	time
whole file	59 277 632 B (100 %)	~10 s
header + preview	5 857 257 B (9.9 %)	0.96 s

How it works

1. read_prefix reads the first PREVIEW_PREFIX (4 KiB); every format whose preview is locatable from the header keeps its pointer well inside that.
2. For Fuji RAF the header's two big-endian u32s at 84 (offset) and 88 (length) are the same fields lightcraft_raw's RAF reader uses. When they declare more than the prefix holds, the prefix is re-read once at exactly that extent: lightcraft_raw::bounded_preview reports the range its buffer covers (slice clamps to b.len()), so a short prefix yields a plausible but truncated range — a real 4 KiB prefix reports 3 948 bytes where the file holds 5.6 MB.
3. embedded_preview_from_range checks the window really starts with a JPEG SOI and trims it at the last EOI marker, exactly as embedded_preview trims the whole-file answer.
4. When the prefix already covers the range — the usual case, since it was grown to it — the window is a slice of the prefix. Reading it again would double a 5.6 MB preview.

Formats whose preview pointer is not in the header — a Canon CR3's boxes, a TIFF raw whose preview tag sits in an IFD the prefix cuts short — are planned instead (next section but one), and what the planner cannot describe keeps the whole-file path, so nothing regresses: preview_window returns None and the loader reads the file as before. A pointer that lies, a short read, a plan that does not fit or a file that changes underneath us ends in the same fallback — the user's preview is never lost to a damaged header.

LIGHTCRAFT_PROFILE=1 prints what each preview cost:

[profile] preview …/DSCF9492.RAF: read 5857257 of 59277632 bytes (header 5857257, window 5857109)

What the header cannot point at: the plan

A Canon CR3 keeps its preview in a JPEG track, and a TIFF raw (CR2, ARW, DNG, RW2, 3FR …) can keep its preview tag in an IFD the header route's prefix cuts short. Neither has a field step 2 above can read, so preview_window asks lightcraft_raw::sparse::preview_plan — the module the Lightroom-catalog import probes with — which ranges embedded_preview reads, and reads exactly those:

• the buffer is the file's length with only the planned ranges filled in; every other byte stays zero and its pages are never written. Its cost is the bytes read — on macOS a freed buffer of that size may stay in the allocator's cache instead of going back to the OS (measured on a 38k-photo import, #832) — and the loader's memory gate counts the whole file either way;
• the module's own guarantee is what this path needs, and its corpus test asserts it: with the skipped bytes 0 and again 0xFF, what a partly loaded buffer yields is what the whole file yields. A second corpus pass now asks preview_plan for every file, including the ones whose header probe reads samples and whose header plan is Whole, which is where that plan was untested before;
• the quick path must be able to show what the whole-file path would. Two container facts are not in the JPEG. A preview colour space of Adobe RGB is read from the planned buffer and handed on (PreviewRead::adobe_rgb), and the quick decode applies it as decode_raw_preview does (issue #1440: a Sony α1 writes Adobe RGB previews, which until then sent every one of them to the whole-file read — 70 MB for an 8 MB JPEG); a container that says sRGB needs nothing, since that is what the decode assumes anyway. The file's own EXIF orientation, when the preview JPEG carries none of its own and the bounded header cannot see it, still declines and the whole file keeps the preview;
• a format the planner cannot describe — NEF, ORF and PEF probe from samples, CRW/MRW/X3F are found by scanning — a plan that does not fit the buffer or wants more than 60 % of the file (the bound the import path's own partial read uses), or a window that does not decode all answer None, and the loader reads the file whole exactly as before: the plan can cost bytes but never the picture.

Measured over the CC0 corpus (111 raws, cargo xtask corpus --download): 52 files take the plan route, reading a median 7.8 % of their bytes (0.9 %–27.7 %) — by format RW2 3.3 %, Leica RWL 4.1 %, ARW 7.5 %, CR3 8.4 %, DNG 9.7 %, CR2 14.3 % — while the 21 RAFs stay on the header route (median 4.5 %). The remaining 38 read whole: NEF, NRW, ORF, PEF and Samsung SRW because the planner does not describe them (the first four say so; an SRW plans to the whole file, and the 60 % budget then keeps the whole-file read), and the ARWs, CR2s, CR3s and DNGs that declared Adobe RGB (these take the plan route since #1440; the counts here are from before) or whose plan wants more than that budget. Across the whole corpus the plan handed on the same preview as the whole file, every time — and wrote it down: cargo test -p lightcraft-raw --release --test sparse_corpus -- --nocapture prints these numbers. LIGHTCRAFT_PROFILE=1 says which route answered:

[profile] preview …/arw-sony-a7rm4a-compressed.arw: read 688128 of 61832192 bytes (plan, window 483441)

A Canon CR3's preview is a JPEG track instead (issue #832 measured 3 MB of one R5 Mark II file, ~15 %), and Canon is the largest bucket in gaps.md's ranking (33 % of photographers), so before this change every unedited CR3 thumbnail paid for the whole file.

The grid thumbnail is the embedded JPEG too

A 512 px grid thumbnail of an unedited raw now keeps the camera's own JPEG instead of rendering the sensor behind it. The grid showed that JPEG first in any case and then queued a decode of the whole raw to replace it — for a folder of 149 Fuji RAFs that is 8.3 GB of traffic, 45 s a photo at 1.2 MB/s, and a queue that delayed the render the user was actually waiting for (measured: the first loupe render of a cold photo finished 174 s after the click, most of it spent behind thumbnails).

• Session::embedded_thumb_is_final(photo) says whether the photo is an unedited raw whose camera JPEG the viewer is showing (the same "unedited raw" gate as the preview path: has_import_look).
• grid::skips_the_real_render(embedded_is_final, from_embedded) is the decision, unit-tested: a cached render as the stand-in, an edited photo and a raw with no embedded JPEG all still render, because their thumbnail must show the pipeline's output rather than the camera's.
• Whether the embedded JPEG can actually be read is only known when the quick job runs, so Session::quick_thumb_job carries the real thumbnail job as its last resort: a raw whose preview the loader can't read renders the raw instead of leaving the cell empty (issue #1448).
• The thumbnail key still changes with the settings hash, so editing a photo re-renders its thumbnail through the ordinary background path.

Measured on the real folder: idle for a minute, the app read 12 previews (26.9 MB) and decoded zero raws for thumbnails, against 638 MB of whole-file reads for the same 12 photos before. The render queue stayed empty.

The smallest JPEG that covers the box

Many TIFF-based raws keep more than one embedded JPEG. A Sony A7R VI ARW holds a 1616 × 1080 one (0.3 MB) beside the 9984 × 6656 one (5.6 MB), and Nikon NEF and Panasonic RW2 files have mid-sized copies too. The loupe stand-in and the grid thumbnail (embedded_preview_srgb) decode the smallest JPEG whose long edge is at least the size asked for (lightcraft_raw::embedded_preview_covering). They take the largest one when no other JPEG is big enough. The plan route picks the same way (preview_window takes the size asked for), so a raw read through the plan gets the JPEG the whole file would give. A smaller JPEG only counts as a copy of the picture when its aspect ratio is within 1 % of the largest one's and it has the same number of colour components. That rules out letterboxed thumbnails of another shape and the grey masks an iPhone ProRAW DNG keeps at the picture's shape. Sources for editing (an unsupported raw's JPEG, load_embedded_preview) and the camera-look fit still use the largest JPEG, so their geometry and colour do not depend on the size level.

A Canon CR3 picks the same way among its three JPEGs: an EOS R5 C file keeps an 8192 × 5464 JPEG track, a 1620 × 1080 PRVW box and a 160 × 120 THMB. Decoding the 8192 px one costs about 100 ms of entropy decoding however small it is asked for (DCT scaling only saves the inverse transform), against a few milliseconds for the 1620 px one. So a grid thumbnail and a loupe up to 1620 px read the PRVW, and a bigger loupe still reads the track (cr3_preview_box_list lists the boxes for embedded_preview_covering).

A plain 8-bit sRGB JPEG (no ICC profile, no Adobe RGB declaration from the container) is then decoded straight to 8-bit (lightcraft_codecs::decode_jpeg_srgb8_fit: DCT-scaled, box-averaged in linear light) without the float image the general decode builds; anything else keeps the general path.

lightcraft-cli bench-cull FOLDER times these steps (and the rest of a culling pass) on a real folder; tools/cull-bench.py times them in the running app.

Measured on 20 EOS R5 C CR3s from a wedding (local NVMe SSD, machine shared with other work): the loader at 1280 px went from 168–322 ms to 31 ms a photo; at 2560 px the decode of the 8192 px JPEG went from 182 to 151 ms (minimum of 15 runs; most of what remains is entropy decoding).

Tests

• crates/raw/src/preview.rs: the header-only range matches embedded_preview byte for byte; a clamped prefix, a padded extent, a late pointer, a lying pointer and a non-JPEG window are all covered. a_stand_in_takes_the_smallest_covering_jpeg_of_the_same_shape covers the picker: a smaller JPEG that covers the box is taken, the largest when none does, and a thumbnail of another shape or a grey mask never is.

• crates/engine/src/files.rs: on a synthetic RAF with a 200 KB tail, the quick path and the whole-file path produce identical pixels, and the read stays under half the file. On a synthetic TIFF/DNG whose preview only its tags locate — the plan path — the same identity holds and the CFA strip is not read; the same structure without the tag that makes it a raw declines instead of guessing, and the caller keeps reading it whole. So does a file whose own orientation only the whole-file path can show. One that states Adobe RGB takes the plan route and shows the same pixels as the whole-file path (the space changes them: decoded as sRGB they differ), and one that states sRGB stays on the fast path. A synthetic DNG with a full-size and a half-size JPEG gets, on the plan path, the half-size one for a box it covers and the full-size one otherwise, with the same pixels as the whole-file path (preview_loading_plans_the_smallest_covering_jpeg).

• crates/raw/tests/it/sparse_corpus.rs: preview_plan is asked for every corpus file, not only the ones whose header plan is Ready, and the preview it yields must equal the whole file's with the skipped bytes 0 and 0xFF. The test prints what each format reads.

• crates/engine/tests/it/preview_read.rs (opt-in, #[ignore]): the same measurement on a real file, typically on a share:

  LC_PREVIEW_RAW="/mnt/nas/…/DSCF0001.RAF" \
    cargo test --release -p lightcraft-engine --test it preview_read:: -- --ignored --nocapture
  

  No raw fixture is committed (media never is, see AGENTS.md).

A network share is still slower than a local disk — the preview itself is 5.6 MB — and the sensor data still has to come over the wire for the developed picture, which is a separate path (fs_pair_loader, the full decode). This change removes the preview's share of it, nothing more.