db

Source: db.js:21

LocalStorage persistence layer for the two face databases. Holds two parallel stores — one for face-api 128-D recognition descriptors (STORAGE_KEY) and one for the MediaPipe ImageEmbedder vectors (STORAGE_KEY_3D) — with IDs aligned between them: when engine.js assigns an ID at save time, the same ID is passed to engine-3d.js so both DBs grow in lockstep.

Why two stores instead of one record with two descriptors: it keeps each engine independent. engine.js never has to know that a 3D embedding exists, and engine-3d.js never has to read or preserve 2D fields it doesn't understand. Disalignment is tolerated (no rollback): if one save fails after the other succeeds, the surviving record is left alone and findFace for the missing engine simply returns no match.

The 3D DB carries a modelVersion field. At load time we compare it with the current DB3D_MODEL_VERSION; a mismatch wipes the store automatically, since embeddings produced by different models are not comparable.

Instance Methods

createEmptyDb3d(): Object

Factory for an empty 3D DB shape with the current model version stamped in. Used both for the initial loadDb3d() path when no stored data exists and for the auto-wipe path triggered by a model-version mismatch.

Returns

• Object

Static Methods

loadDb3d(): Object

Read the 3D face database from localStorage. Returns a fresh empty store if nothing is stored, the JSON is malformed, or the stored model version does not match DB3D_MODEL_VERSION (in which case the old data is wiped via clearDb3d() because it can no longer be matched against new embeddings).

Returns

• Object — The current 3D DB state. There is no nextId field — 3D IDs come from the 2D DB to keep the two stores aligned.

• See:
  • scripts/main.js – called once during init to populate `state.db3d`.
  • clearDb3d – called from inside this function when the model version does not match the stored data.

persistDb3d()

Serialise state.db3d to localStorage under STORAGE_KEY_3D. Called after every successful 3D save so the next reload sees the new embedding.

• See:
  • scripts/engine-3d.js – `saveFace3d()` calls this after pushing a record.

clearDb3d()

Reset the 3D DB to an empty store (preserving the current model version) and persist the empty state. Called by clearDb() as part of a full cross-engine wipe, and internally by loadDb3d() when a model-version mismatch is detected.

• See:
  • clearDb – orchestrates wiping both DBs together.
  • loadDb3d – triggers this on a model-version mismatch.

loadDb(): Object

Read the 2D face database from localStorage. Returns a fresh empty store ({nextId: 0, faces: []}) if nothing is stored or the JSON is malformed or structurally invalid. nextId is the source of truth for the next assigned ID across both engines — the 3D save path reuses it rather than tracking its own counter.

Returns

• Object — The current DB state.

• See:
  • scripts/main.js – called once during init to populate `state.db`.
  • scripts/engine.js – `saveFace()` increments and persists `nextId`.

persistDb()

Serialise state.db to localStorage and emit a dbChanged event on the shared bus so consumers (status badge, bbox overlay) can refresh. Dispatch happens here so every code path that mutates the DB has consistent UI feedback without having to remember to fire the event itself.

• See:
  • scripts/engine.js – `saveFace()` calls this after pushing a record.
  • clearDb – calls this to persist the empty state and notify listeners.
  • tests/unit/db.test.js – verifies persistence and event emission.

renderDbStats()

Push the current DB statistics into the side-panel UI: face count, next ID, the match threshold label, and the badge in the header. Called whenever the DB shape changes or the app starts up.

• See:
  • scripts/main.js – `init()` calls this once after loading the DBs.
  • clearDb – calls this after wiping the data so the UI shows zero.

clearDb()

Wipe both the 2D and 3D face databases, persist the empty state of both, and emit a matchStateChanged event (source: 'clear') so any listening UI (bbox overlay, badges) can reset its derived display. The two underlying stores are cleared in lockstep because their IDs are aligned — dropping one without the other would leave orphan records on the next find.

• See:
  • persistDb – persists the empty 2D state.
  • persistDb3d – persists the empty 3D state (called via reassignment).
  • renderDbStats – refreshes the on-screen counters.
  • tests/unit/db.test.js – covers the cross-DB wipe.

Other

STORAGE_KEY

LocalStorage key for the 2D (face-api) face database.

STORAGE_KEY_3D

LocalStorage key for the 3D (ImageEmbedder) face database.

DB3D_MODEL_VERSION

Version tag stamped into the 3D DB. Bumping this string invalidates the stored embeddings on the next load (they will be auto-cleared). Bump it whenever the embedder model or its preprocessing changes in a way that makes old vectors incomparable with new ones.