Photo analysis and people

Avichive turns a photograph into reviewable evidence before it attaches a person’s name. Local models locate faces and compute recognition features. The archive owner names people, corrects missed detections and decides whether a suggested match is right. These steps produce different records: finding a face does not establish an identity.

The implementation described here is grounded in the October 13, 2026 source snapshot. It establishes available workflows, rather than claiming that every photograph has been processed or every deployed preview is ready.

One analysis for identical content

A photo can survive at several historical paths. Its content hash connects those occurrences to one UniqueFile, and PhotoAnalysis belongs to that shared content identity. The processor prefers a canonical Photo attachment when selecting an input. Reviewing one occurrence therefore does not require independently naming the same bytes in every backup. This is exact-content sharing; visually similar crops or edits remain separate contents. See the analysis model (app/models/photo_analysis.rb:1) and content identity.

Preparing and detecting faces

The owner explicitly queues photo contents, optionally within a life era. The interface offers batches of 50, 100, 200 or 500, with 50 selected initially. Background work records queued, processing, completed, skipped or failed states. A completed photograph with no detected faces is a successful result; it does not enter the unresolved-face queue.

Inference reads a full-frame attachment and verifies its checksum. Missing input is reported instead of substituting a small thumbnail. Input is capped at 50 MiB, decoded images at 40 million pixels, and results at 100 faces. The Python runtime applies EXIF orientation, converts to RGB and limits the prepared image to a 2048-pixel long side. YuNet detects faces; SFace creates normalized 128-value vectors for later comparisons. The stored prepared image makes the normalized boxes and landmarks refer to a reproducible coordinate space. Model revisions, preprocessing and input/output checksums accompany the result. See the processor (app/services/photo_analysis_pipeline/process.rb:89) and local model runtime (tools/photo_analysis/photo_models/cli.py:118).

flowchart LR
  A[Unique photo content] --> B[Prepared image]
  B --> C[Detected face observations]
  C --> D[Owner names or ignores faces]
  C --> E[Explicit matching run]
  E --> F[Candidate identity]
  F --> D
  D --> G[Confirmed person gallery]

Review and recognition

The editor lets the owner reuse an existing person, create a person, ignore a detection or add a missed face. A manually drawn annotation can still be named when recognition features are unavailable. Reviewed means a human examined the photograph; done also removes it from the default open queue. Reopen restores that work to review, and actual face edits clear prior review/done state. Version checks reject stale edits. Failed, skipped or interrupted analyses can be retried; completed detections are preserved.

Known-person matching is a separate experimental run. It compares unresolved vectors against confirmed examples in a compatible model space, selecting up to five references per person. The bounded preview supports up to 1,000 targets and 500 selected references. Cosine similarity generates candidates for Yes/No review; it never silently assigns a name. Rejections persist, and changed references invalidate their old suggestions. A similarity score is not an identity probability or a measured accuracy claim. See reference selection (app/services/face_matching/prepare.rb:7) and candidate decisions (app/services/face_matching/decide.rb:7).

Local editing, production display

Inference and identity editing are owner-only local operations. Production provides owner-only read access to People galleries. Sync transfers people, analyses and annotations through portable identifiers; embeddings and matching state stay local. Production rebuilds its own correctly oriented display images. These permissions and transfers are implemented in the access policy (app/controllers/concerns/photo_analysis_access.rb:4) and people sync (app/services/db_sync/replace_tables.rb:4).

Captions and semantic image retrieval remain research. The installed SigLIP2 CLI does not itself establish an application search index. Continue with media preparation and operations.