zplgrf 1.0

Tools to work with ZPL GRF images and CUPS

zplgrf

This project contains the utils I made to convert to and from GRF images from ZPL while trying to diagnose why barcodes printed from CUPS on Linux and OSX were so blurry/fuzzy/etc. It also contains my attempt are sharpening the barcodes and a CUPS filter you can setup to try for yourself.

Barcode Quality

The way CUPS (and at least my Windows driver too) prints PDFs to label printers is by converting the PDF to an image and then embedding that image in ZPL. The problem with this is that all PDF converters seem to aim to maintain font quality and don’t care much about the quality of vectors. Often this create unscanable barcodes especially at the low 203 dpi of most label printers.

There are a couple of ways around this when generating your own PDFs (a barcode font, snap the barcode to round units, etc.) but they all have their downsides and don’t help you if you have to print a label generated by someone else.

Originally I tried getting a greyscale image from Ghostscript and converting to mono while maintaining barcode quality but I always ended up destroying the font quality. I noticed that GRFs generated by Windows showed similar artifacting on text and a retail OSX driver says in their guide that their driver may also affect text quality so I think this kind of post processing is possibly what others are doing.

In the end I opted for getting a mono image from Ghostscript and then searching the image data to find any suspected barcodes and simplying widening the white areas. It’s very dumb and simple but works for me. You may need to tweak it for your own labels and there’s a good chance it could actually make your barcodes worse.

Installation

Run pip install zplgrf.

Dependencies

Normal installation should handle regular Python dependencies but this project also requires Ghostscript (gs) to be installed. Newer versions of gs are recommended as rotating PDFs doesn’t work properly with some of the old versions of gs many distros still come with.

Using the Python API

Some quick demos.

Open a PDF, optimise the barcodes, and show the ZPL:

from zplgrf import GRF
with open('source.pdf', 'rb') as pdf:
    grf = GRF.from_pdf(pdf.read(), 'DEMO')
grf.optimise_barcodes()
print(grf.to_zpl())

Or you could open an image instead:

from zplgrf import GRF
with open('source.png', 'rb') as image:
    grf = GRF.from_image(image.read(), 'DEMO')
grf.optimise_barcodes()
print(grf.to_zpl(compression=3, quantity=1)) # Some random options

If the ZPL won’t print it’s possible that your printer doesn’t support ZB64 compressed images so try compression=2 instead.

Extract all GRFs from ZPL and save them as PNGs:

from zplgrf import GRF
with open('source.zpl', 'r') as zpl:
    grfs = GRF.from_zpl(zpl.read())
for i, grf in enumerate(grfs):
    grf.to_image().save('output-%s.png' % i, 'PNG')

Optimise all barcodes in a ZPL file:

from zplgrf import GRF
with open('source.zpl', 'r') as zpl:
    print(GRF.replace_grfs_in_zpl(zpl.read()))

Arguments for the various methods are documented in the source. Some such as to_zpl() and optimise_barcodes() have quite a few arguments that may need tweaking for your purposes.

Using the CUPS Filter

Install the package normally and then copy pdftozpl to your CUPS filter directory which is usually /usr/lib/cups/filter. Make sure that the copied file has the same permissions as the other filters in the folder.

Now edit the PPD file for your printer which is usually in /etc/cups/ppd. Find the lines containing *cupsFilter and add the following below them:

*cupsFilter2: "application/pdf application/octet-stream 50 pdftozpl"

Now restart CUPS and this new filter will take affect. Note that *cupsFilter2 filters require CUPS 1.5+ and they disable all regular *cupsFilter filters so you may need to setup more filters for other mimetypes.

application/octet-stream is the mimetype CUPS uses for raw printing which is what we want to send raw ZPL to the printer.

Performance

Performance of the CUPS filter is pretty bad in comparison to the native filters written in C. On a Raspberry Pi 3 it takes about 2.5s to run but is low 100s of ms on a decent computer.