Skip to main content

Introduction

info

The unit of all coordinates, lengths, and sizes are in millimeters.

A label is a JSON object with the following mandatory properties:

PropertyTypeDescription
formatnumberThe label format version. Labels conforming to this specification must be 4 v6.0. Older formats are still accepted, see Format versions.
widthnumberWidth of the label. A width of zero means that it will be automatically calculated.
heightnumberHeight of the label. A height of zero means that it will be automatically calculated.
objsarray of label objectsSee below for description.

The following optional properties are also available:

PropertyTypeDescription
bgColorstringLabel background color.
printDelaynumberPrint delay override in millimeters.
marginnumberDeprecated. Use printDelay instead.
hdpinumberHorizontal resolition setting override (in dots per inch).
vdpinumberVertical resolition setting override (in dots per inch).
vOffsetnumberVertical offset setting override. A positive value moves the label up.
rotationnumberRotation settings override. If set, must be one of NONE, CW90 for 90° clockwise rotation, CW180 for 180° rotation, or CCW90 for 90° counterclockwise rotation.
stretchnumberStretch setting override, where a value of 1 means no stretch.
legacyTextRenderingbooleanIf true, text is laid out as in versions before v6.0, see Text rendering. Default is false. v6.0
Example
{
"format": 4,
"width": 50.0,
"height": 108.37,
"objs": [
{
"type": "Rect",
"x": 10.0,
"y": 10.0,
"height": 20.0,
"width": 20.0,
"fillColor": "black"
}
]
}

Format versions​

The printer reads labels of every format below, and converts them to the current format, so that they look as they did. It always writes labels, e.g. in getLabel, as format 4.

FormatDescription
4The current format v6.0. Text is rendered with kerning and ligatures unless the label sets legacyTextRendering, see Text rendering.
3Borders of label objects are centered on the object's outline, since v3.2. Read with legacyTextRendering set.
2Coordinates in millimeters. Borders are drawn inside the object, so when read, objects with a border are moved and resized to look the same with centered borders.
1Like format 2, but with an unreliable label height, which is corrected when read.
0Coordinates in pixels. Assumed when format is missing.

Text rendering​

Since v6.0, text is rendered with kerning and standard ligatures, and right-to-left scripts such as Arabic are supported. This can move text slightly compared with earlier versions.

A label with legacyTextRendering set to true is laid out as in earlier versions, without kerning, ligatures or support for right-to-left scripts. A label of format 3 or older is read with legacyTextRendering set, so it keeps its layout, and is written back as format 4 with legacyTextRendering set. To get the new text rendering for such a label, remove legacyTextRendering from it, or set it to false.

A character that the text's font does not have is drawn with a built-in Noto font of its script, in a matching style, weight and slant v6.1. There are built-in fonts for Arabic, Hebrew, Japanese, Korean and Thai, and Noto Sans and Noto Serif for other characters. Digits, symbols and punctuation that the text's font has are still drawn with it, and the line height is taken from the text's font alone. Before v6.1, such characters were left out.