Skip to main content

Dithering - Color Conversion to Monochrome

Zebra label printers are monochrome - they can only print black, no shades of gray or colors. When converting any document into ZPL, the API therefore also has to convert the rendering into 1-bit black-and-white (monochrome).

The HTML to ZPL API performs dithering for this color reduction process.

[Dithering] is converting a grayscale image to black and white, such that the density of black dots in the new image approximates the average gray level in the original.

Wikipedia on Dithering

Here is an example of an image converted to monochrome:

Example of an image color reduction using dithering

Customizing Dithering Parameters

The API supports two parameters to control the dithering process:

  • thresholdHigh - numeric value between 0 and 100. Any pixel with a color value below this threshold remains white in the generated ZPL.
  • thresholdLow - numeric value between 0 and 100. Any pixel with a color value above this threshold is printed as black dot in the generated ZPL.

Any pixel with a color value between the low and high threshold, is dithered. The probability of it being printed as black or white depends on the gray level of the original.


In the following example you can see a simple linear gradient (above) and the dithered image below.

The low and high threshold are set to 25% and 75% respectively. You can see that the left quarter of the image remains white, the middle is dithered, and the right quarter is fully black.

Linear grayscale gradient dithered with low and high thresholds


The parameters are optional. If not provided, thresholdLow and thresholdHigh are both set to 75%. This effectively means that any pixel with a gray value larger than 75% is printed as a black dot, while any pixel below that threshold is not printed.


The defaults work well for labels that contain a lot of small text, but might not give the best results for images. Try lowering the thresholdLow parameter when attempting to convert labels with colored images.

Example photo of a printed label

This label was printed on a Zebra Gk420t after having been converted from an HTML document using the HTML-to-ZPL API.

Label with an image that was converted using dithering printed on a Zebra printer