Getting Started¶

Installation¶

Zint bindings are available to install from pip:

pip install zint-bindings

the zint package contains both the compiled bindings, as well as a pyi syntax file which should help you in your IDE.

Basic usage¶

Print a QR Code to file¶

After installation, create a Symbol (aka a barcode, qrcode, etc.) and set the necessary parameters to then produce an image on disk:

from zint import Symbol, Symbology

x = Symbol()
x.symbology = Symbology.QRCODE
x.encode("https://github.com/bindreams/zint-bindings")
x.outfile = "qrcode.png"
x.print()  # Will create qrcode.png

As you can see, in the Zint philosophy, most arguments both for symbol generation and output, are set as fields in the Symbol class.

Create an in-memory image¶

Alternatively, you can produce a bitmap buffer in memory, and then load it, for example into a PIL.Image:

...
x.encode("https://github.com/bindreams/zint-bindings")
x.buffer()

# At this point, x.bitmap stores the RGB bitmap image of the QR code
# This memoryview has a similar syntax to a numpy array.
shape = x.bitmap.shape
print(shape)  # -> (width, height, 3)

from PIL import Image
image = Image.frombytes("RGB", (shape[0], shape[1]), x.bitmap, "raw")
image.show()

Color and transparency¶

You can specify any color for background and foreground using the Symbol.bgcolor and Symbol.fgcolor properties. When transparency is involved, Symbol.alphamap holds the additional alpha channel. Here’s how add it to your PIL.Image:

...
x.bgcolor = "00000000"  # RGBA Transparent background
x.fgcolor = "FFFF00"    # RGB Yellow foreground

x.encode("https://github.com/bindreams/zint-bindings")
x.buffer()

shape = x.bitmap.shape
print(shape)  # -> (width, height, 3)
alpha_shape = x.alphamap.shape
print(alpha_shape)  # -> (width, height)

from PIL import Image
image = Image.frombytes("RGB", (shape[0], shape[1]), x.bitmap, "raw")
alpha_channel = Image.frombytes("L", (shape[0], shape[1]), x.alphamap, "raw")

image.putalpha(alpha_channel)  # Combine the image and the alpha channel
image.show()

Symbol-specific configuration¶

Most of the symbols support configuration through the self-explanatory option_1, option_2, and option_3 properties. These options do something different for every symbol type. For a particular symbol type (symbology) there is extensive documentation in the original Zint manual. For example, according to the Datamatrix docs, option_2 can be used to set the desired size of the resulting datamatrix, independent of the size of the input:

Note

The bitmap size is 96 * 2 = 192 because the default Symbol.scale of 1 produces dots of 2x2 pixels. You can set Symbol.scale to 0.5 to produce pixel-perfect minimal datamatrices.

from zint import Symbol, Symbology

x = Symbol()
x.symbology = Symbology.DATAMATRIX

x.option_2 = 20  # Let's create an enormous 96x96 datamatrix

x.encode("https://github.com/bindreams/zint-bindings")

x.buffer()
print(x.bitmap.shape)  # -> (192, 192, 3)

Human-readable text (human-readable interpretation, HRT, HRI)¶

By default, supported symbols (such as many barcodes) display a human-readable interpretation of the encoded data with the symbol itself. The following methods can be used to configure this behavior:

from zint import Symbol, Symbology

x = Symbol()
x.symbology = Symbology.CODE128

x.text_gap = -5  # Adjust the margin between barcode and text...
#x.show_text = False  # ...or disable the HRT altogether

x.encode("130170X178")
print(x.text)  # When encoded, `x.text` contains the human readable interpretation as a string.

More information¶

Most of the configuration possibilites are not covered in this guide. But since Zint Bindings mirrors the original Zint API almost perfectly, you can consult the Zint manual (general API, specific symbols).

If there is something mentinoned in the manual, but it’s not obvious how to translate that into Python, please feel free to open up an issue.