@viji-dev/core 0.7.0 → 0.7.4

package/dist/artist-global.d.ts

@@ -559,15 +559,25 @@ declare global {
   }
 
   /**
-   * One detected face produced by the video CV pipeline. Always carries `id`,
-   * `bounds`, `center`, and `confidence`; the rest is populated only when the
-   * matching CV feature is enabled (face mesh for `landmarks` and `headPose`,
-   * emotion detection for `expressions` and `blendshapes`).
+   * One detected face produced by the video CV pipeline. Each field is
+   * populated only by its source model; fields whose source model is not
+   * enabled read as `null` so the absence is loud rather than silent. Enable
+   * the relevant `enable*` verb on `viji.video.cv` to populate each group:
+   *
+   * - `bounds`, `center`, `confidence`: populated by `enableFaceDetection(true)`.
+   * - `landmarks`: populated by `enableFaceMesh(true)` (empty array otherwise).
+   * - `headPose`: populated by `enableFaceMesh(true)`.
+   * - `blendshapes`, `expressions`: populated by `enableEmotionDetection(true)`.
+   *
+   * If a field is `null`, call the corresponding `enable*` verb on
+   * `viji.video.cv` to populate it. Each active CV feature consumes its own
+   * WebGL context for MediaPipe; enabling many at once on lower-end hardware
+   * can hit context limits.
    */
   interface FaceData {
       /** Index-based face identifier (`0`, `1`, …). Stable within a single frame, may change between frames. */
       id: number;
-      /** Bounding box, all components normalized to 0..1 of the source frame. */
+      /** Bounding box, all components normalized to 0..1 of the source frame. `null` unless face detection is enabled. */
       bounds: {
           /** Left edge of the face bounding box, normalized 0..1. */
           x: number;
@@ -577,16 +587,16 @@ declare global {
           width: number;
           /** Height of the face bounding box, normalized 0..1. */
           height: number;
-      };
-      /** Center of the bounding box, normalized 0..1. */
+      } | null;
+      /** Center of the bounding box, normalized 0..1. `null` unless face detection is enabled. */
       center: {
           /** Horizontal center of the face, normalized 0..1. */
           x: number;
           /** Vertical center of the face, normalized 0..1. */
           y: number;
-      };
-      /** Detection confidence in 0..1. */
-      confidence: number;
+      } | null;
+      /** Detection confidence in 0..1. `null` unless face detection is enabled. */
+      confidence: number | null;
       /** 468 normalized face mesh landmarks when face mesh is enabled; empty array otherwise. */
       landmarks: {
           /** Horizontal landmark coordinate, normalized 0..1. */
@@ -596,7 +606,16 @@ declare global {
           /** Optional depth (relative). */
           z?: number;
       }[];
-      /** Seven expression confidence scores in 0..1. All zero unless emotion detection is enabled. */
+      /** Estimated head rotation in degrees. `null` unless face mesh is enabled. */
+      headPose: {
+          /** Up/down rotation in degrees (-90..90). Positive = head looking up, negative = looking down. */
+          pitch: number;
+          /** Left/right rotation in degrees (-90..90). Positive = head turned to the subject's right, negative = to the left. */
+          yaw: number;
+          /** Tilt rotation in degrees (-180..180). Positive = head tilted to the subject's right (right ear toward right shoulder). */
+          roll: number;
+      } | null;
+      /** Seven expression confidence scores in 0..1. `null` unless emotion detection is enabled. */
       expressions: {
           /** Confidence (0..1) of a neutral expression. */
           neutral: number;
@@ -612,18 +631,9 @@ declare global {
           disgusted: number;
           /** Confidence (0..1) of a fearful expression. */
           fearful: number;
-      };
-      /** Estimated head rotation. All zero unless face mesh is enabled. */
-      headPose: {
-          /** Up/down rotation in degrees (-90..90). Positive = head looking up, negative = looking down. */
-          pitch: number;
-          /** Left/right rotation in degrees (-90..90). Positive = head turned to the subject's right, negative = to the left. */
-          yaw: number;
-          /** Tilt rotation in degrees (-180..180). Positive = head tilted to the subject's right (right ear toward right shoulder). */
-          roll: number;
-      };
-      /** 52 ARKit-compatible facial muscle coefficients. All zero unless emotion detection is enabled. */
-      blendshapes: FaceBlendshapes;
+      } | null;
+      /** 52 ARKit-compatible facial muscle coefficients. `null` unless emotion detection is enabled. */
+      blendshapes: FaceBlendshapes | null;
   }
 
   /**
@@ -1211,7 +1221,7 @@ declare global {
       isEnding: boolean;
   }
 
-  const VERSION = "0.7.0";
+  const VERSION = "0.7.4";
 
   /**
    * Real-time video API: drawable frame, dimensions, and the source-side
@@ -1320,35 +1330,73 @@ declare global {
       /** Body segmentation mask, or `null` when segmentation is off. */
       segmentation: SegmentationData | null;
       /**
-       * Toggle face detection (bounding box, center, confidence, id).
+       * Toggle face detection. Populates `face.bounds`, `face.center`,
+       * `face.confidence` on each detected face. Independent of face mesh and
+       * emotion detection.
+       *
+       * Safe to call from module scope as well as from inside `render()`. The
+       * verb is idempotent and reference-counted; per-frame calls inside
+       * `render()` (the canonical toggle-gated pattern) are cheap.
+       *
        * @returns Resolves once the underlying pipeline has finished switching.
        */
       enableFaceDetection(enabled: boolean): Promise<void>;
       /**
-       * Toggle 468-point face mesh + head pose (`pitch`, `yaw`, `roll`). Implies
-       * face detection.
+       * Toggle 468-point face mesh and computed head pose (`pitch`, `yaw`,
+       * `roll`). Populates `face.landmarks` and `face.headPose` on the face
+       * entry. Does NOT populate `face.bounds` / `face.center` / `face.confidence`
+       * — those are produced only by face detection. Enable both if you need
+       * both, or compute bounds from `face.landmarks` min/max yourself.
+       *
+       * Safe to call from module scope as well as from inside `render()`. The
+       * verb is idempotent and reference-counted.
+       *
        * @returns Resolves once the pipeline has finished switching.
        */
       enableFaceMesh(enabled: boolean): Promise<void>;
       /**
        * Toggle 7 expressions + 52 ARKit blendshape coefficients on each face.
-       * Implies face mesh.
+       * Populates `face.blendshapes` and `face.expressions`. Internally requires
+       * the face landmarker model (loads it alongside `enableFaceMesh` if both
+       * are enabled; loads it on its own otherwise so `face.landmarks` and
+       * `face.headPose` are also populated). Does NOT populate
+       * `face.bounds` / `face.center` / `face.confidence` — enable face
+       * detection for those.
+       *
+       * Safe to call from module scope as well as from inside `render()`. The
+       * verb is idempotent and reference-counted.
+       *
        * @returns Resolves once the pipeline has finished switching.
        */
       enableEmotionDetection(enabled: boolean): Promise<void>;
       /**
-       * Toggle 21-point hand landmarks + ML-classified gesture confidences for up
-       * to two hands.
+       * Toggle 21-point hand landmarks and ML-classified gesture confidences
+       * for up to two hands. Populates `viji.video.cv.hands[]` with `landmarks`,
+       * `palm`, `bounds` (computed from landmarks), and `gestures`.
+       *
+       * Safe to call from module scope as well as from inside `render()`. The
+       * verb is idempotent and reference-counted.
+       *
        * @returns Resolves once the pipeline has finished switching.
        */
       enableHandTracking(enabled: boolean): Promise<void>;
       /**
        * Toggle 33-point BlazePose body landmarks (face / torso / arms / legs).
+       * Populates `viji.video.cv.pose`.
+       *
+       * Safe to call from module scope as well as from inside `render()`. The
+       * verb is idempotent and reference-counted.
+       *
        * @returns Resolves once the pipeline has finished switching.
        */
       enablePoseDetection(enabled: boolean): Promise<void>;
       /**
-       * Toggle per-pixel person/background segmentation mask.
+       * Toggle per-pixel person/background segmentation mask. Populates
+       * `viji.video.cv.segmentation`.
+       *
+       * Safe to call from module scope as well as from inside `render()`. The
+       * verb is idempotent and reference-counted.
+       *
        * @returns Resolves once the pipeline has finished switching.
        */
       enableBodySegmentation(enabled: boolean): Promise<void>;

package/dist/artist-jsdoc.d.ts

@@ -362,23 +362,27 @@
  */
 
 /**
- * One detected face produced by the video CV pipeline. Always carries `id`, `bounds`, `center`, and `confidence`; the rest is populated only when the matching CV feature is enabled (face mesh for `landmarks` and `headPose`, emotion detection for `expressions` and `blendshapes`).
+ * One detected face produced by the video CV pipeline. Each field is populated only by its source model; fields whose source model is not enabled read as `null` so the absence is loud rather than silent. Enable the relevant `enable*` verb on `viji.video.cv` to populate each group: - `bounds`, `center`, `confidence`: populated by `enableFaceDetection(true)`. - `landmarks`: populated by `enableFaceMesh(true)` (empty array otherwise). - `headPose`: populated by `enableFaceMesh(true)`. - `blendshapes`, `expressions`: populated by `enableEmotionDetection(true)`. If a field is `null`, call the corresponding `enable*` verb on `viji.video.cv` to populate it. Each active CV feature consumes its own WebGL context for MediaPipe; enabling many at once on lower-end hardware can hit context limits.
  * @typedef {Object} FaceData
  * @property {number} id - Index-based face identifier (`0`, `1`, …). Stable within a single frame, may change between frames.
- * @property {Object} bounds - Bounding box, all components normalized to 0..1 of the source frame.
+ * @property {Object} bounds - Bounding box, all components normalized to 0..1 of the source frame. `null` unless face detection is enabled.
  * @property {number} bounds.x - Left edge of the face bounding box, normalized 0..1.
  * @property {number} bounds.y - Top edge of the face bounding box, normalized 0..1.
  * @property {number} bounds.width - Width of the face bounding box, normalized 0..1.
  * @property {number} bounds.height - Height of the face bounding box, normalized 0..1.
- * @property {Object} center - Center of the bounding box, normalized 0..1.
+ * @property {Object} center - Center of the bounding box, normalized 0..1. `null` unless face detection is enabled.
  * @property {number} center.x - Horizontal center of the face, normalized 0..1.
  * @property {number} center.y - Vertical center of the face, normalized 0..1.
- * @property {number} confidence - Detection confidence in 0..1.
+ * @property {number |null} confidence - Detection confidence in 0..1. `null` unless face detection is enabled.
  * @property {Object} landmarks - 468 normalized face mesh landmarks when face mesh is enabled; empty array otherwise.
  * @property {number} landmarks.x - Horizontal landmark coordinate, normalized 0..1.
  * @property {number} landmarks.y - Vertical landmark coordinate, normalized 0..1.
  * @property {number} landmarks.z - Optional depth (relative).
- * @property {Object} expressions - Seven expression confidence scores in 0..1. All zero unless emotion detection is enabled.
+ * @property {Object} headPose - Estimated head rotation in degrees. `null` unless face mesh is enabled.
+ * @property {number} headPose.pitch - Up/down rotation in degrees (-90..90). Positive = head looking up, negative = looking down.
+ * @property {number} headPose.yaw - Left/right rotation in degrees (-90..90). Positive = head turned to the subject's right, negative = to the left.
+ * @property {number} headPose.roll - Tilt rotation in degrees (-180..180). Positive = head tilted to the subject's right (right ear toward right shoulder).
+ * @property {Object} expressions - Seven expression confidence scores in 0..1. `null` unless emotion detection is enabled.
  * @property {number} expressions.neutral - Confidence (0..1) of a neutral expression.
  * @property {number} expressions.happy - Confidence (0..1) of a happy / smiling expression.
  * @property {number} expressions.sad - Confidence (0..1) of a sad expression.
@@ -386,11 +390,7 @@
  * @property {number} expressions.surprised - Confidence (0..1) of a surprised expression.
  * @property {number} expressions.disgusted - Confidence (0..1) of a disgusted expression.
  * @property {number} expressions.fearful - Confidence (0..1) of a fearful expression.
- * @property {Object} headPose - Estimated head rotation. All zero unless face mesh is enabled.
- * @property {number} headPose.pitch - Up/down rotation in degrees (-90..90). Positive = head looking up, negative = looking down.
- * @property {number} headPose.yaw - Left/right rotation in degrees (-90..90). Positive = head turned to the subject's right, negative = to the left.
- * @property {number} headPose.roll - Tilt rotation in degrees (-180..180). Positive = head tilted to the subject's right (right ear toward right shoulder).
- * @property {FaceBlendshapes} blendshapes - 52 ARKit-compatible facial muscle coefficients. All zero unless emotion detection is enabled.
+ * @property {FaceBlendshapes |null} blendshapes - 52 ARKit-compatible facial muscle coefficients. `null` unless emotion detection is enabled.
  */
 
 /**