@dile/scanner 0.0.9 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dile/scanner",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "description": "Web Component to scan documents in the browser: edge detection, perspective correction and multipage PDF or JPEG output, powered by scanic and jsPDF",
   "keywords": [
     "scanner",
@@ -36,5 +36,5 @@
     "scanic": "1.7.1",
     "scanic-ml": "0.2.0"
   },
-  "gitHead": "2aab20e22c7c9ea537e67ca7bacd392ee6936885"
+  "gitHead": "e48f49078bcae4a1c3f879c0c0d03e5445d1a535"
 }

package/src/DileScanner.js

@@ -53,7 +53,9 @@ const SIZE_FALLBACKS = [
 // them, rotate them, adjust them again and remove them. With "ml-detector"
 // the edges are detected with scanic's neural detector (about 2.2 MB
 // downloaded with gzip the first time the scanner opens) instead of the
-// classical one; off by default.
+// classical one; off by default. A photo waits for that download at most
+// "ml-max-wait" ms, and "ml-fast-connection-only" skips it on slow
+// connections.
 //
 // It does not upload anything: when the user saves, it dispatches
 // "dile-document-scanned" with the files and closes. Closing it without saving
@@ -357,6 +359,19 @@ export class DileScanner extends LitElement {
        * ONNX runtime). Empty: they are downloaded from jsDelivr.
        */
       mlAssetsUrl: { type: String, attribute: "ml-assets-url" },
+      /**
+       * Maximum time in milliseconds a photo waits for the ML detector while
+       * it downloads (0 means no limit). When it is not ready, the classical
+       * detector is used for that photo and the download goes on in the
+       * background.
+       */
+      mlMaxWait: { type: Number, attribute: "ml-max-wait" },
+      /**
+       * Does not download the ML detector when the browser reports a slow
+       * connection (2G, 3G or data saver), unless it is already in the cache
+       * (Cache Storage). The classical detector is used instead.
+       */
+      mlFastConnectionOnly: { type: Boolean, attribute: "ml-fast-connection-only" },
       _step: { type: String, state: true },
       _pages: { type: Array, state: true },
       _busy: { type: Boolean, state: true },
@@ -376,6 +391,8 @@ export class DileScanner extends LitElement {
     this.labels = {};
     this.mlDetector = false;
     this.mlAssetsUrl = "";
+    this.mlMaxWait = 5000;
+    this.mlFastConnectionOnly = false;
     this._step = "capture";
     this._pages = [];
     this._busy = false;
@@ -396,6 +413,15 @@ export class DileScanner extends LitElement {
     return { ...DEFAULT_LABELS, ...this.labels };
   }
 
+  get _engineOptions() {
+    return {
+      ml: this.mlDetector,
+      mlAssetsUrl: this.mlAssetsUrl,
+      mlMaxWait: this.mlMaxWait,
+      mlFastConnectionOnly: this.mlFastConnectionOnly,
+    };
+  }
+
   get _modal() {
     return this.shadowRoot.getElementById("modal");
   }
@@ -404,7 +430,7 @@ export class DileScanner extends LitElement {
   open() {
     this._reset();
     this._saved = false;
-    preloadEngine({ ml: this.mlDetector, mlAssetsUrl: this.mlAssetsUrl });
+    preloadEngine(this._engineOptions);
     this._modal.open();
   }
 
@@ -697,10 +723,7 @@ export class DileScanner extends LitElement {
     }
     try {
       const [corners, sourceBlob] = await Promise.all([
-        detectCorners(canvas, {
-          ml: this.mlDetector,
-          mlAssetsUrl: this.mlAssetsUrl,
-        }).catch(() => null),
+        detectCorners(canvas, this._engineOptions).catch(() => null),
         canvasToBlob(canvas, "image/jpeg", SOURCE_QUALITY),
       ]);
       if (session !== this._session) {

package/src/scanner-engine.js

@@ -12,28 +12,121 @@ function loadScanic() {
   return scanicModule;
 }
 
+// Base URL of the "scanic-ml" files when no mlAssetsUrl is given. scanic uses
+// the same one internally; it is repeated here to look for the files in the
+// cache (see isMlCached). scanner-ml.spec.js checks that its version matches
+// the installed "scanic-ml".
+export const CDN_ML_ASSETS_URL = "https://cdn.jsdelivr.net/npm/scanic-ml@0.2.0/dist/";
+
+// The two big files of the ML detector (the .mjs loader is tiny).
+const ML_CACHE_CHECK_FILES = ["doccornernet_lean.ort", "ort-wasm-simd-threaded.wasm"];
+
+// Connections where downloading about 2.2 MB takes too long (see
+// isSlowConnection).
+const SLOW_CONNECTION_TYPES = ["slow-2g", "2g", "3g"];
+
+// scanic aborts the download of the model after 30 s by default. The download
+// goes on in the background even when a photo stops waiting for it (see
+// mlMaxWait), so it gets a much longer limit: on a slow connection it would
+// never finish (nor reach the cache) with 30 s, and with no limit at all a
+// stalled connection would keep it pending until the page is reloaded.
+const ML_MODEL_FETCH_TIMEOUT_MS = 5 * 60 * 1000;
+
+// Loading of the ML detector: { key, promise }. The promise resolves to true
+// when it is ready and to false when it fails or is skipped (slow connection),
+// and never rejects. It is forgotten when it does not end ready, so the next
+// open() or photo decides again (e.g. the network is back or got faster).
+let mlLoad = null;
+
 // Starts downloading scanic in the background (e.g. when the scanner opens),
 // so it is ready by the time the first photo arrives. With "ml" it also
-// downloads the neural detector files and creates its session, so the first
-// photo does not wait for about 2.2 MB. scanic keeps the session cached by
-// URL (also while it is loading), so detectCorners() reuses it and calling
-// this on every open() downloads nothing again. When it fails (e.g. no
-// network) scanic forgets it, so the next open() or photo tries again.
-// Scanner.initialize() ignores errors itself.
-export function preloadEngine({ ml = false, mlAssetsUrl = "" } = {}) {
-  loadScanic()
-    .then(({ Scanner }) => {
-      if (ml) {
-        return new Scanner({ detector: "ml", ml: mlOptions(mlAssetsUrl) }).initialize();
+// prepares the neural detector (see loadMl), so the first photo does not wait
+// for about 2.2 MB. Calling it on every open() downloads nothing again.
+export function preloadEngine({ ml = false, mlAssetsUrl = "", mlFastConnectionOnly = false } = {}) {
+  loadScanic().catch(() => {
+    // Ignored here: the error shows up again when the engine is really used.
+  });
+  if (ml) {
+    loadMl({ mlAssetsUrl, mlFastConnectionOnly });
+  }
+}
+
+// Downloads the ML detector files and creates its session. scanic keeps the
+// session cached by URL, so detectCorners() reuses it. With
+// "mlFastConnectionOnly" nothing is downloaded on a slow connection, unless the
+// files are already in the cache.
+function loadMl({ mlAssetsUrl, mlFastConnectionOnly }) {
+  const key = mlAssetsUrl;
+  if (mlLoad?.key === key) {
+    return mlLoad.promise;
+  }
+  const current = {
+    key,
+    promise: (async () => {
+      if (mlFastConnectionOnly && isSlowConnection() && !(await isMlCached(mlAssetsUrl))) {
+        return false;
       }
-    })
-    .catch(() => {
-      // Ignored here: the error shows up again when the engine is really used.
-    });
+      const { Scanner } = await loadScanic();
+      await new Scanner({ detector: "ml", ml: mlOptions(mlAssetsUrl) }).initialize();
+      return true;
+    })().catch(() => false),
+  };
+  mlLoad = current;
+  current.promise.then((ready) => {
+    if (!ready && mlLoad === current) {
+      mlLoad = null;
+    }
+  });
+  return current.promise;
+}
+
+// True when the browser says the connection is slow or the user asked to save
+// data. Only Chromium browsers have navigator.connection: elsewhere (Safari,
+// Firefox) the connection is unknown and this returns false.
+export function isSlowConnection() {
+  const connection = globalThis.navigator?.connection;
+  if (!connection) {
+    return false;
+  }
+  return connection.saveData === true || SLOW_CONNECTION_TYPES.includes(connection.effectiveType);
+}
+
+// True when the ML files are in the Cache Storage (e.g. cached by the service
+// worker of a PWA). The HTTP cache of the browser can't be checked.
+export async function isMlCached(mlAssetsUrl = "") {
+  if (!globalThis.caches) {
+    return false;
+  }
+  try {
+    const base = new URL(mlAssetsUrl || CDN_ML_ASSETS_URL, document.baseURI);
+    const folder = base.href.endsWith("/") ? base.href : `${base.href}/`;
+    const matches = await Promise.all(
+      ML_CACHE_CHECK_FILES.map((file) => caches.match(new URL(file, folder).href)),
+    );
+    return matches.every(Boolean);
+  } catch {
+    return false;
+  }
 }
 
 function mlOptions(mlAssetsUrl) {
-  return mlAssetsUrl ? { assetBaseUrl: mlAssetsUrl } : {};
+  return {
+    ...(mlAssetsUrl ? { assetBaseUrl: mlAssetsUrl } : {}),
+    modelFetchTimeoutMs: ML_MODEL_FETCH_TIMEOUT_MS,
+  };
+}
+
+// Resolves to the value of the promise, or to false after "ms" milliseconds
+// (0 means no limit). The promise itself goes on.
+function withTimeout(promise, ms) {
+  if (!ms || ms <= 0) {
+    return promise;
+  }
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 
 // Returns the corners of the document or null when none is found.
@@ -45,14 +138,21 @@ function mlOptions(mlAssetsUrl) {
 // 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 (when the
-// scanner opens, see preloadEngine), 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 = "" } = {}) {
+// scanner opens, see preloadEngine), from jsDelivr unless mlAssetsUrl points
+// to a self-hosted copy of the "scanic-ml" package files.
+//
+// The photo waits for the ML detector at most "mlMaxWait" milliseconds (0
+// means no limit). When it is not ready by then, it was skipped (see
+// mlFastConnectionOnly), it finds nothing or fails (e.g. no network), the
+// classical detector is used. The download goes on in the background, so a
+// later photo or the next open() can use it.
+export async function detectCorners(
+  canvas,
+  { ml = false, mlAssetsUrl = "", mlMaxWait = 0, mlFastConnectionOnly = false } = {},
+) {
   const { Scanner } = await loadScanic();
   scanner ??= new Scanner();
-  if (ml) {
+  if (ml && (await withTimeout(loadMl({ mlAssetsUrl, mlFastConnectionOnly }), mlMaxWait))) {
     try {
       const mlResult = await scanner.scan(canvas, {
         mode: "detect",