From ab438b05ca94113f6213b460515e9ca01f34e7d7 Mon Sep 17 00:00:00 2001 From: goujicheng Date: Sat, 10 Oct 2026 22:16:04 +0800 Subject: [PATCH 1/2] LR-IMP-PREVIEW-READ: a preview reads the raw's header, not the raw MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A grid thumbnail and a loupe preview of an unedited raw show the camera's embedded JPEG, which sits near the start of the file — for a 24 MP Fuji RAF, 5.6 MB of a 56 MB file (measured: DSCF9492.RAF). The loader read the file whole and threw the sensor data away, so every preview paid for 50 MB nobody looked at. On a local disk that is merely wasteful; on a network share, where photographers keep libraries, it is the wait: the same preview took 10 s over a GVFS/SMB Wi-Fi share against 0.96 s after this change. - `lightcraft_raw::bounded_preview(bytes)` locates the preview from the header alone and reports its byte range; `embedded_preview_from_range` extracts it, byte for byte what `embedded_preview` returns for the whole file (the pointer is read from the RAF header's fixed u32s at 84/88). - `engine::files::preview_window` reads a 4 KiB prefix, then — because the container reader clamps a slice to the buffer it was given, so a short prefix reports a plausible but truncated 3948 bytes — re-reads exactly the extent the header declares, and takes the window out of the prefix rather than reading those bytes twice. `LIGHTCRAFT_PROFILE=1` prints what each preview cost. - Formats whose preview only the whole file reveals (CR3 boxes, TIFF pointer tags past the prefix, CRW/MRW/X3F scans), a lying pointer, a short read and a file that changes underneath us all fall back to the whole-file path: a damaged header never costs the user their preview. - Tests: the header range matches `embedded_preview` byte for byte, with a clamped prefix, a padded extent, a late pointer, a lying pointer and a non-JPEG window covered; 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; `crates/engine/tests/preview_read.rs` (opt-in, `#[ignore]`) measures a real file on a share. No raw fixture is committed. - `docs/raw-preview-reads.md` records the mechanism and the numbers. Co-Authored-By: DeepSeek V3.2 --- README.md | 1 + crates/engine/src/files.rs | 181 +++++++++++++++++++++++++++- crates/engine/tests/preview_read.rs | 42 +++++++ crates/raw/src/lib.rs | 5 +- crates/raw/src/preview.rs | 163 +++++++++++++++++++++++++ docs/parity.md | 11 +- docs/raw-preview-reads.md | 62 ++++++++++ 7 files changed, 457 insertions(+), 8 deletions(-) create mode 100644 crates/engine/tests/preview_read.rs create mode 100644 docs/raw-preview-reads.md diff --git a/README.md b/README.md index 217092fbf..45e740071 100644 --- a/README.md +++ b/README.md @@ -307,6 +307,7 @@ LightCraft is young and moving fast. **Where we honestly stand** (details in the - **camera colour calibration:** Sony, Nikon, Panasonic, Fujifilm and Canon CR3 raws have guarded estimates from their camera JPEGs, with built-in ILCE-7CR, ILCE-7M4, X-H2S and X-T4 profiles; measured calibration is missing, and other raws or rejected fits retain a neutral matrix; - **compressed Olympus raws and unsupported CR3 variants:** these use embedded JPEG previews when present. Fujifilm lossless/lossy compressed RAF now decodes sensor data; [verification and existing-library reload instructions](docs/raf-compression.md); - **AI masks and denoise:** subject and sky selection are classical heuristics; + - **network libraries:** a preview reads the raw's header and its embedded JPEG only (56.5 MB → 5.9 MB, 10 s → 1 s on the test share), but the *developed* picture still needs the sensor data over the wire; see [docs/raw-preview-reads.md](docs/raw-preview-reads.md); - **on-screen HDR display, video and the Classic Print / Book / Map modules.** - **What's next:** see [where we're going](ROADMAP.md#where-were-going). diff --git a/crates/engine/src/files.rs b/crates/engine/src/files.rs index 31253f66a..b539c9c20 100644 --- a/crates/engine/src/files.rs +++ b/crates/engine/src/files.rs @@ -605,17 +605,144 @@ fn fit_box(max_edge: usize) -> lightcraft_codecs::DecodeOptions { /// Filesystem-backed embedded-preview hook (native). /// -/// Reads the whole file to find the preview, so it holds the memory gate for twice the file's size (the file and the -/// decoded preview): background work (the face scan) waits for room, interactive work is counted and never waits. +/// The quick path reads the file's header and its embedded preview and nothing else (see +/// [`read_preview_window`]); a format whose preview the header cannot point at falls back to the +/// whole-file path, which is what every format used to cost. The memory gate still counts the whole +/// file, which is what the decode of one can hold. pub fn fs_preview_loader() -> PreviewLoader { Arc::new(|path: &str, max_edge: usize| { let len = std::fs::metadata(path).map(|m| usize::try_from(m.len()).unwrap_or(usize::MAX)).unwrap_or(0); let gate = crate::memory::work_gate(); let _permit = if crate::memory::is_background() { gate.acquire(len.saturating_mul(2)) } else { gate.acquire_urgent(len.saturating_mul(2)) }; + if let Some(image) = preview_window(path).ok().flatten().and_then(|(_, window, _)| quick_image_srgb(&window, max_edge)) { + return Some(image); + } embedded_preview_srgb(&std::fs::read(path).ok()?, max_edge) }) } +/// What [`preview_window`] read from a file, so a caller can see what a preview cost. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct PreviewRead { + /// Bytes read. + pub read: u64, + /// The file's size. + pub total: u64, + /// Whether the preview came from a bounded read (`false`: the whole file was read, which is what + /// every preview cost before the header path existed). + pub header_path: bool, +} + +impl PreviewRead { + /// The share of the file that was read, `0.0`..=`1.0`. + pub fn fraction(self) -> f64 { + if self.total == 0 { + return 0.0; + } + (self.read as f64 / self.total as f64).clamp(0.0, 1.0) + } +} + +/// The file's header and its embedded preview, read without the rest of the file: `(header bytes, +/// preview bytes, what was read)`. `None` when the header points at no preview this build can find, +/// which is the caller's cue to read the file whole. +/// +/// Why it exists: a 56 MB Fuji RAF keeps its JPEG in the first 5.6 MB (measured: `DSCF9492.RAF`), +/// so reading the file whole to extract it costs ten times the bytes — and on a network share ten +/// times the wait (measured on that file: 2.5 s local against 25.6 s over SMB). `embedded_preview` +/// still needs the whole container, so the header comes back with the window; for a preview taken +/// out of a container that carries no preview colour space of its own (Nikon's maker note) the +/// whole-file fallback stays in charge. +pub fn preview_window(path: &str) -> Result, Vec, PreviewRead)>, String> { + use std::io::{Read, Seek, SeekFrom}; + + let mut file = std::fs::File::open(path).map_err(|e| format!("{path}: {e}"))?; + let total = file.metadata().map_err(|e| format!("{path}: {e}"))?.len(); + let mut prefix = read_prefix(&mut file, path, total)?; + + // What the header itself declares, before the container reader is asked: it clamps a slice to + // the buffer it was given, so a prefix that stops inside the declared preview yields a + // self-consistently short range that looks trustworthy (measured on a real 56 MB DSCF9492.RAF: + // a 4 KiB prefix reports 3948 bytes where the file holds 5.6 MB). Reading the declared extent + // first costs nothing — it lives in the first bytes of every format covered here. + if let Some(extent) = raf_preview_extent(&prefix) + && extent > prefix.len() as u64 + { + prefix = read_prefix_at(&mut file, path, extent.min(total))?; + } + let Some(range) = lightcraft_raw::bounded_preview(&prefix) else { return Ok(None) }; + // A preview at the file's end may have been padded past it: clamp rather than fail. + let end = range.offset.saturating_add(range.window_len).min(total); + let len = usize::try_from(end.saturating_sub(range.offset)).map_err(|_| format!("{path}: preview too large"))?; + // When the prefix already covers the range (the usual case: the prefix was grown to the declared + // extent), take the window out of it. Reading those bytes twice would double a 5.6 MB preview. + let prefix_len = prefix.len() as u64; + let from_prefix = usize::try_from(range.offset).ok().and_then(|start| prefix.get(start..start.checked_add(len)?)).map(<[u8]>::to_vec); + let (window, bytes_read) = match from_prefix { + Some(window) => (window, prefix_len), + None => { + let mut window = vec![0u8; len]; + file.seek(SeekFrom::Start(range.offset)).map_err(|e| format!("{path}: {e}"))?; + file.read_exact(&mut window).map_err(|e| format!("{path}: {e}"))?; + (window, prefix_len + len as u64) + } + }; + + // A lying pointer must not cost the user their preview: hand the caller the whole-file fallback. + if lightcraft_raw::embedded_preview_from_range(&window, range).is_none() { + return Ok(None); + } + let read = PreviewRead { read: bytes_read, total, header_path: true }; + // On a network share the bytes are the wait, so say what this preview actually cost. A window + // taken from the prefix cost nothing beyond the prefix itself. + if lightcraft_pipeline::profiling() { + eprintln!("[profile] preview {path}: read {} of {} bytes (header {}, window {})", read.read, total, prefix_len, window.len()); + } + Ok(Some((prefix, window, read))) +} + +/// The file's first [`lightcraft_raw::PREVIEW_PREFIX`] bytes (or the whole file when it is shorter), +/// which is what every format [`lightcraft_raw::bounded_preview`] covers keeps its pointer in. +fn read_prefix(file: &mut std::fs::File, path: &str, total: u64) -> Result, String> { + let len = lightcraft_raw::PREVIEW_PREFIX.min(usize::try_from(total).unwrap_or(usize::MAX)); + read_prefix_at(file, path, len as u64) +} + +/// The file's first `len` bytes, read from the start. +fn read_prefix_at(file: &mut std::fs::File, path: &str, len: u64) -> Result, String> { + use std::io::{Read, Seek, SeekFrom}; + let len = usize::try_from(len).map_err(|_| format!("{path}: file too large"))?; + let mut prefix = vec![0u8; len]; + file.seek(SeekFrom::Start(0)).map_err(|e| format!("{path}: {e}"))?; + file.read_exact(&mut prefix).map_err(|e| format!("{path}: {e}"))?; + Ok(prefix) +} + +/// The end of a Fuji RAF's preview block, from the two big-endian u32s every RAF header carries at +/// 84 (offset) and 88 (length) — the same fields `lightcraft_raw`'s RAF reader uses, read here +/// without the rest of the file so the prefix can be made big enough first. +fn raf_preview_extent(prefix: &[u8]) -> Option { + if !prefix.starts_with(b"FUJIFILMCCD-RAW") { + return None; + } + let u32_at = |at: usize| prefix.get(at..at + 4).map(|s| u32::from_be_bytes([s[0], s[1], s[2], s[3]])).map(u64::from); + let (offset, len) = (u32_at(84)?, u32_at(88)?); + (offset > 0 && len > 0).then(|| offset.checked_add(len)).flatten() +} + +/// The display-ready preview of a raw whose embedded JPEG was already located: the counterpart of +/// [`embedded_preview_srgb`] for [`read_preview_window`], which does not re-read the container. +/// `None` when the bytes are not a decodable image. +fn quick_image_srgb(window: &[u8], max_edge: usize) -> Option { + let mut d = lightcraft_codecs::decode(window, fit_box(max_edge)).ok()?; + if d.image.width.max(d.image.height) > max_edge { + d.image = fit(&d.image, max_edge, max_edge, Filter::Box); + d.alpha = None; + } + // The window is the JPEG itself, so its own EXIF carries the orientation; `decode` reports it. + Some(d.to_srgb8().oriented(Orientation::from_exif(d.orientation))) +} + /// The filesystem-backed [`PairLoader`]: the file is read and decoded once, and developed as usual and from the photo's /// denoised picture. It holds two pictures at once, so it counts for more at the memory gate than a plain load. pub fn fs_pair_loader() -> PairLoader { @@ -689,6 +816,56 @@ mod tests { use super::*; use lightcraft_codecs::{ChromaSubsampling, EncodeImage, EncodeMeta, Samples, encode_jpeg}; + /// A RAF whose preview pointer is in its header, then a large raw tail the reader must not need. + fn raf_with_embedded_jpeg(jpeg: &[u8], tail: usize) -> Vec { + let head = 160; + let mut f = vec![0u8; head]; + f.get_mut(..16).expect("head").copy_from_slice(b"FUJIFILMCCD-RAW "); + f.get_mut(84..88).expect("jpeg offset").copy_from_slice(&(head as u32).to_be_bytes()); + f.get_mut(88..92).expect("jpeg length").copy_from_slice(&(jpeg.len() as u32).to_be_bytes()); + f.extend_from_slice(jpeg); + f.extend(std::iter::repeat_n(0x33u8, tail)); + f + } + + /// A raw's preview is read from its header and its JPEG only. Every preview used to cost a + /// whole-file read, which on a 56 MB RAF over a network share is ten times the bytes and ten + /// times the wait (measured: 2.5 s local against 25.6 s over SMB, DSCF9492.RAF). The pixels the + /// quick path produces must equal the whole-file path's, exactly. + #[test] + fn preview_loading_reads_only_the_header_and_the_jpeg() { + let (w, h) = (48u32, 32u32); + let rgb: Vec = (0..w * h * 3).map(|i| (i * 13 % 251) as u8).collect(); + let img = EncodeImage::new(w, h, 3, Samples::U8(&rgb)); + let jpeg = encode_jpeg(&img, 90, ChromaSubsampling::S420, &EncodeMeta::default()).unwrap(); + let file = raf_with_embedded_jpeg(&jpeg, 200_000); + let dir = crate::tests_xmp::temp_dir("preview-window"); + let path = dir.join("dscf0001.raf"); + std::fs::write(&path, &file).unwrap(); + let path = path.to_string_lossy().into_owned(); + let max_edge = 512; + + let (header, window, read) = preview_window(&path).expect("the file reads").expect("it has a preview"); + assert_eq!(header.len(), lightcraft_raw::PREVIEW_PREFIX, "the header prefix is bounded"); + assert!(read.header_path, "the header path is what answered"); + assert_eq!(read.total, file.len() as u64); + assert!(read.fraction() < 0.5, "the read is a fraction of the file: {read:?}"); + assert!(window.len() < file.len() / 2, "the raw tail must not be read: {} of {} bytes", window.len(), file.len()); + + // The quick path and the whole-file path agree byte for byte. + let quick = quick_image_srgb(&window, max_edge).expect("the window holds a decodable preview"); + let whole = embedded_preview_srgb(&file, max_edge).expect("the whole file decodes too"); + assert_eq!((quick.width, quick.height), (whole.width, whole.height), "same preview size"); + assert_eq!(quick.data, whole.data, "byte for byte"); + + // A file with no locatable preview declines (the caller then reads it whole), a missing file errors. + let plain = dir.join("plain.jpg"); + std::fs::write(&plain, &jpeg).unwrap(); + assert!(preview_window(&plain.to_string_lossy()).expect("a plain file reads").is_none()); + assert!(preview_window(&dir.join("nope.raf").to_string_lossy()).is_err()); + let _ = std::fs::remove_dir_all(&dir); + } + /// Issue #367: probes read headers, not pixels, and report what the decode-based probe did: /// oriented dimensions (EXIF orientation 6 swaps them), metadata, the error for a truncated /// file or one that isn't an image. diff --git a/crates/engine/tests/preview_read.rs b/crates/engine/tests/preview_read.rs new file mode 100644 index 000000000..11ffec44e --- /dev/null +++ b/crates/engine/tests/preview_read.rs @@ -0,0 +1,42 @@ +//! Opt-in test of the embedded-preview read path on a **real file the user has** — typically one on a +//! network share, which is where reading only the header instead of the whole raw matters: +//! +//! LC_PREVIEW_RAW="/run/user/1000/gvfs/smb-share:.../DSCF0001.RAF" \ +//! cargo test --release -p lightcraft-engine --test preview_read -- --ignored --nocapture +//! +//! It reports what the preview cost and fails when the read is not the small part of the file the +//! header path promises. Skipped without `LC_PREVIEW_RAW` (there is no committed raw fixture: media +//! is never committed, see AGENTS.md). +use std::time::Instant; + +#[test] +#[ignore = "needs LC_PREVIEW_RAW pointing at a real raw file"] +fn a_preview_reads_only_the_header_and_the_preview() { + let Ok(path) = std::env::var("LC_PREVIEW_RAW") else { + eprintln!("skipped: set LC_PREVIEW_RAW="); + return; + }; + let file_len = std::fs::metadata(&path).expect("the file exists").len(); + assert!(file_len > 0, "empty file"); + + let started = Instant::now(); + let window = + lightcraft_engine::files::preview_window(&path).expect("the file reads").expect("it carries an embedded preview the header can point at"); + let elapsed = started.elapsed(); + let (_, preview, read) = window; + + let frac = read.fraction(); + println!( + "preview of {path}\n read {} of {} bytes ({:.1} %) in {:.2} s{}", + read.read, + read.total, + frac * 100.0, + elapsed.as_secs_f64(), + if read.header_path { " [header path]" } else { " [whole file]" } + ); + + assert!(read.header_path, "the header path must answer for a raw whose pointer is in its header"); + assert_eq!(read.total, file_len, "the report covers the whole file"); + assert!(frac < 0.5, "a preview must not cost most of the file: read {} of {} bytes", read.read, read.total); + assert!(preview.starts_with(&[0xff, 0xd8]), "the preview bytes are a JPEG: {:?}", preview.get(..4)); +} diff --git a/crates/raw/src/lib.rs b/crates/raw/src/lib.rs index f0331d610..6fc491ac4 100644 --- a/crates/raw/src/lib.rs +++ b/crates/raw/src/lib.rs @@ -52,7 +52,10 @@ pub use lightcraft_geom::Orientation; pub use lightcraft_meta::Metadata; pub use lightcraft_raster::Rgb32f; pub use opcodes::{Opcode, OpcodeLists}; -pub use preview::{PreviewColorSpace, embedded_preview, embedded_preview_color_space, embedded_preview_dynamic_range_optimized}; +pub use preview::{ + PREVIEW_PREFIX, PreviewColorSpace, PreviewRange, bounded_preview, embedded_preview, embedded_preview_color_space, + embedded_preview_dynamic_range_optimized, embedded_preview_from_range, +}; pub use semantic::{SemanticMask, semantic_masks}; use lightcraft_color::Xy; diff --git a/crates/raw/src/preview.rs b/crates/raw/src/preview.rs index d34fb4c6f..cff924b2f 100644 --- a/crates/raw/src/preview.rs +++ b/crates/raw/src/preview.rs @@ -167,6 +167,63 @@ pub fn embedded_preview(bytes: &[u8]) -> Option> { /// walking the marker segments and the entropy-coded data. `None` when it is not a complete, displayable /// (baseline or progressive) JPEG, so a stray `D8 FF` in other data is rejected. `*reach` is left at /// the furthest byte looked at (what the walk cost; see [`scan_for_jpeg`]). +/// Where a preview lives in a file, so a caller with a seekable file can read just that part of it. +/// +/// Why it exists: a 56 MB Fuji RAF keeps its JPEG in the first 5.6 MB (measured: DSCF9492.RAF at +/// 5.6 MB), so a grid thumbnail or a loupe preview has no reason to pull the remaining 50 MB — +/// which on a network share is the difference between a moment and half a minute. A caller that has +/// only bytes (`wasm`, tests) keeps using [`embedded_preview`]. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct PreviewRange { + /// Byte offset of the preview in the file. + pub offset: u64, + /// Bytes to read at [`Self::offset`]: the container's declared preview extent, which may carry + /// padding past the preview's end-of-image marker. + pub window_len: u64, +} + +/// The preview's range in the file, when the file's header alone locates it. +/// +/// `bytes` is the file's first [`PREVIEW_PREFIX`] bytes (more is fine). `None` means "read the file +/// whole and call [`embedded_preview`]": the formats not covered here (a TIFF-based raw's pointer +/// tag can sit in an IFD the prefix cuts short; CR3 scans box by box) and files whose pointer is +/// damaged. +/// +/// The caller reads `[range.offset, range.offset + range.window_len)` and passes those bytes to +/// [`embedded_preview_from_range`], which returns exactly what [`embedded_preview`] returns for the +/// whole file. +/// +/// Pass a prefix that actually covers the pointer's range (read [`Self::offset`] + +/// [`Self::window_len`] bytes, or start with [`PREVIEW_PREFIX`] and grow when it is not enough): +/// [`crate::vendor::raf::header`] clamps a slice to the buffer it was given, so a prefix that stops +/// inside the declared extent yields a shorter `window_len` than the file really holds. +pub fn bounded_preview(bytes: &[u8]) -> Option { + if !bytes.starts_with(b"FUJIFILMCCD-RAW") { + return None; + } + let jpeg = crate::vendor::raf::header(bytes).ok()?.jpeg?; + let offset = (jpeg.as_ptr() as usize).checked_sub(bytes.as_ptr() as usize)?; + if offset.checked_add(jpeg.len())? > bytes.len() { + return None; + } + Some(PreviewRange { offset: offset as u64, window_len: jpeg.len() as u64 }) +} + +/// The preview inside `window`, which holds the file's bytes at `[range.offset, range.offset + +/// range.window_len)`: the counterpart of [`bounded_preview`]. Padding past the end-of-image marker +/// is dropped, exactly as [`embedded_preview`] drops it. +pub fn embedded_preview_from_range(window: &[u8], range: PreviewRange) -> Option> { + let preview = window.get(..usize::try_from(range.window_len).ok()?)?; + if !is_dct_jpeg(preview) { + return None; + } + Some(trim_eoi(preview).to_vec()) +} + +/// How many bytes of a raw file are enough for [`bounded_preview`]: every covered format keeps its +/// preview pointer in a fixed header, well inside this. +pub const PREVIEW_PREFIX: usize = 4096; + fn jpeg_extent(b: &[u8], soi: usize, reach: &mut usize) -> Option<(usize, u8)> { let mut i = soi + 2; let r = walk_jpeg(b, &mut i); @@ -322,6 +379,112 @@ mod tests { j } + /// A minimal RAF: the fixed header (JPEG offset/length at 84/88), the JPEG, then a raw tail the + /// caller must not have to read. `jpeg_len` is written as declared, so a test can claim more than + /// the JPEG holds the way a padded container does. + fn raf_fixture(jpeg: &[u8], gap: usize, preamble: usize, declared_len: Option) -> Vec { + let head = 160 + preamble; + let jpeg_off = head; + let mut f = vec![0u8; head]; + f[..16].copy_from_slice(b"FUJIFILMCCD-RAW "); + f[84..88].copy_from_slice(&(jpeg_off as u32).to_be_bytes()); + f[88..92].copy_from_slice(&(declared_len.unwrap_or(jpeg.len()) as u32).to_be_bytes()); + // records directory and raw block are absent (offset 0), which `header` reads as "none" + f.extend_from_slice(jpeg); + f.extend(std::iter::repeat_n(0x33u8, gap)); + f + } + + /// A RAF's preview pointer sits at a fixed offset, so a header-sized prefix locates it and the + /// caller reads just that range instead of the whole file — the whole point on a network share. + #[test] + fn bounded_preview_locates_a_rafs_jpeg_from_the_header_alone() { + let jpeg = fake_jpeg(5000); + let file = raf_fixture(&jpeg, 40_000, 0, None); + // A prefix that covers the pointer's range: header + JPEG, and nothing of the tail. + let prefix_len = 8192.min(file.len()); + let prefix = &file[..prefix_len]; + + let range = bounded_preview(prefix).expect("a RAF's preview is found from its header"); + assert_eq!(range.offset, 160); + assert_eq!(range.window_len, jpeg.len() as u64); + assert!(range.offset + range.window_len <= prefix_len as u64, "the prefix covers the whole range: {range:?} of {prefix_len}"); + assert!((range.offset + range.window_len) < file.len() as u64, "the range stops short of the tail: {range:?} of {}", file.len()); + + // What the caller reads, and what it holds afterwards: identical to the whole-file answer. + let window = prefix.get(range.offset as usize..(range.offset + range.window_len) as usize).expect("the range lies inside the prefix"); + let bounded = embedded_preview_from_range(window, range).expect("the range holds the preview"); + assert_eq!(Some(bounded.clone()), embedded_preview(&file)); + assert!(bounded.ends_with(&[0xff, 0xd9]), "the preview ends at its EOI marker"); + + // A prefix that stops inside the declared extent is clamped by the container reader. The + // caller then reads a short window; what comes back is the whole JPEG it holds (the EOI + // marker is inside), never bytes past the window. + let short = &file[..2000]; + let clipped = bounded_preview(short).expect("a pointer before the cut is still found"); + assert!(clipped.window_len < jpeg.len() as u64, "clamped: {clipped:?}"); + let window = short.get(clipped.offset as usize..).expect("inside"); + let preview = embedded_preview_from_range(window, clipped).expect("the bytes are a JPEG start"); + // No end-of-image marker inside the window: the bytes come back as they are, exactly as the + // whole-file path returns an unclosed JPEG. The decoder refuses it later; nothing is invented. + assert_eq!(preview, window, "an unclosed JPEG is handed on unchanged, never padded"); + assert!(preview.len() <= window.len(), "never past the window"); + } + + /// The preview pointer may sit past the prefix (a long maker-note record before it), and a + /// container may declare padding after the JPEG: both stay correct, and the padding is dropped. + #[test] + fn bounded_preview_handles_a_late_pointer_and_padding() { + let jpeg = fake_jpeg(300); + let late = raf_fixture(&jpeg, 0, 9000, None); + let range = bounded_preview(&late).expect("the whole file is always a valid prefix"); + assert_eq!(range.offset, (160 + 9000) as u64); + let padded = raf_fixture(&jpeg, 500, 0, Some(jpeg.len() + 500)); + let range = bounded_preview(&padded).expect("a padded extent is still located"); + assert_eq!(range.window_len, (jpeg.len() + 500) as u64); + let window = padded.get(range.offset as usize..(range.offset + range.window_len) as usize).expect("the window is inside the file"); + let preview = embedded_preview_from_range(window, range).expect("the padding is dropped"); + assert_eq!(preview, embedded_preview(&padded).expect("the whole-file answer agrees")); + assert!(preview.ends_with(&[0xff, 0xd9])); + } + + /// Without a usable header or pointer the caller must read the file whole: the answer is `None`, + /// never a wrong range. + #[test] + fn bounded_preview_declines_what_the_header_cannot_answer() { + let jpeg = fake_jpeg(64); + let file = raf_fixture(&jpeg, 0, 0, None); + assert_eq!(bounded_preview(&jpeg), None, "not a raw at all"); + assert_eq!(bounded_preview(b""), None); + if let Some(short) = file.get(..64) { + assert_eq!(bounded_preview(short), None, "a header cut short has not shown the pointer yet"); + } + // a pointer that claims more than the file holds: `header` clamps the slice to the buffer, + // so the range never runs past the end (no out-of-bounds read can follow from it) + let mut lying = raf_fixture(&jpeg, 4096, 0, None); + lying[88..92].copy_from_slice(&(u32::MAX / 2).to_be_bytes()); + let clamped = bounded_preview(&lying).expect("a pointer inside the file is still usable"); + assert!(clamped.offset + clamped.window_len <= lying.len() as u64, "clamped to the file: {clamped:?}"); + // a range the window cannot satisfy yields nothing + assert_eq!(embedded_preview_from_range(&jpeg, PreviewRange { offset: 0, window_len: u64::MAX }), None); + // a TIFF-based raw: its pointer tag lives in an IFD this prefix may cut short + let mut tiff = b"II*\0\x08\0\0\0".to_vec(); + tiff.extend_from_slice(&[0u8; 64]); + assert_eq!(bounded_preview(&tiff), None); + } + + /// A range that does not hold a JPEG yields nothing, rather than a truncated image handed on. + #[test] + fn a_range_that_does_not_hold_a_jpeg_yields_nothing() { + let jpeg = fake_jpeg(200); + let range = PreviewRange { offset: 0, window_len: jpeg.len() as u64 }; + assert_eq!(embedded_preview_from_range(&jpeg, range).as_deref(), Some(&jpeg[..])); + assert_eq!(embedded_preview_from_range(&jpeg[..10], range), None, "window shorter than the range claims"); + let not_jpeg = vec![0u8; jpeg.len()]; + assert_eq!(embedded_preview_from_range(¬_jpeg, range), None, "not a JPEG"); + assert_eq!(embedded_preview_from_range(&[], PreviewRange { offset: 0, window_len: 0 }), None, "empty window"); + } + #[test] fn picks_largest_dct_jpeg() { let small = fake_jpeg(10); diff --git a/docs/parity.md b/docs/parity.md index d0bdc35c2..19e298b87 100644 --- a/docs/parity.md +++ b/docs/parity.md @@ -21,7 +21,7 @@ and prints the summary; `cargo xtask parity --write` refreshes the summary table | Section | ✅ | 🟡 | ⬜ | 🚫 | P0 done | P1 done | |---|---:|---:|---:|---:|---:|---:| -| A. Import (IMP) | 11 | 3 | 1 | 1 | 3/5 (60%) | 5/5 (100%) | +| A. Import (IMP) | 12 | 3 | 1 | 1 | 4/6 (67%) | 5/5 (100%) | | B. Library management (LIB) | 22 | 2 | 1 | 2 | 9/9 (100%) | 9/9 (100%) | | C. Views & navigation (VIEW) | 15 | 1 | 1 | 0 | 8/9 (89%) | 4/4 (100%) | | D. Search & filter (FILT) | 11 | 1 | 1 | 0 | 4/4 (100%) | 4/4 (100%) | @@ -42,15 +42,15 @@ and prints the summary; `cargo xtask parity --write` refreshes the summary table | S. Export (EXP) | 15 | 2 | 1 | 0 | 7/7 (100%) | 7/7 (100%) | | T. Share (SHARE) | 0 | 0 | 0 | 4 | — | — | | U. Map & location (MAP) | 0 | 1 | 1 | 0 | — | 0/1 (0%) | -| V. Preferences (PREF) | 7 | 1 | 2 | 2 | 1/1 (100%) | 5/5 (100%) | +| V. Preferences (PREF) | 6 | 2 | 2 | 2 | 1/1 (100%) | 4/5 (80%) | | W. Cloud & AI infrastructure (CLOUD / AI) | 1 | 0 | 1 | 2 | — | — | | X. Cross-cutting behaviours (BEHAV) | 18 | 6 | 1 | 1 | 8/8 (100%) | 6/9 (67%) | | Y. Menus | 82 | 0 | 4 | 8 | 47/47 (100%) | 23/23 (100%) | | Z. Keyboard shortcuts (desktop) | 75 | 3 | 3 | 1 | 49/52 (94%) | 23/24 (96%) | -| Lightroom Classic extras | 32 | 11 | 39 | 9 | — | 22/24 (92%) | -| **Total** | 393 | 39 | 84 | 36 | 192/200 (96%) | 142/152 (93%) | +| Lightroom Classic extras | 33 | 15 | 35 | 9 | — | 23/25 (92%) | +| **Total** | 398 | 49 | 73 | 36 | 193/201 (96%) | 143/155 (92%) | -Weighted completion (✅ = 1, 🟡 = ½, 🚫 left out): **79.9%** of 516 in-scope rows — P0 98.0% of 200 · P1 95.7% of 152 · P2 42.9% of 163. +Weighted completion (✅ = 1, 🟡 = ½, 🚫 left out): **81.2%** of 520 in-scope rows — P0 98.0% of 201 · P1 95.2% of 155 · P2 47.2% of 163. ## Top gaps @@ -148,6 +148,7 @@ under the UI command that wraps it (a no-op error); the UI command now wins. | LR-IMP-SIDECAR-SPLIT | Separate XMP sidecar variants | P2 | ⬜ | `cmd:library.xmpPreferences` | sidecar naming option exists (stem/full), no split sidecars | | LR-IMP-FORMATS | Supported formats | P0 | 🟡 | `crates/codecs/src/lib.rs`, `crates/raw/src/lib.rs`, `crates/raw/src/jxl.rs` | JPEG, PNG, TIFF (1- to 64-bit integer, 16- to 64-bit float, incl. bilevel and CCITT fax), WebP, JXL, PSD, GIF, BMP; DNG (incl. lossy / Smart Preview DNG and DNG 1.7 JPEG XL tiles/strips: lossless ones decode bit-exactly on synthetic CFA and LinearRaw files, lossy ones are restored to the declared linear primaries without clipping or gamut mapping, checked on one real file with 108 lossy tiles, and any tile that fails to decode makes the file preview-only; DNG 1.7 row/column-interleaved rasters (`RowInterleaveFactor` / `ColumnInterleaveFactor`) are undone before the mosaic is read, so a file from Adobe's converter with a 2×2 interleave no longer decodes as four scaled-down copies in the wrong colours; a dimension the factor does not divide decodes with short trailing fields; verified on 4 real ILCE-6400 JPEG XL DNGs rendering bit-identical to their non-interleaved twins, factors above 2 rest on the plain reading of the tag; a single-chunk JPEG XL preview IFD is offered as the embedded preview; a DNG whose samples pile up at one value well below its stated `WhiteLevel`, as a camera app's 12-bit Bayer DNG that states 4095 and clips at 3567, has those samples raised to the white level on decode, so highlight reconstruction sees the clipped areas instead of white balance tinting them magenta, issue #548, `crates/raw/src/saturation.rs`), CR2 (colour-filter layout from the file's `CR2CFAPattern` tag, issue #85), ARW (pre-2017 bodies: white balance and black level from the encrypted `SR2SubIFD`, issue #148, its `WB_RGGBLevels` being the white balance the camera applied, issue #535; the DSLR-A900's packed 12-bit strip, two pixels per three bytes, read only when the strip is exactly 1.5 bytes per pixel, with its camera-JPEG window centred, checked on one CC0 file (A850 unmeasured); downsized Sony lossless YCbCr 4:2:0 / 4:2:2 tiles decoded to linear RGB, verified on private ILCE-7M4 3:2 & 4:3 examples including 16-bit full-resolution export; Sony DSC-R1 .SR2 decodes, its big-endian 16-bit words read in the order that fits the sample range, checked on the CC0 3221 sample; its crop and white balance live in the SR2SubIFD and are not read yet), NEF (uncompressed, lossless and lossy compressed 12/14-bit, `crates/raw/src/vendor/nefc.rs`), RAF (uncompressed, lossless/lossy compressed Bayer and X-Trans; `crates/raw/src/vendor/rafc.rs`, full sensor verification on 13 bodies, `docs/raf-compression.md`), RW2 / Leica RWL / Panasonic RAW in every raw format (compressed 4 and 6, the prefix-coded strips of format 8 from the GH6 on, packed 2/5/7, the 16-bit words of the 2005–2007 bodies; black levels, in-camera aspect crops and mapped-out defect pixels; 178 CC0 files from 118 bodies checked, `crates/raw/src/vendor/rw2.rs`), PEF, ORF (uncompressed; colour-filter layout from the file's Exif `CFAPattern`; 12.8 bit/px 16-byte blocks of ten 12-bit samples + a zero pad byte, E-300 / E-330 / E-500 verified on CC0 files, E-M5 Mark II / PEN-F high-res files decode smooth but CFA and black unverified), Hasselblad 3FR and FFF (a TIFF without a DNG version tag that describes its CFA IFD, levels, crop and white balance with DNG's tags; `RawFormat::CfaTiff`, read by `dng::decode_as`, RGGB when the file states no `CFAPattern`): uncompressed (X1D, X1D II, X2D, CFV 100C) and Hasselblad's lossless JPEG with scan selection value 8 (every FFF; H3D, H4D and CFV-50c 3FR), `ljpeg::decode_hasselblad`, its rule measured on 14 CC0 files with the ljpeg-explorer tool, Samsung SRW without compression (NX5, NX10, NX11 and the NX20-generation bodies NX20, NX200, NX210, NX1000 and NX1100 as 12-bit packed samples in either bit order, EX1 and WB2000 as 16-bit words; layout, camera-JPEG framing, levels and white balance from the maker note, `crates/raw/src/vendor/srw.rs`; median ΔE vs the camera JPEG 2.2–7.6 on 11 of the 12 files from 10 bodies checked, 10.7 (5.7 registered) on the backlit WB2000 sample). 12-bit NEF black level: maker note `0x003d` is in 14-bit units (D750, D780, D850, D7500, Z 50 checked). Lossy type 2 NEF curves of version `0x44 0x40` (D780, D6, Z 5, Z 6, Z 7, Z 7_2) span a quarter of the sample range, read from the table's own point spacing. CR3 lossless CRX Bayer and version 0x100/0x200 C-RAW decodes to sensor pixels with timed white balance, black/white levels and file crop (the shot's aspect ratio from the maker note's `AspectInfo`); full sensor samples match the reference on M50/R100/R8 (`crates/raw/tests/cr3_corpus.rs`, `docs/cr3.md`). Unsupported coding variants retain metadata and use the embedded JPEG when available; HEVC preview decoding remains unsupported. Missing: CR3 unverified CRX variants, compressed ORF, compressed Samsung SRW (NX1, NX30, NX300, NX500, NX2000, NX3000, NX3300, NX mini: preview only with the reason), NEFs labelled compressed (34713) but stored uncompressed without a `0x0096` table (Z 6 packed 14-bit, D850 12-bit uncompressed), Nikon High Efficiency NEF (HE / HE★ from the Z 8, Z 9, Z 6III and Z f: compression 34713 with a JPEG XS codestream and no `0x0096` table; no public specification, so preview only with the reason "Nikon High Efficiency NEF", issue #193; Lossless compressed NEFs from the same bodies decode), NEF "lossy after split" (preview only: imported with `preview_only` = the decoder's reason, rendered as a rendered JPEG, flagged by a grid badge and loupe/Edit/Info notices, `previewOnly` in `catalog.query`; Reload clears it once the file decodes), TIFF-based raws whose raw data sits in a private block (Phase One / Leaf IIQ, Canon EOS-1D / 1Ds and Kodak DCS TIFFs: IFD0 is only a reduced RGB image next to a much larger declared picture) are recognised from that structure and import as `preview_only` with the reason, instead of opening as a thumbnail-sized ordinary image (`thumbnail_shell` in `crates/raw/src/lib.rs`), Recognised raws LightCraft cannot decode open as `preview_only` with any usable embedded JPEG, also Canon CRW, Minolta MRW and Sigma X3F (containers recognised by magic, preview found by a structural JPEG scan), Kodak KDC (IFD0 without `ImageWidth`), Leaf MOS and Epson ERF (scan), and any decode failure of a recognised raw, not only an unsupported variant; ones with no JPEG still fail with "without an embedded preview", AVIF decode (HEIC decodes only behind the non-default `heif` feature, which the release packages enable: `crates/heif`, heic-rs for the container and HEVC (bit-exact against libde265 on iPhone tiles) plus our own colour conversion, matching libheif within 1 code value on iPhone-style grids (VUI full range, Display P3 ICC, nclx, 10-bit, irot/imir/clap, gain map/depth ignored); 4:2:0/monochrome only, 4:2:2/4:4:4 Canon/Sony HIF refused; same policy as PhotoCraft), palette (indexed-colour) TIFF (refused by the `tiff` crate) | | LR-IMP-CAMERA-COVERAGE | Camera coverage, verified per model | P0 | 🟡 | `crates/raw/tests/corpus.rs`, `xtask/src/main.rs` | a supported container is not the same as every camera that writes it decoding correctly: ~55 CC0 corpus files plus 6 exact-sensor CR3 cases (plus ~60 NEFs checked by hand and 178 Panasonic / Leica RW2, RWL and RAW files from 118 bodies, checked against each file's own JPEG) against the >1,000 models Lightroom lists; per-model differences still surface (e.g. the CR2 colour-filter layout differed by model until it was read from the file's own tag, issue #85, checked on 35 CR2 bodies; CR2 black levels were read from border columns light already reaches, left of `SensorInfo`'s border, so CR2s rendered dark with crushed shadows (EOS 6D: 2591 instead of 2047), now measured from the masked columns only, checked on 8 corpus bodies; pre-2017 Sony ARWs opened green until their scrambled white balance / black level were read, issue #148, checked on 16 ARWs from 15 Sony bodies; their white balance now comes from the encrypted `SR2SubIFD`'s `WB_RGGBLevels`, the gains the camera applied, which 14 bodies (DSLR-A450 … A700, NEX-3/5/C3, SLT-A33/A35/A55, ILCE-6001, UMC-R10C) had no other source for and which the maker-note estimate read before missed by up to 100 % on preset shots, issue #535, checked against ExifTool on 100 decoded ARWs from 87 Sony bodies; the encrypted SR2 black level is now read from its directory entry (the DSLR-A450/A500/A550/A700 read 354–975 instead of 512), checked on 126 ARWs from 97 Sony bodies, and downsized lossless M/S ARWs use their measured black level 1024 instead of 512, checked on 12 files from 4 bodies, issue #535; pre-2017 Sony bodies shot in the camera's 16:9 mode (ILCE-7SM2, DSLR-A580) now get the 16:9 crop of their camera JPEG instead of the whole 3:2 frame with padding columns, issue #535; Canon PowerShot and EOS M CR2s whose `ColorData` is stored as bytes opened green until the bytes were read as 16-bit words, 25 files from 25 bodies checked). Compressed RAF sensor arrays verified on 13 Fujifilm bodies (`docs/raf-compression.md`). Sony ILCE-7CR (61 MP): lossless compressed L and M and compressed ARW2 samples of one scene in the corpus (black level, default crop, as-shot gains, lossless vs compressed mosaic agreement, fitted camera look), and all nine public codings (also uncompressed, small and APS-C crop) decode and fit. Grow the CC0 corpus per model and test each sample decodes with plausible colour. Nikon CropArea and untagged-preview colour-space regression tests; private Z 8 crop verified. | +| LR-IMP-PREVIEW-READ | Preview reads the header, not the raw | P0 | ✅ | `crates/raw/src/preview.rs` (`bounded_preview`, `embedded_preview_from_range`), `crates/engine/src/files.rs` (`preview_window`), `docs/raw-preview-reads.md` | a grid thumbnail and a loupe preview of an unedited raw show the camera's embedded JPEG, which sits near the start of the file (a 24 MP Fuji RAF keeps its 5.6 MB JPEG in a 56 MB file), so the preview loader reads the header and that JPEG instead of the whole file: 56.5 MB → 5.9 MB and ~10 s → 0.96 s measured on one real RAF over a GVFS/SMB Wi-Fi share (byte-identical preview pixels; `LIGHTCRAFT_PROFILE=1` reports the bytes); the RAF pointer is read from its fixed header fields, formats whose preview only the whole file reveals (CR3 boxes, TIFF pointer tags past the prefix, CRW/MRW/X3F scans) keep the whole-file path, and a lying pointer, a short read or a file that changes underneath us falls back to it rather than losing the preview | | LR-IMP-CULL-AT-IMPORT | Culling analysis at import | P2 | 🟡 | `cmd:photo.analyze` | run Assisted Culling on the imported photos (they're selected after an import); not automatic | | LR-IMP-MOVE | Move on import [Classic] | P1 | ✅ | `cmd:library.import` (`mode` move), `crates/engine/src/import_move.rs`, `crates/engine/src/tests_import_move.rs`, `crates/ui-egui/src/import.rs` | Transfer ▸ Move with Copy's destination, folders (day / month / one folder / custom template), rename template and example destination; XMP sidecars (both namings) move along; each source is removed only after its destination is written (hard link on the same volume, else copied, synced and compared byte for byte) and its catalog record is saved; failed, duplicate, unchecked files keep their sources, taken names get -1, -2…, never overwritten; files already in the destination/library are added in place; sources that can't be removed (read-only card) are kept and reported (`kept`). Undo removes the photos from the library but leaves the moved files at the destination. No Copy as DNG while moving | | LR-IMP-DNG-CONVERT | Convert to DNG on import [Classic] | P2 | ✅ | `cmd:library.import` (`dng`), `crates/ui-egui/src/import.rs` | copy imports: Raw files ▸ Copy as DNG (lossless; the card is untouched); the raw copy is removed only once its DNG is verified and on disk (issue #106) | diff --git a/docs/raw-preview-reads.md b/docs/raw-preview-reads.md new file mode 100644 index 000000000..51058255f --- /dev/null +++ b/docs/raw-preview-reads.md @@ -0,0 +1,62 @@ +# 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 `u32`s 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 (CR3 scans boxes; a TIFF pointer tag can sit in +an IFD the prefix cuts short; CRW/MRW/X3F are found by scanning) keep 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 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) +``` + +## 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. +- `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. +- `crates/engine/tests/preview_read.rs` (opt-in, `#[ignore]`): the same measurement on a **real** + file, typically on a share: + + ```sh + LC_PREVIEW_RAW="/mnt/nas/…/DSCF0001.RAF" \ + cargo test --release -p lightcraft-engine --test 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. From bc2cbf41db0dabbc40b889a2aabd64fa1ddc1b8f Mon Sep 17 00:00:00 2001 From: goujicheng Date: Sun, 11 Oct 2026 09:39:32 +0800 Subject: [PATCH 2/2] LR-IMP-PREVIEW-READ: an unedited raw's grid thumbnail is its embedded JPEG MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The grid already showed the camera's embedded preview first, then queued a render of the whole raw to replace it. For a 512 px thumbnail that render decodes 50 of a 56 MB Fuji RAF's bytes for a picture the 4 416 × 2 944 embedded JPEG already covers — 45 s a photo on the 1.2 MB/s share this was measured on, 8.3 GB of traffic for a 149-photo folder, 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). Idle for a minute afterwards, the same folder read 12 previews (26.9 MB) and decoded zero raws for thumbnails, against 638 MB of whole-file reads before. - `Session::embedded_thumb_is_final` answers whether a photo is an unedited raw whose camera JPEG the viewer is showing — the same `has_import_look` gate the preview path uses. - `grid::skips_the_real_render` is the decision (unit-tested): a cached render as stand-in, an edited photo and a raw without an embedded JPEG all still render, because their thumbnail must show the pipeline's output rather than the camera's. - `Renderer::remember_embedded_thumb` records the quick render's key and the bucket, and `thumb_quick_is_final` / `thumb_quick_pending` let the per-frame grid request stop at the embedded preview instead of rebuilding the render job (and its cache key) every frame. - The thumbnail key still follows the settings hash, so editing a photo re-renders its thumbnail through the ordinary background path. `docs/raw-preview-reads.md` and the `LR-IMP-PREVIEW-READ` parity row record the behaviour and the numbers. Co-Authored-By: DeepSeek V3.2 --- crates/engine/src/media.rs | 17 +++++++++ crates/ui-egui/src/panels/grid.rs | 39 ++++++++++++++++++--- crates/ui-egui/src/render.rs | 58 +++++++++++++++++++++++++++---- crates/ui-egui/src/tests_grid.rs | 17 +++++++++ docs/parity.md | 2 +- docs/raw-preview-reads.md | 20 +++++++++++ 6 files changed, 141 insertions(+), 12 deletions(-) diff --git a/crates/engine/src/media.rs b/crates/engine/src/media.rs index 6d5b548f1..4716b58cb 100644 --- a/crates/engine/src/media.rs +++ b/crates/engine/src/media.rs @@ -1212,6 +1212,23 @@ impl crate::Session { } } + /// Whether `p`'s thumbnail can be the camera's own JPEG, so a frontend can skip the sensor + /// decode behind it. + /// + /// The grid shows this JPEG first in any case ([`QuickJob`]: "grid thumbnails of unedited raws + /// likewise start from the embedded preview"), and then paid for a render of the raw to replace + /// it. That render decodes the whole sensor — 50 of a 56 MB Fuji RAF's bytes — for a 512 px + /// thumbnail the 4 416 × 2 944 embedded JPEG already covers, and on a share at 1.2 MB/s it is + /// 45 s a photo: a 149-photo folder spent 8.3 GB of traffic on thumbnails, and the queue behind + /// it delayed the render the user was waiting for. + /// + /// Only unedited raws answer `true`: any edit must be rendered, and `has_import_look` is what + /// says the photo still looks the way it did at import. A photo the user edits re-renders + /// through the ordinary path, because its thumbnail key (settings hash) changes. + pub fn embedded_thumb_is_final(&self, p: &Photo) -> bool { + self.embedded_of(p).is_some() + } + /// The camera's embedded preview of a raw file, for the face scan. Faces are read from the unedited picture, so the /// photo's edits do not matter, and the camera's own JPEG (oriented, display-ready) costs a fraction of decoding the /// raw. `None` for anything else, and where the host installed no loader. diff --git a/crates/ui-egui/src/panels/grid.rs b/crates/ui-egui/src/panels/grid.rs index 4264e4290..d3e1f1c59 100644 --- a/crates/ui-egui/src/panels/grid.rs +++ b/crates/ui-egui/src/panels/grid.rs @@ -444,8 +444,10 @@ fn group_header(app: &mut LightcraftApp, ui: &mut egui::Ui, run: &DateRun, ids: } /// Request a grid/filmstrip thumbnail at `priority`. An unedited raw without a thumbnail texture -/// first gets a stand-in (its cached thumbnail, else its embedded camera preview), and its real -/// render then follows in the background. +/// gets its embedded camera preview, and the render of the raw behind it follows in the background +/// — except where that render would only redraw what the embedded JPEG already shows (see +/// [`lightcraft_engine::media::Session::embedded_thumb_is_final`]), which for a folder of raws on a +/// network share is the difference between reading every file whole and reading a preview each. pub fn request_thumb(app: &mut LightcraftApp, id: PhotoId, size: usize, priority: u32) { let bucket = lightcraft_engine::media::thumb_bucket(size); if let Some(photo) = app.session.catalog.photo(id) @@ -453,19 +455,35 @@ pub fn request_thumb(app: &mut LightcraftApp, id: PhotoId, size: usize, priority { return; } + // The camera's embedded preview is this photo's thumbnail (unedited raw): once its quick render + // has arrived there is nothing left to ask for. Without this the grid would rebuild the render + // job — and its cache key — on every frame, which is what the embedded-thumbnail record settles. + if let Some(photo) = app.session.catalog.photo(id) + && (app.renderer.thumb_quick_is_final(photo, bucket, priority) || app.renderer.thumb_quick_pending(photo, bucket)) + { + return; + } let Some(job) = app.session.thumb_job(id, size) else { return }; #[cfg(test)] { app.renderer.thumb_jobs_built += 1; } let quick = if app.renderer.textures.contains_key(&Slot::Thumb(id)) { None } else { app.session.quick_thumb_job(&job) }; + // A cached render is a stand-in for whatever comes next; an embedded camera preview of an + // unedited raw is the picture itself, so no sensor decode is scheduled behind it. + let embedded_is_final = + quick.is_some() && app.session.catalog.photo(id).is_some_and(|p| skips_the_real_render(app.session.embedded_thumb_is_final(p), true)); if let Some(photo) = app.session.catalog.photo(id) { - app.renderer.remember_thumb(photo, bucket, job.key, quick.is_some()); + if embedded_is_final { + app.renderer.remember_embedded_thumb(photo, bucket, job.key); + } else { + app.renderer.remember_thumb(photo, bucket, job.key, quick.is_some()); + } } match quick { Some(q) => { app.renderer.request_quick(Slot::ThumbQuick(id), q, priority + 1); - if !app.renderer.is_pending(Slot::ThumbQuick(id)) { + if !embedded_is_final && !app.renderer.is_pending(Slot::ThumbQuick(id)) { app.renderer.request(Slot::Thumb(id), job, BACKGROUND_THUMB_PRIORITY); } } @@ -473,6 +491,19 @@ pub fn request_thumb(app: &mut LightcraftApp, id: PhotoId, size: usize, priority } } +/// Whether a photo's grid thumbnail is already the picture it should show, so the render of the raw +/// behind it is skipped. `embedded_is_final` is the engine's answer +/// ([`lightcraft_engine::media::Session::embedded_thumb_is_final`]: the photo is an unedited raw +/// whose camera JPEG the viewer is showing) and `from_embedded` says the stand-in actually came from +/// the embedded preview rather than a cached render of the file. +/// +/// Skipping matters where the file is expensive to read: decoding a 56 MB Fuji RAF to draw a 512 px +/// thumbnail — which the 4 416 × 2 944 embedded JPEG already covers — cost 45 s a photo over a +/// 1.2 MB/s share, and the queue it built delayed the render the user was waiting for. +pub(crate) fn skips_the_real_render(embedded_is_final: bool, from_embedded: bool) -> bool { + embedded_is_final && from_embedded +} + /// Rendered thumbnails replacing embedded previews: after everything on screen. pub const BACKGROUND_THUMB_PRIORITY: u32 = 3; diff --git a/crates/ui-egui/src/render.rs b/crates/ui-egui/src/render.rs index 6b2293f65..4f047cc56 100644 --- a/crates/ui-egui/src/render.rs +++ b/crates/ui-egui/src/render.rs @@ -174,6 +174,8 @@ pub struct Renderer { /// Last thumbnail inputs; weak identities do not retain photo histories or force deep clones. /// (photo, size bucket, job key, whether the request went through an embedded stand-in) thumb_inputs: HashMap, usize, u64, bool)>, + /// Photos whose grid thumbnail is the camera's embedded preview itself (no render behind it). + embedded_thumbs: HashMap, usize, u64)>, pool: JobPool, /// Jobs run elsewhere (see [`RenderOffload`]); `queue` holds the ones not started yet. offload: Option>, @@ -251,6 +253,7 @@ impl Renderer { preview_generation: None, pool: JobPool::new(threads), thumb_inputs: HashMap::new(), + embedded_thumbs: HashMap::new(), offload: None, queue: Vec::new(), seq: 0, @@ -295,6 +298,30 @@ impl Renderer { } /// Remember the inputs of the thumbnail just requested (`quick`: through a stand-in). + /// Whether the camera's embedded preview *is* this photo's thumbnail: its quick render arrived + /// (so `Slot::ThumbQuick` holds the picture) and no edit has moved the photo on to a settings + /// hash of its own. The grid stops here instead of decoding the raw behind a thumbnail the + /// embedded JPEG already covers — see `grid::skips_the_real_render`. + pub fn thumb_quick_is_final(&self, photo: &Arc, bucket: usize, priority: u32) -> bool { + let Some((old, size, key)) = self.embedded_thumbs.get(&photo.id) else { return false }; + old.as_ptr() == Arc::as_ptr(photo) && *size == bucket && !self.request_needed(Slot::ThumbQuick(photo.id), *key, priority) + } + + /// Whether this photo's embedded-preview thumbnail is being fetched right now: the grid has + /// asked, and neither the picture nor a render behind it is owed. + pub fn thumb_quick_pending(&self, photo: &Arc, bucket: usize) -> bool { + let Some((old, size, _, quick)) = self.thumb_inputs.get(&photo.id) else { return false }; + old.as_ptr() == Arc::as_ptr(photo) && *size == bucket && *quick && self.pending.contains_key(&Slot::ThumbQuick(photo.id)) + } + + /// Remember that the camera's embedded preview is this photo's final thumbnail, so the grid's + /// per-frame requests stop at it (the quick render's key, which [`Self::thumb_quick_is_final`] + /// compares against). + pub fn remember_embedded_thumb(&mut self, photo: &Arc, bucket: usize, key: u64) { + self.remember_thumb(photo, bucket, key, true); + self.embedded_thumbs.insert(photo.id, (Arc::downgrade(photo), bucket, key)); + } + pub fn remember_thumb(&mut self, photo: &Arc, bucket: usize, key: u64, quick: bool) { if self.thumb_inputs.len() >= 1024 && !self.thumb_inputs.contains_key(&photo.id) { self.thumb_inputs.retain(|_, (p, _, _, _)| p.strong_count() > 0); @@ -1026,8 +1053,9 @@ mod thumbnail_tests { #[test] fn raw_quick_path_frames_build_no_jobs() { - // an unedited raw: the grid shows its embedded preview first (held here until released), - // then queues the real thumbnail behind everything on screen + // an unedited raw: the grid shows its embedded preview (held here until released) and stops + // there — the camera JPEG at 4 416 × 2 944 already covers a 512 px thumbnail, so decoding the + // whole raw behind it only costs the file read (45 s a photo on a 1.2 MB/s share) let gate = Arc::new(std::sync::Mutex::new(())); let held = gate.lock().unwrap(); let mut s = Session::new(); @@ -1055,14 +1083,30 @@ mod thumbnail_tests { std::thread::sleep(std::time::Duration::from_millis(5)); app.renderer.poll(&ctx, &mut app.session); } - // the stand-in is shown: one more job queues the real thumbnail at background priority, - // and the grid asking at its own (higher) priority every frame does not rebuild it + // the embedded preview is the thumbnail: no real render is queued behind it, and the grid + // asking every frame neither rebuilds the job nor re-requests the preview for _ in 0..180 { request(&mut app); } - assert_eq!(app.renderer.thumb_jobs_built, 2); - assert_eq!(app.renderer.queue.len(), 1); - assert_eq!(app.renderer.pending.get(&Slot::Thumb(PhotoId(1))).map(|p| p.1), Some(crate::panels::grid::BACKGROUND_THUMB_PRIORITY)); + assert_eq!(app.renderer.thumb_jobs_built, 1, "an unedited raw's embedded preview is the thumbnail"); + assert!(app.renderer.queue.is_empty(), "nothing is decoded behind it"); + assert!(!app.renderer.is_pending(Slot::Thumb(PhotoId(1)))); + + // an edit takes the embedded preview out of the picture: the real thumbnail is rendered then + let mut edited = (*photo()).clone(); + edited.kind = lightcraft_catalog::MediaKind::Raw; + edited.develop = Arc::new({ + let mut d = edited.camera_defaults(); + d.light.exposure = 0.5; + d + }); + let (mut app, _, _ctx) = fixture_with(Session::new(), edited); + app.renderer.set_offload(Box::new(Blocked)); + for _ in 0..180 { + request(&mut app); + } + assert_eq!(app.renderer.thumb_jobs_built, 1); + assert!(app.renderer.is_pending(Slot::Thumb(PhotoId(1))) || !app.renderer.queue.is_empty(), "an edited raw renders its thumbnail"); } #[test] diff --git a/crates/ui-egui/src/tests_grid.rs b/crates/ui-egui/src/tests_grid.rs index e1a815a54..7aafb212e 100644 --- a/crates/ui-egui/src/tests_grid.rs +++ b/crates/ui-egui/src/tests_grid.rs @@ -155,3 +155,20 @@ fn unloaded_thumbnails_show_their_selection() { } assert!(checked >= 3, "checked {checked}"); } + +/// A folder of unedited raws on a slow share: the grid must not decode every raw to draw a 512 px +/// thumbnail the embedded camera JPEG already covers. Measured on a 56 MB Fuji RAF over a 1.2 MB/s +/// share, that decode is 45 s a photo, and 149 of them queued in front of the render the user asked +/// for. The embedded JPEG stays a *stand-in* — replaced by a real render — whenever it is not the +/// picture the photo should show. +#[test] +fn an_unedited_raws_thumbnail_skips_the_sensor_decode() { + use crate::panels::grid::skips_the_real_render; + // unedited raw, embedded camera JPEG on screen: nothing behind it to render + assert!(skips_the_real_render(true, true)); + // a cached render of the file was the stand-in, even for an unedited raw: the real one follows + assert!(!skips_the_real_render(true, false)); + // edited photo, or a raw with no embedded JPEG: render it + assert!(!skips_the_real_render(false, true)); + assert!(!skips_the_real_render(false, false)); +} diff --git a/docs/parity.md b/docs/parity.md index 19e298b87..1d8a0e578 100644 --- a/docs/parity.md +++ b/docs/parity.md @@ -148,7 +148,7 @@ under the UI command that wraps it (a no-op error); the UI command now wins. | LR-IMP-SIDECAR-SPLIT | Separate XMP sidecar variants | P2 | ⬜ | `cmd:library.xmpPreferences` | sidecar naming option exists (stem/full), no split sidecars | | LR-IMP-FORMATS | Supported formats | P0 | 🟡 | `crates/codecs/src/lib.rs`, `crates/raw/src/lib.rs`, `crates/raw/src/jxl.rs` | JPEG, PNG, TIFF (1- to 64-bit integer, 16- to 64-bit float, incl. bilevel and CCITT fax), WebP, JXL, PSD, GIF, BMP; DNG (incl. lossy / Smart Preview DNG and DNG 1.7 JPEG XL tiles/strips: lossless ones decode bit-exactly on synthetic CFA and LinearRaw files, lossy ones are restored to the declared linear primaries without clipping or gamut mapping, checked on one real file with 108 lossy tiles, and any tile that fails to decode makes the file preview-only; DNG 1.7 row/column-interleaved rasters (`RowInterleaveFactor` / `ColumnInterleaveFactor`) are undone before the mosaic is read, so a file from Adobe's converter with a 2×2 interleave no longer decodes as four scaled-down copies in the wrong colours; a dimension the factor does not divide decodes with short trailing fields; verified on 4 real ILCE-6400 JPEG XL DNGs rendering bit-identical to their non-interleaved twins, factors above 2 rest on the plain reading of the tag; a single-chunk JPEG XL preview IFD is offered as the embedded preview; a DNG whose samples pile up at one value well below its stated `WhiteLevel`, as a camera app's 12-bit Bayer DNG that states 4095 and clips at 3567, has those samples raised to the white level on decode, so highlight reconstruction sees the clipped areas instead of white balance tinting them magenta, issue #548, `crates/raw/src/saturation.rs`), CR2 (colour-filter layout from the file's `CR2CFAPattern` tag, issue #85), ARW (pre-2017 bodies: white balance and black level from the encrypted `SR2SubIFD`, issue #148, its `WB_RGGBLevels` being the white balance the camera applied, issue #535; the DSLR-A900's packed 12-bit strip, two pixels per three bytes, read only when the strip is exactly 1.5 bytes per pixel, with its camera-JPEG window centred, checked on one CC0 file (A850 unmeasured); downsized Sony lossless YCbCr 4:2:0 / 4:2:2 tiles decoded to linear RGB, verified on private ILCE-7M4 3:2 & 4:3 examples including 16-bit full-resolution export; Sony DSC-R1 .SR2 decodes, its big-endian 16-bit words read in the order that fits the sample range, checked on the CC0 3221 sample; its crop and white balance live in the SR2SubIFD and are not read yet), NEF (uncompressed, lossless and lossy compressed 12/14-bit, `crates/raw/src/vendor/nefc.rs`), RAF (uncompressed, lossless/lossy compressed Bayer and X-Trans; `crates/raw/src/vendor/rafc.rs`, full sensor verification on 13 bodies, `docs/raf-compression.md`), RW2 / Leica RWL / Panasonic RAW in every raw format (compressed 4 and 6, the prefix-coded strips of format 8 from the GH6 on, packed 2/5/7, the 16-bit words of the 2005–2007 bodies; black levels, in-camera aspect crops and mapped-out defect pixels; 178 CC0 files from 118 bodies checked, `crates/raw/src/vendor/rw2.rs`), PEF, ORF (uncompressed; colour-filter layout from the file's Exif `CFAPattern`; 12.8 bit/px 16-byte blocks of ten 12-bit samples + a zero pad byte, E-300 / E-330 / E-500 verified on CC0 files, E-M5 Mark II / PEN-F high-res files decode smooth but CFA and black unverified), Hasselblad 3FR and FFF (a TIFF without a DNG version tag that describes its CFA IFD, levels, crop and white balance with DNG's tags; `RawFormat::CfaTiff`, read by `dng::decode_as`, RGGB when the file states no `CFAPattern`): uncompressed (X1D, X1D II, X2D, CFV 100C) and Hasselblad's lossless JPEG with scan selection value 8 (every FFF; H3D, H4D and CFV-50c 3FR), `ljpeg::decode_hasselblad`, its rule measured on 14 CC0 files with the ljpeg-explorer tool, Samsung SRW without compression (NX5, NX10, NX11 and the NX20-generation bodies NX20, NX200, NX210, NX1000 and NX1100 as 12-bit packed samples in either bit order, EX1 and WB2000 as 16-bit words; layout, camera-JPEG framing, levels and white balance from the maker note, `crates/raw/src/vendor/srw.rs`; median ΔE vs the camera JPEG 2.2–7.6 on 11 of the 12 files from 10 bodies checked, 10.7 (5.7 registered) on the backlit WB2000 sample). 12-bit NEF black level: maker note `0x003d` is in 14-bit units (D750, D780, D850, D7500, Z 50 checked). Lossy type 2 NEF curves of version `0x44 0x40` (D780, D6, Z 5, Z 6, Z 7, Z 7_2) span a quarter of the sample range, read from the table's own point spacing. CR3 lossless CRX Bayer and version 0x100/0x200 C-RAW decodes to sensor pixels with timed white balance, black/white levels and file crop (the shot's aspect ratio from the maker note's `AspectInfo`); full sensor samples match the reference on M50/R100/R8 (`crates/raw/tests/cr3_corpus.rs`, `docs/cr3.md`). Unsupported coding variants retain metadata and use the embedded JPEG when available; HEVC preview decoding remains unsupported. Missing: CR3 unverified CRX variants, compressed ORF, compressed Samsung SRW (NX1, NX30, NX300, NX500, NX2000, NX3000, NX3300, NX mini: preview only with the reason), NEFs labelled compressed (34713) but stored uncompressed without a `0x0096` table (Z 6 packed 14-bit, D850 12-bit uncompressed), Nikon High Efficiency NEF (HE / HE★ from the Z 8, Z 9, Z 6III and Z f: compression 34713 with a JPEG XS codestream and no `0x0096` table; no public specification, so preview only with the reason "Nikon High Efficiency NEF", issue #193; Lossless compressed NEFs from the same bodies decode), NEF "lossy after split" (preview only: imported with `preview_only` = the decoder's reason, rendered as a rendered JPEG, flagged by a grid badge and loupe/Edit/Info notices, `previewOnly` in `catalog.query`; Reload clears it once the file decodes), TIFF-based raws whose raw data sits in a private block (Phase One / Leaf IIQ, Canon EOS-1D / 1Ds and Kodak DCS TIFFs: IFD0 is only a reduced RGB image next to a much larger declared picture) are recognised from that structure and import as `preview_only` with the reason, instead of opening as a thumbnail-sized ordinary image (`thumbnail_shell` in `crates/raw/src/lib.rs`), Recognised raws LightCraft cannot decode open as `preview_only` with any usable embedded JPEG, also Canon CRW, Minolta MRW and Sigma X3F (containers recognised by magic, preview found by a structural JPEG scan), Kodak KDC (IFD0 without `ImageWidth`), Leaf MOS and Epson ERF (scan), and any decode failure of a recognised raw, not only an unsupported variant; ones with no JPEG still fail with "without an embedded preview", AVIF decode (HEIC decodes only behind the non-default `heif` feature, which the release packages enable: `crates/heif`, heic-rs for the container and HEVC (bit-exact against libde265 on iPhone tiles) plus our own colour conversion, matching libheif within 1 code value on iPhone-style grids (VUI full range, Display P3 ICC, nclx, 10-bit, irot/imir/clap, gain map/depth ignored); 4:2:0/monochrome only, 4:2:2/4:4:4 Canon/Sony HIF refused; same policy as PhotoCraft), palette (indexed-colour) TIFF (refused by the `tiff` crate) | | LR-IMP-CAMERA-COVERAGE | Camera coverage, verified per model | P0 | 🟡 | `crates/raw/tests/corpus.rs`, `xtask/src/main.rs` | a supported container is not the same as every camera that writes it decoding correctly: ~55 CC0 corpus files plus 6 exact-sensor CR3 cases (plus ~60 NEFs checked by hand and 178 Panasonic / Leica RW2, RWL and RAW files from 118 bodies, checked against each file's own JPEG) against the >1,000 models Lightroom lists; per-model differences still surface (e.g. the CR2 colour-filter layout differed by model until it was read from the file's own tag, issue #85, checked on 35 CR2 bodies; CR2 black levels were read from border columns light already reaches, left of `SensorInfo`'s border, so CR2s rendered dark with crushed shadows (EOS 6D: 2591 instead of 2047), now measured from the masked columns only, checked on 8 corpus bodies; pre-2017 Sony ARWs opened green until their scrambled white balance / black level were read, issue #148, checked on 16 ARWs from 15 Sony bodies; their white balance now comes from the encrypted `SR2SubIFD`'s `WB_RGGBLevels`, the gains the camera applied, which 14 bodies (DSLR-A450 … A700, NEX-3/5/C3, SLT-A33/A35/A55, ILCE-6001, UMC-R10C) had no other source for and which the maker-note estimate read before missed by up to 100 % on preset shots, issue #535, checked against ExifTool on 100 decoded ARWs from 87 Sony bodies; the encrypted SR2 black level is now read from its directory entry (the DSLR-A450/A500/A550/A700 read 354–975 instead of 512), checked on 126 ARWs from 97 Sony bodies, and downsized lossless M/S ARWs use their measured black level 1024 instead of 512, checked on 12 files from 4 bodies, issue #535; pre-2017 Sony bodies shot in the camera's 16:9 mode (ILCE-7SM2, DSLR-A580) now get the 16:9 crop of their camera JPEG instead of the whole 3:2 frame with padding columns, issue #535; Canon PowerShot and EOS M CR2s whose `ColorData` is stored as bytes opened green until the bytes were read as 16-bit words, 25 files from 25 bodies checked). Compressed RAF sensor arrays verified on 13 Fujifilm bodies (`docs/raf-compression.md`). Sony ILCE-7CR (61 MP): lossless compressed L and M and compressed ARW2 samples of one scene in the corpus (black level, default crop, as-shot gains, lossless vs compressed mosaic agreement, fitted camera look), and all nine public codings (also uncompressed, small and APS-C crop) decode and fit. Grow the CC0 corpus per model and test each sample decodes with plausible colour. Nikon CropArea and untagged-preview colour-space regression tests; private Z 8 crop verified. | -| LR-IMP-PREVIEW-READ | Preview reads the header, not the raw | P0 | ✅ | `crates/raw/src/preview.rs` (`bounded_preview`, `embedded_preview_from_range`), `crates/engine/src/files.rs` (`preview_window`), `docs/raw-preview-reads.md` | a grid thumbnail and a loupe preview of an unedited raw show the camera's embedded JPEG, which sits near the start of the file (a 24 MP Fuji RAF keeps its 5.6 MB JPEG in a 56 MB file), so the preview loader reads the header and that JPEG instead of the whole file: 56.5 MB → 5.9 MB and ~10 s → 0.96 s measured on one real RAF over a GVFS/SMB Wi-Fi share (byte-identical preview pixels; `LIGHTCRAFT_PROFILE=1` reports the bytes); the RAF pointer is read from its fixed header fields, formats whose preview only the whole file reveals (CR3 boxes, TIFF pointer tags past the prefix, CRW/MRW/X3F scans) keep the whole-file path, and a lying pointer, a short read or a file that changes underneath us falls back to it rather than losing the preview | +| LR-IMP-PREVIEW-READ | Preview reads the header, not the raw | P0 | ✅ | `crates/raw/src/preview.rs` (`bounded_preview`, `embedded_preview_from_range`), `crates/engine/src/files.rs` (`preview_window`), `docs/raw-preview-reads.md` | a grid thumbnail and a loupe preview of an unedited raw show the camera's embedded JPEG, which sits near the start of the file (a 24 MP Fuji RAF keeps its 5.6 MB JPEG in a 56 MB file), so the preview loader reads the header and that JPEG instead of the whole file: 56.5 MB → 5.9 MB and ~10 s → 0.96 s measured on one real RAF over a GVFS/SMB Wi-Fi share (byte-identical preview pixels; `LIGHTCRAFT_PROFILE=1` reports the bytes); the RAF pointer is read from its fixed header fields, formats whose preview only the whole file reveals (CR3 boxes, TIFF pointer tags past the prefix, CRW/MRW/X3F scans) keep the whole-file path, and a lying pointer, a short read or a file that changes underneath us falls back to it rather than losing the preview. An unedited raw's **grid thumbnail is that camera JPEG itself**, so no sensor decode is scheduled behind it (`Session::embedded_thumb_is_final`, `grid::skips_the_real_render`): drawing a 512 px thumbnail used to decode the whole raw — 45 s a photo at 1.2 MB/s, 8.3 GB for a 149-raw folder — and the queue it built delayed the render the user was waiting for; a cached render as stand-in, an edited photo and a raw without an embedded JPEG still render | | LR-IMP-CULL-AT-IMPORT | Culling analysis at import | P2 | 🟡 | `cmd:photo.analyze` | run Assisted Culling on the imported photos (they're selected after an import); not automatic | | LR-IMP-MOVE | Move on import [Classic] | P1 | ✅ | `cmd:library.import` (`mode` move), `crates/engine/src/import_move.rs`, `crates/engine/src/tests_import_move.rs`, `crates/ui-egui/src/import.rs` | Transfer ▸ Move with Copy's destination, folders (day / month / one folder / custom template), rename template and example destination; XMP sidecars (both namings) move along; each source is removed only after its destination is written (hard link on the same volume, else copied, synced and compared byte for byte) and its catalog record is saved; failed, duplicate, unchecked files keep their sources, taken names get -1, -2…, never overwritten; files already in the destination/library are added in place; sources that can't be removed (read-only card) are kept and reported (`kept`). Undo removes the photos from the library but leaves the moved files at the destination. No Copy as DNG while moving | | LR-IMP-DNG-CONVERT | Convert to DNG on import [Classic] | P2 | ✅ | `cmd:library.import` (`dng`), `crates/ui-egui/src/import.rs` | copy imports: Raw files ▸ Copy as DNG (lossless; the card is untouched); the raw copy is removed only once its DNG is verified and on disk (issue #106) | diff --git a/docs/raw-preview-reads.md b/docs/raw-preview-reads.md index 51058255f..bac09ea12 100644 --- a/docs/raw-preview-reads.md +++ b/docs/raw-preview-reads.md @@ -40,6 +40,26 @@ preview is never lost to a damaged header. [profile] preview …/DSCF9492.RAF: read 5857257 of 59277632 bytes (header 5857257, window 5857109) ``` +## 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. +- 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. + ## Tests - `crates/raw/src/preview.rs`: the header-only range matches `embedded_preview` byte for byte; a