bbox-overlay

Source: bbox-overlay.js:27

Bbox match-state overlay — layer for Ghostmaxxing.

Draws a bounding box around the detected face on its dedicated canvas (#bboxOverlay), colored to reflect the latest match state computed by the engine (matched / eluded / unclear / unknown). Renders the current metrics next to the box: live detection score, live distance and closest match ID.

Reacts to events on state.gstmxxEvents. Does not mutate the engine.

Color convention: red = identified (matched) green = eluded blue = unclear (post-makeup match below threshold against a saved face) grey = unknown (also the fallback for any unmapped state)

Overlay suppression: When the engine reports a matchStateChanged triggered by an explicit user action (source: 'scan' | 'save' | 'find' | 'efficacy'), the corresponding on-screen overlay covers the video for a moment. To avoid double visuals, the bbox is suppressed for OVERLAY_SUPPRESS_MS after such an event. The auto-find loop (source: 'auto') never suppresses.

Instance Methods

clearBbox(): void

Clears the dedicated bbox canvas before each repaint, preventing stale boxes, labels, or mesh dots from lingering when the current mode or detection changes.

Returns

• void

• See:
  • renderOverlay - Clears before drawing the active overlay mode.

renderOverlay(): void

Repaints #bboxOverlay from the cached detection, match, and MediaPipe mesh streams. It mirrors and sizes the canvas to the main overlay, honors temporary suppression after explicit user actions, then draws the selected bbox, mesh, combined, or detailed 2D scaffold view.

Returns

• void

• See:
  • onDetection - Calls this after face-api detection updates.
  • onLandmarks3d - Calls this after MediaPipe mesh updates.
  • onMatchStateChanged - Calls this after match-state updates.
  • setOverlayMode - Calls this after a mode change.

includesBbox(): boolean

Reports whether the current overlay mode should draw the face bounding box and metric label block.

Returns

• boolean — True for bbox-only and combined modes.

• See:
  • renderOverlay - Uses this to decide whether to call `drawBox` and `drawLabels`.

includesMesh(): boolean

Reports whether the current overlay mode should draw the cached 478-point MediaPipe mesh.

Returns

• boolean — True for mesh-only and combined modes.

• See:
  • renderOverlay - Uses this to decide whether to call `drawMesh478`.

getLastBox(): Object | null

Resizes the latest face-api detection to the bbox canvas coordinate space and extracts the current bounding rectangle for drawing.

Returns

• Object | null — Current box in canvas pixels.

• See:
  • renderOverlay - Uses this before drawing bbox metrics.
  • extractBox - Handles the two face-api result shapes.

readPersistedOverlayMode( ): 'bbox' | 'mesh' | 'entrambi' | '2d' | null

Reads the persisted overlay mode from localStorage and validates it against the known Ghostmaxxing overlay modes.

Returns

• 'bbox' | 'mesh' | 'entrambi' | '2d' | null — Persisted mode, or null when unavailable.

• See:
  • init - Applies the persisted mode during overlay startup.

persistOverlayMode( mode: 'bbox' | 'mesh' | 'entrambi' | '2d', ): void

Stores the user's overlay mode preference. Storage failures are ignored because overlay rendering should keep working even when localStorage is unavailable or blocked.

Parameters

• mode ('bbox' | 'mesh' | 'entrambi' | '2d') — Overlay mode to persist.

Returns

• void

• See:
  • setOverlayMode - Persists each accepted mode change.

cssScale(): number

Computes the intrinsic-canvas to CSS-pixel scale so strokes, dots, and text stay visually stable on mobile, high-resolution canvases, and the lab's digital zoom. The bounding rect is used because it includes CSS transforms.

Returns

• number — Canvas-pixels per CSS pixel.

• See:
  • drawBox - Scales bbox stroke width.
  • drawMesh478 - Scales mesh dot radius.
  • drawFaceapiScaffold2d - Scales scaffold strokes and anchors.
  • drawLabels - Scales the metric label block.

drawBox(box: Object): void

Strokes the live face bounding rectangle using the current match-state color and scaled line width, making the box readable across the responsive canvas.

Parameters

• box (Object) — Bounding box in canvas pixels.

Returns

• void

• See:
  • renderOverlay - Draws the standard bbox mode.
  • drawFaceapiScaffold2d - Draws the fallback box for detailed 2D mode.

drawMesh478(): void

Draws the cached MediaPipe 478-point face mesh as colored dots on the bbox canvas. It only renders complete meshes so partial or malformed landmark payloads do not leave misleading points on the video.

Returns

• void

• See:
  • renderOverlay - Calls this for mesh and combined overlay modes.
  • onLandmarks3d - Supplies the cached mesh data this function reads.

drawFaceapiScaffold2d(): void

Draws the detailed 2D face-api scaffold for the 2d overlay mode: bounding box, eye axis, eye contours, jaw, nose, mouth, anchor dots, and a small live detection label. If detailed landmarks are not present, it falls back to the standard bbox and metrics label.

Returns

• void

• See:
  • renderOverlay - Calls this when `view.overlayMode` is `2d`.
  • overlayModeNeedsDetailedFaceapi - Requests the detailed landmark data needed here.
  • drawFaceapiScaffoldLabels - Draws the live-scope scaffold label.

drawFaceapiScaffoldLabels( box: Object, resized: object, scale: number, ): void

Draws the label for the detailed 2D scaffold, explicitly marking it as the live camera view. This matters because the top readout may describe the Ghostyle-composited matcher result, so "live face detected" and "matcher sees no face" can both be true without contradicting each other.

Parameters

• box (Object) — Detection box in canvas pixels.
• resized (object) — Detailed face-api result already resized to canvas coordinates.
• scale (number) — Canvas-pixels per CSS pixel.

Returns

• void

• See:
  • drawFaceapiScaffold2d - Calls this after drawing detailed landmarks.

getResizedDetection(): object | null

Resizes the cached face-api detection to the current bbox canvas dimensions, preserving alignment after camera resize, device-pixel-ratio changes, or overlay canvas resync.

Returns

• object | null — Resized face-api result, or null when no detection is cached.

• See:
  • drawFaceapiScaffold2d - Uses this for detailed 2D drawing.
  • getLastBox - Uses the same resize behavior for bbox extraction.

drawLabels(box: Object, score: number | null): void

Draws the metric label block next to the bounding box, showing live detection confidence, current face-api distance, live face id, and obfuscated id drift when a Ghostyle changes the nearest saved identity. The text is un-mirrored when the webcam canvas is mirrored so it remains readable.

Parameters

• box (Object) — Bounding box in canvas pixels.
• score (number | null) — Live detection score from face-api.

Returns

• void

• See:
  • renderOverlay - Calls this for standard bbox metrics.
  • drawFaceapiScaffold2d - Calls this when detailed landmarks are unavailable.
  • fmt - Formats each numeric metric shown in the label block.

Static Methods

init(): boolean

Resolves the bbox canvas and overlay references after main.js has finished preparing state, DOM elements, and window.gstmxx, then wires the shared event bus that drives all bbox, mesh, and 2D scaffold repainting. The setup is deliberately light enough for tests to call with stub canvases in the DOM.

Returns

• boolean — True when required DOM nodes are present and listeners are attached.

• See:
  • main - Dispatches `ghostatiReady` when the lab environment is ready.
  • onDetection - Receives live face-api detection events.
  • onLandmarks3d - Receives MediaPipe mesh events.
  • onMatchStateChanged - Receives scan/save/find/auto match-state events.
  • onDbChanged - Receives database changes that may reset overlay state.

onDetection(e: CustomEvent): void

Caches the latest face-api detection result and repaints the bbox layer. In Ghostmaxxing this is the bridge from the recognition engine's live camera result to the visual box, metrics label, or 2D landmark scaffold.

Parameters

• e (CustomEvent) — detection event carrying the latest face-api result in detail.result.

Returns

• void

• See:
  • init - Registers this on `state.gstmxxEvents`.
  • detectFaceInCam - Dispatches detection events from the 2D engine.
  • renderOverlay - Repaints after the cached detection changes.

onLandmarks3d(e: CustomEvent): void

Caches the latest 478-point MediaPipe mesh and repaints the bbox layer when the selected overlay mode includes the 3D mesh. This lets the overlay update from MediaPipe frames without asking the 2D engine to redraw.

Parameters

• e (CustomEvent) — landmarks3d event carrying normalized mesh points in detail.landmarks.

Returns

• void

• See:
  • init - Registers this on `state.gstmxxEvents`.
  • tick - Dispatches `landmarks3d` from `mediapipe-loop.js`.
  • renderOverlay - Repaints after cached mesh landmarks change.

onMatchStateChanged(e: CustomEvent): void

Applies a unified matchStateChanged payload to the overlay view and starts temporary suppression for explicit user-action sources. Auto-find events keep drawing continuously, while scan/save/find/efficacy overlays get a short quiet window so the bbox does not compete with the result visualization.

Parameters

• e (CustomEvent) — Match-state event whose detail may include top-level or nested face-api metrics.

Returns

• void

• See:
  • init - Registers this on `state.gstmxxEvents`.
  • tick - Dispatches auto match-state updates from `auto-find-loop.js`.
  • main - Dispatches scan/save match-state updates during user workflows.
  • renderOverlay - Repaints after match colors and labels are updated.

onDbChanged(e: CustomEvent): void

Resets match metrics when the local face archive is cleared, while preserving the current overlay mode and cached camera data. Database additions and stat updates do not invalidate the current visual match state, so they are ignored.

Parameters

• e (CustomEvent) — Database event whose detail.count is zero after archive clearing.

Returns

• void

• See:
  • init - Registers this on `state.gstmxxEvents`.
  • clearDb - Dispatches the zero-count database event after wiping the archive.

setOverlayMode( mode: 'bbox' | 'mesh' | 'entrambi' | '2d', ): 'bbox' | 'mesh' | 'entrambi' | '2d'

Changes which landmark visualization is painted on #bboxOverlay, persists the user's choice, and repaints immediately. The lab uses this to switch between bbox metrics, 3D mesh dots, both layers, and the detailed 2D scaffold.

Parameters

• mode ('bbox' | 'mesh' | 'entrambi' | '2d') — Requested overlay mode.

Returns

• 'bbox' | 'mesh' | 'entrambi' | '2d' — Active overlay mode after validation.

• See:
  • init - Applies the persisted mode on startup.
  • main - Calls this from the overlay mode button.
  • applyView - Calls this when the lab UI switches camera/points/mesh views.
  • renderOverlay - Repaints the chosen mode.

overlayModeNeedsDetailedFaceapi( mode?: 'bbox' | 'mesh' | 'entrambi' | '2d', ): boolean

Tells the 2D engine whether it should request detailed face-api landmarks for the current overlay mode. The detailed scaffold mode needs landmark chains, while bbox and mesh modes can use cheaper detection data.

Parameters

• mode ('bbox' | 'mesh' | 'entrambi' | '2d', optional, default: "view.overlayMode") — Overlay mode to inspect.

Returns

• boolean — True when detailed face-api landmarks are required.

• See:
  • runEffectPass - Uses this to choose the face-api detection pipeline.

extractBox(resized: object): Object | undefined

Pulls the bounding box out of a face-api result, handling both shapes used in the project: plain detections expose result.box, while detailed landmark detections expose result.detection.box.

Parameters

• resized (object) — face-api result already passed through resizeResults.

Returns

• Object | undefined — Extracted bounding box.

• See:
  • getLastBox - Extracts the cached live detection box.
  • drawFaceapiScaffold2d - Extracts the detailed scaffold box.

extractScore(result: object): number | null

Pulls the detection confidence score out of a face-api result, matching the same plain versus detailed result shapes handled by extractBox.

Parameters

• result (object) — face-api result to inspect.

Returns

• number | null — Detection score, or null when no numeric score exists.

• See:
  • renderOverlay - Passes this score into bbox metric labels.
  • drawFaceapiScaffold2d - Uses this score when falling back to bbox labels.

fmt(value: *, digits: number): string

Formats numeric bbox metrics for the overlay label block, using an em dash placeholder when a metric is missing, invalid, or not yet computed.

Parameters

• value (*) — Metric value to display.
• digits (number) — Decimal places for finite numbers.

Returns

• string — Formatted metric or placeholder.

• See:
  • drawLabels - Formats detection score, distance, and face id values.

currentColor(): string

Picks the stroke and label color for the latest match state, mapping identified, eluded, unclear, partial-elusion, and unknown outcomes to the overlay color convention documented by this module.

Returns

• string — CSS color for the current match state.

• See:
  • drawBox - Uses this for the bbox stroke.
  • drawMesh478 - Uses this for mesh dots.
  • drawFaceapiScaffold2d - Uses this for scaffold strokes.
  • drawLabels - Uses this for metric text.

Instance Fields

suppressUntil

Monotonic deadline (performance.now() domain). While now < this, skip drawing.

Other

COLORS: Object

Stroke / label color for each known match state. Exported so tests can assert color choices.

OVERLAY_SUPPRESS_MS

Suppression window after an overlay-producing user action, in milliseconds.

COPYABLE_FIELDS

Numeric matchStateChanged.detail fields that map 1:1 onto view.

INITIAL_VIEW

Pristine values for the rendering view; used as the reset baseline.

view

Current rendering view — single source of truth for what drawLabels and currentColor display. Mutated in place (never reassigned) so the export keeps a stable reference for tests.