pantry-management-frontend/quagga2/quagga2-1.12.1/docs/how-to-guides/use-debug-flags.md

How to Use Debug Flags

Quagga2 includes several debug flags that enable diagnostic console output to help troubleshoot issues with barcode detection and decoding. This guide explains when and how to use them.

Overview

Debug flags control what information Quagga2 logs to the browser console. By default, all debug output is suppressed to keep your console clean. Enable specific flags when you need to diagnose problems.

Important Note

Debug flags only work when ENV.development is true (development builds). Production builds strip out all debug code to minimize bundle size.

Available Debug Flags

Debug flags are organized into three categories:

1. Console logging flags - Print diagnostic information to the console
2. Visual canvas overlays - Draw debugging information on the canvas
3. Performance analysis - Display frequency and pattern data

Console Logging Flags

inputStream.debug.showImageDetails

What it shows: Image loading and frame grabber operations

Console output example:

*** frame_grabber_browser: willReadFrequency=undefined canvas=<canvas>
Image Loader: Loaded 3 images from /path/to/image.jpg

When to use:

• Camera feed not showing
• Images not loading from file input
• Canvas-related issues

How to enable:

Quagga.init({
  inputStream: {
    // ... your input config
    debug: {
      showImageDetails: true
    }
  },
  // ... rest of config
});

decoder.debug.printReaderInfo

What it shows: Barcode reader registration and initialization

Console output example:

* ImageWrapper getCanvasAndContext
Registering reader: code_128_reader
Before registering reader: EANReader
Registered Readers: code_128, ean

When to use:

• Verifying which readers are active
• Reader not detecting expected barcode type
• Multiple reader configuration issues

How to enable:

Quagga.init({
  decoder: {
    readers: ["code_128_reader", "ean_reader"],
    debug: {
      printReaderInfo: true
    }
  },
  // ... rest of config
});

locator.debug.showPatchSize

What it shows: Patch dimensions during barcode localization

Console output example:

Patch-Size: 320x240

When to use:

• Barcode locator not finding barcodes
• Understanding what image size the locator is processing
• Performance optimization (smaller patches = faster)

How to enable:

Quagga.init({
  locator: {
    patchSize: "medium",
    debug: {
      showPatchSize: true
    }
  },
  // ... rest of config
});

locator.debug.showImageDetails

What it shows: Canvas and image wrapper initialization for locator

Console output example:

* initCanvas getCanvasAndContext
* ImageWrapper getCanvasAndContext

When to use:

• Locator canvas not rendering
• Debugging locator initialization failures
• Understanding when canvas contexts are created

How to enable:

Quagga.init({
  locator: {
    // ... your locator config
    debug: {
      showImageDetails: true
    }
  },
  // ... rest of config
});

Visual Canvas Overlay Flags

These flags draw debugging information directly on the canvas, allowing you to visualize the barcode detection algorithm's internal state.

Note: The scan area overlay (defined via inputStream.area) is not a debug flag. When locate: false, Quagga draws the scan area on the overlay canvas each processed frame. You can also draw it manually using Quagga.drawScannerArea(). See the Configuration Reference and API.

decoder.debug.drawBoundingBox

What it shows: Draws a box around the detected barcode location

When to use:

• Verify barcode is being located correctly
• Debug positioning issues
• Understand where the decoder thinks the barcode is

How to enable:

Quagga.init({
  decoder: {
    debug: {
      drawBoundingBox: true
    }
  },
  // ... rest of config
});

decoder.debug.drawScanline

What it shows: Draws the scanline path used for decoding

When to use:

• Verify scanner is reading through the barcode correctly
• Debug angle/orientation issues
• Understand why certain barcodes fail to decode

How to enable:

Quagga.init({
  decoder: {
    debug: {
      drawScanline: true
    }
  },
  // ... rest of config
});

locator.debug.showCanvas

What it shows: Displays the locator's internal canvas used for image processing

When to use:

• Debug localization algorithm
• Verify image preprocessing is working
• Understand what the locator "sees"

How to enable:

Quagga.init({
  locator: {
    debug: {
      showCanvas: true
    }
  },
  // ... rest of config
});

locator.debug.showPatches

What it shows: Draws all patches extracted during the localization phase

When to use:

• Debug patch extraction issues
• Verify patch size is appropriate
• Understand what regions are being analyzed

How to enable:

Quagga.init({
  locator: {
    debug: {
      showPatches: true
    }
  },
  // ... rest of config
});

locator.debug.showFoundPatches

What it shows: Highlights patches where potential barcodes were found

When to use:

• Verify barcode candidates are being identified
• Debug false positives/negatives in patch detection
• Optimize patch threshold settings

How to enable:

Quagga.init({
  locator: {
    debug: {
      showFoundPatches: true
    }
  },
  // ... rest of config
});

locator.debug.showSkeleton

What it shows: Displays the skeleton structure extracted from patches

When to use:

• Debug advanced localization algorithm
• Understand structure detection
• Verify skeleton extraction is working

How to enable:

Quagga.init({
  locator: {
    debug: {
      showSkeleton: true
    }
  },
  // ... rest of config
});

locator.debug.showLabels

What it shows: Displays component labels during connected component analysis

When to use:

• Debug component labeling phase
• Verify components are being identified correctly
• Understand clustering behavior

How to enable:

Quagga.init({
  locator: {
    debug: {
      showLabels: true
    }
  },
  // ... rest of config
});

locator.debug.showPatchLabels

What it shows: Shows labels assigned to individual patches

When to use:

• Debug patch classification
• Verify patches are being labeled correctly
• Understand patch grouping

How to enable:

Quagga.init({
  locator: {
    debug: {
      showPatchLabels: true
    }
  },
  // ... rest of config
});

locator.debug.showRemainingPatchLabels

What it shows: Displays labels for patches remaining after filtering

When to use:

• Debug patch filtering logic
• Verify correct patches survive filtering
• Optimize filter thresholds

How to enable:

Quagga.init({
  locator: {
    debug: {
      showRemainingPatchLabels: true
    }
  },
  // ... rest of config
});

locator.debug.boxFromPatches.showTransformed

What it shows: Shows transformed patch coordinates during box calculation

When to use:

• Debug coordinate transformation
• Verify spatial transformations are correct
• Understand box calculation from patches

How to enable:

Quagga.init({
  locator: {
    debug: {
      boxFromPatches: {
        showTransformed: true
      }
    }
  },
  // ... rest of config
});

locator.debug.boxFromPatches.showTransformedBox

What it shows: Displays the bounding box after transformation

When to use:

• Debug box transformation
• Verify box coordinates after spatial transform
• Understand final box positioning

How to enable:

Quagga.init({
  locator: {
    debug: {
      boxFromPatches: {
        showTransformedBox: true
      }
    }
  },
  // ... rest of config
});

locator.debug.boxFromPatches.showBB

What it shows: Displays the final bounding box around detected barcode region

When to use:

• Verify final bounding box is correct
• Debug box calculation from patches
• Optimize localization accuracy

How to enable:

Quagga.init({
  locator: {
    debug: {
      boxFromPatches: {
        showBB: true
      }
    }
  },
  // ... rest of config
});

Performance Analysis Flags

decoder.debug.showFrequency

What it shows: Displays frequency data from the barcode scanline

When to use:

• Analyze barcode signal quality
• Debug decoding issues at the signal level
• Understand why certain barcodes fail to decode

How to enable:

Quagga.init({
  decoder: {
    debug: {
      showFrequency: true
    }
  },
  // ... rest of config
});

decoder.debug.showPattern

What it shows: Displays the pattern data extracted from the barcode

When to use:

• Analyze pattern recognition issues
• Debug specific barcode format problems
• Understand pattern extraction process

How to enable:

Quagga.init({
  decoder: {
    debug: {
      showPattern: true
    }
  },
  // ... rest of config
});

Common Debugging Scenarios

"No barcodes detected"

Enable console logging first, then add visual overlays if needed:

Quagga.init({
  inputStream: {
    target: document.querySelector('#scanner'),
    debug: {
      showImageDetails: true
    }
  },
  decoder: {
    readers: ["code_128_reader"],
    debug: {
      printReaderInfo: true,
      drawBoundingBox: true,  // Visual: see if barcode is located
      drawScanline: true       // Visual: see scan path
    }
  },
  locator: {
    debug: {
      showPatchSize: true,
      showImageDetails: true,
      showFoundPatches: true   // Visual: see candidate patches
    }
  }
}, function(err) {
  if (err) {
    console.error("Init error:", err);
    return;
  }
  console.log("Starting Quagga...");
  Quagga.start();
});

Check console for:

• ✅ Readers registered correctly?
• ✅ Images loading?
• ✅ Patch size reasonable (not 0x0)?
• ✅ Canvas contexts created?

Check canvas overlay for:

• ✅ Are patches being detected? (green highlights)
• ✅ Is a bounding box drawn?
• ✅ Is the scanline visible and passing through the barcode?

"Camera not working"

Enable input stream debugging:

Quagga.init({
  inputStream: {
    type: "LiveStream",
    debug: {
      showImageDetails: true  // Shows camera/canvas setup
    }
  },
  // ... rest of config
});

"Wrong barcode type detected"

Enable reader info to verify configuration:

Quagga.init({
  decoder: {
    readers: [
      "code_128_reader",  // Did you enable the right readers?
      "ean_reader"
    ],
    debug: {
      printReaderInfo: true  // Shows which readers are active
    }
  },
  // ... rest of config
});

"Deep-dive localization debugging"

For advanced debugging of the localization algorithm, enable all visual overlays:

Quagga.init({
  locator: {
    debug: {
      showCanvas: true,
      showPatches: true,
      showFoundPatches: true,
      showSkeleton: true,
      showLabels: true,
      showPatchLabels: true,
      showRemainingPatchLabels: true,
      boxFromPatches: {
        showTransformed: true,
        showTransformedBox: true,
        showBB: true
      }
    }
  }
}, function(err) {
  if (err) {
    console.error(err);
    return;
  }
  Quagga.start();
});

This will display every step of the localization process visually on the canvas. Use this to:

• Understand the complete localization pipeline
• Optimize patch size and thresholds
• Debug complex barcode positioning issues
• Learn how the algorithm works

Warning: Enabling all visual overlays may impact performance and make the canvas cluttered. Enable only what you need.

Performance Impact

Debug flags have varying performance impacts:

Console logging flags (minimal impact):

• showImageDetails, printReaderInfo, showPatchSize - negligible overhead
• Only execute when enabled and only in development builds

Visual canvas overlays (moderate to high impact):

• Drawing operations on canvas can slow down real-time detection
• More overlays = more draw calls = slower performance
• Consider disabling in production or using only for development/debugging

Performance analysis flags (high impact):

• showFrequency, showPattern - can generate large amounts of data
• Best used sparingly when diagnosing specific decoding issues

Recommendation: Enable only the flags you need. Disable all visual overlays for production.

Disabling Debug Output

To turn off all debug output, either:

Option 1: Remove debug properties entirely

Quagga.init({
  inputStream: {
    // debug property removed
  },
  // ...
});

Option 2: Set flags to false

Quagga.init({
  inputStream: {
    debug: {
      showImageDetails: false
    }
  },
  decoder: {
    debug: {
      printReaderInfo: false,
      drawBoundingBox: false,
      drawScanline: false,
      showFrequency: false,
      showPattern: false
    }
  },
  locator: {
    debug: {
      showCanvas: false,
      showPatches: false,
      showFoundPatches: false,
      showSkeleton: false,
      showLabels: false,
      showPatchLabels: false,
      showRemainingPatchLabels: false,
      showPatchSize: false,
      showImageDetails: false,
      boxFromPatches: {
        showTransformed: false,
        showTransformedBox: false,
        showBB: false
      }
    }
  }
});

Using in Node.js

Debug flags work in Node.js too! Output goes to console.log:

const Quagga = require('@ericblade/quagga2').default;

Quagga.decodeSingle({
  src: './barcode.jpg',
  decoder: {
    readers: ['code_128_reader'],
    debug: {
      printReaderInfo: true  // Shows reader registration
    }
  }
}, (result) => {
  // Check console for debug output
  if (result) {
    console.log('Decoded:', result.codeResult.code);
  }
});

Development vs Production

Development builds (dist/quagga.js or when using webpack dev server):

• Debug flags work
• Console output visible
• Larger file size

Production builds (dist/quagga.min.js):

• Debug flags are stripped out (no-op)
• No console output
• Smaller file size

To enable debug output in production:

1. Use the development build (quagga.js instead of quagga.min.js)
2. Set ENV.development = true before importing Quagga

Summary

Quagga2 provides 19 debug flags organized into three categories:

Console logging (4 flags) - Minimal performance impact:

• inputStream.debug.showImageDetails - Frame grabber and image loading
• decoder.debug.printReaderInfo - Reader registration
• locator.debug.showPatchSize - Patch dimensions
• locator.debug.showImageDetails - Canvas initialization

Visual canvas overlays (13 flags) - Moderate to high performance impact:

• decoder.debug.drawBoundingBox - Barcode location box
• decoder.debug.drawScanline - Scan path
• locator.debug.showCanvas - Locator's internal canvas
• locator.debug.showPatches - All extracted patches
• locator.debug.showFoundPatches - Candidate patches
• locator.debug.showSkeleton - Skeleton structure
• locator.debug.showLabels - Component labels
• locator.debug.showPatchLabels - Patch labels
• locator.debug.showRemainingPatchLabels - Post-filter labels
• locator.debug.boxFromPatches.showTransformed - Transformed coordinates
• locator.debug.boxFromPatches.showTransformedBox - Transformed box
• locator.debug.boxFromPatches.showBB - Final bounding box

Performance analysis (2 flags) - High impact:

• decoder.debug.showFrequency - Signal frequency data
• decoder.debug.showPattern - Pattern extraction data

Debugging strategy: Start with console logging flags, then add visual overlays as needed. Disable all flags in production.

Related

• Configuration Reference - Complete config documentation
• Optimize Performance - Speed up barcode detection
• Handle Difficult Barcodes - Improve detection accuracy

Changelog

v1.8.4+ (November 2025): Debug flags introduced to replace always-on console spam

Prior versions logged debug information unconditionally, making it difficult to debug application code. The new flag system provides fine-grained control over diagnostic output.

---

Questions? Ask in Gitter Chat or open an issue.