feat(api): expose per-face boundingBox on carousel candidate refs #1053

Merged
chris merged 1 commit from feat/carousel-face-zoom-api into main 2026-10-06 22:17:52 +02:00
Owner

What

Adds the contracted boundingBox field to every face-annotation ref of the suggestions-carousel candidates listing (GET /api/discovery/domains/{domainKey}/class-instance-candidates), so the carousel can zoom to the face like the people page's "Vis område" mode.

The enrichment already existed for mediaItemId / thumbnailUrl / scope (withEvidencePreviewEnrichment → enrichEvidenceRefs); this extends it:

  • boundingBox: {x, y, width, height} (numbers, normalized 0..1, same values as discovery_results.scope) is written from the same batched lookup — no extra query, no N+1 (one discovery_results scope query + one media query per listing).
  • Present on refs in both occurrenceRefs and representativeEvidence (the shared enrichment walks both arrays).
  • Faces without a usable region scope get no boundingBox key at all (absent, not null), matching the existing "no null fields added" convention; unresolvable refs stay untouched.
  • Field name is exactly boundingBox (camelCase).

Compatibility note

scope (same values, snake_case) was already shipped to this view by commit 20abc0b5 and is consumed by apps/web; it is kept unchanged — boundingBox is purely additive and always mirrors discovery_results.scope. The shared enrichment also runs on tentativeCandidates (people page), where the new field is additive alongside the existing representativeBbox view field; that behavior is otherwise unchanged.

Scope

  • apps/api only: ClassInstanceDiscoveryService + its test + gradle.properties (1.21.68 → 1.21.69).
  • No worker/thumbnail changes, no apps/web, no KNOWN_ISSUES/specs.

Tests

rtk ./gradlew :apps:api:test → BUILD SUCCESSFUL, 1573 tests, 0 failures/errors, 9 pre-existing skips.

New candidateEvidenceRefsCarryBoundingBoxFromDiscoveryScope asserts:

  • boxed face ref carries the exact boundingBox (and scope) in occurrenceRefs and representativeEvidence of the candidatesPaged projection the endpoint serves;
  • a face with empty scope carries neither key (absent, not null);
  • CountingJdbcClient batching guard: exactly 1 scope query + 1 media query for the whole listing despite multiple candidates/refs (no N+1).
## What Adds the contracted `boundingBox` field to every face-annotation ref of the suggestions-carousel candidates listing (`GET /api/discovery/domains/{domainKey}/class-instance-candidates`), so the carousel can zoom to the face like the people page's "Vis område" mode. The enrichment already existed for `mediaItemId` / `thumbnailUrl` / `scope` (`withEvidencePreviewEnrichment` → `enrichEvidenceRefs`); this extends it: - `boundingBox: {x, y, width, height}` (numbers, normalized 0..1, same values as `discovery_results.scope`) is written from the **same batched lookup** — no extra query, no N+1 (one `discovery_results` scope query + one media query per listing). - Present on refs in **both** `occurrenceRefs` and `representativeEvidence` (the shared enrichment walks both arrays). - Faces without a usable region scope get **no `boundingBox` key at all** (absent, not null), matching the existing "no null fields added" convention; unresolvable refs stay untouched. - Field name is exactly `boundingBox` (camelCase). ## Compatibility note `scope` (same values, snake_case) was already shipped to this view by commit `20abc0b5` and is consumed by `apps/web`; it is kept unchanged — `boundingBox` is purely additive and always mirrors `discovery_results.scope`. The shared enrichment also runs on `tentativeCandidates` (people page), where the new field is additive alongside the existing `representativeBbox` view field; that behavior is otherwise unchanged. ## Scope - `apps/api` only: `ClassInstanceDiscoveryService` + its test + `gradle.properties` (1.21.68 → 1.21.69). - No worker/thumbnail changes, no `apps/web`, no KNOWN_ISSUES/specs. ## Tests `rtk ./gradlew :apps:api:test` → **BUILD SUCCESSFUL, 1573 tests, 0 failures/errors, 9 pre-existing skips**. New `candidateEvidenceRefsCarryBoundingBoxFromDiscoveryScope` asserts: - boxed face ref carries the exact `boundingBox` (and `scope`) in `occurrenceRefs` **and** `representativeEvidence` of the `candidatesPaged` projection the endpoint serves; - a face with empty scope carries neither key (absent, not null); - `CountingJdbcClient` batching guard: exactly 1 scope query + 1 media query for the whole listing despite multiple candidates/refs (no N+1).
feat(api): expose per-face boundingBox on carousel candidate refs
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 5s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 8m24s
b25d7a0dbe
The suggestions-carousel candidates listing (GET /api/discovery/domains/{domainKey}/class-instance-candidates) already enriches face-annotation refs with mediaItemId, thumbnailUrl and the normalized scope box, but the parallel carousel face-zoom lane is contracted on the camelCase field name boundingBox.

- enrichEvidenceRefs now writes boundingBox alongside scope from the SAME batched discovery_results lookup (one scope query + one media query per listing, no N+1), on refs in both occurrenceRefs and representativeEvidence.
- Faces whose scope is unusable/absent keep the existing convention: no boundingBox key at all (absent, not null); unresolvable refs stay untouched.
- scope (shipped by the original zoom lane, consumed by apps/web) is kept unchanged, so both fields carry identical normalized values.
- Adds a listing test covering both arrays, the absent-box case, and a CountingJdbcClient batching guard.
- Bumps memoriesVersion to 1.21.69.
chris merged commit 133cbdb6e2 into main 2026-10-06 22:17:52 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1053
No description provided.