Skip to content

Thumbnails: camera RAW, a checked cache, clearer misses - #66

Closed
dhh wants to merge 16 commits into
mainfrom
raw-thumbnails
Closed

dhh wants to merge 16 commits into
mainfrom
raw-thumbnails

Conversation

@dhh

@dhh dhh commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

By GM (@thisisgm), from #17: the work and the description below are theirs, with their commits kept as they made them. This pull request carries it on from our own branch, with the fixes from review added as commits on top, so it can land without waiting on a push to their fork.

Six changes to thumbnails, one commit each with its own tests: camera RAW files show their picture without a RAW thumbnailer, a cached thumbnail has to belong to its file, a failure is tried again once Folio can draw more, a thumbnailer is found through a type's aliases, a type nothing installed can draw says which package would, and a thumbnailer installed later draws what failed before. Two smaller commits on top answer review: a RAW preview is turned by its own directory's orientation, and no package is named for a PDF that pdftoppm draws. No library is linked in and nothing new is needed to run.

What you'd notice

  • Camera RAW files show their picture. Most RAW files were a blank tile unless a RAW thumbnailer was installed. The camera stores a finished JPEG inside each file, and a bounded reader of the TIFF directories now finds the largest one in a CR2, NEF, NRW, ARW, SR2, DNG or PEF, so nothing is decoded from the sensor data and nothing is linked in. A preview that does not decode is passed over for the next largest, all within one read limit. A preview is turned by the orientation its own directory names, and by the file's when it names none. An installed thumbnailer still answers first, and a broken file is refused rather than guessed at (offsets, counts and lengths are checked against named limits). CR3, RAF, ORF, RW2 and SRW keep their JPEG in other containers and still show an icon.
  • A thumbnail made for another file is not shown as this one's. A cache entry or failure marker was trusted on its modified time alone. It now also has to carry this file's Thumb::URI, as the thumbnail spec asks a reader to check; otherwise the thumbnail is made again.
  • A file that failed once gets another try once Folio can draw it. Failure markers went to fail/folio, so a file one release could not thumbnail stayed blank under every later one, as camera RAW would here. They now go to the spec's fail/<program>-<version>, as fail/folio-2: the number is raised whenever Folio learns to draw more.
  • A thumbnailer that names a type by an alias is used. Folio asks with the canonical name, so a thumbnailer that declares only an alias never matched: glycin declares image/x-dds and the file is image/vnd.ms-dds. Declared types are resolved to canonical names once, when the thumbnailers are read. On a stock Omarchy install 23 of the 196 declared names are aliases, and DDS pictures and WAV audio gain the thumbnailer they already had.
  • A thumbnailer installed later gets its turn. A file nothing installed could draw kept its failure marker, so installing the thumbnailer for its type changed nothing until the file or Folio did. The marker now records the thumbnailer command the type had when it failed, none included, and holds the file back only while that is the same. A thumbnailer that failed is still run once.
  • A missing thumbnailer has a name. A type with no installed thumbnailer showed an empty preview and nothing else. The details pane now says which optional package draws it, from the types ffmpegthumbnailer, papers, glycin and libgsf declare. A PDF names none where pdftoppm is there to draw it.

Numbers

Measured on a mini PC with no RAW thumbnailer installed, cold start, main against this branch. Both tables are from the branch as it stands on the CMake build.

A folder of 100 RAW files in twelve formats, three runs each:

main this branch
Files with a picture 26 56
Failure markers written 40 10
Thumbnails finished after 1154 to 1273 ms 1148 to 1441 ms

The rest of Folio pays nothing for it. Time until the window is up and the process has gone quiet, six runs a view:

View main this branch
Grid, 100,000 files 3989 to 4083 ms, 235.8 to 236.6 MiB 4012 to 4167 ms, 235.9 to 236.6 MiB
List, 100,000 files 3788 to 4234 ms, 183.9 to 197.8 MiB 3868 to 4426 ms, 183.9 to 197.7 MiB
Columns, 100,000 files 5131 to 5493 ms, 195.7 to 207.8 MiB 3850 to 5448 ms, 195.5 to 213.8 MiB
Grid, 2,000 pictures and videos 4446 to 4627 ms, 153.6 to 154.2 MiB 4522 to 5081 ms, 152.7 to 155.3 MiB

The ranges overlap in every view, and the media folder draws the same 105 thumbnails on both.

Screenshots

One RAW file from each of twelve cameras, main above and this branch below: Nikon, Pentax and Sony gain their picture.

Camera RAW tiles before and after

A cache entry written for another file (the first tile, which should be red) and one that names no file (the third, flipped so it shows), each with a matching modified time, main on the left and this branch on the right:

Stale cache entries before and after

The details pane for a video with ffmpegthumbnailer not installed, before and after:

Missing package before and after

Changed in review

  • A RAW preview's own orientation is read right. The embedded JPEG's Exif orientation was missed when the JPEG had fill bytes before its marker, and the orientation of its thumbnail's directory (IFD1) could be taken for the picture's own. Both could draw an upright preview turned. It now skips fill bytes and reads only IFD0, with a test for each.
  • Clearing old failure markers never follows a link. The start-up cleanup of fail/folio and older fail/folio-<n> folders now leaves links alone; following one would have emptied the folder it pointed to, outside the cache. A newer Folio's markers are left too.
  • A hostile RAW costs little. A preview claiming an impossible size (beyond 250 megapixels) is skipped before decoding, and the reader's work on a crafted file is bounded. 20,000 fuzzed files ran clean under AddressSanitizer and UndefinedBehaviorSanitizer.
  • Where the table of packages' types came from is noted beside it, and main's changes since are merged in.

Reviewed with Codex.

🤖 Generated with Claude Code

thisisgm and others added 15 commits November 11, 2026 12:26
A cache entry or failure marker was trusted on its modified time alone,
so one made for another file with the same time was shown as this
file's. It now has to carry this file's Thumb::URI as well, as the
thumbnail spec asks a reader to check.
Failure markers went to fail/folio, so a file Folio could not
thumbnail stayed blank after it learned to, as it does for camera RAW
here. They now go to the spec's fail/<program>-<version>, as
fail/folio-2: the number is raised whenever Folio learns to draw more.
A thumbnailer that names a type only by an alias never matched the
canonical name Folio asks with, so glycin's image/x-dds left a DDS
file blank. The declared types are resolved to canonical names once,
when the thumbnailers are read.
A CR2, NEF, NRW, ARW, SR2, DNG or PEF showed a blank tile unless a RAW
thumbnailer was installed. The camera stores a finished JPEG in each,
and a bounded reader of the TIFF directories now finds the largest
one. An installed thumbnailer still answers first.
A type with no installed thumbnailer showed a blank tile and nothing
else. The details pane now says which optional package draws it, from
the types ffmpegthumbnailer, papers, glycin and libgsf declare.
A file nothing installed could draw kept its failure marker, so a
thumbnailer installed afterwards never ran for it. The marker now
records the thumbnailer the type had, none included, and holds the
file back only while that is unchanged.
One orientation was kept for the whole file, so a preview whose
directory names a turn of its own was turned by IFD0's instead. Each
embedded JPEG now carries its directory's orientation, and takes the
file's only when its directory names none.
With Poppler installed and no PDF thumbnailer, a PDF that failed to
draw (damaged, or locked with a password) had the details pane name
papers as missing. A PDF's package is now named only when pdftoppm is
not there either.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A JPEG may put 0xFF fill bytes ahead of a marker, and the Exif segment
of one that did was missed, so an upright preview got the RAW's turn.
And the walk followed IFD0's next pointer into IFD1, the Exif
thumbnail's directory, whose orientation then passed for the picture's.
Only IFD0's own Orientation is read now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Markers moved from fail/folio to fail/folio-2, and nothing reads the old
folder again. It is removed on a worker thread at start, as is any
fail/folio-<n> a later bump leaves behind.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The start-up sweep listed fail/folio and fail/folio-* with QDir::Dirs, which
includes symlinks to folders, and removeRecursively() deletes through a link:
a fail/folio that pointed elsewhere had everything it pointed at deleted.
Symlinks are now skipped.

It also removed every fail/folio-<n> but the current one, so an installed
Folio and a newer build run side by side cleared each other's markers on
every start. Only plain fail/folio and lower numbers are removed now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A preview is no longer ranked when its frame header claims more than 250
million pixels, more than any camera's; a few KiB claiming 57000 by 56000
otherwise ranked first and cost a 270 MB decode that failed, up to sixteen
times per file.

The header budget now caps the number of reads as well as their bytes: each
read is its own system call, a round trip on a network mount, and crafted
directories reached some 60,000 tiny reads within the byte budget.

The embedded JPEG is read into a buffer with room for the Exif segment, so
putting the segment in front no longer copies up to 64 MiB.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Elsewhere in this file "the spec" is the freedesktop thumbnail spec.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@greptile-apps

greptile-apps Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; the latest change fixes the previously reported cleanup problem.

Summary

Adds embedded RAW previews, checks cached thumbnails against their file URI, improves retries, and names optional thumbnail packages.

  • Folio shows embedded previews from more camera RAW files.
  • Cached thumbnails and failures now have to name the file they belong to.
  • Thumbnail failures no longer block drawing support added later.
  • Thumbnailers now match files whose types use an alias.
  • The details pane names a package that may draw a missing preview.

Reviews (2) · Last reviewed commit: "Never clear failure markers through a fa..." · Reviewed by Greptile

Comment thread src/thumbnails.cpp Resolved
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dhh

dhh commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Thank you @thisisgm! This branch had grown past what's easy to review at once, so its parts have been taken into focused pull requests off today's main, each crediting you:

What isn't carried on, and why:

  • Checking Thumb::URI on a cached thumbnail. The cache file is named by the MD5 of the URI, so a mismatch needs a collision; it adds a check without a case it fixes in practice.
  • Naming the missing package. The details pane it lived in has become the details column, and which packages to suggest is a product call; worth its own small PR against the column if you'd like to pursue it.
  • A thumbnailer installed later drawing what failed. Main already writes no marker when no thumbnailer ran, so this only matters when one thumbnailer is replaced by another; Thumbnail camera RAW from its embedded JPEG #186 covers the RAW case it was written for.
  • Moving markers to fail/folio-N and clearing old ones at start-up. Main has since gained a round on each marker (X-Folio::Round), which retries old failures without a new folder, walking the cache, or the link-safety code that came with it.

Closing this in favor of those PRs.

@dhh dhh closed this Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants