tempest-react-sdk 0.19.0 → 0.20.0

package/dist/vision.d.ts

@@ -1,4 +1,5 @@
 import type * as ort from 'onnxruntime-web';
+import { RefObject } from 'react';
 
 /**
  * Per-class NMS — boxes are suppressed only by other boxes of the same class.
@@ -103,6 +104,18 @@ export declare class Boxes {
     get data(): Float32Array;
 }
 
+/** A classified camera error with a human-readable, English message. */
+export declare interface CameraStreamError {
+    kind: CameraStreamErrorKind;
+    message: string;
+}
+
+/** Classified reason a camera stream could not be acquired. */
+export declare type CameraStreamErrorKind = "unsupported" | "permission-denied" | "no-camera" | "in-use" | "insecure" | "unknown";
+
+/** Lifecycle status of the camera stream. */
+export declare type CameraStreamStatus = "idle" | "loading" | "ready" | "error";
+
 /**
  * Output of an image classification inference.
  */
@@ -245,6 +258,25 @@ export declare interface ClassProbability {
 /** COCO 2017 80-class labels in canonical class-id order. */
 export declare const COCO_CLASSES: readonly string[];
 
+/**
+ * Mean BT.709 luminance (`0.2126*R + 0.7152*G + 0.0722*B`) of a decoded
+ * `<img>`, `<video>` or `<canvas>`, scaled to `0..255`.
+ *
+ * The source is downsampled so its longest edge is at most
+ * {@link LUMINANCE_SAMPLE_MAX_EDGE} before pixels are read. The 2D context is
+ * created with `willReadFrequently` so repeated sampling (live feedback) stays
+ * on the fast path.
+ *
+ * Pass `reusableCanvas` to avoid allocating a fresh canvas every frame in a hot
+ * loop; when omitted a one-shot detached canvas is created.
+ *
+ * @param source - the image/video/canvas to sample.
+ * @param reusableCanvas - optional canvas reused across frames to avoid GC churn.
+ * @returns The mean luminance in `0..255`, or `0` when the source is unloaded
+ *   (zero-sized) or a 2D context is unavailable.
+ */
+export declare function computeImageLuminance(source: LuminanceSource, reusableCanvas?: HTMLCanvasElement): number;
+
 export declare interface DecodedAnchors {
     /** Indices into the original `numAnchors` axis, in descending confidence order. */
     readonly anchorIndices: Int32Array;
@@ -554,6 +586,20 @@ export declare class ImageLoadError extends OrtVisionError {
 export declare class InferenceError extends OrtVisionError {
 }
 
+/**
+ * Whether a measured luminance clears a brightness threshold.
+ *
+ * `threshold` is intentionally required — a sensible value is
+ * application-specific (it depends on the model, the lighting the model was
+ * trained on, and the acceptable false-reject rate), so the SDK does not bake
+ * in a default.
+ *
+ * @param luminance - measured mean luminance in `0..255`.
+ * @param threshold - minimum acceptable luminance in `0..255`.
+ * @returns `true` when `luminance >= threshold`.
+ */
+export declare function isLuminanceAcceptable(luminance: number, threshold: number): boolean;
+
 /** Raised when class labels cannot be resolved from the supplied spec. */
 export declare class LabelMapError extends OrtVisionError {
 }
@@ -605,6 +651,34 @@ export declare interface LetterboxResult {
      */
  export declare function loadImage(source: ImageInput): Promise<RGBImage>;
 
+ /**
+  * Error raised when a captured frame is too dark to be analysed reliably.
+  * Carries the measured luminance and the threshold it failed so callers can
+  * surface actionable feedback.
+  */
+ export declare class LowLuminanceError extends Error {
+     /** Measured mean luminance, `0..255`. */
+     readonly luminance: number;
+     /** Threshold that was checked against, `0..255`. */
+     readonly threshold: number;
+     /**
+      * @param luminance - the measured mean luminance in `0..255`.
+      * @param threshold - the threshold the measurement failed to reach.
+      */
+     constructor(luminance: number, threshold: number);
+ }
+
+ /**
+  * Longest edge (in pixels) the source is downsampled to before sampling.
+  * Averaging over a small downsample is statistically equivalent for a
+  * brightness threshold and orders of magnitude faster than reading every pixel
+  * of a full-resolution camera frame.
+  */
+ export declare const LUMINANCE_SAMPLE_MAX_EDGE = 256;
+
+ /** Drawable source we can sample luminance from — image, video, or canvas. */
+ export declare type LuminanceSource = HTMLImageElement | HTMLVideoElement | HTMLCanvasElement;
+
  /**
   * Single-channel binary or grayscale mask, laid out row-major.
   *
@@ -1018,6 +1092,74 @@ export declare interface LetterboxResult {
         */
        export declare function toTensor(image: RGBImage): Float32Array;
 
+       /**
+        * Acquire a `MediaStream` via `getUserMedia`, attach it to a `<video>` element,
+        * and expose status/error so the page can render permission and error states.
+        * The stream is automatically released on unmount or retry.
+        *
+        * Defaults to the rear ("environment") camera; desktops fall back to whatever
+        * single camera they expose. Pass `options.constraints` to override.
+        *
+        * Implementation notes:
+        * - Cleanup detaches the stream from a *snapshotted* video node, so it releases
+        *   the same element it attached to even if the page remounts the `<video>`.
+        * - When `getUserMedia` is missing, an insecure context is the usual cause, so
+        *   the hook prefers that (actionable) error; otherwise it reports `unsupported`.
+        * - `video.play()` rejections are swallowed: autoplay may be blocked, but the
+        *   user gesture that opened the camera usually counts and playback resumes on
+        *   the next interaction.
+        *
+        * @param options - optional configuration (see {@link UseCameraStreamOptions}).
+        * @returns The stream status, classified error, a `videoRef` to attach, and a
+        *   `retry()` to re-attempt acquisition.
+        */
+       export declare function useCameraStream(options?: UseCameraStreamOptions): UseCameraStreamApi;
+
+       /** Value returned by {@link useCameraStream}. */
+       export declare interface UseCameraStreamApi {
+           /** Current lifecycle status. */
+           status: CameraStreamStatus;
+           /** The classified error, or `null` while not in the `error` status. */
+           error: CameraStreamError | null;
+           /** Attach to a `<video ref={…} />`. The stream is wired to it once ready. */
+           videoRef: RefObject<HTMLVideoElement | null>;
+           /** Manually re-attempt after an error (e.g. the user changed permissions). */
+           retry: () => void;
+       }
+
+       /** Options for {@link useCameraStream}. */
+       export declare interface UseCameraStreamOptions {
+           /**
+            * Constraints passed to `getUserMedia`. Defaults to the rear
+            * ("environment") camera at Full-HD ideal resolution with audio off.
+            * Read when the stream (re)starts — change it and call `retry()` to apply.
+            */
+           constraints?: MediaStreamConstraints;
+       }
+
+       /**
+        * Sample mean luminance from a `<video>` source on a `requestAnimationFrame`
+        * loop and expose the rolling value. Sampling is throttled by `intervalMs` and
+        * paused whenever `enabled` is `false` or the video is not ready yet
+        * (`readyState < 2` or `videoWidth === 0`).
+        *
+        * One offscreen canvas is reused across frames to avoid GC pressure. Designed
+        * to feed a live brightness bar / border color on a camera page.
+        *
+        * @param videoRef - ref to the `<video>` element to sample.
+        * @param options - optional configuration (see {@link UseLiveLuminanceOptions}).
+        * @returns The rolling mean luminance in `0..255` (`0` until the first sample).
+        */
+       export declare function useLiveLuminance(videoRef: RefObject<HTMLVideoElement | null>, { enabled, intervalMs }?: UseLiveLuminanceOptions): number;
+
+       /** Options for {@link useLiveLuminance}. */
+       export declare interface UseLiveLuminanceOptions {
+           /** When `false` the loop is paused (e.g. while a capture is in flight). Default: `true`. */
+           enabled?: boolean;
+           /** Throttle measurements in milliseconds. Default: `160` (~6 fps), plenty for UX. */
+           intervalMs?: number;
+       }
+
        export declare const VERSION: string;
 
        export declare abstract class VisionTask {