1 ADR 0002 class instance thumbnail aspect ratio
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0002: Class Instance Thumbnail Aspect Ratio

Status: Accepted
Date: 2026-07-19
Deciders: Christian Wiwie

Context

People (and other class instances) need representative thumbnails — crop of the face/marker area shown in browse grids, detail headers, and suggestion dialogs. Multiple bug cycles revealed recurring tension between:

  • CSS-based bounding-box cropping on the full photo (dynamic, no precomputed asset)
  • Face-crop derived assets (async worker-generated, timing race with person creation)
  • Square grid layout requiring square thumbnails vs. non-square face bounding boxes

Three different fix attempts (PR#642, PR#644/646, PR#650, PR#651) chased the wrong root cause because the aspect-ratio invariant was never stated explicitly. This ADR codifies it.

Options Considered

Option Summary Benefits Costs / Risks
A CSS bounding-box crop on full photo, zoom to fill square, crop overflow Simple, no async dependency Distorts/loses content; zoom beyond original resolution → blurry
B Precomputed face-crop derived asset (async worker) Correct aspect ratio, no runtime CSS math Timing race: person created before worker runs → no thumbnail; worker complexity
C CSS bounding-box crop keeping original aspect ratio, extend bbox to square within photo bounds No distortion, no async dep, works immediately Dynamic CSS computation; zoom capped at original resolution
D Hybrid: CSS bbox crop when derived asset unavailable, precomputed asset when available Best-effort, covers both cases Two code paths to maintain; PR#651 shows CSS path works reliably with bbox only

Decision

Chosen: Option C, with Option D as implementation strategy.

  1. Aspect ratio of the original photo must be preserved. Never distort/stretch the thumbnail.
  2. Square thumbnails required by UI (grid cards, detail header). If marker bbox is non-square, extend the shorter dimension symmetrically within photo bounds until square. Never crop content outside the extended bbox.
  3. Zoom is allowed, but never beyond the original photo resolution (1:1 pixel). Upscaling beyond original resolution produces blurry thumbnails — not acceptable.
  4. Implementation: CSS bounding-box crop on the full-resolution photo. No async dependency. The bbox comes from face_annotations (or equivalent marker table), which exists immediately after marker creation.
  5. Future: Precomputed derived assets may replace the CSS approach, but must respect this same aspect-ratio invariant.

Consequences

Easier:

  • Immediate face crops for newly created people (no worker timing race)
  • No additional worker jobs or derived assets needed for thumbnails
  • Single violation: CSS background-size + background-position in cardStyle() — manageable

Harder:

  • CSS crop math is non-trivial: must compute extend-to-square, clamp to photo bounds, scale without exceeding 1:1
  • Precomputed-derived-asset path (Option B) would need re-architecture to respect this rule
  • Explore/detail pages must both use the same crop logic

Revisit Triggers

Revisit this decision if these assumptions change:

  • CSS-based cropping becomes a performance bottleneck (many thumbnails on one page)
  • Precomputed derived asset pipeline is implemented for other reasons and could subsume thumbnails
  • Photo resolution metadata becomes unreliable or unavailable at crop time