Rendering a QR code from a matrix

The hand-off point

Everything covered in how QR codes are generated (modes, Reed–Solomon, masking) ends at a data structure, not an image: a square boolean matrix, true for dark, typically row-major. UseQR's core returns exactly this (modules: boolean[][], with size counting modules per side, quiet zone not included). Rendering is the separate, dumber, easier-to-get-wrong job of turning that matrix into pixels or vectors.

The core loop

Three numbers govern the geometry:

• moduleSize: pixels per module (UseQR defaults to 8);
• quietZone: blank modules on every side (default 4, the spec minimum);
• total, the output edge: (size + 2 × quietZone) × moduleSize.

The loop itself:

total = (size + 2*quietZone) * moduleSize
fill entire total × total area with background   // opaque, not assumed

for row in 0..size-1:
  for col in 0..size-1:
    if matrix[row][col]:
      x = (col + quietZone) * moduleSize
      y = (row + quietZone) * moduleSize
      fillRect(x, y, moduleSize, moduleSize)     // foreground

Note col maps to x and row to y: transposing them mirrors the code, which often still scans and therefore survives testing until it ships. Keep moduleSize an integer: fractional module widths force modules onto fractional pixel boundaries, and anti-aliasing turns crisp edges into grey gradients that cost contrast exactly where the decoder samples.

Painting the background explicitly matters too. A transparent-background PNG dropped onto a dark page becomes a polarity accident; if you want transparency, treat it as a deliberate feature with known placement, per transparent background QR codes.

Canvas and the device pixel ratio

On the web, a canvas has two sizes: its CSS layout size and its pixel buffer. On a 2× or 3× display, drawing a 320 px code into a 320-buffer canvas displayed at 320 CSS pixels renders soft, the browser upscales your buffer. The standard correction:

dpr = window.devicePixelRatio || 1
canvas.style.width  = cssSize + "px"
canvas.style.height = cssSize + "px"
canvas.width  = cssSize * dpr
canvas.height = cssSize * dpr
ctx.scale(dpr, dpr)
// …then draw in CSS pixel coordinates as normal

A blurry on-screen QR code usually still scans (phone cameras are forgiving of soft edges at screen sizes), but it looks broken, and screenshots of it inherit the blur.

PNG or SVG

The loop above describes raster thinking, but the same traversal emits vectors: instead of fillRect, append a rectangle sub-path per dark module and fill once, the approach dissected in QR code SVG path structure.

The decision rule is destination, not preference. Fixed-size screen display: PNG (or canvas directly). Anything that will be scaled, printed or handed to a designer: SVG, because raster scaling is where codes go blurry or pixelated. If you must ship raster for print, render at the final physical size at 300 DPI or more: the arithmetic lives on vector vs raster.

However rendered, the output is a claim, not a fact, until a decoder reads it back: /validate does render-then-decode in one step.

FAQ

How do I draw a QR code from a matrix of booleans?

Iterate rows and columns; for each true cell, fill a square of moduleSize pixels at ((column + quietZone) × moduleSize, (row + quietZone) × moduleSize). Paint the background first and include four quiet-zone modules on every side.

Why is my canvas QR code blurry on Retina screens?

The canvas pixel buffer matches CSS size, so high-DPI displays upscale it. Multiply canvas.width and canvas.height by devicePixelRatio, keep the CSS size unchanged, and scale the drawing context by the same factor before drawing.

Do I add the quiet zone before or after rendering?

During. Offset every module by the quiet-zone width and size the output as (modules + 2 × quiet zone) × moduleSize, so the margin is baked into the file. Margins left to whoever places the image have a way of disappearing.

Should moduleSize be an integer?

Yes, for raster output. Fractional module sizes put module edges between pixels, and the resulting anti-aliasing greys out edges and shrinks effective contrast. Pick an integer pixel count per module and let overall image size follow from it.