engine

Source: engine.js:2

Static Methods

detectFaceInCam(drawOverlay: boolean): Promise.<(Object|null)>

Detect a face in the webcam video and optionally draw an overlay. Returns the face detection result or null if no face is found.

Parameters

• drawOverlay (boolean) — Whether to draw the detection overlay.

Returns

• Promise.<(Object|null)> — Detection result, faceapi object.

• See:
  • saveFace - uses detectFaceInCam before saving a face.
  • lab-js/auto-find-loop.js - obtains the live baseline used for periodic matching.
  • computeCompositeMetrics - uses detectFaceInCam as the baseline detection.

compositeAndDetect(liveResult: Object): Promise.<Object>

Build a canvas with video compositing and the active 2D/3D Ghostyle overlay. Calls the active 2D Ghostyle's onDraw() hook to render the overlay. Executes a Face API detection with landmarks and descriptor on the composite. Returns an object containing the canvas, obfuscatedResult, and weakDetection flag. If detection with the normal threshold (scoreThreshold: 0.5) fails, it retries with a relaxed threshold (0.1) to still extract numeric metrics from the composite — useful as a "makeup efficacy indicator" even beyond the detection threshold. weakDetection indicates when a fallback detection was required.

Parameters

• liveResult (Object) — Result from the live face detection.

Returns

• Promise.<Object> — An object with canvas, obfuscatedResult, and weakDetection.

• See:
  • lab-js/auto-find-loop.js - uses this function for post-Ghostyle comparison.
  • computeCompositeMetrics - uses detectFaceInCam as the baseline detection.

runEffectPass(): Promise.<boolean>

Run a single effect pass: performs face detection (with optional landmarks) and draws the effect overlay. Manages state flags to avoid concurrent inference.

Returns

• Promise.<boolean> — Whether the overlay should be cleared (no face detected without active effect).

• See:
  • drawGhostyleOverlay - invoked to render the effect.
  • detectFaceInCam - used internally for detection when an active effect is present.

drawGhostyleOverlay( result: Object, includeDetectionScaffold?: boolean, )

Draw the effect overlay onto the canvas, optionally including the detection scaffold. Resizes the canvas, clears previous drawings, and renders the active effect style if present.

Parameters

• result (Object) — Face detection result.
• includeDetectionScaffold (boolean, optional, default: false) — Whether to draw the detection scaffold.

• See:
  • runEffectPass - calls this to render overlay after detection.
  • drawDetectionScaffold - optionally used when includeDetectionScaffold is true.

drawDetectionScaffold( ctx: CanvasRenderingContext2D, resized: Object, )

Draw visual scaffolding for a detection result: bounding box, eye line, and facial landmarks. Useful for debugging and user feedback.

Parameters

• ctx (CanvasRenderingContext2D) — Canvas context to draw on.
• resized (Object) — Resized detection result containing box and landmarks.

• See:
  • drawGhostyleOverlay - may call this when includeDetectionScaffold is true.
  • drawResult - calls this to display detection scaffold.

drawResult(result: Object)

Draw the detection result on the overlay canvas, including the detection scaffold and any active effect.

Parameters

• result (Object) — Detection result.

• See:
  • drawDetectionScaffold - used to draw scaffold.
  • drawGhostyleOverlay - effect drawing is performed here if active.

saveFace(): Promise.<({id: number, result: object}|undefined)>

Capture the current face, convert its typed descriptor and landmark points to JSON-safe arrays, assign the next local ID, persist it, and log the action.

Returns

• Promise.<({id: number, result: object}|undefined)> — The assigned ID and original face-api result, or undefined when no face is detected.

• See:
  • detectFaceInCam - obtains the face data to be saved.

evaluateMatch( liveInfo: Object, composite: object | null, ): Object

Convert raw live/composite distance data into the 2D section consumed by matchStateChanged. Composite detections are reduced to efficacy metrics; decideMatchState then chooses the effective distance and matched ID. With no composite, the live nearest-neighbour distance drives the decision.

Parameters

• liveInfo (Object) — Nearest saved face for the unmodified camera frame.
• composite (object | null) — Detection result from the Ghostyle-composited frame, when an effect is active.
  • composite.obfuscatedResult (object, optional) — face-api result detected on the composited frame.
  • composite.weakDetection (boolean, optional) — Whether the relaxed detector was required to recover that result.

Returns

• Object — Localized decision text plus normalized live/composite metrics for the UI and event payload.

• See:
  • lab-js/auto-find-loop.js - publishes the returned values periodically.

hasActivePlugin(): boolean

Determine whether a 2D or 3D effect plugin is currently active.

Returns

• boolean — True if an effect plugin is active.

• See:
  • lab-js/auto-find-loop.js - skips composite work when no plugin is active.