@dile/scanner 0.0.0-stage → 0.0.2

package/src/corner-editor-styles.js

@@ -0,0 +1,101 @@
+import { css } from "lit";
+
+// Styles of scanic's corner editor (scanic 1.7.1). scanic injects them into
+// document.head, which does not reach the shadow root, so the component
+// includes them. Only the handles are needed: the toolbar and the nudge pad
+// are disabled. Review this copy when updating scanic.
+export const cornerEditorStyles = css`
+  .scanic-corner-editor {
+    --scanic-accent: var(--dile-scanner-accent-color, var(--dile-primary-color, #6366f1));
+    --scanic-mask: var(--dile-scanner-mask-color, rgba(15, 23, 42, 0.45));
+    --scanic-edge-color: var(--scanic-accent);
+    --scanic-edge-width: 2.5;
+    --scanic-handle-size: 22px;
+    --scanic-handle-hit: 44px;
+    --scanic-handle-color: #ffffff;
+    --scanic-handle-ring: 2px;
+    --scanic-handle-ring-color: var(--scanic-accent);
+    --scanic-handle-shadow: 0 1px 4px rgba(15, 23, 42, 0.45);
+    --scanic-handle-active-shadow: 0 8px 22px rgba(15, 23, 42, 0.5);
+    --scanic-handle-active-scale: 1.28;
+  }
+  .scanic-handle {
+    position: absolute;
+    box-sizing: border-box;
+    width: var(--scanic-handle-size);
+    height: var(--scanic-handle-size);
+    margin: 0;
+    padding: 0;
+    border: var(--scanic-handle-ring) solid var(--scanic-handle-ring-color);
+    border-radius: 50%;
+    background: var(--scanic-handle-color);
+    box-shadow: var(--scanic-handle-shadow);
+    transform: translate(-50%, -50%);
+    cursor: grab;
+    touch-action: none;
+    z-index: 2;
+    transition:
+      transform 0.12s ease,
+      box-shadow 0.12s ease,
+      background 0.12s ease,
+      border-color 0.12s ease;
+  }
+  /* Enlarges the touch target without changing the visual size. */
+  .scanic-handle::after {
+    content: "";
+    position: absolute;
+    left: 50%;
+    top: 50%;
+    width: var(--scanic-handle-hit);
+    height: var(--scanic-handle-hit);
+    transform: translate(-50%, -50%);
+    border-radius: 50%;
+  }
+  .scanic-handle::before {
+    content: "";
+    position: absolute;
+    left: 50%;
+    top: 50%;
+    width: 0;
+    height: 0;
+    border-radius: 50%;
+    background: var(--scanic-accent);
+    opacity: 0;
+    transform: translate(-50%, -50%);
+    transition:
+      opacity 0.15s ease,
+      width 0.15s ease,
+      height 0.15s ease;
+    pointer-events: none;
+  }
+  .scanic-handle:hover {
+    transform: translate(-50%, -50%) scale(1.12);
+  }
+  .scanic-handle:focus-visible {
+    outline: none;
+    box-shadow:
+      0 0 0 3px color-mix(in srgb, var(--scanic-accent) 45%, transparent),
+      var(--scanic-handle-shadow);
+  }
+  .scanic-handle.is-selected {
+    border-color: var(--scanic-accent);
+    transform: translate(-50%, -50%) scale(1.12);
+  }
+  .scanic-handle.is-selected::before {
+    opacity: 0.16;
+    width: calc(var(--scanic-handle-size) * 2);
+    height: calc(var(--scanic-handle-size) * 2);
+  }
+  .scanic-handle.is-active {
+    cursor: grabbing;
+    background: var(--scanic-accent);
+    border-color: #ffffff;
+    transform: translate(-50%, -50%) scale(var(--scanic-handle-active-scale));
+    box-shadow: var(--scanic-handle-active-shadow);
+  }
+  .scanic-handle.is-active::before {
+    opacity: 0.22;
+    width: calc(var(--scanic-handle-size) * 2.8);
+    height: calc(var(--scanic-handle-size) * 2.8);
+  }
+`;

package/src/default-labels.js

@@ -0,0 +1,41 @@
+// Texts of the scanner. Pass a partial object in the "labels" property to
+// translate or change any of them; the missing ones keep these defaults.
+export const DEFAULT_LABELS = {
+  title: "Scan document",
+  captureHint:
+    "Take a photo of the document or choose an image. You will be able to adjust the edges before saving it.",
+  takePhoto: "Take photo",
+  chooseImage: "Choose image",
+  addPhoto: "Add photo",
+  addImage: "Add image",
+  retakePhoto: "Repeat photo",
+  replaceImage: "Choose another image",
+  adjustHint: "Drag the corners to the edges of the document.",
+  notDetected:
+    "The edges of the document were not detected. Drag the corners to the edges of the document.",
+  reset: "Reset",
+  useFullImage: "Use full image",
+  accept: "Accept",
+  cancel: "Cancel",
+  confirm: "Save document",
+  page: "Page",
+  rotate: "Rotate",
+  adjust: "Adjust edges",
+  moveBefore: "Move before",
+  moveAfter: "Move after",
+  remove: "Remove page",
+  processing: "Processing…",
+  readError:
+    "The image could not be read. Try with another image (JPG, PNG or WebP).",
+  processError: "The image could not be processed. Try again.",
+  sizeLimitReached:
+    "The document has reached the maximum size. Remove a page to add another one.",
+  tooBig:
+    "The document exceeds the maximum size even with reduced quality. Remove some pages.",
+  sizeOf: "of",
+  filenamePrefix: "scan",
+  topLeftCorner: "Top-left corner",
+  topRightCorner: "Top-right corner",
+  bottomRightCorner: "Bottom-right corner",
+  bottomLeftCorner: "Bottom-left corner",
+};

package/src/image-utils.js

@@ -0,0 +1,86 @@
+// Canvas helpers for the scanner. Every image is handled as a canvas while it
+// is being processed and stored as a JPEG Blob afterwards, so a document with
+// many pages does not keep several full-size canvases in memory.
+
+// Decodes an image file into a canvas, applying the EXIF orientation and
+// reducing it so its longest side is at most maxSide. iOS limits the area of
+// a canvas (about 16.7 megapixels) and current phone cameras go well beyond
+// that, so the reduction is also what makes big photos work at all.
+export async function fileToCanvas(file, maxSide) {
+  const bitmap = await createImageBitmap(file, {
+    imageOrientation: "from-image",
+  });
+  try {
+    return drawScaled(bitmap, bitmap.width, bitmap.height, maxSide);
+  } finally {
+    bitmap.close();
+  }
+}
+
+export async function blobToCanvas(blob) {
+  const bitmap = await createImageBitmap(blob);
+  try {
+    return drawScaled(bitmap, bitmap.width, bitmap.height, Infinity);
+  } finally {
+    bitmap.close();
+  }
+}
+
+export function canvasToBlob(canvas, type = "image/jpeg", quality = 0.92) {
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (blob) =>
+        blob ? resolve(blob) : reject(new Error("Canvas could not be encoded")),
+      type,
+      quality,
+    );
+  });
+}
+
+// Rotates clockwise in steps of 90 degrees.
+export function rotateCanvas(canvas, rotation) {
+  const turns = (((rotation / 90) % 4) + 4) % 4;
+  if (turns === 0) {
+    return canvas;
+  }
+  const rotated = document.createElement("canvas");
+  const swapSides = turns % 2 === 1;
+  rotated.width = swapSides ? canvas.height : canvas.width;
+  rotated.height = swapSides ? canvas.width : canvas.height;
+  const context = rotated.getContext("2d");
+  context.translate(rotated.width / 2, rotated.height / 2);
+  context.rotate((turns * Math.PI) / 2);
+  context.drawImage(canvas, -canvas.width / 2, -canvas.height / 2);
+  return rotated;
+}
+
+// Final encoding of a page: limits the longest side and compresses to JPEG
+// over a white background (a transparent PNG would turn black otherwise).
+export async function encodeJpeg(canvas, { maxSide, quality }) {
+  const scaled = drawScaled(canvas, canvas.width, canvas.height, maxSide, true);
+  const blob = await canvasToBlob(scaled, "image/jpeg", quality);
+  return { blob, width: scaled.width, height: scaled.height };
+}
+
+export function fullImageCorners(width, height) {
+  return {
+    topLeft: { x: 0, y: 0 },
+    topRight: { x: width, y: 0 },
+    bottomRight: { x: width, y: height },
+    bottomLeft: { x: 0, y: height },
+  };
+}
+
+function drawScaled(source, width, height, maxSide, whiteBackground = false) {
+  const scale = Math.min(1, maxSide / Math.max(width, height));
+  const canvas = document.createElement("canvas");
+  canvas.width = Math.max(1, Math.round(width * scale));
+  canvas.height = Math.max(1, Math.round(height * scale));
+  const context = canvas.getContext("2d");
+  if (whiteBackground) {
+    context.fillStyle = "#ffffff";
+    context.fillRect(0, 0, canvas.width, canvas.height);
+  }
+  context.drawImage(source, 0, 0, canvas.width, canvas.height);
+  return canvas;
+}

package/src/pdf-builder.js

@@ -0,0 +1,31 @@
+// Joins the scanned pages (JPEG) into a PDF. jsPDF embeds each JPEG as it is
+// (DCTDecode), without encoding it again, so the PDF weighs about the same as
+// the sum of its pages.
+//
+// Each PDF page takes the proportions of its image (a receipt stays narrow
+// instead of being stretched to A4). The physical size is computed at
+// PAGE_DPI, so a full-width scan of an A4 page prints at roughly A4 size.
+
+const PAGE_DPI = 170;
+const POINTS_PER_INCH = 72;
+
+export async function buildPdf(pages, filename) {
+  const { jsPDF } = await import("jspdf");
+  let pdf;
+  for (const page of pages) {
+    const width = (page.width * POINTS_PER_INCH) / PAGE_DPI;
+    const height = (page.height * POINTS_PER_INCH) / PAGE_DPI;
+    const orientation = width > height ? "landscape" : "portrait";
+    if (pdf) {
+      pdf.addPage([width, height], orientation);
+    } else {
+      pdf = new jsPDF({ unit: "pt", format: [width, height], orientation });
+    }
+    const bytes = new Uint8Array(await page.blob.arrayBuffer());
+    pdf.addImage(bytes, "JPEG", 0, 0, width, height, undefined, "NONE");
+  }
+  return new File([pdf.output("blob")], filename, {
+    type: "application/pdf",
+    lastModified: Date.now(),
+  });
+}

package/src/scanner-engine.js

@@ -0,0 +1,98 @@
+// The only module that talks to scanic (edge detection, perspective
+// correction and the corner editor). Keeping it isolated allows replacing the
+// library (e.g. with OpenCV.js) without touching the component.
+//
+// scanic is loaded on demand, so it is only downloaded when someone scans.
+
+let scanicModule;
+let scanner;
+
+function loadScanic() {
+  scanicModule ??= import("scanic");
+  return scanicModule;
+}
+
+// Starts downloading scanic in the background (e.g. when the scanner opens),
+// so it is ready by the time the first photo arrives.
+export function preloadEngine() {
+  loadScanic().catch(() => {
+    // Ignored here: the error shows up again when the engine is really used.
+  });
+}
+
+// Returns the corners of the document or null when none is found.
+//
+// By default it uses the classical detector (Canny, included in scanic).
+// With "ml" it uses scanic's neural detector first, more robust with
+// cluttered backgrounds, low contrast or strong perspective. It goes first,
+// not as a retry, because on hard photos the classical detector does not
+// always fail: it can return a wrong shape (e.g. a line of text) as if it
+// were the document. The neural detector downloads about 2.2 MB with gzip
+// (3.5 MB uncompressed: model + ONNX runtime) the first time, from jsDelivr
+// unless mlAssetsUrl points to a self-hosted copy of the "scanic-ml" package
+// files. When it finds nothing or fails (e.g. no network), the classical
+// detector is used.
+export async function detectCorners(canvas, { ml = false, mlAssetsUrl = "" } = {}) {
+  const { Scanner } = await loadScanic();
+  scanner ??= new Scanner();
+  if (ml) {
+    try {
+      const mlResult = await scanner.scan(canvas, {
+        mode: "detect",
+        detector: "ml",
+        ml: mlAssetsUrl ? { assetBaseUrl: mlAssetsUrl } : {},
+      });
+      if (mlResult.success) {
+        return mlResult.corners;
+      }
+    } catch {
+      // Falls back to the classical detector.
+    }
+  }
+  const result = await scanner.scan(canvas, { mode: "detect" });
+  return result.success ? result.corners : null;
+}
+
+// Perspective correction: returns a new canvas with the document straightened.
+export async function extractDocument(canvas, corners) {
+  const { extractDocument } = await loadScanic();
+  const result = await extractDocument(canvas, corners, { output: "canvas" });
+  if (!result.success || !result.output) {
+    throw new Error(result.message || "The document could not be extracted");
+  }
+  return result.output;
+}
+
+// scanic injects its stylesheet into document.head, which does not reach a
+// shadow root, so it is disabled and the component provides the styles
+// (corner-editor-styles.js). Its toolbar is disabled too: the component uses
+// its own buttons, calling reset(), getCorners() and setCorners().
+export async function createCornerEditor({ container, image, corners, labels }) {
+  const { createCornerEditor } = await loadScanic();
+  const editor = createCornerEditor({
+    container,
+    image,
+    corners: corners ?? undefined,
+    injectStyles: false,
+    toolbar: { enabled: false },
+    magnifier: { zoom: 2, size: 110 },
+  });
+  translateHandles(container, labels);
+  return editor;
+}
+
+// scanic labels the handles in English and does not allow changing it.
+function translateHandles(container, labels) {
+  const handleLabels = {
+    topLeft: labels.topLeftCorner,
+    topRight: labels.topRightCorner,
+    bottomRight: labels.bottomRightCorner,
+    bottomLeft: labels.bottomLeftCorner,
+  };
+  for (const handle of container.querySelectorAll(".scanic-handle")) {
+    const label = handleLabels[handle.dataset.corner];
+    if (label) {
+      handle.setAttribute("aria-label", label);
+    }
+  }
+}

package/test/scanner-test-helpers.js

@@ -0,0 +1,183 @@
+// Shared helpers for the dile-scanner component tests.
+
+// Synthetic photo of a document: dark noisy background and a light sheet of
+// paper in perspective with some lines of "text".
+export function documentCanvas({ width = 1200, height = 900, background = 'dark' } = {}) {
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  const context = canvas.getContext('2d');
+  context.fillStyle = background === 'dark' ? '#2b2b2b' : '#d8d4cc';
+  context.fillRect(0, 0, width, height);
+  for (let i = 0; i < 4000; i++) {
+    const shade = background === 'dark' ? 30 + Math.random() * 40 : 190 + Math.random() * 40;
+    context.fillStyle = `rgb(${shade},${shade},${shade})`;
+    context.fillRect(Math.random() * width, Math.random() * height, 3, 3);
+  }
+  const quad = [
+    [width * 0.22, height * 0.12],
+    [width * 0.8, height * 0.16],
+    [width * 0.84, height * 0.88],
+    [width * 0.16, height * 0.84],
+  ];
+  context.fillStyle = '#f7f7f2';
+  context.beginPath();
+  quad.forEach(([x, y], index) => (index ? context.lineTo(x, y) : context.moveTo(x, y)));
+  context.closePath();
+  context.fill();
+  context.fillStyle = '#555';
+  for (let line = 0; line < 12; line++) {
+    const y = height * (0.25 + line * 0.045);
+    context.fillRect(width * 0.3, y, width * (0.35 + (line % 3) * 0.05), 6);
+  }
+  return canvas;
+}
+
+// Light sheet of paper with dark lines of text over a light wood-like
+// texture. The classical detector picks a line of text as the document; the
+// ML detector finds the sheet. Uses a seeded random so it is always the same.
+export function hardDocumentCanvas({ width = 1200, height = 900, seed = 7 } = {}) {
+  const random = seededRandom(seed);
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  const context = canvas.getContext('2d');
+  context.fillStyle = '#e2ddd3';
+  context.fillRect(0, 0, width, height);
+  for (let i = 0; i < 260; i++) {
+    const shade = 170 + random() * 60;
+    const y = random() * height;
+    context.strokeStyle = `rgb(${shade},${shade - 8},${shade - 20})`;
+    context.lineWidth = 1 + random() * 4;
+    context.beginPath();
+    context.moveTo(0, y);
+    context.bezierCurveTo(width / 3, y + 30, (width * 2) / 3, y - 30, width, y + random() * 20);
+    context.stroke();
+  }
+  const quad = [
+    [width * 0.22, height * 0.12],
+    [width * 0.8, height * 0.16],
+    [width * 0.84, height * 0.88],
+    [width * 0.16, height * 0.84],
+  ];
+  context.fillStyle = '#f5f4ef';
+  context.beginPath();
+  quad.forEach(([x, y], index) => (index ? context.lineTo(x, y) : context.moveTo(x, y)));
+  context.closePath();
+  context.fill();
+  context.fillStyle = '#222';
+  for (let line = 0; line < 14; line++) {
+    const y = height * (0.22 + line * 0.045);
+    context.fillRect(width * 0.28, y, width * (0.4 + (line % 3) * 0.05), 9);
+  }
+  return canvas;
+}
+
+function seededRandom(seed) {
+  return () => {
+    seed = (seed + 0x6d2b79f5) | 0;
+    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export function canvasToFile(canvas, name = 'photo.jpg', type = 'image/jpeg') {
+  return new Promise((resolve) => {
+    canvas.toBlob((blob) => resolve(new File([blob], name, { type })), type, 0.92);
+  });
+}
+
+export function documentFile(options) {
+  return canvasToFile(documentCanvas(options));
+}
+
+export function waitFor(fn, timeout = 15000) {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const check = () => {
+      const result = fn();
+      if (result) return resolve(result);
+      if (Date.now() - start > timeout) return reject(new Error('waitFor timed out'));
+      setTimeout(check, 20);
+    };
+    check();
+  });
+}
+
+export function nextEvent(el, eventName) {
+  return new Promise((resolve) => {
+    el.addEventListener(eventName, resolve, { once: true });
+  });
+}
+
+export async function imageSize(blob) {
+  const bitmap = await createImageBitmap(blob);
+  const size = { width: bitmap.width, height: bitmap.height };
+  bitmap.close();
+  return size;
+}
+
+export async function renderScanner(attrs = '') {
+  document.body.innerHTML = `<dile-scanner ${attrs}></dile-scanner>`;
+  const el = document.body.querySelector('dile-scanner');
+  await el.updateComplete;
+  return el;
+}
+
+export async function openScanner(attrs) {
+  const el = await renderScanner(attrs);
+  el.open();
+  await el.updateComplete;
+  return el;
+}
+
+export const query = (el, selector) => el.shadowRoot.querySelector(selector);
+export const queryAll = (el, selector) => [...el.shadowRoot.querySelectorAll(selector)];
+export const button = (el, icon) => query(el, `.step:not([hidden]) dile-button[icon="lucide.${icon}"]`);
+export const pageButtons = (el, icon) => queryAll(el, `.page dile-button[icon="lucide.${icon}"]`);
+export const pages = (el) => queryAll(el, '.page');
+export const errorMessage = (el) => query(el, '.message.error')?.textContent.trim();
+
+export function selectFiles(el, files, inputId = 'galleryinput') {
+  const input = query(el, `#${inputId}`);
+  const transfer = new DataTransfer();
+  files.forEach((file) => transfer.items.add(file));
+  input.files = transfer.files;
+  input.dispatchEvent(new Event('change'));
+}
+
+export async function waitForIdle(el) {
+  await el.updateComplete;
+  await waitFor(() => !query(el, '.busy'));
+}
+
+export function waitForEditor(el) {
+  return waitFor(() => !query(el, '.busy') && query(el, '#editor .scanic-handle'));
+}
+
+export function waitForPages(el, count) {
+  return waitFor(() => !query(el, '.busy') && pages(el).length === count && query(el, '.pages'));
+}
+
+export async function acceptAdjust(el) {
+  await waitForEditor(el);
+  button(el, 'check').click();
+}
+
+// Adds the files, accepting the detected corners of each one.
+export async function scanFiles(el, files) {
+  const expected = pages(el).length + (el.multipage ? files.length : Math.max(0, 1 - pages(el).length));
+  selectFiles(el, files);
+  for (let i = 0; i < (el.multipage ? files.length : 1); i++) {
+    await acceptAdjust(el);
+    await waitForIdle(el);
+  }
+  await waitForPages(el, expected);
+}
+
+export async function save(el) {
+  const scanned = nextEvent(el, 'dile-document-scanned');
+  button(el, 'check').click();
+  return (await scanned).detail;
+}

package/vite-plugin.js

@@ -0,0 +1,64 @@
+// Vite plugin that serves a self-hosted copy of the ML detector files
+// ("scanic-ml" package, installed with @dile/scanner at the version that
+// matches its scanic version). Use it with the "ml-assets-url" attribute:
+//
+//   // vite.config.js
+//   import { scannerMlAssets } from '@dile/scanner/vite-plugin.js';
+//   export default { plugins: [scannerMlAssets()] };
+//
+//   <dile-scanner ml-detector ml-assets-url="/dile-scanner-ml/"></dile-scanner>
+//
+// The files are served by the dev server and copied to the build with their
+// original names (scanic expects them together in one folder). They are only
+// downloaded by the browser when the ML detector is actually used.
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+
+export const ML_ASSET_FILES = [
+  "doccornernet_lean.ort",
+  "ort-wasm-simd-threaded.mjs",
+  "ort-wasm-simd-threaded.wasm",
+];
+
+const CONTENT_TYPES = {
+  ".ort": "application/octet-stream",
+  ".mjs": "text/javascript",
+  ".wasm": "application/wasm",
+};
+
+// Folder of the "scanic-ml" files, resolved from this package so it is the
+// version pinned by @dile/scanner.
+export function mlAssetsDir() {
+  const require = createRequire(import.meta.url);
+  return join(dirname(require.resolve("scanic-ml/package.json")), "dist");
+}
+
+export function scannerMlAssets({ path = "dile-scanner-ml" } = {}) {
+  const folder = path.replace(/^\/+|\/+$/g, "");
+  const assetsDir = mlAssetsDir();
+  return {
+    name: "dile-scanner-ml-assets",
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const prefix = `${server.config.base}${folder}/`;
+        const url = req.url.split("?")[0];
+        const file = url.startsWith(prefix) ? url.slice(prefix.length) : null;
+        if (!ML_ASSET_FILES.includes(file)) {
+          return next();
+        }
+        res.setHeader("Content-Type", CONTENT_TYPES[extname(file)]);
+        res.end(readFileSync(join(assetsDir, file)));
+      });
+    },
+    generateBundle() {
+      for (const file of ML_ASSET_FILES) {
+        this.emitFile({
+          type: "asset",
+          fileName: `${folder}/${file}`,
+          source: readFileSync(join(assetsDir, file)),
+        });
+      }
+    },
+  };
+}