API Reference

Single class, two static convenience methods, three custom errors.

class Quadscan

import { Quadscan } from 'quadscan';

const q = new Quadscan(options?);

A Quadscan instance holds an onnxruntime-web InferenceSession. Keep one warm for batch / real-time work; or skip the constructor entirely and use the static Quadscan.scan / Quadscan.extract for one-offs (they share a lazy internal singleton).

Constructor options: QuadscanOptions

Instance methods

async initialize(): Promise<void>

Eagerly download the model and create the ORT session. Optional; scan() and extract() do this on first call. Call it during app startup if you want to amortize the load.

async scan(input, options?): Promise<ScanResult>

Detect document corners; optionally perspective-warp.

input is one of:

async extract(input, corners, options?): Promise<ScanResult>

Perspective-warp input using user-supplied corners, skipping detection. Does not invoke the model, does not download it either. Use this when corners come from manual UI adjustment, a prior scan, or another detector.

dispose(): void

Release the ORT session. Subsequent scan() calls re-initialize. Idempotent.

[Symbol.dispose]()

Enables using q = new Quadscan() syntax (TypeScript 5.2+).

Static methods

ScanOptions

Per-call options for scan().

ProgressEvent

type ProgressEvent =
  | { phase: 'model-download'; loaded: number; total: number }
  | { phase: 'model-compile' }
  | { phase: 'preprocess' }
  | { phase: 'inference' }
  | { phase: 'decode' }
  | { phase: 'warp' };

model-download is the only event with progress; the rest are lifecycle markers. total may be 0 if the server didn’t send Content-Length.

ScanResult

interface ScanResult {
  success: boolean;
  message: string;
  confidence: number | null;
  output: HTMLCanvasElement | ImageData | string | null;
  corners: CornerPoints | null;
  timings: Timing[];
  debug: DebugInfo | null;
}

Always check result.success before reading corners or output. In TypeScript, the result is structurally typed. Narrow with if (r.success) and treat r.corners as non-null inside.

CornerPoints

interface CornerPoint { x: number; y: number; confidence: number }
interface CornerPoints {
  topLeft: CornerPoint;
  topRight: CornerPoint;
  bottomRight: CornerPoint;
  bottomLeft: CornerPoint;
}

Coordinates are in source-image pixels (not normalized). confidence is the heatmap peak value at that corner.

For input to extract(), confidence is optional and defaults to 1.

Errors

All errors inherit from QuadscanError and carry a stable code:

import { Quadscan, ModelLoadError } from 'quadscan';
try {
  await Quadscan.scan(file);
} catch (err) {
  if (err instanceof ModelLoadError) {
    console.error('Model fetch failed:', err.message, err.cause);
  } else throw err;
}

Failed detection (the model ran but found no document) is not an error. It comes back as { success: false, message } in the ScanResult.

Exports

export { Quadscan } from 'quadscan';
export {
  QuadscanError, ModelLoadError, InvalidInputError, DegenerateQuadError,
} from 'quadscan';
export type {
  ScanResult, ScanOptions, ScanInput, ScanMode, OutputFormat,
  CornerPoint, CornerPoints, CornerPointInput, CornerPointsInput,
  QuadscanOptions, ModelPreset, ExecutionProvider, Normalization,
  ProgressEvent, Timing, DebugInfo,
} from 'quadscan';