quadscan

Self-hosting model & runtime

By default quadscan fetches both:

  • the .onnx model from cdn.jsdelivr.net/npm/quadscan@<version>/models/...
  • the onnxruntime-web .wasm runtime from cdn.jsdelivr.net/npm/onnxruntime-web@<version>/dist/

That makes the install zero-config. But if you need to ship offline, run behind a strict CSP, or want full control over caching headers, you can serve both yourself.

1. Bundle the model

The package exposes the model files via subpath exports:

// Vite / webpack: ?url asks the bundler to copy the file into the build and return a hashed URL.
import lcnetUrl from 'quadscan/models/lcnet?url';
import fastvitUrl from 'quadscan/models/fastvit?url';

const q = new Quadscan({ modelUrl: lcnetUrl });

The exports map (defined in the package):

{
  "exports": {
    ".": { "import": "./dist/quadscan.js", "types": "./dist/index.d.ts" },
    "./models/lcnet":   "./models/lcnet100_h_e_bifpn_256_fp32.onnx",
    "./models/fastvit": "./models/fastvit_t8_h_e_bifpn_256_fp32.onnx"
  }
}

Alternatively, copy the .onnx into public/ yourself and point at the public URL.

2. Bundle the ORT runtime

npm install onnxruntime-web

Copy node_modules/onnxruntime-web/dist/*.wasm (and the matching *.mjs loader scripts) into public/ort/ during your build. Then:

const q = new Quadscan({
  modelUrl: lcnetUrl,
  wasmPaths: '/ort/', // must end with a trailing slash
});

wasmPaths is passed straight to ort.env.wasm.wasmPaths. It tells ORT where to look for ort-wasm-simd-threaded.wasm etc. Whatever path you pass must serve those files with application/wasm MIME and (for the threaded build) Cross-Origin-Opener-Policy: same-origin + Cross-Origin-Embedder-Policy: require-corp.

3. CSP

If you serve under a strict Content-Security-Policy, you’ll need:

script-src 'self' 'wasm-unsafe-eval';
connect-src 'self';
worker-src 'self' blob:;

wasm-unsafe-eval is required by onnxruntime-web’s WASM execution provider. worker-src 'self' blob: is needed because ORT spawns its threaded worker from a Blob URL.

4. WebGPU-only deploy

If your target audience is WebGPU-capable and you want to drop the WASM runtime entirely, restrict execution providers:

const q = new Quadscan({
  modelUrl: lcnetUrl,
  executionProviders: ['webgpu'],
});

Note: onnxruntime-web still ships .wasm files even for WebGPU-only use in some shape-inference helpers. You can omit them, but you may see warnings. Test on your actual target browsers before stripping them.