Rename options

Author: paulmillr

benchmark/decode-quality.ts

@@ -61,7 +61,7 @@ function runCategory(files) {
     if (vector.expected) stats.expected++;
     let decoded;
     try {
-      decoded = decodeQR(readImage(vector.path), { moreEffort: true });
+      decoded = decodeQR(readImage(vector.path), { multiPass: 'max' });
     } catch {
       stats.errors++;
     }

src/decode.ts

@@ -2325,21 +2325,19 @@ export type DecodeOpts = {
    */
   grid?: DecodeGrid;
   /**
-   * Retry failed decodes with inverted colors (light-on-dark codes, screens)
-   * and 2x..32x box-downscaled rasters (codes overflowing the frame, moire).
+   * Adaptive multi-pass detection.
    *
-   * Enabled by default: both retries only run after the primary pass fails,
-   * so images that already decode pay nothing. Set to `false` to disable.
+   * - `true` (default): for large frames, detect on a downscaled raster
+   *   first; retry failed decodes with inverted colors (light-on-dark codes,
+   *   screens) and 2x..32x box-downscaled rasters (codes overflowing the
+   *   frame, moire). Extra passes only run after the primary pass fails, so
+   *   images that already decode pay nothing.
+   * - `'max'`: additionally try rotated, cropped, and upscaled fallback
+   *   candidates — decodes more hard images, but can be several times
+   *   slower on frames that still fail.
+   * - `false`: strict single-pass decode.
    */
-  invertDownscale?: boolean;
-  /**
-   * Try rotated, cropped, and upscaled fallback candidates after the primary
-   * decode attempt fails.
-   *
-   * Disabled by default because these retries can be much slower on hard
-   * failures.
-   */
-  moreEffort?: boolean;
+  multiPass?: boolean | 'max';
   /**
    * Custom byte-to-text decoder used for byte segments.
    *
@@ -2467,7 +2465,7 @@ function cropImageWithOffset(
 
 // Fallback candidates copy pixels with plain byte moves: a per-pixel
 // `data.subarray()` + `set()` allocated millions of temporary views per frame
-// and dominated moreEffort profiles (~57% self time on 9MP failures).
+// and dominated multiPass:'max' profiles (~57% self time on 9MP failures).
 function copyPixel(
   dst: Uint8Array,
   dstPos: number,
@@ -2642,7 +2640,11 @@ function visitFallbackImageCandidates(img: TArg<Image>, visit: CandidateVisitor)
   // from nearest-neighbor upscaling, while large multi-QR scenes need window
   // crops before full-frame rotations. This also avoids allocating three full
   // rotated frames before trying the much smaller windows on >4MP images.
-  if (area <= 150_000) {
+  // Upscaling adds no pixels of information, but it shrinks the binarizer's
+  // fixed 8x8 blocks relative to the modules — a cheap stand-in for a
+  // finer-grained binarizer. 1MP was measured as the sweet spot on BoofCV
+  // (multiPass:'max' 344->353); 2.5MP decodes nothing more and costs 18% extra.
+  if (area <= 1_000_000) {
     const found = visitRotatedImageCandidates(base, (candidate) => {
       if (visit(scaleNearestCandidate(candidate, 2))) return true;
       return visit(scaleNearestCandidate(candidate, 3));
@@ -2770,8 +2772,8 @@ function decodePreparedImage(
   // color-inverted bitmap (ISO/IEC 18004:2024 §12 b)5 reflectance reversal):
   // light-on-dark codes can fail at any stage after the finder, so the legacy
   // finder-level negate retry inside detectTriples() is not enough.
-  // `opts.invertDownscale: false` keeps only the legacy finder-level retry.
-  const fullInvert = options.invertDownscale !== false;
+  // `opts.multiPass: false` keeps only the legacy finder-level retry.
+  const fullInvert = options.multiPass !== false;
   let lastErr: unknown;
   for (let polarity = 0; polarity < 2; polarity++) {
     let triples;
@@ -2964,12 +2966,12 @@ function validateDecodeOptions(opts: TArg<DecodeOpts>): DecodeOpts {
   const options = validateObject(opts, 'opts') as DecodeOpts;
   if (options.cropToSquare !== undefined && typeof options.cropToSquare !== 'boolean')
     throw new Error(`invalid opts.cropToSquare=${options.cropToSquare}`);
-  if (options.moreEffort !== undefined && typeof options.moreEffort !== 'boolean')
-    throw new Error(`invalid opts.moreEffort=${options.moreEffort} (${typeof options.moreEffort})`);
-  if (options.invertDownscale !== undefined && typeof options.invertDownscale !== 'boolean')
-    throw new Error(
-      `invalid opts.invertDownscale=${options.invertDownscale} (${typeof options.invertDownscale})`
-    );
+  if (
+    options.multiPass !== undefined &&
+    typeof options.multiPass !== 'boolean' &&
+    options.multiPass !== 'max'
+  )
+    throw new Error(`invalid opts.multiPass=${options.multiPass} (${typeof options.multiPass})`);
   if (options.grid !== undefined) {
     const grid = validateObject(options.grid, 'opts.grid') as DecodeGrid;
     asafenumber(grid.moduleSize, 'opts.grid.moduleSize');
@@ -3040,7 +3042,7 @@ export function decodeQR(img: TArg<Image | Bitmap>, opts: TArg<DecodeOpts> = {})
   // full-resolution cost; when it fails, the full pipeline below still runs,
   // adding at most ~25% to the failure path.
   let preScale = 0;
-  if (options.invertDownscale !== false && options.grid === undefined) {
+  if (options.multiPass !== false && options.grid === undefined) {
     let img = image;
     let scale = 1;
     while (
@@ -3063,7 +3065,7 @@ export function decodeQR(img: TArg<Image | Bitmap>, opts: TArg<DecodeOpts> = {})
     return decodePreparedImage(image, options, mapPoint);
   } catch (e) {
     if (isUserDecodeError(e)) throw e.error;
-    if (options.invertDownscale !== false && options.grid === undefined) {
+    if (options.multiPass !== false && options.grid === undefined) {
       try {
         const retry = decodeWithDownscale(image, options, mapPoint, preScale);
         if (retry !== undefined) return retry;
@@ -3072,7 +3074,7 @@ export function decodeQR(img: TArg<Image | Bitmap>, opts: TArg<DecodeOpts> = {})
         throw downscaleError;
       }
     }
-    if (options.moreEffort && options.grid === undefined) {
+    if (options.multiPass === 'max' && options.grid === undefined) {
       try {
         const retry = decodeWithFallback(image, options, mapPoint);
         if (retry !== undefined) return retry;

test/decode.test.ts

@@ -129,8 +129,8 @@ should('decodeQR validates textDecoder option before decoding', () => {
     new Error('invalid opts.textDecoder=1 (number)')
   );
   throws(
-    () => readQR(img, { moreEffort: 1 as never }),
-    new Error('invalid opts.moreEffort=1 (number)')
+    () => readQR(img, { multiPass: 1 as never }),
+    new Error('invalid opts.multiPass=1 (number)')
   );
 });
 
@@ -334,7 +334,7 @@ should('automatic grid sampling covers representative versions and borders', ()
 
 should('decodeQR fallback works with diagnostic hooks', () => {
   // rotations/image037 decodes directly since the BR-corner nudge retries;
-  // nominal/image018 still requires the moreEffort fallback candidates.
+  // nominal/image018 still requires the multiPass:'max' fallback candidates.
   const img = readJPEG('detection/nominal/image018.jpg');
   const expected = 'http://www.lonelyplanet.com/';
   let detectedPoints = 0;
@@ -343,7 +343,7 @@ should('decodeQR fallback works with diagnostic hooks', () => {
   let resultImages = 0;
   throws(() => readQR(img));
   const res = readQR(img, {
-    moreEffort: true,
+    multiPass: 'max',
     pointsOnDetect: (points) => {
       deepStrictEqual(points.length, 4);
       detectedPoints++;
@@ -369,7 +369,7 @@ should('decodeQR fallback maps diagnostic points to original image coordinates',
   const img = readJPEG('detection/blurred/image025.jpg');
   let detectedPoints;
   const res = readQR(img, {
-    moreEffort: true,
+    multiPass: 'max',
     pointsOnDetect: (points) => {
       detectedPoints = points;
     },
@@ -411,7 +411,7 @@ should('decodeQR fallback propagates user callback errors', () => {
   const textDecoderError = new Error('custom text decoder failed');
   try {
     readQR(img, {
-      moreEffort: true,
+      multiPass: 'max',
       textDecoder: () => {
         throw textDecoderError;
       },
@@ -423,7 +423,7 @@ should('decodeQR fallback propagates user callback errors', () => {
   const pointsError = new Error('points hook failed');
   try {
     readQR(img, {
-      moreEffort: true,
+      multiPass: 'max',
       pointsOnDetect: () => {
         throw pointsError;
       },
@@ -1070,7 +1070,7 @@ for (const category of listFiles(DETECTION_PATH, true)) {
       // console.log('Decoding', p.replace(DIR, ''));
       let res;
       try {
-        res = readQR(img, { moreEffort: true });
+        res = readQR(img, { multiPass: 'max' });
       } catch (e) {
         //console.log('TEST ERR', e);
       }