Feature/star ratings

[zorange-CN]

Star ratings (#201)

Summary

Rate a photo 0–5 stars from the numeric keypad and have it stored where the rest of the world can read it: in the file for a JPEG or TIFF, in a same-name .xmp sidecar for a RAW. Ratings are read and shown in the gallery, the compact info panel and the full info panel, and a folded RAW+JPEG pair behaves as one photo with one rating.

No new dependency: reading is a plain header scan, writing goes through WIC, and the XMP editing is a few dozen lines of string work. Nothing here is reachable from the decode pipeline.

What it does

• Rate from the numpad. Rate0–Rate5 are ordinary rebindable hotkeys under their own heading in Settings ▸ Shortcuts, defaulting to Numpad 0–5, with 0 clearing the rating.
• Interoperates in both directions. A rating set here shows up in Explorer, in Photos and in Lightroom; a rating set by any of them shows up here.
• Shown where culling needs it. Filled stars on the gallery thumbnail (nothing at all for an unrated photo, so an unrated folder looks exactly as before), a field in the compact panel, and a row in the full panel that shows empty stars rather than coming and going.
• A pair is one photo. The rendered file and the RAW of a folded pair resolve to the same stars, whichever face is on screen, and rating either writes both.

The write path

Writing a JPEG or TIFF goes through the fast metadata encoder first, which patches the value into the padding the file already has and leaves every pixel byte alone. When there is no room the file is rebuilt with WriteSource(frame, NULL), which copies the compressed frame verbatim.

Two things that rebuild needs, both found the hard way:

• The source is decoded from a copy in memory. A decoder opened on the path keeps the file open even after every interface has been released, and ReplaceFileW then fails with a sharing violation.
• The IWICMetadataQueryWriter is released before the swap as well, since it holds the frame encoder, which holds the temp file's stream, and ReplaceFileW needs the replacement to itself.

Only System.SimpleRating (0–5) is written, into the Exif tag and xmp:Rating. I verified on this machine that this alone is enough for both ecosystems: Explorer's Rating column showed 4 stars and the property system derived System.Rating = 75 without RatingPercent or MicrosoftPhoto:Rating ever being written.

A RAW is rated through its sidecar. An existing sidecar carries that photo's develop settings, so the update rewrites the xmp:Rating property where it stands and copies everything else through byte for byte — a test asserts that rating a Lightroom-shaped sidecar changes exactly one character. A document that is not shaped as expected, or too large to read whole, is refused rather than overwritten: someone's develop settings are worth more than one rating. Only a RAW has a sidecar created for it; for a JPEG or TIFF an existing one is updated but never brought into being.

Following the constraints from this thread

• Isolated from the decode pipeline. RatingStore owns its cache, queue and worker; nothing is called from CImageLoader::ReadMetadata or the thumbnail path. A read costs one 128 KB header scan, or 16 KB of a sidecar. SHGetPropertyStore is never called on a RAW — or on anything else.
• Optimistic UI, debounced writes. A keypress updates memory and repaints at once; the disk write follows on its own thread behind a 400 ms debounce, so running 1-3-5 through a photo leaves one write. The debounce never costs a rating: navigating away commits it immediately, and anything pending is flushed on shutdown. ReleaseImageResources is never called on this path, so the viewport neither flickers nor reloads.
• Lossless fallback. WICDecodeMetadataCacheOnDemand plus WriteSource(frame, NULL), as described above. Because the rebuild replaces the file, which is not safe while it is mapped for display, a write for the photo on screen waits until the user navigates away instead of retrying on a timer.
• XMP safety. In-place update of xmp:Rating only, never a regeneration, and a refusal rather than a guess when the document is unfamiliar.
• No watcher storms. A sidecar write creates a file in the watched folder. The notification carries no file name, so the navigator asks an injected predicate whether we wrote something a moment ago and skips the rescan when we did. It is injected rather than called directly so that the navigator, and the test binary, stay free of the rating subsystem.

Two places I went beyond the brief

• Reading falls back to XMP. The Exif tag alone is not enough: Lightroom rates a JPEG by writing only xmp:Rating, so an Exif-only scan reports every Lightroom-rated file as unrated. The scan now tries the Exif tag first and the XMP packet second, and a test file with zero Exif tags but an XMP rating confirms the fallback is what answers.
• Adobe's rejected mark is recognized. xmp:Rating="-1" is read as "rejected" rather than mistaken for a star count. QuickView never writes it.

Hotkeys

Per your reply, the hardcoded 1 and 0 shortcuts for 100% and Fit are gone and ratings default to Numpad 0–5. Z and F remain the zoom bindings; the help overlay and the context menu labels are updated to match, and the help overlay gains a line for the rating keys.

One dependency surfaced while removing them: the context menu's own "Actual Size" and "Fit to Screen" entries were implemented by faking those keypresses, so they silently relied on the hardcoded block. They now invoke the actions directly.

Testing

• 40 unit tests for ratings, all green, covering both XMP serializations, both Exif byte orders, Exif-over-XMP precedence, the XMP fallback, out-of-range and malformed values, pair resolution, the surgical sidecar update (including that it preserves crs: develop settings and refuses an unfamiliar document), and a pass over every prefix of a synthetic JPEG so a truncated header read cannot read out of bounds. Test images are assembled in memory, so the suite passes on a fresh clone.
• Manual, on a folder of files covering every path: 0–5 stars, a Lightroom-style XMP-only rating, a file whose sidecar disagrees with its in-file value, a sidecar-only rating, and a standalone RAW. Ratings round-trip through Explorer and survive a restart; clearing removes the tag; rapid input coalesces; the sidecar's develop settings come through untouched.

Known limitations, stated plainly

• The full panel's item list is a whitelist stored in the ini, so a one-shot migration adds Rating to it once. If an older build later runs against the same ini it will strip the item again, and the flag will stop the migration from re-adding it — relevant now that the update channel can be downgraded.
• When a JPEG has no metadata padding, the rebuild rewrites the file: the bytes change and the timestamp moves, though the pixels do not.
• A rating that lives only in a RAW's sidecar is invisible to Explorer, which does not read sidecars. That is a platform limit, not a bug.
• HEIC/HIF is read-only: Microsoft's rating policy covers JPEG and TIFF only. In a HIF+RAW pair the rating lives in the RAW's sidecar, so the workflow still works; a standalone HEIC reports through the OSD that the format cannot store a rating rather than swallowing the keystroke.

Notes

• Default off is not applicable here: reading is free and writing only ever happens on an explicit keypress.
• Rebase target: dev.