react-native-rectangle-doc-scanner 0.45.0 → 0.47.0

package/README.md

@@ -19,6 +19,7 @@ Install the module alongside these peer dependencies (your host app should alrea
 - `react-native-vision-camera` (v3+) with frame processors enabled
 - `vision-camera-resize-plugin`
 - `react-native-fast-opencv`
+- `react-native-perspective-image-cropper`
 - `react-native-reanimated` + `react-native-worklets-core`
 - `@shopify/react-native-skia`
 - `react`, `react-native`
@@ -30,6 +31,7 @@ yarn add react-native-rectangle-doc-scanner \
   react-native-vision-camera \
   vision-camera-resize-plugin \
   react-native-fast-opencv \
+  react-native-perspective-image-cropper \
   react-native-reanimated \
   react-native-worklets-core \
   @shopify/react-native-skia
@@ -52,58 +54,133 @@ Follow each dependency’s native installation guide:
 
 ## Usage
 
+### Basic Document Scanning
+
 ```tsx
-import React from 'react';
+import React, { useState } from 'react';
 import { StyleSheet, Text, TouchableOpacity, View } from 'react-native';
-import { DocScanner } from 'react-native-rectangle-doc-scanner';
-
-export const ScanScreen = () => (
-  <View style={styles.container}>
-    <DocScanner
-      onCapture={({ path, quad }) => {
-        console.log('Document captured at', path, quad);
-      }}
-      overlayColor="#ff8800"
-      autoCapture
-      minStableFrames={8}
-      cameraProps={{ enableZoomGesture: true }}
-    >
-      <View style={styles.overlayControls}>
-        <TouchableOpacity style={styles.button}>
-          <Text style={styles.label}>Manual Capture</Text>
-        </TouchableOpacity>
-      </View>
-    </DocScanner>
-  </View>
-);
+import { DocScanner, CropEditor, type CapturedDocument } from 'react-native-rectangle-doc-scanner';
+
+export const ScanScreen = () => {
+  const [capturedDoc, setCapturedDoc] = useState<CapturedDocument | null>(null);
+
+  if (capturedDoc) {
+    // Show crop editor after capture
+    return (
+      <CropEditor
+        document={capturedDoc}
+        overlayColor="rgba(0,0,0,0.5)"
+        overlayStrokeColor="#e7a649"
+        handlerColor="#e7a649"
+        onCropChange={(rectangle) => {
+          console.log('User adjusted corners:', rectangle);
+          // Process the adjusted corners
+        }}
+      />
+    );
+  }
+
+  return (
+    <View style={styles.container}>
+      <DocScanner
+        onCapture={(doc) => {
+          console.log('Document captured:', doc);
+          setCapturedDoc(doc);
+        }}
+        overlayColor="#e7a649"
+        autoCapture
+        minStableFrames={8}
+        cameraProps={{ enableZoomGesture: true }}
+      >
+        <View style={styles.overlayControls}>
+          <Text style={styles.hint}>Position document in frame</Text>
+        </View>
+      </DocScanner>
+    </View>
+  );
+};
 
 const styles = StyleSheet.create({
   container: { flex: 1 },
   overlayControls: {
     position: 'absolute',
-    bottom: 32,
+    top: 60,
     alignSelf: 'center',
   },
-  button: {
-    paddingHorizontal: 24,
-    paddingVertical: 12,
-    borderRadius: 999,
-    backgroundColor: 'rgba(0,0,0,0.7)',
+  hint: {
+    color: '#fff',
+    fontSize: 16,
+    fontWeight: '600',
+    textShadowColor: 'rgba(0,0,0,0.75)',
+    textShadowOffset: { width: 0, height: 1 },
+    textShadowRadius: 3,
   },
-  label: { color: '#fff', fontWeight: '600' },
 });
 ```
 
+### Advanced Configuration
+
+```tsx
+import { DocScanner, type DetectionConfig } from 'react-native-rectangle-doc-scanner';
+
+const detectionConfig: DetectionConfig = {
+  processingWidth: 1280,      // Higher = more accurate but slower
+  cannyLowThreshold: 40,      // Lower = detect more edges
+  cannyHighThreshold: 120,    // Edge strength threshold
+  snapDistance: 8,            // Corner lock sensitivity
+  maxAnchorMisses: 20,        // Frames to hold anchor when detection fails
+  maxCenterDelta: 200,        // Max camera movement while maintaining lock
+};
+
+<DocScanner
+  detectionConfig={detectionConfig}
+  onCapture={(doc) => {
+    // doc includes: path, quad, width, height
+    console.log('Captured with size:', doc.width, 'x', doc.height);
+  }}
+/>
+```
+
 Passing `children` lets you render any UI on top of the camera preview, so you can freely add buttons, tutorials, or progress indicators without modifying the package.
 
-### Props
+## API Reference
+
+### DocScanner Props
+
+- `onCapture({ path, quad, width, height })` — called when a photo is taken
+  - `path`: file path to the captured image
+  - `quad`: detected corner coordinates (or `null` if none found)
+  - `width`, `height`: original frame dimensions for coordinate scaling
+- `overlayColor` (default `#e7a649`) — stroke color for the contour overlay
+- `autoCapture` (default `true`) — auto-captures after stability is reached
+- `minStableFrames` (default `8`) — consecutive stable frames required before auto capture
+- `cameraProps` — forwarded to underlying `Camera` (zoom, HDR, torch, etc.)
+- `children` — custom UI rendered over the camera preview
+- `detectionConfig` — advanced detection configuration (see below)
+
+### DetectionConfig
+
+Fine-tune the detection algorithm for your specific use case:
+
+```typescript
+interface DetectionConfig {
+  processingWidth?: number;      // Default: 1280 (higher = more accurate but slower)
+  cannyLowThreshold?: number;    // Default: 40 (lower = detect more edges)
+  cannyHighThreshold?: number;   // Default: 120 (edge strength threshold)
+  snapDistance?: number;         // Default: 8 (corner lock sensitivity in pixels)
+  maxAnchorMisses?: number;      // Default: 20 (frames to hold anchor when detection fails)
+  maxCenterDelta?: number;       // Default: 200 (max camera movement while maintaining lock)
+}
+```
+
+### CropEditor Props
 
-- `onCapture({ path, quad })` — called when a photo is taken; `quad` contains the detected corner coordinates (or `null` if none were found).
-- `overlayColor` (default `#e7a649`) — stroke colour for the contour overlay.
-- `autoCapture` (default `true`) — when `true`, captures automatically after stability is reached; set to `false` to show the built-in shutter button.
-- `minStableFrames` (default `8`) — number of consecutive stable frames required before auto capture triggers.
-- `cameraProps` — forwarded to the underlying `Camera` (except for `frameProcessor`), enabling features such as zoom gestures, HDR, torch control, device selection, etc.
-- `children` — rendered over the camera/overlay for fully custom controls.
+- `document` — `CapturedDocument` object from `onCapture` callback
+- `overlayColor` (default `rgba(0,0,0,0.5)`) — color of overlay outside crop area
+- `overlayStrokeColor` (default `#e7a649`) — color of crop boundary lines
+- `handlerColor` (default `#e7a649`) — color of corner drag handles
+- `enablePanStrict` (default `false`) — enable strict panning behavior
+- `onCropChange(rectangle)` — callback when user adjusts corners
 
 ### Notes on camera behaviour
 
@@ -113,34 +190,46 @@ Passing `children` lets you render any UI on top of the camera preview, so you c
 
 ## Detection Algorithm
 
-The scanner uses a sophisticated multi-stage pipeline:
-
-1. **Pre-processing** (1280p resolution for accuracy)
-   - Converts frame to grayscale
-   - Applies morphological opening to reduce noise
-   - Gaussian blur for smoother edges
-   - Canny edge detection with 50/150 thresholds
-
-2. **Contour Detection**
-   - Finds external contours using CHAIN_APPROX_SIMPLE
-   - Applies convex hull for better corner detection
-   - Tests multiple epsilon values (0.1%-10%) for approxPolyDP
-   - Validates quadrilaterals for convexity
-
-3. **Anchor Locking System**
-   - Once corners are detected, they "snap" to stable positions
-   - Maintains lock even when camera moves (up to 200px center delta)
-   - Holds anchor for up to 20 missed detections
-   - Adaptive blending between old and new positions for smooth transitions
-   - Builds confidence over time (max 30 frames) for stronger locking
-
-4. **Quad Validation**
-   - Checks area ratio (0.02%-90% of frame)
-   - Validates minimum edge lengths
-   - Ensures reasonable aspect ratios
-   - Filters out non-convex shapes
-
-This approach ensures corners remain locked once detected, allowing you to move the camera slightly without losing the document boundary.
+The scanner uses a sophisticated multi-stage pipeline optimized for quality and stability:
+
+### 1. Pre-processing (Configurable Resolution)
+- Resizes frame to `processingWidth` (default 1280p) for optimal accuracy
+- Converts to grayscale
+- **Enhanced morphological operations**:
+  - MORPH_CLOSE to fill small holes in edges (7x7 kernel)
+  - MORPH_OPEN to remove small noise
+- **Bilateral filter** for edge-preserving smoothing (better than Gaussian)
+- **Adaptive Canny edge detection** with configurable thresholds (default 40/120)
+
+### 2. Contour Detection
+- Finds external contours using CHAIN_APPROX_SIMPLE
+- Applies convex hull for improved corner accuracy
+- Tests **23 epsilon values** (0.1%-10%) for approxPolyDP to find exact 4 corners
+- Validates quadrilaterals for convexity and valid coordinates
+
+### 3. Advanced Anchor Locking System
+Once corners are detected, the system maintains stability through:
+- **Snap locking**: Corners lock to positions when movement is minimal
+- **Camera movement tolerance**: Maintains lock during movement (up to 200px center delta)
+- **Persistence**: Holds anchor for up to 20 consecutive failed detections
+- **Adaptive blending**: Smoothly transitions between old and new positions
+- **Confidence building**: Increases lock strength over time (max 30 frames)
+- **Intelligent reset**: Only resets when document clearly changes
+
+### 4. Quad Validation
+- Area ratio filtering (0.02%-90% of frame)
+- Minimum edge length validation
+- Aspect ratio constraints (max 7:1)
+- Convexity checks to filter invalid shapes
+
+### 5. Post-Capture Editing
+After capture, users can manually adjust corners using the `CropEditor` component:
+- Grid-based interface with perspective view
+- Draggable corner handles
+- Real-time preview of adjusted crop area
+- Exports adjusted coordinates for final processing
+
+This multi-layered approach ensures high-quality detection with maximum flexibility for various document types and lighting conditions.
 
 ## Build
 ```sh

package/dist/CropEditor.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+import type { Rectangle, CapturedDocument } from './types';
+interface CropEditorProps {
+    document: CapturedDocument;
+    overlayColor?: string;
+    overlayStrokeColor?: string;
+    handlerColor?: string;
+    enablePanStrict?: boolean;
+    onCropChange?: (rectangle: Rectangle) => void;
+}
+/**
+ * CropEditor Component
+ *
+ * Displays a captured document image with adjustable corner handles.
+ * Uses react-native-perspective-image-cropper for the cropping UI.
+ *
+ * @param document - The captured document with path and detected quad
+ * @param overlayColor - Color of the overlay outside the crop area (default: 'rgba(0,0,0,0.5)')
+ * @param overlayStrokeColor - Color of the crop boundary lines (default: '#e7a649')
+ * @param handlerColor - Color of the corner handles (default: '#e7a649')
+ * @param enablePanStrict - Enable strict panning behavior
+ * @param onCropChange - Callback when user adjusts crop corners
+ */
+export declare const CropEditor: React.FC<CropEditorProps>;
+export {};

package/dist/CropEditor.js

@@ -0,0 +1,113 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CropEditor = void 0;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const react_native_perspective_image_cropper_1 = require("react-native-perspective-image-cropper");
+const coordinate_1 = require("./utils/coordinate");
+/**
+ * CropEditor Component
+ *
+ * Displays a captured document image with adjustable corner handles.
+ * Uses react-native-perspective-image-cropper for the cropping UI.
+ *
+ * @param document - The captured document with path and detected quad
+ * @param overlayColor - Color of the overlay outside the crop area (default: 'rgba(0,0,0,0.5)')
+ * @param overlayStrokeColor - Color of the crop boundary lines (default: '#e7a649')
+ * @param handlerColor - Color of the corner handles (default: '#e7a649')
+ * @param enablePanStrict - Enable strict panning behavior
+ * @param onCropChange - Callback when user adjusts crop corners
+ */
+const CropEditor = ({ document, overlayColor = 'rgba(0,0,0,0.5)', overlayStrokeColor = '#e7a649', handlerColor = '#e7a649', enablePanStrict = false, onCropChange, }) => {
+    const [imageSize, setImageSize] = (0, react_1.useState)(null);
+    const [displaySize, setDisplaySize] = (0, react_1.useState)({
+        width: react_native_1.Dimensions.get('window').width,
+        height: react_native_1.Dimensions.get('window').height,
+    });
+    // Get initial rectangle from detected quad or use default
+    const getInitialRectangle = (0, react_1.useCallback)(() => {
+        if (!document.quad || !imageSize) {
+            return undefined;
+        }
+        const rect = (0, coordinate_1.quadToRectangle)(document.quad);
+        if (!rect) {
+            return undefined;
+        }
+        // Scale from original detection coordinates to image coordinates
+        const scaled = (0, coordinate_1.scaleRectangle)(rect, document.width, document.height, imageSize.width, imageSize.height);
+        return scaled;
+    }, [document.quad, document.width, document.height, imageSize]);
+    const handleImageLoad = (0, react_1.useCallback)((event) => {
+        const { width, height } = event.nativeEvent.source;
+        setImageSize({ width, height });
+    }, []);
+    const handleLayout = (0, react_1.useCallback)((event) => {
+        const { width, height } = event.nativeEvent.layout;
+        setDisplaySize({ width, height });
+    }, []);
+    const handleDragEnd = (0, react_1.useCallback)((coordinates) => {
+        if (!imageSize) {
+            return;
+        }
+        // Convert back to Rectangle type
+        const rect = {
+            topLeft: coordinates.topLeft,
+            topRight: coordinates.topRight,
+            bottomRight: coordinates.bottomRight,
+            bottomLeft: coordinates.bottomLeft,
+        };
+        onCropChange?.(rect);
+    }, [imageSize, onCropChange]);
+    // Wait for image to load to get dimensions
+    if (!imageSize) {
+        return (react_1.default.createElement(react_native_1.View, { style: styles.container, onLayout: handleLayout },
+            react_1.default.createElement(react_native_1.Image, { source: { uri: `file://${document.path}` }, style: styles.hiddenImage, onLoad: handleImageLoad, resizeMode: "contain" })));
+    }
+    return (react_1.default.createElement(react_native_1.View, { style: styles.container, onLayout: handleLayout },
+        react_1.default.createElement(react_native_perspective_image_cropper_1.CustomImageCropper, { height: displaySize.height, width: displaySize.width, image: `file://${document.path}`, rectangleCoordinates: getInitialRectangle(), overlayColor: overlayColor, overlayStrokeColor: overlayStrokeColor, handlerColor: handlerColor, enablePanStrict: enablePanStrict, onDragEnd: handleDragEnd })));
+};
+exports.CropEditor = CropEditor;
+const styles = react_native_1.StyleSheet.create({
+    container: {
+        flex: 1,
+        backgroundColor: '#000',
+    },
+    hiddenImage: {
+        width: 1,
+        height: 1,
+        opacity: 0,
+    },
+});

package/dist/DocScanner.d.ts

@@ -2,16 +2,37 @@ import React, { ReactNode } from 'react';
 import { Camera } from 'react-native-vision-camera';
 import type { Point } from './types';
 type CameraOverrides = Omit<React.ComponentProps<typeof Camera>, 'style' | 'ref' | 'frameProcessor'>;
+/**
+ * Configuration for detection quality and behavior
+ */
+export interface DetectionConfig {
+    /** Processing resolution width (default: 1280) - higher = more accurate but slower */
+    processingWidth?: number;
+    /** Canny edge detection lower threshold (default: 40) */
+    cannyLowThreshold?: number;
+    /** Canny edge detection upper threshold (default: 120) */
+    cannyHighThreshold?: number;
+    /** Snap distance in pixels for corner locking (default: 8) */
+    snapDistance?: number;
+    /** Max frames to hold anchor when detection fails (default: 20) */
+    maxAnchorMisses?: number;
+    /** Maximum center movement allowed while maintaining lock (default: 200px) */
+    maxCenterDelta?: number;
+}
 interface Props {
     onCapture?: (photo: {
         path: string;
         quad: Point[] | null;
+        width: number;
+        height: number;
     }) => void;
     overlayColor?: string;
     autoCapture?: boolean;
     minStableFrames?: number;
     cameraProps?: CameraOverrides;
     children?: ReactNode;
+    /** Advanced detection configuration */
+    detectionConfig?: DetectionConfig;
 }
 export declare const DocScanner: React.FC<Props>;
 export {};

package/dist/DocScanner.js

@@ -79,7 +79,7 @@ const isConvexQuadrilateral = (points) => {
         return false;
     }
 };
-const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, minStableFrames = 8, cameraProps, children, }) => {
+const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, minStableFrames = 8, cameraProps, children, detectionConfig = {}, }) => {
     const device = (0, react_native_vision_camera_1.useCameraDevice)('back');
     const { hasPermission, requestPermission } = (0, react_native_vision_camera_1.useCameraPermission)();
     const { resize } = (0, vision_camera_resize_plugin_1.useResizePlugin)();
@@ -99,20 +99,25 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
     const anchorConfidenceRef = (0, react_1.useRef)(0);
     const lastMeasurementRef = (0, react_1.useRef)(null);
     const frameSizeRef = (0, react_1.useRef)(null);
+    // Detection parameters - configurable via props with sensible defaults
+    const PROCESSING_WIDTH = detectionConfig.processingWidth ?? 1280;
+    const CANNY_LOW = detectionConfig.cannyLowThreshold ?? 40;
+    const CANNY_HIGH = detectionConfig.cannyHighThreshold ?? 120;
+    const SNAP_DISTANCE = detectionConfig.snapDistance ?? 8;
+    const MAX_ANCHOR_MISSES = detectionConfig.maxAnchorMisses ?? 20;
+    const REJECT_CENTER_DELTA = detectionConfig.maxCenterDelta ?? 200;
+    // Fixed parameters for algorithm stability
     const MAX_HISTORY = 5;
-    const SNAP_DISTANCE = 8; // pixels; keep corners locked when movement is tiny (increased for stronger lock)
     const SNAP_CENTER_DISTANCE = 18;
-    const BLEND_DISTANCE = 80; // pixels; softly ease between similar shapes (increased)
-    const MAX_CENTER_DELTA = 120; // increased to allow more camera movement
-    const REJECT_CENTER_DELTA = 200; // increased to maintain lock during camera movement
-    const MAX_AREA_SHIFT = 0.55; // more tolerance for perspective changes
+    const BLEND_DISTANCE = 80;
+    const MAX_CENTER_DELTA = 120;
+    const MAX_AREA_SHIFT = 0.55;
     const HISTORY_RESET_DISTANCE = 90;
     const MIN_AREA_RATIO = 0.0002;
     const MAX_AREA_RATIO = 0.9;
     const MIN_EDGE_RATIO = 0.015;
-    const MAX_ANCHOR_MISSES = 20; // increased to hold anchor longer when detection temporarily fails
     const MIN_CONFIDENCE_TO_HOLD = 2;
-    const MAX_ANCHOR_CONFIDENCE = 30; // increased max confidence for stronger anchoring
+    const MAX_ANCHOR_CONFIDENCE = 30;
     const updateQuad = (0, react_native_worklets_core_1.useRunOnJS)((value) => {
         if (__DEV__) {
             console.log('[DocScanner] quad', value);
@@ -249,8 +254,8 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
         try {
             // Report frame size for coordinate transformation
             updateFrameSize(frame.width, frame.height);
-            // Use higher resolution for better accuracy - 1280p for improved corner detection
-            const ratio = 1280 / frame.width;
+            // Use configurable resolution for accuracy vs performance balance
+            const ratio = PROCESSING_WIDTH / frame.width;
             const width = Math.floor(frame.width * ratio);
             const height = Math.floor(frame.height * ratio);
             step = 'resize';
@@ -262,26 +267,42 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
             });
             step = 'frameBufferToMat';
             reportStage(step);
-            const mat = react_native_fast_opencv_1.OpenCV.frameBufferToMat(height, width, 3, resized);
+            let mat = react_native_fast_opencv_1.OpenCV.frameBufferToMat(height, width, 3, resized);
             step = 'cvtColor';
             reportStage(step);
             react_native_fast_opencv_1.OpenCV.invoke('cvtColor', mat, mat, react_native_fast_opencv_1.ColorConversionCodes.COLOR_BGR2GRAY);
-            const morphologyKernel = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, 5, 5);
+            // Enhanced morphological operations for noise reduction
+            const morphologyKernel = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, 7, 7);
             step = 'getStructuringElement';
             reportStage(step);
             const element = react_native_fast_opencv_1.OpenCV.invoke('getStructuringElement', react_native_fast_opencv_1.MorphShapes.MORPH_RECT, morphologyKernel);
             step = 'morphologyEx';
             reportStage(step);
+            // MORPH_CLOSE to fill small holes in edges
+            react_native_fast_opencv_1.OpenCV.invoke('morphologyEx', mat, mat, react_native_fast_opencv_1.MorphTypes.MORPH_CLOSE, element);
+            // MORPH_OPEN to remove small noise
             react_native_fast_opencv_1.OpenCV.invoke('morphologyEx', mat, mat, react_native_fast_opencv_1.MorphTypes.MORPH_OPEN, element);
-            const gaussianKernel = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, 5, 5);
-            step = 'GaussianBlur';
+            // Bilateral filter for edge-preserving smoothing (better quality than Gaussian)
+            step = 'bilateralFilter';
             reportStage(step);
-            react_native_fast_opencv_1.OpenCV.invoke('GaussianBlur', mat, mat, gaussianKernel, 0);
+            try {
+                const tempMat = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat);
+                react_native_fast_opencv_1.OpenCV.invoke('bilateralFilter', mat, tempMat, 9, 75, 75);
+                mat = tempMat;
+            }
+            catch (error) {
+                if (__DEV__) {
+                    console.warn('[DocScanner] bilateralFilter unavailable, falling back to GaussianBlur', error);
+                }
+                step = 'gaussianBlurFallback';
+                reportStage(step);
+                const blurKernel = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, 5, 5);
+                react_native_fast_opencv_1.OpenCV.invoke('GaussianBlur', mat, mat, blurKernel, 0);
+            }
             step = 'Canny';
             reportStage(step);
-            // Improved Canny parameters for better edge detection accuracy
-            // Lower threshold (50 -> more edges detected) and higher threshold (150 -> stronger edges kept)
-            react_native_fast_opencv_1.OpenCV.invoke('Canny', mat, mat, 50, 150);
+            // Configurable Canny parameters for adaptive edge detection
+            react_native_fast_opencv_1.OpenCV.invoke('Canny', mat, mat, CANNY_LOW, CANNY_HIGH);
             step = 'createContours';
             reportStage(step);
             const contours = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.PointVectorOfVectors);
@@ -419,14 +440,19 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
     }, [quad]);
     (0, react_1.useEffect)(() => {
         const capture = async () => {
-            if (autoCapture && quad && stable >= minStableFrames && camera.current) {
+            if (autoCapture && quad && stable >= minStableFrames && camera.current && frameSize) {
                 const photo = await camera.current.takePhoto({ qualityPrioritization: 'quality' });
-                onCapture?.({ path: photo.path, quad });
+                onCapture?.({
+                    path: photo.path,
+                    quad,
+                    width: frameSize.width,
+                    height: frameSize.height,
+                });
                 setStable(0);
             }
         };
         capture();
-    }, [autoCapture, minStableFrames, onCapture, quad, stable]);
+    }, [autoCapture, minStableFrames, onCapture, quad, stable, frameSize]);
     const { device: overrideDevice, ...cameraRestProps } = cameraProps ?? {};
     const resolvedDevice = overrideDevice ?? device;
     if (!resolvedDevice || !hasPermission) {
@@ -436,11 +462,16 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
         react_1.default.createElement(react_native_vision_camera_1.Camera, { ref: handleCameraRef, style: react_native_1.StyleSheet.absoluteFillObject, device: resolvedDevice, isActive: true, photo: true, frameProcessor: frameProcessor, frameProcessorFps: 15, ...cameraRestProps }),
         react_1.default.createElement(overlay_1.Overlay, { quad: quad, color: overlayColor, frameSize: frameSize }),
         !autoCapture && (react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.button, onPress: async () => {
-                if (!camera.current) {
+                if (!camera.current || !frameSize) {
                     return;
                 }
                 const photo = await camera.current.takePhoto({ qualityPrioritization: 'quality' });
-                onCapture?.({ path: photo.path, quad });
+                onCapture?.({
+                    path: photo.path,
+                    quad,
+                    width: frameSize.width,
+                    height: frameSize.height,
+                });
             } })),
         children));
 };

package/dist/index.d.ts

@@ -1 +1,5 @@
-export * from './DocScanner';
+export { DocScanner } from './DocScanner';
+export { CropEditor } from './CropEditor';
+export type { Point, Quad, Rectangle, CapturedDocument } from './types';
+export type { DetectionConfig } from './DocScanner';
+export { quadToRectangle, rectangleToQuad, scaleCoordinates, scaleRectangle, } from './utils/coordinate';

package/dist/index.js

@@ -1,17 +1,14 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./DocScanner"), exports);
+exports.scaleRectangle = exports.scaleCoordinates = exports.rectangleToQuad = exports.quadToRectangle = exports.CropEditor = exports.DocScanner = void 0;
+// Main components
+var DocScanner_1 = require("./DocScanner");
+Object.defineProperty(exports, "DocScanner", { enumerable: true, get: function () { return DocScanner_1.DocScanner; } });
+var CropEditor_1 = require("./CropEditor");
+Object.defineProperty(exports, "CropEditor", { enumerable: true, get: function () { return CropEditor_1.CropEditor; } });
+// Utilities
+var coordinate_1 = require("./utils/coordinate");
+Object.defineProperty(exports, "quadToRectangle", { enumerable: true, get: function () { return coordinate_1.quadToRectangle; } });
+Object.defineProperty(exports, "rectangleToQuad", { enumerable: true, get: function () { return coordinate_1.rectangleToQuad; } });
+Object.defineProperty(exports, "scaleCoordinates", { enumerable: true, get: function () { return coordinate_1.scaleCoordinates; } });
+Object.defineProperty(exports, "scaleRectangle", { enumerable: true, get: function () { return coordinate_1.scaleRectangle; } });

package/dist/types.d.ts

@@ -2,3 +2,16 @@ export type Point = {
     x: number;
     y: number;
 };
+export type Quad = [Point, Point, Point, Point];
+export type Rectangle = {
+    topLeft: Point;
+    topRight: Point;
+    bottomRight: Point;
+    bottomLeft: Point;
+};
+export type CapturedDocument = {
+    path: string;
+    quad: Point[] | null;
+    width: number;
+    height: number;
+};

package/dist/utils/coordinate.d.ts

@@ -0,0 +1,19 @@
+import type { Point, Rectangle } from '../types';
+/**
+ * Convert quad points array to Rectangle format for perspective cropper
+ * Assumes quad points are ordered: [topLeft, topRight, bottomRight, bottomLeft]
+ */
+export declare const quadToRectangle: (quad: Point[]) => Rectangle | null;
+/**
+ * Convert Rectangle format back to quad points array
+ */
+export declare const rectangleToQuad: (rect: Rectangle) => Point[];
+/**
+ * Scale coordinates from one dimension to another
+ * Useful when image dimensions differ from display dimensions
+ */
+export declare const scaleCoordinates: (points: Point[], fromWidth: number, fromHeight: number, toWidth: number, toHeight: number) => Point[];
+/**
+ * Scale a rectangle
+ */
+export declare const scaleRectangle: (rect: Rectangle, fromWidth: number, fromHeight: number, toWidth: number, toHeight: number) => Rectangle;

package/dist/utils/coordinate.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scaleRectangle = exports.scaleCoordinates = exports.rectangleToQuad = exports.quadToRectangle = void 0;
+/**
+ * Convert quad points array to Rectangle format for perspective cropper
+ * Assumes quad points are ordered: [topLeft, topRight, bottomRight, bottomLeft]
+ */
+const quadToRectangle = (quad) => {
+    if (!quad || quad.length !== 4) {
+        return null;
+    }
+    return {
+        topLeft: quad[0],
+        topRight: quad[1],
+        bottomRight: quad[2],
+        bottomLeft: quad[3],
+    };
+};
+exports.quadToRectangle = quadToRectangle;
+/**
+ * Convert Rectangle format back to quad points array
+ */
+const rectangleToQuad = (rect) => {
+    return [
+        rect.topLeft,
+        rect.topRight,
+        rect.bottomRight,
+        rect.bottomLeft,
+    ];
+};
+exports.rectangleToQuad = rectangleToQuad;
+/**
+ * Scale coordinates from one dimension to another
+ * Useful when image dimensions differ from display dimensions
+ */
+const scaleCoordinates = (points, fromWidth, fromHeight, toWidth, toHeight) => {
+    const scaleX = toWidth / fromWidth;
+    const scaleY = toHeight / fromHeight;
+    return points.map(p => ({
+        x: p.x * scaleX,
+        y: p.y * scaleY,
+    }));
+};
+exports.scaleCoordinates = scaleCoordinates;
+/**
+ * Scale a rectangle
+ */
+const scaleRectangle = (rect, fromWidth, fromHeight, toWidth, toHeight) => {
+    const scaleX = toWidth / fromWidth;
+    const scaleY = toHeight / fromHeight;
+    return {
+        topLeft: { x: rect.topLeft.x * scaleX, y: rect.topLeft.y * scaleY },
+        topRight: { x: rect.topRight.x * scaleX, y: rect.topRight.y * scaleY },
+        bottomRight: { x: rect.bottomRight.x * scaleX, y: rect.bottomRight.y * scaleY },
+        bottomLeft: { x: rect.bottomLeft.x * scaleX, y: rect.bottomLeft.y * scaleY },
+    };
+};
+exports.scaleRectangle = scaleRectangle;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-rectangle-doc-scanner",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "repository": {
@@ -20,6 +20,7 @@
     "react": "*",
     "react-native": "*",
     "react-native-fast-opencv": "*",
+    "react-native-perspective-image-cropper": "*",
     "react-native-reanimated": "*",
     "react-native-vision-camera": "*",
     "react-native-worklets-core": "*",

package/src/CropEditor.tsx

@@ -0,0 +1,134 @@
+import React, { useState, useCallback } from 'react';
+import { View, StyleSheet, Image, Dimensions } from 'react-native';
+import { CustomImageCropper } from 'react-native-perspective-image-cropper';
+import type { Rectangle as CropperRectangle } from 'react-native-perspective-image-cropper';
+import type { Point, Rectangle, CapturedDocument } from './types';
+import { quadToRectangle, scaleRectangle } from './utils/coordinate';
+
+interface CropEditorProps {
+  document: CapturedDocument;
+  overlayColor?: string;
+  overlayStrokeColor?: string;
+  handlerColor?: string;
+  enablePanStrict?: boolean;
+  onCropChange?: (rectangle: Rectangle) => void;
+}
+
+/**
+ * CropEditor Component
+ *
+ * Displays a captured document image with adjustable corner handles.
+ * Uses react-native-perspective-image-cropper for the cropping UI.
+ *
+ * @param document - The captured document with path and detected quad
+ * @param overlayColor - Color of the overlay outside the crop area (default: 'rgba(0,0,0,0.5)')
+ * @param overlayStrokeColor - Color of the crop boundary lines (default: '#e7a649')
+ * @param handlerColor - Color of the corner handles (default: '#e7a649')
+ * @param enablePanStrict - Enable strict panning behavior
+ * @param onCropChange - Callback when user adjusts crop corners
+ */
+export const CropEditor: React.FC<CropEditorProps> = ({
+  document,
+  overlayColor = 'rgba(0,0,0,0.5)',
+  overlayStrokeColor = '#e7a649',
+  handlerColor = '#e7a649',
+  enablePanStrict = false,
+  onCropChange,
+}) => {
+  const [imageSize, setImageSize] = useState<{ width: number; height: number } | null>(null);
+  const [displaySize, setDisplaySize] = useState<{ width: number; height: number }>({
+    width: Dimensions.get('window').width,
+    height: Dimensions.get('window').height,
+  });
+
+  // Get initial rectangle from detected quad or use default
+  const getInitialRectangle = useCallback((): CropperRectangle | undefined => {
+    if (!document.quad || !imageSize) {
+      return undefined;
+    }
+
+    const rect = quadToRectangle(document.quad);
+    if (!rect) {
+      return undefined;
+    }
+
+    // Scale from original detection coordinates to image coordinates
+    const scaled = scaleRectangle(
+      rect,
+      document.width,
+      document.height,
+      imageSize.width,
+      imageSize.height
+    );
+
+    return scaled as CropperRectangle;
+  }, [document.quad, document.width, document.height, imageSize]);
+
+  const handleImageLoad = useCallback((event: any) => {
+    const { width, height } = event.nativeEvent.source;
+    setImageSize({ width, height });
+  }, []);
+
+  const handleLayout = useCallback((event: any) => {
+    const { width, height } = event.nativeEvent.layout;
+    setDisplaySize({ width, height });
+  }, []);
+
+  const handleDragEnd = useCallback((coordinates: CropperRectangle) => {
+    if (!imageSize) {
+      return;
+    }
+
+    // Convert back to Rectangle type
+    const rect: Rectangle = {
+      topLeft: coordinates.topLeft,
+      topRight: coordinates.topRight,
+      bottomRight: coordinates.bottomRight,
+      bottomLeft: coordinates.bottomLeft,
+    };
+
+    onCropChange?.(rect);
+  }, [imageSize, onCropChange]);
+
+  // Wait for image to load to get dimensions
+  if (!imageSize) {
+    return (
+      <View style={styles.container} onLayout={handleLayout}>
+        <Image
+          source={{ uri: `file://${document.path}` }}
+          style={styles.hiddenImage}
+          onLoad={handleImageLoad}
+          resizeMode="contain"
+        />
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.container} onLayout={handleLayout}>
+      <CustomImageCropper
+        height={displaySize.height}
+        width={displaySize.width}
+        image={`file://${document.path}`}
+        rectangleCoordinates={getInitialRectangle()}
+        overlayColor={overlayColor}
+        overlayStrokeColor={overlayStrokeColor}
+        handlerColor={handlerColor}
+        enablePanStrict={enablePanStrict}
+        onDragEnd={handleDragEnd}
+      />
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#000',
+  },
+  hiddenImage: {
+    width: 1,
+    height: 1,
+    opacity: 0,
+  },
+});

package/src/DocScanner.tsx

@@ -76,13 +76,33 @@ type CameraRef = {
 
 type CameraOverrides = Omit<React.ComponentProps<typeof Camera>, 'style' | 'ref' | 'frameProcessor'>;
 
+/**
+ * Configuration for detection quality and behavior
+ */
+export interface DetectionConfig {
+  /** Processing resolution width (default: 1280) - higher = more accurate but slower */
+  processingWidth?: number;
+  /** Canny edge detection lower threshold (default: 40) */
+  cannyLowThreshold?: number;
+  /** Canny edge detection upper threshold (default: 120) */
+  cannyHighThreshold?: number;
+  /** Snap distance in pixels for corner locking (default: 8) */
+  snapDistance?: number;
+  /** Max frames to hold anchor when detection fails (default: 20) */
+  maxAnchorMisses?: number;
+  /** Maximum center movement allowed while maintaining lock (default: 200px) */
+  maxCenterDelta?: number;
+}
+
 interface Props {
-  onCapture?: (photo: { path: string; quad: Point[] | null }) => void;
+  onCapture?: (photo: { path: string; quad: Point[] | null; width: number; height: number }) => void;
   overlayColor?: string;
   autoCapture?: boolean;
   minStableFrames?: number;
   cameraProps?: CameraOverrides;
   children?: ReactNode;
+  /** Advanced detection configuration */
+  detectionConfig?: DetectionConfig;
 }
 
 export const DocScanner: React.FC<Props> = ({
@@ -92,6 +112,7 @@ export const DocScanner: React.FC<Props> = ({
   minStableFrames = 8,
   cameraProps,
   children,
+  detectionConfig = {},
 }) => {
   const device = useCameraDevice('back');
   const { hasPermission, requestPermission } = useCameraPermission();
@@ -115,20 +136,26 @@ export const DocScanner: React.FC<Props> = ({
   const lastMeasurementRef = useRef<Point[] | null>(null);
   const frameSizeRef = useRef<{ width: number; height: number } | null>(null);
 
+  // Detection parameters - configurable via props with sensible defaults
+  const PROCESSING_WIDTH = detectionConfig.processingWidth ?? 1280;
+  const CANNY_LOW = detectionConfig.cannyLowThreshold ?? 40;
+  const CANNY_HIGH = detectionConfig.cannyHighThreshold ?? 120;
+  const SNAP_DISTANCE = detectionConfig.snapDistance ?? 8;
+  const MAX_ANCHOR_MISSES = detectionConfig.maxAnchorMisses ?? 20;
+  const REJECT_CENTER_DELTA = detectionConfig.maxCenterDelta ?? 200;
+
+  // Fixed parameters for algorithm stability
   const MAX_HISTORY = 5;
-  const SNAP_DISTANCE = 8; // pixels; keep corners locked when movement is tiny (increased for stronger lock)
   const SNAP_CENTER_DISTANCE = 18;
-  const BLEND_DISTANCE = 80; // pixels; softly ease between similar shapes (increased)
-  const MAX_CENTER_DELTA = 120; // increased to allow more camera movement
-  const REJECT_CENTER_DELTA = 200; // increased to maintain lock during camera movement
-  const MAX_AREA_SHIFT = 0.55; // more tolerance for perspective changes
+  const BLEND_DISTANCE = 80;
+  const MAX_CENTER_DELTA = 120;
+  const MAX_AREA_SHIFT = 0.55;
   const HISTORY_RESET_DISTANCE = 90;
   const MIN_AREA_RATIO = 0.0002;
   const MAX_AREA_RATIO = 0.9;
   const MIN_EDGE_RATIO = 0.015;
-  const MAX_ANCHOR_MISSES = 20; // increased to hold anchor longer when detection temporarily fails
   const MIN_CONFIDENCE_TO_HOLD = 2;
-  const MAX_ANCHOR_CONFIDENCE = 30; // increased max confidence for stronger anchoring
+  const MAX_ANCHOR_CONFIDENCE = 30;
 
   const updateQuad = useRunOnJS((value: Point[] | null) => {
     if (__DEV__) {
@@ -290,8 +317,8 @@ export const DocScanner: React.FC<Props> = ({
       // Report frame size for coordinate transformation
       updateFrameSize(frame.width, frame.height);
 
-      // Use higher resolution for better accuracy - 1280p for improved corner detection
-      const ratio = 1280 / frame.width;
+      // Use configurable resolution for accuracy vs performance balance
+      const ratio = PROCESSING_WIDTH / frame.width;
       const width = Math.floor(frame.width * ratio);
       const height = Math.floor(frame.height * ratio);
       step = 'resize';
@@ -304,29 +331,45 @@ export const DocScanner: React.FC<Props> = ({
 
       step = 'frameBufferToMat';
       reportStage(step);
-      const mat = OpenCV.frameBufferToMat(height, width, 3, resized);
+      let mat = OpenCV.frameBufferToMat(height, width, 3, resized);
 
       step = 'cvtColor';
       reportStage(step);
       OpenCV.invoke('cvtColor', mat, mat, ColorConversionCodes.COLOR_BGR2GRAY);
 
-      const morphologyKernel = OpenCV.createObject(ObjectType.Size, 5, 5);
+      // Enhanced morphological operations for noise reduction
+      const morphologyKernel = OpenCV.createObject(ObjectType.Size, 7, 7);
       step = 'getStructuringElement';
       reportStage(step);
       const element = OpenCV.invoke('getStructuringElement', MorphShapes.MORPH_RECT, morphologyKernel);
       step = 'morphologyEx';
       reportStage(step);
+      // MORPH_CLOSE to fill small holes in edges
+      OpenCV.invoke('morphologyEx', mat, mat, MorphTypes.MORPH_CLOSE, element);
+      // MORPH_OPEN to remove small noise
       OpenCV.invoke('morphologyEx', mat, mat, MorphTypes.MORPH_OPEN, element);
 
-      const gaussianKernel = OpenCV.createObject(ObjectType.Size, 5, 5);
-      step = 'GaussianBlur';
+      // Bilateral filter for edge-preserving smoothing (better quality than Gaussian)
+      step = 'bilateralFilter';
       reportStage(step);
-      OpenCV.invoke('GaussianBlur', mat, mat, gaussianKernel, 0);
+      try {
+        const tempMat = OpenCV.createObject(ObjectType.Mat);
+        OpenCV.invoke('bilateralFilter', mat, tempMat, 9, 75, 75);
+        mat = tempMat;
+      } catch (error) {
+        if (__DEV__) {
+          console.warn('[DocScanner] bilateralFilter unavailable, falling back to GaussianBlur', error);
+        }
+        step = 'gaussianBlurFallback';
+        reportStage(step);
+        const blurKernel = OpenCV.createObject(ObjectType.Size, 5, 5);
+        OpenCV.invoke('GaussianBlur', mat, mat, blurKernel, 0);
+      }
+
       step = 'Canny';
       reportStage(step);
-      // Improved Canny parameters for better edge detection accuracy
-      // Lower threshold (50 -> more edges detected) and higher threshold (150 -> stronger edges kept)
-      OpenCV.invoke('Canny', mat, mat, 50, 150);
+      // Configurable Canny parameters for adaptive edge detection
+      OpenCV.invoke('Canny', mat, mat, CANNY_LOW, CANNY_HIGH);
 
       step = 'createContours';
       reportStage(step);
@@ -489,15 +532,20 @@ export const DocScanner: React.FC<Props> = ({
 
   useEffect(() => {
     const capture = async () => {
-      if (autoCapture && quad && stable >= minStableFrames && camera.current) {
+      if (autoCapture && quad && stable >= minStableFrames && camera.current && frameSize) {
         const photo = await camera.current.takePhoto({ qualityPrioritization: 'quality' });
-        onCapture?.({ path: photo.path, quad });
+        onCapture?.({
+          path: photo.path,
+          quad,
+          width: frameSize.width,
+          height: frameSize.height,
+        });
         setStable(0);
       }
     };
 
     capture();
-  }, [autoCapture, minStableFrames, onCapture, quad, stable]);
+  }, [autoCapture, minStableFrames, onCapture, quad, stable, frameSize]);
 
   const { device: overrideDevice, ...cameraRestProps } = cameraProps ?? {};
   const resolvedDevice = overrideDevice ?? device;
@@ -523,12 +571,17 @@ export const DocScanner: React.FC<Props> = ({
         <TouchableOpacity
           style={styles.button}
           onPress={async () => {
-            if (!camera.current) {
+            if (!camera.current || !frameSize) {
               return;
             }
 
             const photo = await camera.current.takePhoto({ qualityPrioritization: 'quality' });
-            onCapture?.({ path: photo.path, quad });
+            onCapture?.({
+              path: photo.path,
+              quad,
+              width: frameSize.width,
+              height: frameSize.height,
+            });
           }}
         />
       )}

package/src/external.d.ts

@@ -107,3 +107,28 @@ declare module '@shopify/react-native-skia' {
 
   export const Path: ComponentType<PathProps>;
 }
+
+declare module 'react-native-perspective-image-cropper' {
+  import type { ComponentType } from 'react';
+
+  export type Rectangle = {
+    topLeft: { x: number; y: number };
+    topRight: { x: number; y: number };
+    bottomLeft: { x: number; y: number };
+    bottomRight: { x: number; y: number };
+  };
+
+  export type CustomImageCropperProps = {
+    height: number;
+    width: number;
+    image: string;
+    rectangleCoordinates?: Rectangle;
+    overlayColor?: string;
+    overlayStrokeColor?: string;
+    handlerColor?: string;
+    enablePanStrict?: boolean;
+    onDragEnd?: (coordinates: Rectangle) => void;
+  };
+
+  export const CustomImageCropper: ComponentType<CustomImageCropperProps>;
+}

package/src/index.ts

@@ -1 +1,15 @@
-export * from './DocScanner';
+// Main components
+export { DocScanner } from './DocScanner';
+export { CropEditor } from './CropEditor';
+
+// Types
+export type { Point, Quad, Rectangle, CapturedDocument } from './types';
+export type { DetectionConfig } from './DocScanner';
+
+// Utilities
+export {
+  quadToRectangle,
+  rectangleToQuad,
+  scaleCoordinates,
+  scaleRectangle,
+} from './utils/coordinate';

package/src/types.ts

@@ -1 +1,17 @@
 export type Point = { x: number; y: number };
+
+export type Quad = [Point, Point, Point, Point];
+
+export type Rectangle = {
+  topLeft: Point;
+  topRight: Point;
+  bottomRight: Point;
+  bottomLeft: Point;
+};
+
+export type CapturedDocument = {
+  path: string;
+  quad: Point[] | null;
+  width: number;
+  height: number;
+};

package/src/utils/coordinate.ts

@@ -0,0 +1,71 @@
+import type { Point, Rectangle } from '../types';
+
+/**
+ * Convert quad points array to Rectangle format for perspective cropper
+ * Assumes quad points are ordered: [topLeft, topRight, bottomRight, bottomLeft]
+ */
+export const quadToRectangle = (quad: Point[]): Rectangle | null => {
+  if (!quad || quad.length !== 4) {
+    return null;
+  }
+
+  return {
+    topLeft: quad[0],
+    topRight: quad[1],
+    bottomRight: quad[2],
+    bottomLeft: quad[3],
+  };
+};
+
+/**
+ * Convert Rectangle format back to quad points array
+ */
+export const rectangleToQuad = (rect: Rectangle): Point[] => {
+  return [
+    rect.topLeft,
+    rect.topRight,
+    rect.bottomRight,
+    rect.bottomLeft,
+  ];
+};
+
+/**
+ * Scale coordinates from one dimension to another
+ * Useful when image dimensions differ from display dimensions
+ */
+export const scaleCoordinates = (
+  points: Point[],
+  fromWidth: number,
+  fromHeight: number,
+  toWidth: number,
+  toHeight: number
+): Point[] => {
+  const scaleX = toWidth / fromWidth;
+  const scaleY = toHeight / fromHeight;
+
+  return points.map(p => ({
+    x: p.x * scaleX,
+    y: p.y * scaleY,
+  }));
+};
+
+/**
+ * Scale a rectangle
+ */
+export const scaleRectangle = (
+  rect: Rectangle,
+  fromWidth: number,
+  fromHeight: number,
+  toWidth: number,
+  toHeight: number
+): Rectangle => {
+  const scaleX = toWidth / fromWidth;
+  const scaleY = toHeight / fromHeight;
+
+  return {
+    topLeft: { x: rect.topLeft.x * scaleX, y: rect.topLeft.y * scaleY },
+    topRight: { x: rect.topRight.x * scaleX, y: rect.topRight.y * scaleY },
+    bottomRight: { x: rect.bottomRight.x * scaleX, y: rect.bottomRight.y * scaleY },
+    bottomLeft: { x: rect.bottomLeft.x * scaleX, y: rect.bottomLeft.y * scaleY },
+  };
+};