@moveris/shared 2.7.0 → 2.9.0

package/README.md

@@ -94,6 +94,7 @@ const crops: CropData[] = capturedFrames.map((f) => ({
 const result = await client.fastCheckCrops(crops, {
   model: '10',
   source: 'live',
+  bgSegmentation: true, // optional — sent as bg_segmentation in payload
 });
 ```
 
@@ -443,6 +444,9 @@ const status = getStatusMessage('capturing', DEFAULT_LOCALE);
 | `eyes_overexposed`  | "Eye region overexposed…"      | Eye region too bright        |
 | `glasses_glare`     | "Glare detected…"              | Specular highlights on eyes  |
 | `eye_quality_poor`  | "Eye region quality is poor"   | Generic eye quality failure  |
+| `camera_angle_low`  | "Raise camera to eye level"    | Camera below face (Y < 0.3)  |
+| `camera_angle_high` | "Lower camera to eye level"    | Camera above face (Y > 0.7)  |
+| `camera_tilted`     | "Hold camera level"            | Eye line deviates > 15°      |
 
 ---
 
@@ -529,7 +533,13 @@ if (bounds) {
 Utilities for assessing frame quality before submission.
 
 ```typescript
-import { isFaceFullyVisible, isFaceInOval, calculateFaceCropRegion } from '@moveris/shared';
+import {
+  isFaceFullyVisible,
+  isFaceInOval,
+  calculateFaceCropRegion,
+  detectFaceRoll,
+  detectCameraAngle,
+} from '@moveris/shared';
 
 // Check if face is fully visible in frame
 const visibility = isFaceFullyVisible(faceBbox, frameWidth, frameHeight);
@@ -547,8 +557,17 @@ const cropRegion = calculateFaceCropRegion(faceBbox, frameWidth, frameHeight);
 
 // Calculate adaptive crop multiplier based on face size
 import { calculateAdaptiveCropMultiplier } from '@moveris/shared';
-const multiplier = calculateAdaptiveCropMultiplier(faceSize, videoSize);
-// Returns 1.8–2.5x (matched to cognito-check for ~50% face coverage)
+const multiplier = calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight);
+// Returns 2.5–4.0x (matched to cognito-check for ~33% face coverage in 224×224 crop)
+
+// Detect face roll (device tilt) from eye-corner landmarks
+const rollResult = detectFaceRoll(landmarks); // requires ≥364 landmarks
+// { roll: number (degrees), tooTilted: boolean }
+
+// Detect camera vertical angle from forehead/nose/chin landmark ratio
+const angleResult = detectCameraAngle(landmarks); // requires ≥153 landmarks
+// { ratio: number, cameraAbove: boolean, cameraBelow: boolean }
+// ratio ~1.0 at eye level; >1.35 = camera above user; <0.75 = camera below user
 ```
 
 #### Crop Constants (aligned with cognito-check)

package/dist/index.d.mts

@@ -301,7 +301,7 @@ interface FrameQualityResult {
     alignment?: FaceAlignmentResult;
     rejectionReason?: 'blur' | 'backlit' | 'low_light' | 'partial_face' | 'no_face' | 'too_close' | 'too_far' | 'misaligned';
 }
-declare const DEFAULT_BLUR_THRESHOLD = 100;
+declare const DEFAULT_BLUR_THRESHOLD = 110;
 declare const BLUR_THRESHOLD_MOBILE = 60;
 declare const BACKLIT_RATIO_THRESHOLD = 0.6;
 declare const LOW_LIGHT_THRESHOLD = 50;
@@ -353,6 +353,14 @@ interface FaceRollResult {
 }
 declare const MAX_FACE_ROLL_DEGREES = 15;
 declare function detectFaceRoll(landmarks: FaceLandmarkPoint[]): FaceRollResult;
+interface CameraAngleResult {
+    ratio: number;
+    cameraAbove: boolean;
+    cameraBelow: boolean;
+}
+declare const CAMERA_ANGLE_HIGH_RATIO = 1.35;
+declare const CAMERA_ANGLE_LOW_RATIO = 0.75;
+declare function detectCameraAngle(landmarks: FaceLandmarkPoint[]): CameraAngleResult;
 declare class BaseFrameCollector {
     protected frames: CapturedFrame[];
     protected maxFrames: number;
@@ -489,6 +497,7 @@ declare class LivenessClient {
         model?: FastCheckModel;
         source?: FrameSource;
         warnings?: string[];
+        bgSegmentation?: boolean;
     }): Promise<LivenessResult>;
     streamFrame(frame: CapturedFrame, options: {
         sessionId: string;
@@ -704,8 +713,9 @@ declare const FEEDBACK_MESSAGES: {
     readonly poor_lighting: "Improve lighting";
     readonly too_dark: "Low lighting - move to a brighter area";
     readonly backlit: "Backlit - try facing the light source";
-    readonly phone_angle_low: "Raise your phone to eye level";
-    readonly phone_tilted: "Hold your phone level";
+    readonly camera_angle_low: "Raise camera to eye level";
+    readonly camera_angle_high: "Lower camera to eye level";
+    readonly camera_tilted: "Hold camera level";
     readonly hand_detected: "Remove hand from face";
     readonly eyes_not_visible: "Eyes not clearly visible";
     readonly eyes_shadowed: "Eyes are in shadow - improve lighting";
@@ -738,8 +748,9 @@ interface CaptureQualityState {
     targetFrames: number;
     tooFarFromIdeal?: boolean;
     tooCloseToIdeal?: boolean;
-    phoneAngled?: boolean;
-    phoneTilted?: boolean;
+    cameraAngleLow?: boolean;
+    cameraAngleHigh?: boolean;
+    cameraTilted?: boolean;
 }
 declare function getCaptureQualityFeedback(state: CaptureQualityState): string;
 declare function canCaptureFrame(state: Omit<CaptureQualityState, 'framesCaptured' | 'targetFrames' | 'isCapturing'>): boolean;
@@ -790,4 +801,4 @@ declare function analyzeEyeRegionContrast(pixels: Uint8Array | Uint8ClampedArray
 declare function detectSpecularHighlights(pixels: Uint8Array | Uint8ClampedArray, relativeFactor?: number, meanBrightness?: number): number;
 declare function checkEyeRegionQuality(pixels: Uint8Array | Uint8ClampedArray, thresholds?: EyeQualityThresholds): EyeRegionQuality;
 
-export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceRollResult, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, decodeBase64, detectFaceRoll, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceRollResult, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, decodeBase64, detectCameraAngle, detectFaceRoll, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.d.ts

@@ -301,7 +301,7 @@ interface FrameQualityResult {
     alignment?: FaceAlignmentResult;
     rejectionReason?: 'blur' | 'backlit' | 'low_light' | 'partial_face' | 'no_face' | 'too_close' | 'too_far' | 'misaligned';
 }
-declare const DEFAULT_BLUR_THRESHOLD = 100;
+declare const DEFAULT_BLUR_THRESHOLD = 110;
 declare const BLUR_THRESHOLD_MOBILE = 60;
 declare const BACKLIT_RATIO_THRESHOLD = 0.6;
 declare const LOW_LIGHT_THRESHOLD = 50;
@@ -353,6 +353,14 @@ interface FaceRollResult {
 }
 declare const MAX_FACE_ROLL_DEGREES = 15;
 declare function detectFaceRoll(landmarks: FaceLandmarkPoint[]): FaceRollResult;
+interface CameraAngleResult {
+    ratio: number;
+    cameraAbove: boolean;
+    cameraBelow: boolean;
+}
+declare const CAMERA_ANGLE_HIGH_RATIO = 1.35;
+declare const CAMERA_ANGLE_LOW_RATIO = 0.75;
+declare function detectCameraAngle(landmarks: FaceLandmarkPoint[]): CameraAngleResult;
 declare class BaseFrameCollector {
     protected frames: CapturedFrame[];
     protected maxFrames: number;
@@ -489,6 +497,7 @@ declare class LivenessClient {
         model?: FastCheckModel;
         source?: FrameSource;
         warnings?: string[];
+        bgSegmentation?: boolean;
     }): Promise<LivenessResult>;
     streamFrame(frame: CapturedFrame, options: {
         sessionId: string;
@@ -704,8 +713,9 @@ declare const FEEDBACK_MESSAGES: {
     readonly poor_lighting: "Improve lighting";
     readonly too_dark: "Low lighting - move to a brighter area";
     readonly backlit: "Backlit - try facing the light source";
-    readonly phone_angle_low: "Raise your phone to eye level";
-    readonly phone_tilted: "Hold your phone level";
+    readonly camera_angle_low: "Raise camera to eye level";
+    readonly camera_angle_high: "Lower camera to eye level";
+    readonly camera_tilted: "Hold camera level";
     readonly hand_detected: "Remove hand from face";
     readonly eyes_not_visible: "Eyes not clearly visible";
     readonly eyes_shadowed: "Eyes are in shadow - improve lighting";
@@ -738,8 +748,9 @@ interface CaptureQualityState {
     targetFrames: number;
     tooFarFromIdeal?: boolean;
     tooCloseToIdeal?: boolean;
-    phoneAngled?: boolean;
-    phoneTilted?: boolean;
+    cameraAngleLow?: boolean;
+    cameraAngleHigh?: boolean;
+    cameraTilted?: boolean;
 }
 declare function getCaptureQualityFeedback(state: CaptureQualityState): string;
 declare function canCaptureFrame(state: Omit<CaptureQualityState, 'framesCaptured' | 'targetFrames' | 'isCapturing'>): boolean;
@@ -790,4 +801,4 @@ declare function analyzeEyeRegionContrast(pixels: Uint8Array | Uint8ClampedArray
 declare function detectSpecularHighlights(pixels: Uint8Array | Uint8ClampedArray, relativeFactor?: number, meanBrightness?: number): number;
 declare function checkEyeRegionQuality(pixels: Uint8Array | Uint8ClampedArray, thresholds?: EyeQualityThresholds): EyeRegionQuality;
 
-export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceRollResult, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, decodeBase64, detectFaceRoll, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceRollResult, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, decodeBase64, detectCameraAngle, detectFaceRoll, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.js

@@ -31,6 +31,8 @@ __export(index_exports, {
   BACKLIT_RATIO_THRESHOLD: () => BACKLIT_RATIO_THRESHOLD,
   BLUR_THRESHOLD_MOBILE: () => BLUR_THRESHOLD_MOBILE,
   BaseFrameCollector: () => BaseFrameCollector,
+  CAMERA_ANGLE_HIGH_RATIO: () => CAMERA_ANGLE_HIGH_RATIO,
+  CAMERA_ANGLE_LOW_RATIO: () => CAMERA_ANGLE_LOW_RATIO,
   DEFAULT_BLUR_THRESHOLD: () => DEFAULT_BLUR_THRESHOLD,
   DEFAULT_ENDPOINT: () => DEFAULT_ENDPOINT,
   DEFAULT_FACE_DETECTION_TIERS: () => DEFAULT_FACE_DETECTION_TIERS,
@@ -95,6 +97,7 @@ __export(index_exports, {
   checkEyeRegionQuality: () => checkEyeRegionQuality,
   checkFrameQuality: () => checkFrameQuality,
   decodeBase64: () => decodeBase64,
+  detectCameraAngle: () => detectCameraAngle,
   detectFaceRoll: () => detectFaceRoll,
   detectSpecularHighlights: () => detectSpecularHighlights,
   encodeBase64: () => encodeBase64,
@@ -481,7 +484,8 @@ var LivenessClient = class _LivenessClient {
       model: options.model ?? "10",
       source: options.source ?? "live",
       crops,
-      ...options.warnings?.length ? { warnings: options.warnings } : {}
+      ...options.warnings?.length ? { warnings: options.warnings } : {},
+      ...options.bgSegmentation !== void 0 ? { bg_segmentation: options.bgSegmentation } : {}
     };
     const response = await this.requestWithRetry(API_PATHS.fastCheckCrops, {
       method: "POST",
@@ -1254,9 +1258,10 @@ var FEEDBACK_MESSAGES = {
   poor_lighting: "Improve lighting",
   too_dark: "Low lighting - move to a brighter area",
   backlit: "Backlit - try facing the light source",
-  // Phone orientation
-  phone_angle_low: "Raise your phone to eye level",
-  phone_tilted: "Hold your phone level",
+  // Camera angle (platform-agnostic)
+  camera_angle_low: "Raise camera to eye level",
+  camera_angle_high: "Lower camera to eye level",
+  camera_tilted: "Hold camera level",
   // Hand occlusion
   hand_detected: "Remove hand from face",
   // Eye region quality
@@ -1316,9 +1321,10 @@ var ES_LOCALE = {
     poor_lighting: "Mejora la iluminaci\xF3n",
     too_dark: "Poca luz - mu\xE9vete a un \xE1rea m\xE1s iluminada",
     backlit: "Contraluz - intenta mirar hacia la fuente de luz",
-    // Phone orientation
-    phone_angle_low: "Levanta el tel\xE9fono a la altura de los ojos",
-    phone_tilted: "Mant\xE9n el tel\xE9fono nivelado",
+    // Camera angle (platform-agnostic)
+    camera_angle_low: "Levanta la c\xE1mara a la altura de los ojos",
+    camera_angle_high: "Baja la c\xE1mara a la altura de los ojos",
+    camera_tilted: "Mant\xE9n la c\xE1mara nivelada",
     // Hand occlusion
     hand_detected: "Retira la mano del rostro",
     // Eye region quality
@@ -1354,17 +1360,21 @@ function getCaptureQualityFeedback(state) {
     targetFrames,
     tooFarFromIdeal,
     tooCloseToIdeal,
-    phoneAngled,
-    phoneTilted
+    cameraAngleLow,
+    cameraAngleHigh,
+    cameraTilted
   } = state;
   if (!hasFace) {
     return FEEDBACK_MESSAGES.no_face;
   }
-  if (phoneTilted) {
-    return FEEDBACK_MESSAGES.phone_tilted;
+  if (cameraTilted) {
+    return FEEDBACK_MESSAGES.camera_tilted;
+  }
+  if (cameraAngleLow) {
+    return FEEDBACK_MESSAGES.camera_angle_low;
   }
-  if (phoneAngled) {
-    return FEEDBACK_MESSAGES.phone_angle_low;
+  if (cameraAngleHigh) {
+    return FEEDBACK_MESSAGES.camera_angle_high;
   }
   if (tooClose) {
     return FEEDBACK_MESSAGES.too_close;
@@ -1408,10 +1418,11 @@ function canCaptureFrame(state) {
     isPartialFace,
     tooFarFromIdeal,
     tooCloseToIdeal,
-    phoneAngled,
-    phoneTilted
+    cameraAngleLow,
+    cameraAngleHigh,
+    cameraTilted
   } = state;
-  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace && !tooFarFromIdeal && !tooCloseToIdeal && !phoneAngled && !phoneTilted;
+  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace && !tooFarFromIdeal && !tooCloseToIdeal && !cameraAngleLow && !cameraAngleHigh && !cameraTilted;
 }
 
 // src/utils/validators.ts
@@ -1478,7 +1489,7 @@ function decodeBase64(base64) {
 }
 
 // src/utils/frameAnalysis.ts
-var DEFAULT_BLUR_THRESHOLD = 100;
+var DEFAULT_BLUR_THRESHOLD = 110;
 var BLUR_THRESHOLD_MOBILE = 60;
 var BACKLIT_RATIO_THRESHOLD = 0.6;
 var LOW_LIGHT_THRESHOLD = 50;
@@ -1779,6 +1790,30 @@ function detectFaceRoll(landmarks) {
     tooTilted: roll > MAX_FACE_ROLL_DEGREES
   };
 }
+var CAMERA_ANGLE_HIGH_RATIO = 1.35;
+var CAMERA_ANGLE_LOW_RATIO = 0.75;
+function detectCameraAngle(landmarks) {
+  if (landmarks.length < 153) {
+    return { ratio: 1, cameraAbove: false, cameraBelow: false };
+  }
+  const forehead = landmarks[10];
+  const noseTip = landmarks[1];
+  const chin = landmarks[152];
+  if (!forehead || !noseTip || !chin) {
+    return { ratio: 1, cameraAbove: false, cameraBelow: false };
+  }
+  const foreheadToNose = Math.abs(forehead.y - noseTip.y);
+  const noseToChin = Math.abs(noseTip.y - chin.y);
+  if (noseToChin < 1e-3) {
+    return { ratio: 1, cameraAbove: false, cameraBelow: false };
+  }
+  const ratio = foreheadToNose / noseToChin;
+  return {
+    ratio,
+    cameraAbove: ratio > CAMERA_ANGLE_HIGH_RATIO,
+    cameraBelow: ratio < CAMERA_ANGLE_LOW_RATIO
+  };
+}
 var BaseFrameCollector = class {
   constructor(maxFrames = 10) {
     this.frames = [];
@@ -1996,6 +2031,8 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   BACKLIT_RATIO_THRESHOLD,
   BLUR_THRESHOLD_MOBILE,
   BaseFrameCollector,
+  CAMERA_ANGLE_HIGH_RATIO,
+  CAMERA_ANGLE_LOW_RATIO,
   DEFAULT_BLUR_THRESHOLD,
   DEFAULT_ENDPOINT,
   DEFAULT_FACE_DETECTION_TIERS,
@@ -2060,6 +2097,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   checkEyeRegionQuality,
   checkFrameQuality,
   decodeBase64,
+  detectCameraAngle,
   detectFaceRoll,
   detectSpecularHighlights,
   encodeBase64,

package/dist/index.mjs

@@ -348,7 +348,8 @@ var LivenessClient = class _LivenessClient {
       model: options.model ?? "10",
       source: options.source ?? "live",
       crops,
-      ...options.warnings?.length ? { warnings: options.warnings } : {}
+      ...options.warnings?.length ? { warnings: options.warnings } : {},
+      ...options.bgSegmentation !== void 0 ? { bg_segmentation: options.bgSegmentation } : {}
     };
     const response = await this.requestWithRetry(API_PATHS.fastCheckCrops, {
       method: "POST",
@@ -1121,9 +1122,10 @@ var FEEDBACK_MESSAGES = {
   poor_lighting: "Improve lighting",
   too_dark: "Low lighting - move to a brighter area",
   backlit: "Backlit - try facing the light source",
-  // Phone orientation
-  phone_angle_low: "Raise your phone to eye level",
-  phone_tilted: "Hold your phone level",
+  // Camera angle (platform-agnostic)
+  camera_angle_low: "Raise camera to eye level",
+  camera_angle_high: "Lower camera to eye level",
+  camera_tilted: "Hold camera level",
   // Hand occlusion
   hand_detected: "Remove hand from face",
   // Eye region quality
@@ -1183,9 +1185,10 @@ var ES_LOCALE = {
     poor_lighting: "Mejora la iluminaci\xF3n",
     too_dark: "Poca luz - mu\xE9vete a un \xE1rea m\xE1s iluminada",
     backlit: "Contraluz - intenta mirar hacia la fuente de luz",
-    // Phone orientation
-    phone_angle_low: "Levanta el tel\xE9fono a la altura de los ojos",
-    phone_tilted: "Mant\xE9n el tel\xE9fono nivelado",
+    // Camera angle (platform-agnostic)
+    camera_angle_low: "Levanta la c\xE1mara a la altura de los ojos",
+    camera_angle_high: "Baja la c\xE1mara a la altura de los ojos",
+    camera_tilted: "Mant\xE9n la c\xE1mara nivelada",
     // Hand occlusion
     hand_detected: "Retira la mano del rostro",
     // Eye region quality
@@ -1221,17 +1224,21 @@ function getCaptureQualityFeedback(state) {
     targetFrames,
     tooFarFromIdeal,
     tooCloseToIdeal,
-    phoneAngled,
-    phoneTilted
+    cameraAngleLow,
+    cameraAngleHigh,
+    cameraTilted
   } = state;
   if (!hasFace) {
     return FEEDBACK_MESSAGES.no_face;
   }
-  if (phoneTilted) {
-    return FEEDBACK_MESSAGES.phone_tilted;
+  if (cameraTilted) {
+    return FEEDBACK_MESSAGES.camera_tilted;
+  }
+  if (cameraAngleLow) {
+    return FEEDBACK_MESSAGES.camera_angle_low;
   }
-  if (phoneAngled) {
-    return FEEDBACK_MESSAGES.phone_angle_low;
+  if (cameraAngleHigh) {
+    return FEEDBACK_MESSAGES.camera_angle_high;
   }
   if (tooClose) {
     return FEEDBACK_MESSAGES.too_close;
@@ -1275,10 +1282,11 @@ function canCaptureFrame(state) {
     isPartialFace,
     tooFarFromIdeal,
     tooCloseToIdeal,
-    phoneAngled,
-    phoneTilted
+    cameraAngleLow,
+    cameraAngleHigh,
+    cameraTilted
   } = state;
-  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace && !tooFarFromIdeal && !tooCloseToIdeal && !phoneAngled && !phoneTilted;
+  return hasFace && alignment >= ALIGNMENT_THRESHOLD_CAPTURE && !tooClose && !tooFar && !isBlurry && !isPartialFace && !tooFarFromIdeal && !tooCloseToIdeal && !cameraAngleLow && !cameraAngleHigh && !cameraTilted;
 }
 
 // src/utils/validators.ts
@@ -1345,7 +1353,7 @@ function decodeBase64(base64) {
 }
 
 // src/utils/frameAnalysis.ts
-var DEFAULT_BLUR_THRESHOLD = 100;
+var DEFAULT_BLUR_THRESHOLD = 110;
 var BLUR_THRESHOLD_MOBILE = 60;
 var BACKLIT_RATIO_THRESHOLD = 0.6;
 var LOW_LIGHT_THRESHOLD = 50;
@@ -1646,6 +1654,30 @@ function detectFaceRoll(landmarks) {
     tooTilted: roll > MAX_FACE_ROLL_DEGREES
   };
 }
+var CAMERA_ANGLE_HIGH_RATIO = 1.35;
+var CAMERA_ANGLE_LOW_RATIO = 0.75;
+function detectCameraAngle(landmarks) {
+  if (landmarks.length < 153) {
+    return { ratio: 1, cameraAbove: false, cameraBelow: false };
+  }
+  const forehead = landmarks[10];
+  const noseTip = landmarks[1];
+  const chin = landmarks[152];
+  if (!forehead || !noseTip || !chin) {
+    return { ratio: 1, cameraAbove: false, cameraBelow: false };
+  }
+  const foreheadToNose = Math.abs(forehead.y - noseTip.y);
+  const noseToChin = Math.abs(noseTip.y - chin.y);
+  if (noseToChin < 1e-3) {
+    return { ratio: 1, cameraAbove: false, cameraBelow: false };
+  }
+  const ratio = foreheadToNose / noseToChin;
+  return {
+    ratio,
+    cameraAbove: ratio > CAMERA_ANGLE_HIGH_RATIO,
+    cameraBelow: ratio < CAMERA_ANGLE_LOW_RATIO
+  };
+}
 var BaseFrameCollector = class {
   constructor(maxFrames = 10) {
     this.frames = [];
@@ -1862,6 +1894,8 @@ export {
   BACKLIT_RATIO_THRESHOLD,
   BLUR_THRESHOLD_MOBILE,
   BaseFrameCollector,
+  CAMERA_ANGLE_HIGH_RATIO,
+  CAMERA_ANGLE_LOW_RATIO,
   DEFAULT_BLUR_THRESHOLD,
   DEFAULT_ENDPOINT,
   DEFAULT_FACE_DETECTION_TIERS,
@@ -1926,6 +1960,7 @@ export {
   checkEyeRegionQuality,
   checkFrameQuality,
   decodeBase64,
+  detectCameraAngle,
   detectFaceRoll,
   detectSpecularHighlights,
   encodeBase64,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moveris/shared",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "Core business logic for Moveris Live SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",