ADR 0094: Discovery Instance Representative Thumbnail Must Use Extended Centered Square Crop
Status: proposed Date: 2026-07-20
Context
Discovery domain instance cards (people, plants, any future domain) need a representative thumbnail that lets users identify the subject without opening the photo. A full-photo thumbnail fails this when the subject is small (e.g., face in a crowd, flower in a garden). ADR 0002 established the square-crop invariant for class instances but did not specify the crop center algorithm, the padding/breathing-room constant, the clamp-vs-shrink rule for overflow, or how the CSS path and worker path must stay consistent. Multiple implementations diverged. This ADR specifies the complete algorithm so all paths stay aligned.
Decision
All thumbnails representing a discovered class instance (person, plant, any future domain) must: (1) Be square. (2) Be cropped around the detected marker bbox, centered on the bbox center (cx = bbox.x + bbox.width/2, cy = bbox.y + bbox.height/2). (3) Use a square crop size of max(bbox.width, bbox.height) / 0.85 in normalized [0,1] space — marker fills 85% of the square, 15% breathing room. (4) Clamp the crop center so the square stays within photo bounds (shift, never shrink). (5) If cropSize > 1.0 (marker too large for 85% fill to fit): use cropSize = min(1.0, cropSize) — largest square that fits, still centered on bbox center (clamped). Never letterbox. Never distort. (6) Max zoom constraint: 1:1 pixel — no upscaling beyond original photo resolution. CSS path uses object-fit which handles this natively; worker path must enforce explicitly. (7) Apply consistently: CSS path (frontend cards via bboxCropStyle() in apps/web/src/lib/utils/discoveryThumbnail.ts), precomputed path (worker renderRegionThumbnailJpeg), any future thumbnail generation. (8) When representativeBbox is null: show full photo, no crop. (9) bboxCropStyle() is the single canonical CSS implementation — no duplicate per-component implementations allowed. (10) Precomputed crop from original is canonical for grid cards. CSS bboxCropStyle() is detail-page only. (11) Core is generic. No domain-specific thumbnail types. Single job type generate_discovery_thumbnail.
Consequences
Positive: users can identify discovered subjects from thumbnails without opening photos; consistent grid layout (always square); single shared util eliminates crop implementation drift; algorithm degrades gracefully when marker fills photo. Negative: ClassInstanceBrowseView must carry representativeBbox field (backend join to discovery_markers); CSS path requires transform:scale + object-position math which is non-trivial to reason about; oversized-marker edge case (cropSize > 1.0) needs explicit handling in both paths. Risk: CSS transform:scale interacts with container overflow — container must use overflow:hidden.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference