@mikashboks/capture-intelligence-core 0.1.0

package/dist/esm/metrics.js

@@ -0,0 +1,291 @@
+/**
+ * Frame metrics computation on raw pixel arrays.
+ *
+ * DOM-free: all functions accept Uint8Array / numeric data. No
+ * HTMLVideoElement, HTMLCanvasElement, or any browser API.
+ *
+ * The caller is responsible for capturing pixel data from the video/camera
+ * source and providing the overlay region. This module computes brightness,
+ * blur (Laplacian variance), edge energy, frame-to-frame stability, and
+ * document rectangle detection.
+ */
+import { CAM_EDGE_PIXEL_THRESHOLD, CAM_EDGE_COVERAGE_THRESHOLD, CAM_DOC_CENTER_OFFSET_MAX, } from './types.js';
+/* -- Greyscale conversion ------------------------------------------------- */
+/**
+ * Convert an RGBA pixel buffer to greyscale in-place into a pre-allocated
+ * output array. Uses fixed-point ITU-R BT.601 weights.
+ *
+ * @param rgba       - RGBA pixel buffer (length = pixelCount * 4)
+ * @param out        - Pre-allocated Uint8Array to write greyscale values into
+ * @param pixelCount - Total pixel count (width * height)
+ */
+export function rgbaToGreyInPlace(rgba, out, pixelCount) {
+    for (let i = 0; i < pixelCount; i++) {
+        const p = i * 4;
+        out[i] = (rgba[p] * 77 + rgba[p + 1] * 150 + rgba[p + 2] * 29) >> 8;
+    }
+}
+/* -- Brightness ----------------------------------------------------------- */
+/**
+ * Compute average brightness within a rectangular sub-region of a greyscale
+ * image. The region is defined as fractional overlay coordinates [0..1].
+ *
+ * @param grey    - Greyscale pixel array
+ * @param w       - Image width
+ * @param h       - Image height
+ * @param region  - Overlay region in fractional coordinates
+ */
+export function computeBrightness(grey, w, h, region) {
+    const bx1 = Math.max(0, Math.round(region.x1 * w));
+    const by1 = Math.max(0, Math.round(region.y1 * h));
+    const bx2 = Math.min(w, Math.round(region.x2 * w));
+    const by2 = Math.min(h, Math.round(region.y2 * h));
+    let brightSum = 0;
+    let brightCount = 0;
+    for (let by = by1; by < by2; by++) {
+        for (let bx = bx1; bx < bx2; bx++) {
+            brightSum += grey[by * w + bx];
+            brightCount++;
+        }
+    }
+    return brightCount > 0 ? brightSum / brightCount : 0;
+}
+/* -- Blur (Laplacian variance) -------------------------------------------- */
+/**
+ * Compute Laplacian variance for sharpness detection.
+ * Higher values indicate sharper images.
+ *
+ * @param grey - Greyscale pixel array
+ * @param w    - Image width
+ * @param h    - Image height
+ */
+export function computeLaplacianVariance(grey, w, h) {
+    let lapSum = 0;
+    let lapCount = 0;
+    for (let ly = 1; ly < h - 1; ly++) {
+        for (let lx = 1; lx < w - 1; lx++) {
+            const ci = ly * w + lx;
+            const lap = -4 * grey[ci] + grey[ci - w] + grey[ci + w] + grey[ci - 1] + grey[ci + 1];
+            lapSum += lap * lap;
+            lapCount++;
+        }
+    }
+    return lapCount > 0 ? lapSum / lapCount : 0;
+}
+/**
+ * Compute Laplacian variance using floating-point greyscale values.
+ * Used for static image quality checks where Float32Array precision is
+ * preferred.
+ *
+ * @param grey - Floating-point greyscale pixel array
+ * @param w    - Image width
+ * @param h    - Image height
+ */
+export function computeLaplacianVarianceFloat(grey, w, h) {
+    let lapSum = 0;
+    let lapCount = 0;
+    for (let ly = 1; ly < h - 1; ly++) {
+        for (let lx = 1; lx < w - 1; lx++) {
+            const lap = -4 * grey[ly * w + lx] +
+                grey[(ly - 1) * w + lx] +
+                grey[(ly + 1) * w + lx] +
+                grey[ly * w + lx - 1] +
+                grey[ly * w + lx + 1];
+            lapSum += lap * lap;
+            lapCount++;
+        }
+    }
+    return lapCount > 0 ? lapSum / lapCount : 0;
+}
+/**
+ * Compute Sobel edge energy within an overlay sub-region of a greyscale image.
+ *
+ * @param grey    - Greyscale pixel array
+ * @param w       - Full image width
+ * @param h       - Full image height
+ * @param region  - Overlay region in fractional coordinates
+ */
+export function computeEdgeEnergy(grey, w, h, region) {
+    const rx1 = Math.max(1, Math.round(region.x1 * w));
+    const ry1 = Math.max(1, Math.round(region.y1 * h));
+    const rx2 = Math.min(w - 2, Math.round(region.x2 * w));
+    const ry2 = Math.min(h - 2, Math.round(region.y2 * h));
+    const regionW = Math.max(1, rx2 - rx1);
+    const regionH = Math.max(1, ry2 - ry1);
+    const rowEnergy = new Float32Array(regionH);
+    const colEnergy = new Float32Array(regionW);
+    let edgeSum = 0;
+    let edgeCount = 0;
+    let strongEdgeCount = 0;
+    for (let ey = ry1; ey < ry2; ey++) {
+        for (let ex = rx1; ex < rx2; ex++) {
+            const ei = ey * w + ex;
+            const gx2 = -grey[ei - w - 1] +
+                grey[ei - w + 1] -
+                2 * grey[ei - 1] +
+                2 * grey[ei + 1] -
+                grey[ei + w - 1] +
+                grey[ei + w + 1];
+            const gy2 = -grey[ei - w - 1] -
+                2 * grey[ei - w] -
+                grey[ei - w + 1] +
+                grey[ei + w - 1] +
+                2 * grey[ei + w] +
+                grey[ei + w + 1];
+            const mag2 = Math.abs(gx2) + Math.abs(gy2);
+            const rRow = ey - ry1;
+            const rCol = ex - rx1;
+            if (rRow >= 0 && rRow < regionH)
+                rowEnergy[rRow] += mag2;
+            if (rCol >= 0 && rCol < regionW)
+                colEnergy[rCol] += mag2;
+            edgeSum += mag2;
+            edgeCount++;
+            if (mag2 > CAM_EDGE_PIXEL_THRESHOLD)
+                strongEdgeCount++;
+        }
+    }
+    return {
+        avgEdge: edgeCount > 0 ? edgeSum / edgeCount : 0,
+        edgeCoverage: edgeCount > 0 ? strongEdgeCount / edgeCount : 0,
+        rowEnergy,
+        colEnergy,
+        regionW,
+        regionH,
+    };
+}
+/* -- Document rectangle detection ----------------------------------------- */
+/**
+ * Detect a document rectangle within edge energy profiles.
+ *
+ * @returns Area ratio, aspect ratio, and center offset of the detected region.
+ */
+export function detectDocumentRect(rowEnergy, colEnergy, regionW, regionH) {
+    let docAreaRatio = 0;
+    let docAspectRatio = 0;
+    let docCenterOffset = 1;
+    const energyThreshold = 0.24;
+    let rowMax = 0, colMax = 0;
+    for (let ri = 0; ri < regionH; ri++)
+        if (rowEnergy[ri] > rowMax)
+            rowMax = rowEnergy[ri];
+    for (let ci2 = 0; ci2 < regionW; ci2++)
+        if (colEnergy[ci2] > colMax)
+            colMax = colEnergy[ci2];
+    if (rowMax > 0 && colMax > 0) {
+        let docTop = 0, docBot = regionH - 1, docLeft = 0, docRight = regionW - 1;
+        for (let rt = 0; rt < regionH - 1; rt++) {
+            if (rowEnergy[rt] / rowMax > energyThreshold) {
+                docTop = rt;
+                break;
+            }
+        }
+        for (let rb = regionH - 1; rb > docTop; rb--) {
+            if (rowEnergy[rb] / rowMax > energyThreshold) {
+                docBot = rb;
+                break;
+            }
+        }
+        for (let cl = 0; cl < regionW - 1; cl++) {
+            if (colEnergy[cl] / colMax > energyThreshold) {
+                docLeft = cl;
+                break;
+            }
+        }
+        for (let cr = regionW - 1; cr > docLeft; cr--) {
+            if (colEnergy[cr] / colMax > energyThreshold) {
+                docRight = cr;
+                break;
+            }
+        }
+        const docW = docRight - docLeft + 1;
+        const docH = docBot - docTop + 1;
+        if (docW > 2 && docH > 2) {
+            docAreaRatio = (docW * docH) / (regionW * regionH);
+            docAspectRatio = docW / docH;
+            const docCenterX = (docLeft + docRight) / 2;
+            const docCenterY = (docTop + docBot) / 2;
+            const regionCenterX = regionW / 2;
+            const regionCenterY = regionH / 2;
+            docCenterOffset = Math.max(Math.abs(docCenterX - regionCenterX) / regionW, Math.abs(docCenterY - regionCenterY) / regionH);
+        }
+    }
+    return { docAreaRatio, docAspectRatio, docCenterOffset };
+}
+/* -- Frame-to-frame difference (stability) -------------------------------- */
+/**
+ * Compute mean absolute difference between two greyscale frames.
+ * Returns 999 if no previous frame is available.
+ *
+ * @param current  - Current greyscale frame
+ * @param previous - Previous greyscale frame (or null if first frame)
+ */
+export function computeFrameDiff(current, previous) {
+    if (!previous || previous.length !== current.length)
+        return 999;
+    let diffSum = 0;
+    for (let di = 0; di < current.length; di++) {
+        diffSum += Math.abs(current[di] - previous[di]);
+    }
+    return diffSum / current.length;
+}
+/* -- Full frame analysis -------------------------------------------------- */
+/**
+ * Compute all frame metrics from a greyscale image and an overlay region.
+ * This is the DOM-free equivalent of `camAnalyzeFrame()`.
+ *
+ * @param grey            - Greyscale pixel array (w * h bytes)
+ * @param w               - Image width
+ * @param h               - Image height
+ * @param region          - Overlay region in fractional coordinates
+ * @param prevGreyData    - Previous frame's greyscale data (for stability), or null
+ * @returns FrameMetrics for the frame
+ */
+export function analyzeFrame(grey, w, h, region, prevGreyData) {
+    // 1. Brightness
+    const brightness = computeBrightness(grey, w, h, region);
+    // 2. Blur (Laplacian variance)
+    const blurScore = computeLaplacianVariance(grey, w, h);
+    // 3. Edge energy
+    const edgeResult = computeEdgeEnergy(grey, w, h, region);
+    // 4. Document rectangle detection
+    const docRect = detectDocumentRect(edgeResult.rowEnergy, edgeResult.colEnergy, edgeResult.regionW, edgeResult.regionH);
+    // 5. Frame-to-frame difference (stability)
+    const frameDiff = computeFrameDiff(grey, prevGreyData);
+    return {
+        brightness,
+        blurScore,
+        edgeEnergy: edgeResult.avgEdge,
+        frameDiff,
+        docAreaRatio: docRect.docAreaRatio,
+        docAspectRatio: docRect.docAspectRatio,
+        docCenterOffset: docRect.docCenterOffset,
+        edgeCoverage: edgeResult.edgeCoverage,
+    };
+}
+/* -- Document shape match per overlay variant ----------------------------- */
+/**
+ * Check whether frame metrics indicate a document-like shape for the given
+ * overlay variant. DOM-free: the overlay variant is passed as a value.
+ *
+ * @param metrics  - Computed frame metrics
+ * @param variant  - Overlay variant ('card', 'passport', or 'a4')
+ */
+export function looksLikeDocument(metrics, variant) {
+    const areaRatio = metrics.docAreaRatio || 0;
+    const aspectRatio = metrics.docAspectRatio || 0;
+    const centerOffset = metrics.docCenterOffset || 1;
+    const edgeCoverage = metrics.edgeCoverage || 0;
+    if (centerOffset > CAM_DOC_CENTER_OFFSET_MAX || edgeCoverage < CAM_EDGE_COVERAGE_THRESHOLD) {
+        return false;
+    }
+    if (variant === 'a4') {
+        return areaRatio > 0.2 && areaRatio < 0.98 && aspectRatio > 0.45 && aspectRatio < 1.65;
+    }
+    if (variant === 'passport') {
+        return areaRatio > 0.15 && areaRatio < 0.92 && aspectRatio > 0.5 && aspectRatio < 2.0;
+    }
+    // Default (ID cards, voter IDs, driver's licences)
+    return areaRatio > 0.15 && areaRatio < 0.92 && aspectRatio > 0.5 && aspectRatio < 2.5;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/esm/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/metrics.ts"],"names":[],"mappings":"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"}

package/dist/esm/quality-checks.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Quality checks -- threshold comparison logic and failure escalation rules.
+ *
+ * DOM-free: no HTMLElement, no document.*, no navigator.*. All functions
+ * operate on plain data (FrameMetrics, QualityCheckResults, numeric values).
+ *
+ * The DOM-coupled parts of quality-review.ts (banner updates, button state,
+ * shake animations, Svelte store, etc.) remain in the SDK. This module
+ * exposes the pure decision logic that can be reused in React Native or
+ * Node.js environments.
+ */
+import type { QualityCheckResults, DetectedFace, QualityBucket, ReviewDecisionOptions, ReviewMode } from './types.js';
+/**
+ * Map a step signature string and optional review mode to a quality bucket.
+ */
+export declare function getQualityBucket(stepSig: string, reviewMode?: ReviewMode): QualityBucket | '';
+/**
+ * Get the number of consecutive failures required before the "submit anyway"
+ * override becomes available for a given step signature.
+ */
+export declare function getSubmitAnywayThreshold(stepSig: string, reviewMode?: ReviewMode): number;
+/**
+ * Mutable failure counter state. Create one per flow session.
+ */
+export interface QualityFailureState {
+    document_front: number;
+    document_back: number;
+    selfie: number;
+    address_document: number;
+    address_front_door: number;
+    /** Signature of the last counted failure (prevents double-counting) */
+    lastFailedSignature: string;
+}
+/**
+ * Create a fresh failure state.
+ */
+export declare function createQualityFailureState(): QualityFailureState;
+/**
+ * Increment the failure counter for a bucket if this is a new failure
+ * (not a re-render of the same failed review).
+ *
+ * @param state         - Mutable failure state
+ * @param stepSig       - Step signature string
+ * @param failSignature - Unique signature for this failure (e.g. bucket + image src)
+ * @param anyFail       - Whether any quality check actually failed
+ * @returns true if the counter was incremented
+ */
+export declare function countFailedReview(state: QualityFailureState, stepSig: string, failSignature: string, anyFail: boolean, reviewMode?: ReviewMode): boolean;
+/**
+ * Check whether the submit-anyway override should be available.
+ */
+export declare function shouldShowSubmitAnyway(state: QualityFailureState, stepSig: string, reviewMode?: ReviewMode): boolean;
+/**
+ * Input for running document quality checks on a static (already-captured)
+ * image. All values are pre-computed by the caller from raw pixel data.
+ */
+export interface DocumentQualityInput {
+    /** Average brightness (0-255), computed from RGBA -> luminance */
+    avgBrightness: number;
+    /** Laplacian variance (sharpness measure) */
+    laplacianVariance: number;
+    /** Greyscale pixel array for the document classifier */
+    grey: Uint8Array;
+    /** RGBA pixel array for the document classifier */
+    imgData: Uint8ClampedArray;
+    /** Analysis width */
+    w: number;
+    /** Analysis height */
+    h: number;
+    /** Whether corners were detected as OK by crop detection (null = unknown) */
+    cornersOk: boolean | null;
+    /** Document type for the classifier (optional) */
+    documentType?: string | null;
+    /** Whether this is an address proof document */
+    isAddressProof: boolean;
+}
+/**
+ * Result of document quality checks.
+ */
+export interface DocumentQualityResult {
+    /** All individual check results */
+    checks: QualityCheckResults;
+    /** Whether any check explicitly failed */
+    anyFail: boolean;
+    /** Human-readable failure message (empty if all passed) */
+    failMessage: string;
+}
+/**
+ * Run quality checks on a static document image. Returns the check results
+ * and a human-readable failure message.
+ *
+ * This is the pure-logic extraction from `runQualityCheck()`. The caller
+ * handles image loading, Canvas rasterization, and UI updates.
+ */
+export declare function runDocumentQualityChecks(input: DocumentQualityInput): DocumentQualityResult;
+/**
+ * Input for running selfie quality checks.
+ */
+export interface SelfieQualityInput {
+    /** Average brightness (0-255) */
+    avgBrightness: number;
+    /** Laplacian variance (sharpness measure) */
+    laplacianVariance: number;
+}
+/**
+ * Run basic selfie quality checks (lighting + sharpness, before face
+ * detection). Returns the `good_lighting` check result.
+ */
+export declare function runSelfieQualityChecks(input: SelfieQualityInput): QualityCheckResults;
+/**
+ * Check face position and size relative to image dimensions.
+ * Returns an array of warning strings (empty = face is OK).
+ *
+ * @param faces       - Detected faces
+ * @param imageWidth  - Full image width
+ * @param imageHeight - Full image height
+ */
+export declare function checkFaceInImage(faces: DetectedFace[], imageWidth: number, imageHeight: number): string[];
+/**
+ * Check whether a detected face is well-centered and appropriately sized
+ * for live capture (stricter than static image checks).
+ *
+ * @param face        - Detected face
+ * @param videoWidth  - Video frame width
+ * @param videoHeight - Video frame height
+ */
+export declare function isFaceCentered(face: DetectedFace, videoWidth: number, videoHeight: number): boolean;
+/**
+ * Evaluate document quality check results and produce a prioritised failure
+ * message. Handles address-proof and ID-document modes.
+ */
+export declare function evaluateDocumentFailure(checks: QualityCheckResults, isAddressProof: boolean): {
+    anyFail: boolean;
+    failMessage: string;
+};
+/**
+ * Evaluate selfie quality check results and produce a prioritised failure
+ * message.
+ */
+export declare function evaluateSelfieFailure(checks: QualityCheckResults): {
+    anyFail: boolean;
+    failMessage: string;
+};
+/**
+ * Evaluate quality failures for a specific review mode using the same
+ * prioritization rules as the SDK review banner.
+ */
+export declare function evaluateReviewFailure(checks: QualityCheckResults, options: ReviewDecisionOptions): {
+    anyFail: boolean;
+    failMessage: string;
+};
+/**
+ * Determine whether the "next" button should be disabled based on the
+ * current quality check state.
+ *
+ * @param checks         - Current quality check results
+ * @param isSelfie       - Whether this is a selfie review
+ * @param isAddressProof - Whether this is an address proof review
+ * @returns Disabled reason string (empty = should be enabled)
+ */
+export declare function getNextButtonDisabledReason(checks: QualityCheckResults, isSelfieOrOptions: boolean | ReviewDecisionOptions, isAddressProof?: boolean): string;
+/**
+ * Get the override button text for the submit-anyway flow.
+ */
+export declare function getOverrideButtonText(stepSig: string): string;
+/**
+ * Get the override banner message based on failure count and bucket.
+ */
+export declare function getOverrideBannerMessage(stepSig: string, failCount: number, reviewMode?: ReviewMode): string;
+//# sourceMappingURL=quality-checks.d.ts.map

package/dist/esm/quality-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-checks.d.ts","sourceRoot":"","sources":["../../src/quality-checks.ts"],"names":[],"mappings":"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"}