RAW preview: exiftool fallback for MakerNote / SubIFD previews
kamadak-exif's In::PRIMARY / In::THUMBNAIL only address IFD0 and IFD1. On modern Nikon NEFs the full-res review JPEG lives in the MakerNote's PreviewIFD (and many Canon CR2s / DNGs put theirs in a SubIFD chain) — both unreachable through the existing reader, so the previous patch still produced no preview for those files and the pipeline fell through to ffmpeg, which writes black frames when it can't decode the RAW. Add a slow-path layer in extract_embedded_jpeg_preview that shells out to exiftool for PreviewImage / JpgFromRaw / OtherImage (one process per tag). All candidates from both layers are pooled and the largest valid JPEG wins. exiftool not on PATH degrades to fast-path-only behavior rather than breaking — the fallback is a strict superset. Documented the new optional dependency in README.md and CLAUDE.md with install commands for apt / brew / winget / choco. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
31
README.md
31
README.md
@@ -28,14 +28,31 @@ Builds used in development: the `gyan.dev` full build on Windows, and distro `ff
|
||||
packages on Linux work fine. If HEIC thumbnails silently fail, check
|
||||
`ffmpeg -formats | grep heif` to confirm HEIF support.
|
||||
|
||||
### RAW photo thumbnails (no extra dependency)
|
||||
### RAW photo thumbnails
|
||||
RAW formats (ARW, NEF, CR2, CR3, DNG, RAF, ORF, RW2, PEF, SRW, TIFF) are thumbnailed
|
||||
by reading the embedded JPEG preview from the TIFF IFD1 using `kamadak-exif`. No
|
||||
external RAW decoder (libraw / dcraw) is required. Files without an embedded preview
|
||||
fall back to ffmpeg (works for most NEF files), and anything that still can't be
|
||||
decoded is marked with a `<thumb>.unsupported` sentinel in the thumbnail directory
|
||||
so we don't retry it every scan. Delete those sentinels to force retries after a
|
||||
tooling upgrade.
|
||||
by reading an embedded JPEG preview out of the TIFF container — no external RAW
|
||||
decoder (libraw / dcraw) is involved. The pipeline tries two layers in order and
|
||||
keeps the largest valid JPEG:
|
||||
|
||||
1. **Fast path (no extra dependency)** — `kamadak-exif` reads
|
||||
`JPEGInterchangeFormat` from IFD0 / IFD1 directly. Covers older bodies and
|
||||
most DNGs.
|
||||
2. **`exiftool` fallback (recommended for RAW-heavy libraries)** — shells out
|
||||
to extract `PreviewImage` / `JpgFromRaw` / `OtherImage`, which reaches
|
||||
MakerNote and SubIFD-hosted previews kamadak-exif can't see (e.g. Nikon's
|
||||
`PreviewIFD`, where modern Nikon bodies stash the full-res review JPEG).
|
||||
If `exiftool` isn't on `PATH` this layer is skipped silently and only the
|
||||
fast-path result is used.
|
||||
|
||||
Install `exiftool` via your package manager:
|
||||
- macOS: `brew install exiftool`
|
||||
- Linux (Debian/Ubuntu): `apt install libimage-exiftool-perl`
|
||||
- Windows: `winget install OliverBetz.ExifTool` or `choco install exiftool`
|
||||
|
||||
Files where neither layer produces a valid preview fall back to ffmpeg. Anything
|
||||
that still can't be decoded is marked with a `<thumb>.unsupported` sentinel in
|
||||
the thumbnail directory so we don't retry it every scan. Delete those sentinels
|
||||
(and any cached black thumbnails) to force retries after a tooling upgrade.
|
||||
|
||||
## Environment
|
||||
There are a handful of required environment variables to have the API run.
|
||||
|
||||
Reference in New Issue
Block a user