Introduction
The unit of all coordinates, lengths, and sizes are in millimeters.
A label is a JSON object with the following mandatory properties:
| Property | Type | Description |
|---|---|---|
| format | number | The label format version. Labels conforming to this specification must be 4 v6.0. Older formats are still accepted, see Format versions. |
| width | number | Width of the label. A width of zero means that it will be automatically calculated. |
| height | number | Height of the label. A height of zero means that it will be automatically calculated. |
| objs | array of label objects | See below for description. |
The following optional properties are also available:
| Property | Type | Description |
|---|---|---|
| bgColor | string | Label background color. |
| printDelay | number | Print delay override in millimeters. |
| margin | number | Deprecated. Use printDelay instead. |
| hdpi | number | Horizontal resolition setting override (in dots per inch). |
| vdpi | number | Vertical resolition setting override (in dots per inch). |
| vOffset | number | Vertical offset setting override. A positive value moves the label up. |
| rotation | number | Rotation settings override. If set, must be one of NONE, CW90 for 90° clockwise rotation, CW180 for 180° rotation, or CCW90 for 90° counterclockwise rotation. |
| stretch | number | Stretch setting override, where a value of 1 means no stretch. |
| legacyTextRendering | boolean | If true, text is laid out as in versions before v6.0, see Text rendering. Default is false. v6.0 |
{
"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.
| Format | Description |
|---|---|
4 | The current format v6.0. Text is rendered with kerning and ligatures unless the label sets legacyTextRendering, see Text rendering. |
3 | Borders of label objects are centered on the object's outline, since v3.2. Read with legacyTextRendering set. |
2 | Coordinates 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. |
1 | Like format 2, but with an unreliable label height, which is corrected when read. |
0 | Coordinates 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.