Document Corner Capture

A document review tool with draggable corners and an image loupe, with configurable image, labels, palette, and fonts. Your app supplies capture results and the multipage collection.

How it works

1. Your host renders the camera preview and supplies an oriented, frozen image in response to a capture request. The component never opens a camera.
2. A single UI record drives the quadrilateral, exterior mask, corner handles, and magnifier. Coordinates always refer to the source image, through the shared cover scale and crop.
3. Each corner moves independently. Convexity, minimum edge length, minimum area, and image bounds constrain every proposal. Invalid movement is projected back along the movement segment without reordering corners.
4. A completed drag or coordinate nudge proposes corners to the host. Controlled corners remain authoritative; provisional geometry is restored if the host does not authorize the proposal.
5. Confirmation requests host acceptance. Only a matching response and effective accepted page list start the transfer. Over 740 ms, the captured quadrilateral straightens with a projective warp, crossfades to the host’s flat image, and springs into the page stack. This warp is visual only; export pixels remain the host’s responsibility.
6. Accepted page IDs remain stable. Reconfirming a page replaces it instead of increasing the count. Uncorrected originals keep an Original label.

This is a presentation and editing component. Detection, camera permissions, orientation, OCR, PDF creation, persistence, and pixel correction belong to the host.

Install

Copy the files listed in piece.json into your project, then install SDK-compatible dependencies:

npx expo install @shopify/react-native-skia expo-image react-native-gesture-handler react-native-reanimated react-native-worklets

Wrap your application in GestureHandlerRootView. Follow Skia's web setup when targeting browsers and load CanvasKit before mounting this component. The component does not install a router, font provider, camera, or safe-area provider.

Usage

A host response is required even in uncontrolled mode. This minimal example supplies an existing image after capture and accepts its original pixels:

import { useRef, useState } from 'react';
import DocumentCornerCapture, {
  type DocumentCornerCaptureHandle,
  type Page,
} from './document-corner-capture';

export function DocumentReview({ page, onSave }: {
  page: Page;
  onSave: (pages: readonly Page[]) => void;
}) {
  const ref = useRef<DocumentCornerCaptureHandle>(null);
  const [capture, setCapture] = useState<{ requestId: string; page: Page }>();
  const [acceptance, setAcceptance] = useState<{ requestId: string; page: Page }>();

  return (
    <DocumentCornerCapture
      ref={ref}
      capture={capture}
      acceptance={acceptance}
      onCaptureRequest={({ requestId }) => setCapture({ requestId, page })}
      onRetake={({ requestId }) => setCapture({ requestId, page })}
      onConfirm={({ requestId, corners }) =>
        setAcceptance({ requestId, page: { ...page, corners } })
      }
      onFinish={onSave}
    />
  );
}

onSave is your application's persistence callback. Supply renderPreview={() => <YourCameraPreview />} for a live preview. The slot is noninteractive; review and magnification always use the frozen image. A standalone source with imageSize and defaultStatus="review" uses the stable page ID source until a host capture supplies its own ID.

Controlled corners and personality knobs:

const [corners, setCorners] = useState<Quad>(page.corners);
const [revision, setRevision] = useState(0);

<DocumentCornerCapture
  source={page.source}
  imageSize={page.imageSize}
  defaultStatus="review"
  corners={corners}
  revision={revision}
  onCornersCommit={(next) => {
    setCorners(next);
    setRevision((value) => value + 1);
  }}
  colorScheme="dark"
  palette={{ accent: '#89DFC0', onAccent: '#102C22' }}
  loupeZoom={1.8}
  maskOpacity={0.32}
  motion={{ durationScale: 1, glowOpacity: 0.18 }}
  labels={{ title: 'Review your page', confirm: 'Keep page' }}
/>

Import Quad from the same entry point. Pair this example with the capture/acceptance handlers above to accept pages.

Props

Point={x:number,y:number}. Quad is a readonly tuple in physical TL, TR, BR, BL order. Each coordinate is normalized to the oriented source image; RTL does not mirror pixels.

Page={id,source,imageSize,corners,label,correctedSource?,correctedSize?}. Sources use expo-image's public source type. Supply the corrected dimensions when supplying corrected pixels. All IDs must be unique. Invalid geometry or dimensions block confirmation and show an error; unknown page IDs are ignored. Finite out-of-range movement is constrained, while nonfinite deltas are ignored. Nonfinite revision values fall back to zero. Duplicate or invalid pages are omitted from the displayed stack and block new capture/confirmation until the host supplies a valid list. Invalid host corners are never silently accepted as a replacement quad.

The handle exposes capture(), retake(), openPage(id), closeReview(), selectCorner(id), adjustCorner(id,delta), confirm(), finish(), and reset(). Programmatic actions request the same changes as touch actions. reset() invalidates pending request IDs and restores uncontrolled defaults. Late responses and duplicate response IDs are ignored. With controlled pages, publish the proposed page including its returned source, corrected source, and corners before acceptance is reported. Keep image source object identities stable between renders.

When controlling corners, update them when opening a different page as well as when accepting an edit. Controlled activePageId and status must also honor the corresponding callbacks. Confirmation does not repeat a geometry commit. Capture and processing wait for actual host data; neither fabricates pixels after a timeout.

Compatibility

Expo SDK 58, React Native 0.88.0 with New Architecture, React 19, Reanimated 4.7.1, Worklets 0.13.0, Gesture Handler 3.3, Skia 2.14.0, and Expo Image 58. Targets iOS, Android, and web with the installed stack. Compatible with Expo Go's bundled native modules; custom camera providers may require a development build.

The host owns safe areas and supplies a bounded flex container. The component uses a 3:4 viewer with 16-point side margins, a 24-point radius, and a shared cover transform for the photo and editing geometry. Short containers use a smaller 3:4 viewer; wide containers place controls beside it. The demo reserves a separate bottom bar for its theme controls. Coordinates recompute after resize or orientation changes. Fine adjustments open an overlay from the labeled coordinate icon. Keep the last camera frame mounted while preparing a page; a subtle 1.2-second sweep indicates progress.

Accessibility

Corner targets and controls are at least 48×48 points. Use Adjust coordinates to select a corner and move it with four labeled buttons. On web, corner selectors support arrows, Shift+arrow, Escape to cancel the active drag, and Enter to request acceptance. Completed nudges are commits; canceling later does not undo an already authorized edit.

Reduced motion replaces transfer movement with a 200 ms fade and removes scale feedback. The active geometry remains valid when the system preference changes. State changes can announce through formatAnnouncement; no per-frame announcements are generated. The -checkpoint accessibility label contains phase, page ID, authorized quad, accepted IDs, and revision for host automation. State and failures also have text; selection has a border and accessible selected state.

Stable suffixes include -capture, -confirm, -retake, -finish, -corner-tl/tr/br/bl, -select-tl/tr/br/bl, -page-<id>, -nudge-left/right/up/down, and -checkpoint.

Why this one

A free convex quadrilateral gives each document corner its own identity while the photograph stays still. The lens shows the same source detail under that corner. Request IDs and host authorization connect this visual editing workflow to a real capture pipeline without pretending to perform detection or image processing.

Demo artwork is original, supplied as coherent camera/flat pairs. Document layouts use the project's OFL fonts on an original generated tabletop. The Lumen lamp uses the project's Lucide kit (ISC). No reference imagery or reference branding ships with this folder.