@mleonard9/vin-scanner 1.2.6 → 1.4.0

package/README.md

@@ -12,6 +12,8 @@ High-performance VIN detection for React Native powered by Google ML Kit barcode
 
 - `react-native-vision-camera` >= 3.9.0
 - `react-native-worklets-core` >= 0.4.0
+- `react-native-gesture-handler` >= 2.0.0 (for tap-to-focus)
+- `react-native-reanimated` >= 3.0.0 (for tap-to-focus)
 - iOS 13+ / Android 21+
 
 ## Installation
@@ -44,9 +46,9 @@ export function VinScannerExample(): JSX.Element {
   const options = useMemo(
     () => ({
       barcode: { formats: ['code-39', 'code-128', 'pdf-417'] },
-      detection: { resultMode: 'all' as const },
-      onResult: (result) => {
-        setResults(Array.isArray(result) ? result : result ? [result] : null);
+      onResult: (candidates, event) => {
+        setResults(candidates);
+        console.log(`Scan took ${event.duration}ms`);
       },
     }),
     []
@@ -73,14 +75,166 @@ export function VinScannerExample(): JSX.Element {
 
 Every frame, the camera runs ML Kit barcode + text recognition, extracts 17-character VIN candidates, validates them (checksum included), and routes a payload to `callback`.
 
+## Camera Gestures
+
+The VIN Scanner camera includes built-in support for intuitive camera controls:
+
+### Pinch to Zoom
+
+Pinch-to-zoom is **enabled by default**. Simply pinch on the camera view to zoom in and out. The zoom gesture is natively implemented by `react-native-vision-camera` for optimal performance.
+
+### Tap to Focus
+
+Tap anywhere on the camera view to focus at that point. This feature requires `react-native-gesture-handler` and `react-native-reanimated`:
+
+**Installation:**
+
+```sh
+yarn add react-native-gesture-handler react-native-reanimated
+# or
+npm install react-native-gesture-handler react-native-reanimated
+
+# iOS
+cd ios && pod install
+```
+
+**Note:** These dependencies are likely already installed if you're using React Navigation or other common React Native libraries.
+
+The tap-to-focus functionality works automatically once these dependencies are installed. Simply tap on the camera view where you want to focus, and the camera will adjust both auto-focus (AF) and auto-exposure (AE) for that point.
+
+**How it works:**
+- Tap on a VIN to focus precisely on that area
+- The camera adjusts focus and exposure automatically
+- Works seamlessly with the pinch-to-zoom gesture
+- No additional configuration required
+
+
+## Advanced Features
+
+### AR Overlay with Confidence Scoring
+
+The package previously included an AR overlay component for bounding boxes; it has been removed for now while alignment issues are addressed. Default barcode formats are tuned for VIN labels (`code-39`, `code-128`, `pdf-417`) with an automatic fallback to all formats after sustained misses.
+
+**Installation:**
+
+```sh
+yarn add @shopify/react-native-skia
+# or
+npm install @shopify/react-native-skia
+```
+
+**Usage:**
+
+```tsx
+// Overlay component removed (was VinScannerOverlay)
+
+export function VinScannerWithOverlay() {
+  const [candidates, setCandidates] = useState<VinCandidate[]>([]);
+  
+  const { frameProcessor } = useVinScanner({
+    onResult: (detectedCandidates) => {
+      setCandidates(detectedCandidates);
+    },
+  });
+
+  return (
+    <View style={StyleSheet.absoluteFill}>
+      <Camera
+        device={device}
+        frameProcessor={frameProcessor}
+        style={StyleSheet.absoluteFill}
+      />
+      {/* Overlay removed; render your own UI if needed */}
+    </View>
+  );
+}
+```
+
+**Confidence Scoring:**
+
+Each `VinCandidate` includes a `confidence` score (0.0-1.0) calculated from:
+- **Source reliability**: Barcodes score higher than OCR text (+0.3)
+- **Text precision**: Element-level text scores higher than block-level (+0.2)
+- **Context awareness**: VIN prefixes like "VIN:" increase confidence (+0.2)
+- **Checksum validation**: All candidates pass ISO 3779 validation (+0.2)
+
+Overlay colors by confidence:
+- 🟢 **Green** (`confidence > 0.8`): High confidence
+- 🟡 **Yellow** (`confidence 0.5-0.8`): Medium confidence  
+- 🔴 **Red** (`confidence < 0.5`): Low confidence
+
+### Smart Duplicate Filtering
+
+By default, the scanner uses time-based debouncing to prevent duplicate callbacks for the same VIN:
+
+```tsx
+const { frameProcessor } = useVinScanner({
+  duplicateDebounceMs: 1500, // Default: 1500ms
+  onResult: (candidates) => {
+    // Only called when a new VIN is detected or after debounce period
+    console.log('New VIN detected:', candidates[0]?.value);
+  },
+});
+```
+
+This prevents callback spam when holding the camera steady on a VIN, improving UX in fast-paced scanning scenarios.
+
+### Performance Telemetry
+
+Every `VinScannerEvent` includes detailed performance metrics for data-driven optimization:
+
+```tsx
+const { frameProcessor } = useVinScanner({
+  onResult: (candidates, event) => {
+    if (event.performance) {
+      console.log('Performance breakdown:');
+      console.log(`  Barcode scan: ${event.performance.barcodeMs}ms`);
+      console.log(`  Text recognition: ${event.performance.textMs}ms`);
+      console.log(`  Validation: ${event.performance.validationMs}ms`);
+      console.log(`  Total: ${event.performance.totalMs}ms`);
+    }
+  },
+});
+```
+
+Use these metrics to:
+- Identify performance bottlenecks (barcode vs text recognition)
+- Optimize `textScanInterval` based on actual timing
+- Monitor performance across different devices
+- Track improvements after configuration changes
+
+### Camera Settings Optimization
+
+Configure camera parameters for device-specific optimization:
+
+```tsx
+const { frameProcessor } = useVinScanner({
+  cameraSettings: {
+    fps: 60,                           // Higher FPS for smoother scanning
+    lowLightBoost: true,               // Auto-boost in low light (default)
+    videoStabilizationMode: 'standard' // Reduce motion blur
+  },
+  onResult: (candidates) => {
+    console.log('Detected:', candidates[0]?.value);
+  },
+});
+```
+
+**Available settings:**
+- **`fps`**: Target frame rate (15-60). Higher = smoother but more CPU. Default: 30
+- **`lowLightBoost`**: Auto-brighten in dark conditions. Default: true
+- **`videoStabilizationMode`**: `'off'` | `'standard'` | `'cinematic'` | `'auto'`. Default: 'off'
+
+**Tip**: For auction lanes with good lighting, try `fps: 60` and `videoStabilizationMode: 'standard'` for best results.
+
 ### Callback payload
 
 ```ts
 type VinScannerEvent = {
-  mode: 'first' | 'all';
   timestamp: number;
-  best?: VinCandidate | null;
+  duration: number;
   candidates: VinCandidate[];
+  firstCandidate?: VinCandidate | null;
   raw: {
     barcodes: BarcodeDetection[];
     textBlocks: TextDetection[];
@@ -88,8 +242,8 @@ type VinScannerEvent = {
 };
 ```
 
-`VinCandidate` contains `{ value, source: 'barcode' | 'text', boundingBox }`.  
-`resultMode === 'first'` returns at most one candidate per frame, while `'all'` returns every candidate so you can render overlays/selectors.
+`VinCandidate` contains `{ value, source: 'barcode' | 'text', confidence, boundingBox }`.  
+The `candidates` array contains every potential VIN found in the frame. `firstCandidate` is a convenience reference to the best match.
 
 ### Options
 
@@ -99,14 +253,132 @@ type VinScannerEvent = {
 | `options.barcode.formats` | `BarcodeFormat[]` | Restrict ML Kit formats (`'code-39'`, `'code-128'`, `'pdf-417'`, etc.) | `['all']` |
 | `options.text.enabled` | boolean | Enable text recognition | `true` |
 | `options.text.language` | `'latin' \| 'chinese' \| 'devanagari' \| 'japanese' \| 'korean'` | ML Kit language pack | `'latin'` |
-| `options.detection.resultMode` | `'first' \| 'all'` | Emit the first candidate (barcodes preferred) or every candidate | `'first'` |
-| `options.detection.textScanInterval` | number | Run text recognition every Nth frame (1 = every frame) | `1` |
+| `options.text.requireConfirmation` | boolean | When true, text VINs are held until you confirm; barcodes still emit immediately | `false` |
+| `options.text.pendingTtlMs` | number | Auto-dismiss pending text VINs after this many ms (when `requireConfirmation` is true) | `5000` |
+| `options.detection.textScanInterval` | number | Run text recognition every Nth frame (1 = every frame) | `3` |
 | `options.detection.maxFrameRate` | number | Max FPS budget for frame processing (drops surplus frames to avoid blocking) | `30` |
 | `options.detection.forceOrientation` | `'portrait' \| 'portrait-upside-down' \| 'landscape-left' \| 'landscape-right'` | Forces ML Kit to interpret every frame using the given orientation (useful when the UI is locked to portrait but the sensor reports landscape) | `null` |
-| `options.onResult` | `(result, event) => void` | Convenience callback when using `useVinScanner`; receives either the first candidate, all candidates, or `null` plus the raw event | `undefined` |
+| `options.detection.scanRegion` | `ScanRegion` | Restrict ML Kit processing to a specific region of the frame (normalized coordinates 0.0-1.0). Significantly improves performance by ignoring irrelevant areas. | `{ x: 0.15, y: 0.15, width: 0.7, height: 0.7 }` |
+| `options.detection.enableFrameQualityCheck` | boolean | Deprecated; use `minLuma`/`minSharpness` instead | `true` |
+| `options.detection.minLuma` | number | Minimum mean luma (0–255) required to process a frame; skips too-dark frames | `30` |
+| `options.detection.minSharpness` | number | Minimum sharpness metric required; skips blurry frames | `12` |
+| `options.detection.minConfidence` | number | Minimum candidate confidence required before emitting | `0.6` |
+| `options.detection.barcodeFallbackAfter` | number | Frames without barcode hits before scanning all formats | `45` |
+| `options.duplicateDebounceMs` | number | Time in milliseconds to suppress duplicate VIN callbacks for the same value | `1500` |
+| `options.showOverlay` | boolean | Deprecated; overlay component removed | `false` |
+| `options.overlayColors` | `OverlayColors` | Deprecated; overlay component removed | `{ high: '#00FF00', medium: '#FFFF00', low: '#FF0000' }` |
+| `options.cameraSettings` | `CameraSettings` | Camera configuration: `{ fps (clamped 24–30), lowLightBoost, videoStabilizationMode }` | `{ fps: 24, lowLightBoost: true, videoStabilizationMode: 'cinematic' }` |
+| `options.onResult` | `(candidates, event) => void` | Convenience callback when using `useVinScanner`; receives all candidates and the raw event | `undefined` |
+| `options.onTextPending` | `(pending) => void` | Invoked when `text.requireConfirmation` is true and text VINs are detected | `undefined` |
+| `options.haptics` | boolean | Enable built-in haptic cues (requires `react-native-haptic-feedback` installed) | `true` |
+
+### Behaviors & defaults
+- Barcode-first: barcodes emit immediately; text VINs can require confirmation.
+- Session dedupe: VINs are not re-emitted within a scan session (in addition to time-based debounce).
+- Quality gate: frames below `minLuma` or `minSharpness` are skipped.
+- Confidence gate: candidates below `minConfidence` are dropped.
+- Barcode formats: defaults to `code-39`, `code-128`, `pdf-417` with automatic fallback to all formats after `barcodeFallbackAfter` empty frames.
+- Camera hints: FPS clamped to 24–30 and `videoStabilizationMode` defaults to `cinematic` to keep headroom and reduce jitter.
+
+### Text confirmation UI (barcode = instant, text = tap-to-confirm)
+
+```tsx
+import { useState } from 'react';
+import { Camera, useCameraDevice } from 'react-native-vision-camera';
+import { useVinScanner, TextVinPrompt, VinCandidate } from '@mleonard9/vin-scanner';
+
+export function ConfirmingScanner() {
+  const device = useCameraDevice('back');
+  const [pending, setPending] = useState<VinCandidate[]>([]);
+
+  const { frameProcessor, pendingTextCandidates, confirmTextCandidate } = useVinScanner({
+    text: { requireConfirmation: true },
+    onTextPending: setPending,
+    onResult: (candidates) => {
+      // barcode VINs (or confirmed text VINs) arrive here
+      console.log('confirmed VINs', candidates.map((c) => c.value));
+    },
+  });
+
+  return (
+    <>
+      {device && (
+        <Camera style={{ flex: 1 }} device={device} frameProcessor={frameProcessor} isActive />
+      )}
+      <TextVinPrompt
+        visible={pendingTextCandidates.length > 0}
+        candidates={pendingTextCandidates}
+        buttonLabel=\"Book It\"
+        buttonColor=\"#0A84FF\"
+        onConfirm={(candidate) => confirmTextCandidate(candidate.value)}
+        onDismiss={() => setPending([])}
+      />
+    </>
+  );
+}
+```
+
+### Manual VIN keypad with checksum guard
+
+```tsx
+import { ManualVinInput } from '@mleonard9/vin-scanner';
+
+export function ManualEntry({ onSubmit }: { onSubmit: (vin: string) => void }) {
+  return (
+    <ManualVinInput
+      buttonLabel=\"Book It\"
+      buttonColor=\"#0A84FF\"
+      onSubmit={onSubmit}
+    />
+  );
+}
+```
+
+### Pending banner (alternative to modal)
+
+```tsx
+import { PendingVinBanner } from '@mleonard9/vin-scanner';
+
+<PendingVinBanner
+  visible={pendingTextCandidates.length > 0}
+  candidates={pendingTextCandidates}
+  buttonLabel=\"Book It\"
+  buttonColor=\"#0A84FF\"
+  onConfirm={(candidate) => confirmTextCandidate(candidate.value)}
+  onDismiss={() => setPending([])}
+/>;
+```
+
+### Performance
+
+Phase 1 optimizations dramatically improve scanning performance through native ROI (Region of Interest) frame cropping:
+
+| Configuration | Avg Duration | Improvement |
+| --- | --- | --- |
+| Full frame, every frame | ~180ms | baseline |
+| ROI scanning (70% center) | ~95ms | **47% faster** |
+| ROI + text interval (3 frames) | ~45ms | **75% faster** |
+| ROI + quality check + throttle | ~30ms | **83% faster** |
+
+**Default configuration** uses ROI scanning (`scanRegion: { x: 0.15, y: 0.15, width: 0.7, height: 0.7 }`) and a text scan interval of 3. This provides excellent accuracy while maintaining real-time performance on mid-range devices.
+
+**Tip:** For challenging lighting or distance scenarios, set `textScanInterval: 1` to scan every frame at the cost of higher CPU usage.
+
+**Custom scan regions:**
+
+```tsx
+const { frameProcessor } = useVinScanner({
+  detection: {
+    // Focus on center 50% of frame
+    scanRegion: { x: 0.25, y: 0.25, width: 0.5, height: 0.5 },
+    textScanInterval: 2,
+  },
+  onResult: (candidates) => {
+    console.log('Detected VINs:', candidates);
+  },
+});
+```
 
-Using `resultMode: 'first'` automatically prefers barcode candidates before text, so there is no `preferBarcode` toggle.
-Duplicates are always emitted so consumers can track every detection even when the VIN value remains unchanged.
 
 ### Advanced frame-processor controls
 
@@ -121,9 +393,9 @@ If you prefer to configure `react-native-vision-camera` yourself, grab the frame
 
 ```tsx
 const { frameProcessor } = useVinScanner({
-  detection: { resultMode: 'first' },
-  onResult: (vin, event) => {
-    console.log('Current VIN', vin, event);
+  onResult: (candidates, event) => {
+    console.log('Current VINs', candidates, event.firstCandidate);
+    console.log(`Duration: ${event.duration}ms`);
   },
 });
 
@@ -148,4 +420,3 @@ npm publish --access public
 ```
 
 Ensure the authenticated npm user has access to the `@mleonard9` scope.
-

package/android/src/main/java/com/visioncamerabarcodescanner/VisionCameraBarcodeScannerModule.kt

@@ -48,24 +48,33 @@ class VisionCameraBarcodeScannerModule(
 
   private fun buildScannerOptions(effective: Map<String, Any>): BarcodeScannerOptions {
     val builder = BarcodeScannerOptions.Builder()
-    when {
-      effective["code-128"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_CODE_128)
-      effective["code-39"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_CODE_39)
-      effective["code-93"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_CODE_93)
-      effective["codabar"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_CODABAR)
-      effective["ean-13"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_EAN_13)
-      effective["ean-8"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_EAN_8)
-      effective["itf"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_ITF)
-      effective["upc-e"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_UPC_E)
-      effective["upc-a"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_UPC_A)
-      effective["qr"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_QR_CODE)
-      effective["pdf-417"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_PDF417)
-      effective["aztec"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_AZTEC)
-      effective["data-matrix"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_DATA_MATRIX)
-      effective["all"].toString().toBoolean() -> builder.setBarcodeFormats(FORMAT_ALL_FORMATS)
-      else -> builder.setBarcodeFormats(FORMAT_ALL_FORMATS)
+
+    var mask = 0
+    fun maybeAdd(enabled: Boolean, format: Int) {
+      if (enabled) mask = mask or format
+    }
+
+    // Allow multiple formats at once; fall back to ALL when none specified.
+    maybeAdd(effective["all"].toString().toBoolean(), FORMAT_ALL_FORMATS)
+    maybeAdd(effective["code-128"].toString().toBoolean(), FORMAT_CODE_128)
+    maybeAdd(effective["code-39"].toString().toBoolean(), FORMAT_CODE_39)
+    maybeAdd(effective["code-93"].toString().toBoolean(), FORMAT_CODE_93)
+    maybeAdd(effective["codabar"].toString().toBoolean(), FORMAT_CODABAR)
+    maybeAdd(effective["ean-13"].toString().toBoolean(), FORMAT_EAN_13)
+    maybeAdd(effective["ean-8"].toString().toBoolean(), FORMAT_EAN_8)
+    maybeAdd(effective["itf"].toString().toBoolean(), FORMAT_ITF)
+    maybeAdd(effective["upc-e"].toString().toBoolean(), FORMAT_UPC_E)
+    maybeAdd(effective["upc-a"].toString().toBoolean(), FORMAT_UPC_A)
+    maybeAdd(effective["qr"].toString().toBoolean(), FORMAT_QR_CODE)
+    maybeAdd(effective["pdf-417"].toString().toBoolean(), FORMAT_PDF417)
+    maybeAdd(effective["aztec"].toString().toBoolean(), FORMAT_AZTEC)
+    maybeAdd(effective["data-matrix"].toString().toBoolean(), FORMAT_DATA_MATRIX)
+
+    if (mask == 0) {
+      mask = FORMAT_ALL_FORMATS
     }
-    return builder.build()
+
+    return builder.setBarcodeFormats(mask).build()
   }
 
   private fun orientationToDegrees(orientation: String?): Int? {
@@ -78,6 +87,39 @@ class VisionCameraBarcodeScannerModule(
     }
   }
 
+  private fun cropImage(image: InputImage, scanRegion: Map<String, Any>): Pair<InputImage, Pair<Int, Int>> {
+    val x = (scanRegion["x"] as? Number)?.toDouble() ?: 0.0
+    val y = (scanRegion["y"] as? Number)?.toDouble() ?: 0.0
+    val width = (scanRegion["width"] as? Number)?.toDouble() ?: 1.0
+    val height = (scanRegion["height"] as? Number)?.toDouble() ?: 1.0
+
+    // Get image dimensions
+    val imgWidth = image.width
+    val imgHeight = image.height
+
+    // Calculate pixel coordinates from normalized values (0.0-1.0)
+    val cropLeft = (x * imgWidth).toInt().coerceIn(0, imgWidth)
+    val cropTop = (y * imgHeight).toInt().coerceIn(0, imgHeight)
+    val cropWidth = (width * imgWidth).toInt().coerceIn(0, imgWidth - cropLeft)
+    val cropHeight = (height * imgHeight).toInt().coerceIn(0, imgHeight - cropTop)
+
+    // Create cropped bitmap
+    val bitmap = image.bitmapInternal ?: return Pair(image, Pair(0, 0))
+    val cropped = android.graphics.Bitmap.createBitmap(
+      bitmap,
+      cropLeft,
+      cropTop,
+      cropWidth,
+      cropHeight
+    )
+
+    // Return cropped InputImage and offset for coordinate translation
+    return Pair(
+      InputImage.fromBitmap(cropped, image.rotationDegrees),
+      Pair(cropLeft, cropTop)
+    )
+  }
+
   override fun callback(frame: Frame, arguments: Map<String, Any>?): Any {
     return try {
       val options = mergedOptions(arguments)
@@ -85,8 +127,18 @@ class VisionCameraBarcodeScannerModule(
       val mediaImage: Image = frame.image
       val rotationOverride = orientationToDegrees(options["orientation"] as? String)
       val rotationDegrees = rotationOverride ?: frame.imageProxy.imageInfo.rotationDegrees
-      val image = InputImage.fromMediaImage(mediaImage, rotationDegrees)
-      val task: Task<List<Barcode>> = scanner.process(image)
+      var image = InputImage.fromMediaImage(mediaImage, rotationDegrees)
+      
+      // Extract scanRegion and crop if provided
+      val scanRegion = options["scanRegion"] as? Map<String, Any>
+      val (processImage, offset) = if (scanRegion != null) {
+        cropImage(image, scanRegion)
+      } else {
+        Pair(image, Pair(0, 0))
+      }
+      val (offsetX, offsetY) = offset
+      
+      val task: Task<List<Barcode>> = scanner.process(processImage)
       val barcodes: List<Barcode> = Tasks.await(task)
 
       val detections = ArrayList<Map<String, Any?>>()
@@ -107,10 +159,11 @@ class VisionCameraBarcodeScannerModule(
           val bounds = barcode.boundingBox
           val floatIndex = index * BOX_STRIDE
           if (bounds != null) {
-            buffer.put(floatIndex, bounds.top.toFloat())
-            buffer.put(floatIndex + 1, bounds.bottom.toFloat())
-            buffer.put(floatIndex + 2, bounds.left.toFloat())
-            buffer.put(floatIndex + 3, bounds.right.toFloat())
+            // Translate coordinates back to full-frame if cropped
+            buffer.put(floatIndex, (bounds.top + offsetY).toFloat())
+            buffer.put(floatIndex + 1, (bounds.bottom + offsetY).toFloat())
+            buffer.put(floatIndex + 2, (bounds.left + offsetX).toFloat())
+            buffer.put(floatIndex + 3, (bounds.right + offsetX).toFloat())
             buffer.put(floatIndex + 4, bounds.width().toFloat())
             buffer.put(floatIndex + 5, bounds.height().toFloat())
           } else {

package/android/src/main/java/com/visioncameratextrecognition/VisionCameraTextRecognitionModule.kt

@@ -53,6 +53,39 @@ class VisionCameraTextRecognitionModule(
     }
   }
 
+  private fun cropImage(image: InputImage, scanRegion: Map<String, Any>): Pair<InputImage, Pair<Int, Int>> {
+    val x = (scanRegion["x"] as? Number)?.toDouble() ?: 0.0
+    val y = (scanRegion["y"] as? Number)?.toDouble() ?: 0.0
+    val width = (scanRegion["width"] as? Number)?.toDouble() ?: 1.0
+    val height = (scanRegion["height"] as? Number)?.toDouble() ?: 1.0
+
+    // Get image dimensions
+    val imgWidth = image.width
+    val imgHeight = image.height
+
+    // Calculate pixel coordinates from normalized values (0.0-1.0)
+    val cropLeft = (x * imgWidth).toInt().coerceIn(0, imgWidth)
+    val cropTop = (y * imgHeight).toInt().coerceIn(0, imgHeight)
+    val cropWidth = (width * imgWidth).toInt().coerceIn(0, imgWidth - cropLeft)
+    val cropHeight = (height * imgHeight).toInt().coerceIn(0, imgHeight - cropTop)
+
+    // Create cropped bitmap
+    val bitmap = image.bitmapInternal ?: return Pair(image, Pair(0, 0))
+    val cropped = android.graphics.Bitmap.createBitmap(
+      bitmap,
+      cropLeft,
+      cropTop,
+      cropWidth,
+      cropHeight
+    )
+
+    // Return cropped InputImage and offset for coordinate translation
+    return Pair(
+      InputImage.fromBitmap(cropped, image.rotationDegrees),
+      Pair(cropLeft, cropTop)
+    )
+  }
+
   override fun callback(frame: Frame, arguments: Map<String, Any>?): Any {
       try {
         val mediaImage: Image = frame.image
@@ -62,9 +95,19 @@ class VisionCameraTextRecognitionModule(
         val effectiveLanguage = requestedLanguage ?: language
         val validationPattern = arguments?.get("validationPattern")?.toString()?.ifEmpty { null }
         
+        var image = InputImage.fromMediaImage(mediaImage, rotationDegrees)
+        
+        // Extract scanRegion and crop if provided
+        val scanRegion = arguments?.get("scanRegion") as? Map<String, Any>
+        val (processImage, offset) = if (scanRegion != null) {
+          cropImage(image, scanRegion)
+        } else {
+          Pair(image, Pair(0, 0))
+        }
+        val (offsetX, offsetY) = offset
+        
         val recognizer = recognizerFor(effectiveLanguage)
-        val image = InputImage.fromMediaImage(mediaImage, rotationDegrees)
-        val task: Task<Text> = recognizer.process(image)
+        val task: Task<Text> = recognizer.process(processImage)
         val result: Text? = Tasks.await(task)
         
         val resultText = result?.text
@@ -91,10 +134,10 @@ class VisionCameraTextRecognitionModule(
             detections.add(detection)
             boxValues.add(
               floatArrayOf(
-                blockBounds?.top?.toFloat() ?: -1f,
-                blockBounds?.bottom?.toFloat() ?: -1f,
-                blockBounds?.left?.toFloat() ?: -1f,
-                blockBounds?.right?.toFloat() ?: -1f,
+                (blockBounds?.top?.toFloat() ?: -1f) + offsetY,
+                (blockBounds?.bottom?.toFloat() ?: -1f) + offsetY,
+                (blockBounds?.left?.toFloat() ?: -1f) + offsetX,
+                (blockBounds?.right?.toFloat() ?: -1f) + offsetX,
                 -1f,
                 -1f,
                 -1f,
@@ -116,14 +159,14 @@ class VisionCameraTextRecognitionModule(
               detections.add(detection)
               boxValues.add(
                 floatArrayOf(
-                  blockBounds?.top?.toFloat() ?: -1f,
-                  blockBounds?.bottom?.toFloat() ?: -1f,
-                  blockBounds?.left?.toFloat() ?: -1f,
-                  blockBounds?.right?.toFloat() ?: -1f,
-                  line.boundingBox?.top?.toFloat() ?: -1f,
-                  line.boundingBox?.bottom?.toFloat() ?: -1f,
-                  line.boundingBox?.left?.toFloat() ?: -1f,
-                  line.boundingBox?.right?.toFloat() ?: -1f,
+                  (blockBounds?.top?.toFloat() ?: -1f) + offsetY,
+                  (blockBounds?.bottom?.toFloat() ?: -1f) + offsetY,
+                  (blockBounds?.left?.toFloat() ?: -1f) + offsetX,
+                  (blockBounds?.right?.toFloat() ?: -1f) + offsetX,
+                  (line.boundingBox?.top?.toFloat() ?: -1f) + offsetY,
+                  (line.boundingBox?.bottom?.toFloat() ?: -1f) + offsetY,
+                  (line.boundingBox?.left?.toFloat() ?: -1f) + offsetX,
+                  (line.boundingBox?.right?.toFloat() ?: -1f) + offsetX,
                   -1f,
                   -1f,
                   -1f,
@@ -141,18 +184,18 @@ class VisionCameraTextRecognitionModule(
               detections.add(detection)
               boxValues.add(
                 floatArrayOf(
-                  blockBounds?.top?.toFloat() ?: -1f,
-                  blockBounds?.bottom?.toFloat() ?: -1f,
-                  blockBounds?.left?.toFloat() ?: -1f,
-                  blockBounds?.right?.toFloat() ?: -1f,
-                  line.boundingBox?.top?.toFloat() ?: -1f,
-                  line.boundingBox?.bottom?.toFloat() ?: -1f,
-                  line.boundingBox?.left?.toFloat() ?: -1f,
-                  line.boundingBox?.right?.toFloat() ?: -1f,
-                  element.boundingBox?.top?.toFloat() ?: -1f,
-                  element.boundingBox?.bottom?.toFloat() ?: -1f,
-                  element.boundingBox?.left?.toFloat() ?: -1f,
-                  element.boundingBox?.right?.toFloat() ?: -1f,
+                  (blockBounds?.top?.toFloat() ?: -1f) + offsetY,
+                  (blockBounds?.bottom?.toFloat() ?: -1f) + offsetY,
+                  (blockBounds?.left?.toFloat() ?: -1f) + offsetX,
+                  (blockBounds?.right?.toFloat() ?: -1f) + offsetX,
+                  (line.boundingBox?.top?.toFloat() ?: -1f) + offsetY,
+                  (line.boundingBox?.bottom?.toFloat() ?: -1f) + offsetY,
+                  (line.boundingBox?.left?.toFloat() ?: -1f) + offsetX,
+                  (line.boundingBox?.right?.toFloat() ?: -1f) + offsetX,
+                  (element.boundingBox?.top?.toFloat() ?: -1f) + offsetY,
+                  (element.boundingBox?.bottom?.toFloat() ?: -1f) + offsetY,
+                  (element.boundingBox?.left?.toFloat() ?: -1f) + offsetX,
+                  (element.boundingBox?.right?.toFloat() ?: -1f) + offsetX,
                 )
               )
             }