quadscan

Getting Started

quadscan detects the four corners of a document in a photo and perspective-warps it to an axis-aligned rectangle. All in the browser, no backend.

Install

npm install quadscan
# or
pnpm add quadscan
# or
yarn add quadscan
# or
bun add quadscan

Works with any bundler that understands ES modules (Vite, webpack, esbuild, Rollup, Parcel, Bun, …). The package is sideEffects: false and ships ESM.

Or, no bundler:

<script src="https://cdn.jsdelivr.net/npm/quadscan/dist/quadscan.iife.js"></script>
<script>
  const r = await Quadscan.scan(image);
  console.log(r.corners); // { topLeft, topRight, bottomRight, bottomLeft }
</script>

The IIFE build inlines onnxruntime-web and exposes a global Quadscan.

Hello world

import { Quadscan } from 'quadscan';

const result = await Quadscan.scan(file, { mode: 'extract' });

if (result.success) {
  console.log(result.corners); // { topLeft, topRight, bottomRight, bottomLeft }
  console.log(result.output);  // HTMLCanvasElement, the warped doc
} else {
  console.warn(result.message);
}

That’s it. The static Quadscan.scan() lazily instantiates a singleton on first call: the ~330 KB onnxruntime-web runtime and the 4.5 MB DocAligner model are fetched once and cached by the browser.

What you’ll see

scan() returns a ScanResult:

{
  success: true,
  message: 'OK',
  confidence: 0.94,
  output: <HTMLCanvasElement>, // the warped doc
  corners: { topLeft, topRight, bottomRight, bottomLeft },
  timings: [ { step: 'preprocess', ms: 8 }, ... ],
  debug: null
}

A failed detection (no document found) comes back as { success: false, message }, not an exception. True system errors (network failure loading the model, malformed input) do throw. See Troubleshooting.