1 ADR 0094 discovery instance representative thumbnail crop
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

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.