MaxiCode barcode in a PDF

Where the symbol comes from

This API renders HTML to PDF. It does not generate barcodes, so the MaxiCode symbol itself is produced by an encoder in your own stack and placed in the markup, either as inline SVG or as a data URI. That split matters more than it sounds: the encoders are mature and correct, and almost every barcode that will not scan failed for a layout reason rather than an encoding one. Everything below is about the layout half.

What it can encode

886 hexagonal modules arranged in 33 rows around a central bullseye finder, of which 884 carry data. Capacity is roughly 93 alphanumeric or 138 numeric characters. In practice the content is not free-form: the modes that matter carry a structured carrier message, meaning a postcode, a three digit country code and a service class in a primary message, with the address and package details in a secondary message.

The check digit, and who computes it

Reed-Solomon error correction, and unusually it is split. The primary message carrying the postcode, country and service class gets a heavier proportion of correction than the secondary message, on the reasoning that a sortation system needs the routing fields even from a damaged symbol. The encoder computes both and you supply neither.

Size and quiet zone

The two measurements that decide whether a scanner accepts the symbol, and the two most often lost when a design is adjusted to fit.

• X-dimension: There is no X-dimension to choose, and that is the entire printing story for this symbology. The symbol is 28.14 by 26.91mm and the module pitch follows from that. Every other code on this list has a magnification range; MaxiCode has a size. A symbol printed at 90 percent to fit a label is out of specification even though it will often still read.
• Quiet zone: 1.02mm minimum on all four sides. Small compared with a linear symbology, because the bullseye is the finder and the decoder does not have to locate an outer edge, but not optional: the outermost hexagons are data.

Where it is used

• parcel sortation, where it is scanned at speed and at an unknown orientation on a moving belt
• carrier labels produced to a shipper's own specification, alongside a linear tracking barcode
• the structured carrier message modes, where the routing fields are read separately from the rest
• nowhere else, realistically, which is worth knowing before you choose it

Placing it in the markup

The quiet zone is padding on the container rather than part of the encoder's output, so it survives a change of encoder. Dimensions are in millimetres, because a bar width is a physical measurement and a percentage makes it depend on whatever the container happens to be.

<!-- Fixed physical size. Do not set a percentage width, do not set
     one dimension and let the other follow, and do not let a print
     dialog scale the page. -->
<figure class="maxicode">
  <img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0i..." alt="Carrier routing symbol">
</figure>

<style>
.maxicode {
  margin: 0;
  /* 1.02mm minimum on all four sides, rounded up. */
  padding: 1.5mm;
  background: #fff;
  width: max-content;
  print-color-adjust: exact;
  -webkit-print-color-adjust: exact;
}
.maxicode img {
  /* The specified size, both axes, in millimetres. These two numbers are
     not a starting point. */
  width: 28.14mm;
  height: 26.91mm;
  display: block;
  image-rendering: crisp-edges;
}
</style>

What goes wrong on paper

Scaling it, in any direction, for any reason. The most common route to that is not a CSS width at all: it is a page that is rendered at one size and then printed with a fit-to-page or shrink-to-fit setting, which scales everything on it by a few percent. On a 4 by 6 label with a MaxiCode, that setting has to be off, and the safest way to guarantee it is to render the label at its true size so nothing downstream has a reason to adjust.

First thing to check when it will not scan

Look at the bullseye first. It is the finder and the orientation reference, and a printhead streak or a label fold through the centre disables the whole symbol in a way that equivalent damage at the edge does not. Then check the symbol has not been scaled: measure it on the printed label with a rule, because 28mm and 26mm looks right to the eye and is not.

Vector, not a bitmap

Encode to SVG wherever the encoder offers it. A rasterised barcode is resampled when the PDF is printed, and at 203 or 300 dots per inch the bar edges land between printer dots, so the ratio of bar to space drifts by a fraction of a millimetre. That fraction is the whole tolerance. An SVG stays vector inside the PDF and is rendered at the printer's own resolution, which removes the entire failure mode. Where a bitmap is unavoidable, generate it at the final physical size and set image-rendering so nothing smooths the edges.

Frequently asked

Other symbologies

Codes of the same kind, and one from each of the other kinds.