face-thumbnails

Source: face-thumbnails.js:2

Instance Methods

defaultStore(): Object

Creates the empty thumbnail-store shape used when localStorage has no saved face thumbnails, contains malformed data, or is being reset with the database.

Returns

• Object — Empty thumbnail store with configured capacity.

• See:
  • loadThumbnailsStore - Falls back to this shape when storage cannot be read.
  • clearAllThumbnails - Persists this shape when the local face archive is cleared.

persistStore(store: Object): void

Writes the normalized face-thumbnail store to localStorage under the module's dedicated key, keeping images separate from the 2D and 3D biometric databases.

Parameters

• store (Object) — Store object to serialize.

Returns

• void

• See:
  • saveThumbnail - Persists after adding or evicting a thumbnail.
  • deleteThumbnail - Persists after removing one face thumbnail.
  • clearAllThumbnails - Persists the empty thumbnail store.

normalizeId(id: number | string): number

Converts face IDs from UI, database, or test inputs into the numeric key used by the thumbnail store.

Parameters

• id (number | string) — Face id to normalize.

Returns

• number — Numeric id, possibly NaN for invalid input.

• See:
  • saveThumbnail - Normalizes the saved face id before storage.
  • deleteThumbnail - Normalizes the target id before removal.
  • getThumbnail - Normalizes the lookup id before reading.

logThumbnailEvent(message: string): void

Logs thumbnail storage events through the plugin-facing logger when available, falling back to the app logger during tests or early module use. In practice this reports FIFO evictions when the local thumbnail cache reaches capacity.

Parameters

• message (string) — Message to write under the thumbnails source.

Returns

• void

• See:
  • saveThumbnail - Reports evicted thumbnails when capacity is exceeded.

normalizeStoreShape(parsed: *): Object

Repairs parsed localStorage data into the current thumbnail-store contract. Invalid records are dropped, IDs are coerced to numbers, and capacity falls back to the configured default when older or corrupted data omits it.

Parameters

• parsed (*) — Parsed JSON value read from localStorage.

Returns

• Object — Normalized thumbnail store.

• See:
  • loadThumbnailsStore - Applies this after parsing persisted thumbnail data.

shiftRectInsideBounds( rect: Object, frameWidth: number, frameHeight: number, ): Object

Moves a crop rectangle back inside the video frame without changing its size unless the requested crop is larger than the frame. This keeps edge-face thumbnails from sampling outside the webcam image.

Parameters

• rect (Object) — Desired crop rectangle with margin applied.
• frameWidth (number) — Source video frame width.
• frameHeight (number) — Source video frame height.

Returns

• Object — Crop rectangle safe for drawImage.

• See:
  • captureThumbnail - Uses this before drawing the face crop into the square thumbnail canvas.

Static Methods

captureThumbnail( videoEl: HTMLVideoElement, box: Object, options?: object, ): Promise.<string>

Captures a square JPEG thumbnail around a detected face box from the live webcam frame. The crop includes configurable margin, is clamped to frame bounds, letterboxes with black when needed, and is used as the small identity preview in history and analysis comparisons.

Parameters

• videoEl (HTMLVideoElement) — Live webcam video element to sample from.
• box (Object) — face-api detection box in video pixels.
• options (object, optional, default: "{}") — Optional thumbnail rendering overrides.
  • options.marginRatio (number, optional) — Extra crop margin as a ratio of the face box short side.
  • options.outputSize (number, optional) — Square output canvas size in pixels.
  • options.jpegQuality (number, optional) — JPEG quality passed to toDataURL.

Returns

• Promise.<string> — JPEG data URL for storage or comparison.

Throws

• Error — When the video element, face box, video frame, or canvas context is unavailable.

• See:
  • tryCaptureThumbnailOnSave - Captures the saved-face thumbnail during the Save workflow.
  • buildVisualComparison - Captures the current face thumbnail for the analysis panel.

loadThumbnailsStore(): Object

Loads the persisted face-thumbnail store from localStorage, tolerating missing entries, malformed JSON, and stale shapes so the history drawer never fails because thumbnail metadata is corrupt.

Returns

• Object — Normalized thumbnail store.

• See:
  • saveThumbnail - Reads the current store before adding an entry.
  • deleteThumbnail - Reads the current store before filtering an entry.
  • getThumbnail - Reads the current store before lookup.

saveThumbnail(id: number | string, dataUrl: string): void

Saves or replaces the thumbnail for a face id and enforces the configured FIFO capacity. When capacity is exceeded, the oldest savedAt entries are evicted and a thumbnail log message is emitted.

Parameters

• id (number | string) — Saved face id associated with the thumbnail.
• dataUrl (string) — JPEG data URL produced by captureThumbnail.

Returns

• void

• See:
  • init - Calls this after `saveFace` succeeds in the Save workflow.
  • logThumbnailEvent - Reports FIFO eviction messages.

deleteThumbnail(id: number | string): void

Deletes the thumbnail associated with a face id, used when a history card removes the corresponding 2D/3D face records.

Parameters

• id (number | string) — Face id whose thumbnail should be removed.

Returns

• void

• See:
  • removeFaceById - Removes thumbnail data when deleting a single saved face.

getThumbnail(id: number | string): string | null

Retrieves the stored thumbnail data URL for a saved face id. Missing or invalid ids return null so history and analysis UI can fall back gracefully.

Parameters

• id (number | string) — Face id to look up.

Returns

• string | null — Stored JPEG data URL, or null when no thumbnail exists.

• See:
  • createHistoryCard - Displays saved thumbnails in the history drawer.
  • buildVisualComparison - Retrieves the baseline thumbnail for analysis comparisons.

clearAllThumbnails(): void

Clears all saved face thumbnails while preserving the thumbnail-store schema. This keeps the thumbnail cache aligned with the local 2D and 3D biometric databases when the user clears the archive.

Returns

• void

• See:
  • clearDb - Calls this when wiping the local biometric archive.