Skip to content
P4 Software P4 Software / BarcoderX English

Add these docs to Claude

Ask Claude questions about these docs. Claude reads the published pages and links you back to them. Copy this address:

https://p4-software.opendocs.page/mcp

In claude.ai or Claude Desktop: open Settings, then Connectors, choose Add custom connector and paste the address.

In Claude Code, run:

claude mcp add --transport http docs https://p4-software.opendocs.page/mcp

The label engine

The label engine

Applies to: BarcoderX Basic and Ultimate

Status: Built, not yet released. The first part of the label engine exists and is tested, but nothing is released yet and there is nothing to download. It is the part of BarcoderX that every label passes through, and it is still being built. There is no released package, and the licensed engine will be the only public way to produce output. The engine makes the drawing of a label. The part that draws it and saves a PNG file is joined to the engine, and the label service uses both. The part that turns a picture into ZPL commands is joined to the engine, so a template becomes the commands of a whole label, sent to the printer as one picture (see ZPL output). Anything marked "planned" is not usable yet.

The label engine takes a template and makes the drawing of one label. It is the part of BarcoderX that decides where everything goes: it turns lengths into printer dots, lays out the text, the boxes and the barcodes, and writes down the drawing as a list of steps. This page says what the engine takes, what it gives back, what it draws today and what it leaves out, and what a program that hosts it must do to stay safe.

What the engine does

For one template, the engine does these things in this order:

  1. It checks the template. A template that is not valid gives messages and no drawing.
  2. It works out the size of the label in printer dots at the resolution you ask for.
  3. It lays out every element in the order of the template. The first element is at the bottom.
  4. It writes the drawing: first a white page the size of the label, then each element on top of it.

The engine does not make pixels, a file or printer commands. What it makes is a list of drawing steps, in dots. See Drawing shapes for the list of drawing steps and the surfaces. The list stays inside BarcoderX: a program that calls the engine cannot read it, draw it itself or save it. The one public way from the engine to a picture is the PNG renderer, which takes the whole result of the engine and gives back a PNG file or the reason there is none. It is described in PNG output, and the label service runs it for you. The part that writes ZPL commands from a black-and-white picture is described in ZPL output. This is on purpose: nothing can draw a label without passing through the engine.

The smallest template on The label template format page, with one text, one box and one EAN-13 barcode, gives a label of 799 by 400 dots at 203 dots per inch. That is 100 mm by 50 mm, rounded to whole dots.

What goes in

InputWhat it is
The templateThe label design. The engine checks it itself, so a program that calls it does not have to. An invalid template gives messages and no drawing. The engine never throws an error for a template.
The resolutionThe printer resolution to draw at, in dots per inch, from 96 to 1,200. If you give none, the engine uses the resolution of the template.
The limitsThe most that one label may use. If you give none, the engine uses the defaults in the table below.

A length written in millimeters, inches or points keeps its physical size when you draw at another resolution. A length written in dots is scaled in proportion to the two resolutions. Every edge is rounded to a whole dot, so a bar or a border never has a blurred edge. The next section gives the rule.

From a length to printer dots

There is no fixed number of dots in a millimeter. A millimeter is exactly 1/25.4 inch, so at 203 dots per inch it is 203/25.4 dots, about 7.99 and not 8. For example, 10 mm at 203 dots per inch is 79.92 dots, and the engine rounds it to 80.

  • The conversion is exact. An inch is 25.4 mm, a point is 1/72 inch, a mil is 1/1000 inch, a twip is 1/1440 inch and a micrometer is 1/25400 inch. The engine converts a length by one exact ratio and rounds only at the end.
  • Rounding goes to the nearest dot, and a half goes away from zero. It is never truncation and never rounding up. The same rule is used everywhere a length must become whole dots.
  • Position and size. The four edges of an element, left, top, right and bottom, are each rounded to a whole dot, and the size is the difference of the rounded edges. Two boxes that touch before rounding therefore touch after it. A size can differ by one dot from the rounded width.
  • The page. The width and the height of the label are rounded.
  • Borders and strokes. They are rounded, but a width above zero is never less than one dot.
  • The bar height of a barcode. It is rounded, and it is at least one dot.
  • The module width of a barcode. It is rounded to a whole dot, with a minimum of one dot. A module narrower than one dot is raised to one dot with a warning (BX4013). For a module of one dot or more, BX3906 says the width that was used whenever it differs from the one asked for. The bar width adjustment is rounded the same way.
  • The font size is not rounded. The text library uses the size in points as it is and rounds only the starting point of each letter to a whole dot.
  • A length written in dots is scaled by the new resolution divided by the resolution of the template. The scaled value is not rounded by the conversion itself.
  • Moving a template to another resolution converts again from the values you wrote, and rounds again. It does not round twice.

What comes out

OutputWhat it is
Succeeded or notWhether a drawing was made for the whole label. It does not mean that every element is on it: an element that cannot be drawn is left out with a message.
The drawingThe list of drawing steps, with the origin at the top left, kept inside BarcoderX. A program cannot read it, but it can pass the whole result to the PNG renderer. When a label fails there is no drawing at all, never a part of the label, because a half label on a printer is worse than none.
The sizeThe width and height of the label in dots, for the surface that is drawn on.
The resolutionThe resolution that the label was laid out at.
CountsHow many elements were drawn and how many were left out.
The messagesWhat the engine and the parts it uses have to report, in the order they were found. They are the diagnostic codes in Diagnostic codes.
The drawing limitsThe limits that the drawing was made with. They stay inside BarcoderX with the drawing.

The engine gives the same drawing for the same template and the same resolution. In BarcoderX's automatic tests, the fingerprint of the drawing of the smallest template at 203 and at 300 dots per inch is the same on Windows x64, Linux x64 and Linux arm64. Many labels can be made at the same time from different threads.

What it draws today

  • Text. Fixed text, as described in Text on a label: alignment, spacing, vertical alignment and shrink to fit, with the built-in typeface BX Core.
  • Boxes. A box has a fill, a border of its own width on each side and a corner radius. One radius is used for all four corners, the largest one that the template gives, and a rounded box with borders of different widths uses the widest. The engine reports both.
  • Barcodes. The content is written in the template. Fifteen barcode types are drawn: EAN-13, EAN-8, UPC-A, UPC-E, ITF-14, GS1-128 and SSCC-18, the two add-on symbols on their own, and EAN-13, UPC-A and UPC-E each with a two-digit and a five-digit add-on. The bars are drawn on whole printer dots. If you give a module width (xDimension), BarcoderX rounds it to whole dots and tells you the width it used (BX3906). If you give none, the barcode fills its box with the largest whole-dot module that fits. The digits under the bars are drawn when the barcode has a humanReadable setting with below or above, and not otherwise. See Barcodes.
  • Turning. An element can be turned about its anchor point. Turns of 90, 180 and 270 degrees keep the edges of bars and boxes on the printer's dot grid. Other angles are drawn as shapes, and they are not a good choice for a printer.

The digits of an add-on are drawn above the add-on's bars. See UPC-E and add-on symbols.

Digits that do not fit under a barcode

When the digits under a barcode are wider than the space the barcode gives them, for example EAN-13 at 2 dots per module and a 10-point font, the engine makes them smaller. Every group of digits gets the same size, the largest at which the groups fit, and never less than 70 percent of the size you asked for. The 70 percent is a first choice that the builders made (builder's choice, owner confirmation pending). The engine reports the change once for the element (BX3412). If the digits still do not fit at that size, the engine does not cut or move them. They may overlap the quiet zone or the next group, and the engine says so once for the element (BX3915). To make them fit, use a wider module or a smaller font size on purpose.

What it leaves out, and says so

A template can ask for things that the engine does not draw yet. It draws the rest of the label, and each omission comes with a message, so nothing disappears without a word:

  • Elements of the kinds line and ellipse (BX3903). Pictures and the other kinds are not read from a template yet either. See The label template format.
  • Content that comes from data or from an expression (BX3904). Write the content as fixed text for now.
  • Content written as bytes or with escape sequences in a barcode (BX3914).
  • Settings that are not applied yet (BX3902): the options of a barcode and the check digit modes other than automatic, text markup, text from right to left, text on an arc, number and date formats, input masks, the sizing values stretch and scale, underline, strikeout and printer-resident fonts, the rules for when to print an element, computed properties, the back side of a page, the corner radius of each corner, the rounded corners of the box around a text, a different border width on each side of a rounded box, and the page settings for orientation and for several labels on one page.
  • A barcode type that has no encoder (BX3905).

Other things are planned and not built: pictures, grids, repeaters, several labels on one page, and the printer's own text and barcode commands (the ZPL composer already sends the whole label as one picture: see ZPL output). The engine checks the license before anything is drawn. A license problem never stops a label: at worst the output carries the evaluation mark. See Evaluation mark and license keys.

Limits

BarcoderX checks every limit before it spends the resource it protects. A label that needs more than the limits allow is refused as a whole, and nothing is drawn (BX3909). A label that takes longer than the time limit is refused too (BX3910). The limits below are what the engine uses when you give none. A program that calls the engine can set lower ones, and it should for a public page.

Every number in this table, except where it says so, is a first choice that the builders made (builder's choice, owner confirmation pending). It has not been confirmed yet and can change before the first release.

LimitDefault
Elements in a template2,000 (set by the plan; the limit of the template check)
Pixels of the label64,000,000 (64 megapixels; set by the plan)
Longest side of the label65,536 dots
Path segments in one fill1,000,000 (set by the plan)
Time to lay out and write one label2 seconds (set by the plan)
Characters of text in one element10,000
Lines of text in one element500
Characters of text in all elements of a label, digits under barcodes included50,000
Path segments kept for all elements of a label (letters, rounded boxes, turned shapes)500,000, about 12.5 MB
Rectangles kept for all elements of a label (bars, borders, fills)100,000
Work units of the drawing25,000,000
Clips open at one time16 (the engine draws no clip yet)
Messages in one result500; the rest are counted and replaced by one warning, and the first and the latest error are always listed
Distance of an element from the label100,000,000 dots

The limits of one text element are a quarter to a fifth of the defaults of the text library, and the label totals are chosen so that one label keeps about 12.5 MB of path segments at most.

Values proposed for a public demo page

The security reviews propose lower values for a page that anyone on the internet can use. They are first choices too (builder's choice, owner confirmation pending), and the owner decides.

LimitProposed value
Elements in a template200
Characters of text in one element2,000
Lines of text in one element200
Work units of the layout of one text2,000,000
Characters of text in all elements of a label5,000
Path segments kept for all elements of a label200,000
Rectangles kept for all elements of a label20,000
Messages in one result100
Time to lay out and write one label1 second
Path segments in one fill100,000
Pixels of a surface9,000,000 for a black-and-white printer picture, 2,500,000 for a color or gray preview
Longest side8,192
Flattened edges400,000 (200,000 for a preview)
Work units of the drawing25,000,000 (10,000,000 for a preview)
Clips open at one time16
Time for one render2 seconds at most
Size of a PNG file2,000,000 bytes
Resolution72 to 600 dots per inch

A public page should also offer no font upload.

If you host the engine

The engine is built to be safe for a program that hosts it. A host has duties of its own.

  • Draw the result only with the PNG renderer. The engine works out an upper bound of the work that the renderer needs for the label, and refuses a label whose bound is above the work limit of the drawing (BX3909, resource renderWork), so a label that is accepted is one that the renderer can finish. The renderer still gives back no picture at all, never a half-drawn one, if it is stopped for any other reason, because a half-drawn barcode must never reach a printer. A program that uses the renderer has nothing to discard, and nothing else can draw the engine's result. The work limit is a ceiling on the label itself. A label that carries the evaluation mark also gets an allowance for the mark, on top of the ceiling, in the limits that come back with the result, so the mark is always drawn complete and a label is accepted or refused the same way with or without the mark. On the largest page the allowance reaches about 7.9 million units, about a third of the 25,000,000 default, so an operator can count on it when setting the limit.
  • Pass a time limit to every render. The 2 seconds of the engine cover laying out and writing the label. Drawing is the host's own time. Pass a cancellation time limit to every render of the PNG renderer. 2 seconds is the value proposed for a public page.
  • Call LabelEngine.WarmUp() once at start. The first request of a process pays for work that is done only once: the first compilation of the code, the built-in font and the tables of the barcodes. That is about half a second on the development machine, and more on a small or busy one. The engine does that work itself before the time limit of the first request starts, so that request is not refused for it; calling WarmUp at start only moves the wait to a moment that you choose. The time limit is time on the clock, so a machine that is busy can still make a label slow enough to fail it. For a limit that does not depend on the speed of the machine, rely on the counted limits (BX3909). Work that a request chooses for itself, such as an uploaded font, is still counted in the time of that request.
  • Cap how many labels are read and rendered at once. Reading a large template uses a lot of memory, and so does a render. At the proposed demo limits, one color render is estimated at about 135 MB. The PNG renderer is created with the number of renders that it may run at once, and it refuses the next one at once (BX3707) instead of queuing it. Size that number from the memory of the host.
  • Warm up at start. The first render in a new process was measured up to about 18 times slower than a later one, in a security review (3.9 seconds against 0.21 seconds in one test case). Render one label when the host starts.
  • Show messages as text. A message carries the id of an element and names that were written in the template. Insert them into a page as text, never as markup, and show them in an isolated direction context. Replace line breaks, other control characters and direction characters before you write them to a log. See Diagnostic codes.
  • Encode the template before you show it. The canonical text of a template is not escaped for HTML. Encode it before you embed it in a page, and put it in a script block only with every < written as \u003C. See The label template format.

What is not built yet

  • A label from a template to a printer. Built for ZPL as one picture: see ZPL output. Native text and barcode commands are not built. The join to PNG output exists in the label service.
  • Data and expressions. Labels with fields, variables and counters.
  • The other element kinds. Lines, ellipses, pictures, grids and repeaters.
  • Several labels on one page, and page orientation.

BarcoderX is a product of P4 Software.

Was this page helpful?