react-native-rectangle-doc-scanner 0.1.0 → 0.2.0

package/README.md

@@ -5,25 +5,56 @@ VisionCamera + Fast-OpenCV powered document scanner template built for React Nat
 ## Features
 - Real-time quad detection using `react-native-fast-opencv`
 - Frame processor worklet executed on the UI thread via `react-native-vision-camera`
-- Resize plugin to keep frame processing fast on lower-end devices
-- Skia overlay for visualizing detected document contours
-- Stability tracker for auto-capture once the document is steady
+- Resize plugin keeps frame processing fast on lower-end devices
+- Skia overlay visualises detected document contours
+- Stability tracker enables auto-capture once the document is steady
+
+## Requirements
+Install the module alongside these peer dependencies (your host app should already include them or install them now):
+
+- `react-native-vision-camera` (v3+) with frame processors enabled
+- `vision-camera-resize-plugin`
+- `react-native-fast-opencv`
+- `react-native-reanimated` + `react-native-worklets-core`
+- `@shopify/react-native-skia`
+- `react`, `react-native`
 
 ## Installation
-Install the template as a package and make sure the peer dependencies already exist in your app:
 
 ```sh
-yarn add react-native-rectangle-doc-scanner
+yarn add react-native-rectangle-doc-scanner \
+  react-native-vision-camera \
+  vision-camera-resize-plugin \
+  react-native-fast-opencv \
+  react-native-reanimated \
+  react-native-worklets-core \
+  @shopify/react-native-skia
 ```
 
+Follow each dependency’s native installation guide:
+
+- Run `npx pod-install` after adding iOS dependencies.
+- For `react-native-reanimated`, add the Babel plugin, enable the JSI runtime, and ensure Reanimated is the first import in `index.js`.
+- Configure `react-native-fast-opencv` according to its README (adds native OpenCV binaries on both platforms).
+- For `react-native-vision-camera`, enable frame processors by adding the new architecture build and the proxy registration they describe. You must also request camera permissions at runtime.
+- Register the resize plugin once in native code (for example inside your `VisionCameraProxy` setup):
+
+  ```ts
+  import { VisionCameraProxy } from 'react-native-vision-camera';
+  import { ResizePlugin } from 'vision-camera-resize-plugin';
+
+  VisionCameraProxy.installFrameProcessorPlugin('resize', ResizePlugin);
+  ```
+
 ## Usage
+
 ```tsx
 import React from 'react';
-import { View } from 'react-native';
+import { StyleSheet, Text, TouchableOpacity, View } from 'react-native';
 import { DocScanner } from 'react-native-rectangle-doc-scanner';
 
 export const ScanScreen = () => (
-  <View style={{ flex: 1 }}>
+  <View style={styles.container}>
     <DocScanner
       onCapture={({ path, quad }) => {
         console.log('Document captured at', path, quad);
@@ -31,11 +62,51 @@ export const ScanScreen = () => (
       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>
 );
+
+const styles = StyleSheet.create({
+  container: { flex: 1 },
+  overlayControls: {
+    position: 'absolute',
+    bottom: 32,
+    alignSelf: 'center',
+  },
+  button: {
+    paddingHorizontal: 24,
+    paddingVertical: 12,
+    borderRadius: 999,
+    backgroundColor: 'rgba(0,0,0,0.7)',
+  },
+  label: { color: '#fff', fontWeight: '600' },
+});
 ```
 
+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
+
+- `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.
+
+### Notes on camera behaviour
+
+- If you disable `autoCapture`, the built-in shutter button appears; you can still provide your own UI as `children` to replace or augment it.
+- The internal frame processor handles document detection; do not override `frameProcessor` in `cameraProps`.
+- Adjust `minStableFrames` or tweak lighting conditions if auto capture is too sensitive or too slow.
+
 ## Build
 ```sh
 yarn build

package/dist/DocScanner.d.ts

@@ -1,5 +1,7 @@
-import React from 'react';
+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'>;
 interface Props {
     onCapture?: (photo: {
         path: string;
@@ -8,6 +10,8 @@ interface Props {
     overlayColor?: string;
     autoCapture?: boolean;
     minStableFrames?: number;
+    cameraProps?: CameraOverrides;
+    children?: ReactNode;
 }
 export declare const DocScanner: React.FC<Props>;
 export {};

package/dist/DocScanner.js

@@ -42,7 +42,7 @@ const react_native_reanimated_1 = require("react-native-reanimated");
 const react_native_fast_opencv_1 = require("react-native-fast-opencv");
 const overlay_1 = require("./utils/overlay");
 const stability_1 = require("./utils/stability");
-const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, minStableFrames = 8, }) => {
+const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, minStableFrames = 8, cameraProps, children, }) => {
     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)();
@@ -115,11 +115,13 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
         };
         capture();
     }, [autoCapture, minStableFrames, onCapture, quad, stable]);
-    if (!device || !hasPermission) {
+    const { device: overrideDevice, ...cameraRestProps } = cameraProps ?? {};
+    const resolvedDevice = overrideDevice ?? device;
+    if (!resolvedDevice || !hasPermission) {
         return null;
     }
     return (react_1.default.createElement(react_native_1.View, { style: { flex: 1 } },
-        react_1.default.createElement(react_native_vision_camera_1.Camera, { ref: handleCameraRef, style: react_native_1.StyleSheet.absoluteFillObject, device: device, isActive: true, photo: true, frameProcessor: frameProcessor, frameProcessorFps: 15 }),
+        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 }),
         !autoCapture && (react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.button, onPress: async () => {
                 if (!camera.current) {
@@ -127,7 +129,8 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
                 }
                 const photo = await camera.current.takePhoto({ qualityPrioritization: 'quality' });
                 onCapture?.({ path: photo.path, quad });
-            } }))));
+            } })),
+        children));
 };
 exports.DocScanner = DocScanner;
 const styles = react_native_1.StyleSheet.create({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-rectangle-doc-scanner",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {

package/src/DocScanner.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useRef, useState } from 'react';
+import React, { ReactNode, useCallback, useEffect, useRef, useState } from 'react';
 import { View, TouchableOpacity, StyleSheet } from 'react-native';
 import { Camera, useCameraDevice, useCameraPermission, useFrameProcessor } from 'react-native-vision-camera';
 import { useResizePlugin } from 'vision-camera-resize-plugin';
@@ -22,11 +22,15 @@ type CameraRef = {
   }>;
 };
 
+type CameraOverrides = Omit<React.ComponentProps<typeof Camera>, 'style' | 'ref' | 'frameProcessor'>;
+
 interface Props {
   onCapture?: (photo: { path: string; quad: Point[] | null }) => void;
   overlayColor?: string;
   autoCapture?: boolean;
   minStableFrames?: number;
+  cameraProps?: CameraOverrides;
+  children?: ReactNode;
 }
 
 export const DocScanner: React.FC<Props> = ({
@@ -34,6 +38,8 @@ export const DocScanner: React.FC<Props> = ({
   overlayColor = '#e7a649',
   autoCapture = true,
   minStableFrames = 8,
+  cameraProps,
+  children,
 }) => {
   const device = useCameraDevice('back');
   const { hasPermission, requestPermission } = useCameraPermission();
@@ -126,7 +132,10 @@ export const DocScanner: React.FC<Props> = ({
     capture();
   }, [autoCapture, minStableFrames, onCapture, quad, stable]);
 
-  if (!device || !hasPermission) {
+  const { device: overrideDevice, ...cameraRestProps } = cameraProps ?? {};
+  const resolvedDevice = overrideDevice ?? device;
+
+  if (!resolvedDevice || !hasPermission) {
     return null;
   }
 
@@ -135,11 +144,12 @@ export const DocScanner: React.FC<Props> = ({
       <Camera
         ref={handleCameraRef}
         style={StyleSheet.absoluteFillObject}
-        device={device}
+        device={resolvedDevice}
         isActive
         photo
         frameProcessor={frameProcessor}
         frameProcessorFps={15}
+        {...cameraRestProps}
       />
       <Overlay quad={quad} color={overlayColor} />
       {!autoCapture && (
@@ -155,6 +165,7 @@ export const DocScanner: React.FC<Props> = ({
           }}
         />
       )}
+      {children}
     </View>
   );
 };