EduOne Scanner SDK 📸

A high-performance, license-free, client-side document scanner SDK built for the EduOne platform. It utilizes a custom Web Worker architecture to run OpenCV.js and ONNX Runtime (WASM) off the main thread, delivering premium document detection, alignment, perspective cropping, and auto-capture without UI stutter.

Key Features

• ✨ Zero License Fees: Completely self-contained; no subscription or API key required.
• 🚀 Multi-Threaded Execution: Moves heavy image processing and ML inference to a Web Worker, keeping the main camera feed running at 60 FPS.
• 🤖 Smart Auto-Capture: Detects A4 document boundaries, tracks camera stability over frames, and auto-snaps once steady.
• 📏 Perspective Correction: Automatically crops and straightens captured documents to clean, rectangular JPEG outputs.
• 💡 Optimized Model Caching: Supports seamless pause()/resume() states when switching screens, avoiding multi-second OpenCV/ONNX reload times.
• 📱 Haptic & Visual Feedback: Includes device vibration on capture and a smooth, flying-thumbnail animation targetable to any gallery button.

Installation

You can install the SDK within your organisation's repositories using any of the following methods:

1. Direct from Git (Recommended)

Add the dependency directly to your target package.json pointing to your Git repository branch:

"dependencies": {
  "eduone-scanner-sdk": "git+https://github.com/fonixedu/eduone-scanner-sdk.git#main"
}

2. Local/Monorepo Reference

If developing inside a monorepo workspace or linking locally:

npm install ../eduone-scanner-sdk

Quick Start

1. Launching the Scanner UI Overlay

The easiest way to integrate the scanner is via the static startUI overlay, which handles the entire camera feed, guidelines, capture triggers, review grid, and page reordering.

import { DocumentScanner } from "eduone-scanner-sdk";

// Launch the fullscreen scanner overlay
const scannerUI = DocumentScanner.startUI({
  // URL path containing opencv.js, ONNX models, and WebAssembly assets
  assetsPath: "https://fonixedugrading.blob.core.windows.net/scanner-assets/",
  
  // (Optional) Override the logo in the header with your custom SVG markup
  logoHTML: `
    <svg width="120" height="24" viewBox="0 0 152 30" fill="none">
      <path d="..." fill="white"/>
    </svg>
  `,

  // Triggered when the user approves and submits the captured scans
  onComplete: async (pages: string[]) => {
    console.log("Captured cropped page DataURLs:", pages);
    // e.g., Upload each page to your server
  },

  // Triggered if the user cancels or closes the scanner overlay
  onCancel: () => {
    console.log("Scanner dismissed");
  }
});

// To programmatically close the scanner UI from parent application:
// scannerUI.stop();

API Configuration Options

DocumentScannerUIOptions

Passed as the argument to DocumentScanner.startUI(options):

| Option | Type | Required | Description | | :--- | :--- | :--- | :--- | | assetsPath | string | Yes | The base CDN or storage container URL containing OpenCV, WASM modules, and models (/onnx/, /opencv.js, etc.). | | onComplete | (pages: string[]) => void | Yes | Callback receiving an array of cropped document JPEGs formatted as base64 DataURLs. | | onCancel | () => void | No | Callback fired when the scanner is closed without submitting. | | logoHTML | string | No | Custom SVG/HTML markup to replace the default logo in the top header. |

Model Caching Design & Performance

To avoid multi-second pauses when navigating between screens, the SDK supports state preservation:

• pause(): Stops camera video tracks and disconnects resize observers but keeps the Web Worker and compiled WASM models alive in memory.
• resume(containerId): Re-acquires the camera stream and recreates rendering canvases instantly without reloading OpenCV or ONNX.

This lifecycle is handled automatically within startUI when opening the Captured Pages Review screen.

Development & Building

To make modifications to the SDK:

1. Install development dependencies:

   npm install

2. Build the production bundles (generates CommonJS, ESM, and TypeScript declaration files inside /dist):

   npm run build

Developed and Maintained by the EduOne Engineering Team.