Rendering & Layout
render

How layout works

Modules become pixels

A QR symbol is a grid of square modules. Chilkat draws every module as an exact integer number of pixels (the pitch), which is what makes the result crisp and reliably readable. Around the symbol comes the quiet zone (in modules), then optional padding and an optional caption band; the whole canvas can then be rotated by a quarter turn. PNG and SVG are produced from the same rectangle list, so both formats have identical geometry.

Module size and units

Pixels or physical units

{ "payload": { "text": "https://www.chilkatsoft.com" },
  "render": { "units": "mm", "moduleSize": 0.5, "dpi": 300 } }

{ "index": 0, "fits": true, "units": "mm", "dpi": 300, "pitch": 6, "requestedPitch": 5.905512, "pitchAdjusted": true,
  "moduleSize": 0.508, "canvasWidth": 222, "canvasHeight": 222, "physicalWidth": 18.796, "physicalHeight": 18.796, ... }

Quiet zone and padding

Space around the symbol

The quiet zone is the blank margin readers need; the QR standard requires 4 modules on each side, which is the default. Padding is additional space outside the quiet zone, measured in units.

{ "payload": { "text": "https://www.chilkatsoft.com" },
  "render": { "moduleSize": 5, "quietZone": { "left": 10, "top": 10, "right": 10, "bottom": 10 }, "padding": 8 } }

Rotation

Quarter turns

render.rotation accepts 0, 90, 180 or 270 (degrees, clockwise). The entire canvas rotates — quiet zone, padding and caption included — and canvasWidth/canvasHeight describe the rotated result. Other angles are rejected (invalidEnum).

{ "payload": { "text": "ORDER-12345" },
  "render": { "moduleSize": 5, "rotation": 90, "text": { "enabled": true, "value": "ORDER-12345" } } }

Colors

Foreground, background and opacity

A paint is either a "#RRGGBB" string or an object { "color": "#RRGGBB", "opacity": 0..1 }. The foreground paints the dark modules (and the caption); the background fills the whole canvas.

The PNG pixel format follows the paints: 8-bit grayscale when both paints are neutral (gray) and opaque, RGB when the background is opaque, RGBA when it is not. Translucent paints are composited with ordinary source-over alpha; SVG carries the same colors as fill and fill-opacity, so both formats look the same.

{ "payload": { "text": "https://www.chilkatsoft.com" },
  "render": { "moduleSize": 6, "foreground": "#083e7d", "background": { "color": "#ffffff", "opacity": 0 } } }

Caption text

Human-readable text under or over the symbol

A caption is drawn with a built-in 5×7 pixel font — no system fonts are used, so PNG and SVG captions are identical on every platform and the SVG needs no text elements. Each glyph cell is scaled by an integer factor.

{ "payload": { "text": "ORDER-12345" },
  "render": { "moduleSize": 6,
              "text": { "enabled": true, "value": "SCAN TO TRACK", "position": "above", "scale": 2, "gap": 6, "alignment": "left" } } }

The caption band is reported as measurements[0].textBandPx, with the text and scale used in measurements[0].text / textScale.

Size constraints

maxWidth, maxHeight and shrink-to-fit

Give the maximum canvas size the symbol may occupy. By default ("sizing": "fixed") a symbol that exceeds it is a no-fit. With "sizing": "shrinkToFit" the pitch is reduced, one pixel at a time, until the canvas fits — but never below minModuleSize.

{ "payload": { "text": "https://www.chilkatsoft.com" },
  "render": { "moduleSize": 10, "maxWidth": 200, "sizing": "shrinkToFit", "minModuleSize": 2 } }

{ "pitch": 5, "requestedPitch": 10, "pitchAdjusted": true, "canvasWidth": 185, "canvasHeight": 185, ... }

When nothing fits

generate fails with noFit at /render and names the reason in the message; measure succeeds with fits: false and a reasons[] entry so you can decide what to change.

Reserved options

Styling that is not yet available

These render members are part of the design and are accepted only with their default values; anything else is rejected so that no symbol is ever produced in an unintended style.