Zint: Manual

4. Using the Command Line

This section describes how to encode data using the command line frontend program. The examples given are for the Linux platform, but the same options are available for Windows - just remember to include the executable file extension if ".EXE" is not in your PATHEXT environment variable, i.e.:

zint.exe -d "This Text"

For compatibility with Windows the examples use double quotes to delimit data, though on Linux single quotes are generally preferable as they stop the shell from processing any characters such as backslash or dollar. A single quote itself is dealt with by terminating the single-quoted text, backslashing the single quote, and then continuing:

zint -d 'Text containing a single quote '\'' in the middle'

4.1 Inputting data

The data to encode can be entered at the command line using the -d option, for example

zint -d "This Text"

This will encode the text "This Text". Zint will use the default symbology, Code 128, and output to the default file out.png in the current directory. Alternatively, if libpng was not present when Zint was built, the default output file will be out.gif.

The data input to the Zint CLI is assumed to be encoded in Unicode (UTF-8) format (Zint will correctly handle UTF-8 data on Windows). If you are encoding characters beyond the 7-bit ASCII set using a scheme other than UTF-8 then you will need to set the appropriate input options as shown in section 4.10 below.

Non-printing characters can be entered on the command line using the backslash (\) as an escape character in combination with the --esc switch. Permissible sequences are shown in the table below.

Escape Character ASCII Equivalent Name Interpretation
\0 000 NUL Null character
\E 004 EOT End of Transmission
\a 007 BEL Bell
\b 008 BS Backspace
\t 009 HT Horizontal Tab
\n 00A LF Line Feed
\v 00B VT Vertical Tab
\f 00C FF Form Feed
\r 00D CR Carriage Return
\e 01B ESC Escape
\G 01D GS Group Selector
\R 01E RS Record Selector
\xNN 0xNN Any 8-bit character where NN is hexadecimal
\uNNNN Any 16-bit Unicode Basic Multilingual Plane (BMP) character where NNNN is hexadecimal

Input data can be read directly from file using the -i switch as shown below. The input file is assumed to be Unicode (UTF-8) formatted unless an alternative mode is selected. This command replaces the use of the -d switch.

zint -i ./somefile.txt

Note that except when batch processing (section 4.11 below), the file should not end with a newline (LF on Unix, CR+LF on Windows) unless you want the newline to be encoded in the symbol.

4.2 Directing Output

Output can be directed to a file other than the default using the -o switch. For example:

zint -o here.png -d "This Text"

This draws a Code 128 barcode in the file here.png. If an encapsulated PostScript file is needed simply append the file name with .eps, and so on for the other supported file types:

zint -o there.eps -d "This Text"

4.3 Selecting barcode type

Selecting which type of barcode you wish to produce (i.e. which symbology to use) can be done at the command line using the -b or --barcode= switch followed by the appropriate integer value or name in the following table. For example to create a Data Matrix symbol you could use:

zint -b 71 -o datamatrix.png -d "Data to encode"

or

zint -b DATAMATRIX -o datamatrix.png -d "Data to encode"
Numeric Value Name (case - insensitive) Barcode Name
1 CODE11 Code 11
2 C25STANDARD Standard Code 2 of 5
3 C25INTER Interleaved 2 of 5
4 C25IATA Code 2 of 5 IATA
6 C25LOGIC Code 2 of 5 Data Logic
7 C25IND Code 2 of 5 Industrial
8 CODE39 Code 3 of 9 (Code 39)
9 EXCODE39 Etended Code 3 of 9 (Code 39+)
13 EANX EAN (Including EAN-8 and EAN-13)
14 EANX_CHK EAN + Check Digit
16 GS1_128 GS1-128 (UCC.EAN-128)
18 CODABAR Codabar
20 CODE128 Code 128 (automatic subset switching)
21 DPLEIT Deutshe Post Leitcode
22 DPIDENT Deutshe Post Identcode
23 CODE16K Code 16K
24 CODE49 Code 49
25 CODE93 Code 93
28 FLAT Flattermarken
29 DBAR_OMN GS1 DataBar Omnidirectional (including GS1 DataBar Truncated)
30 DBAR_LTD GS1 DataBar Limited
31 DBAR_EXT GS1 DataBar Etended
32 TELEPEN Telepen Alpha
34 UPCA UPC-A
35 UPCA_CHK UPC-A + Check Digit
37 UPCE UPC-E
38 UPCE_CHK UPC-E + Check Digit
40 POSTNET PostNet
47 MSI_PLESSEY MSI Plessey
49 FIM FIM
50 LOGMARS LOGMARS
51 PHARMA Pharmacode One-Track
52 PZN PZN
53 PHARMA_TWO Pharmacode Two-Track
55 PDF417 PDF417
56 PDF417COMP Compact PDF417 (Truncated PDF417)
57 MAXICODE Maxicode
58 QRCODE QR Code
60 CODE128B Code 128 (Subset B)
63 AUSPOST Australia Post Standard Customer
66 AUSREPLY Australia Post Reply Paid
67 AUSROUTE Australia Post Routing
68 AUSREDIRECT Australia Post Redirection
69 ISBNX ISBN (EAN-13 with verification stage)
70 RM4SCC Royal Mail 4 State (RM4SCC)
71 DATAMATRIX Data Matrix (ECC200)
72 EAN14 EAN-14
73 VIN Vehicle Identification Number (America)
74 CODABLOCKF Codablock-F
75 NVE18 NVE-18
76 JAPANPOST Japanese Postal Code
77 KOREAPOST Korea Post
79 DBAR_STK GS1 DataBar Stacked (stacked version of GS1 DataBar Truncated)
80 DBAR_OMNSTK GS1 DataBar-14 Stacked Omnidirectional
81 DBAR_EXPSTK GS1 DataBar Expanded Stacked
82 PLANET PLANET
84 MICROPDF417 MicroPDF417
85 USPS_IMAIL USPS Intelligent Mail (OneCode)
86 PLESSEY Plessey Code
87 TELEPEN_NUM Telepen Numeric
89 ITF14 ITF-14
90 KIX Dutch Post KIX Code
92 AZTEC Aztec Code
93 DAFT DAFT Code
96 DPD DPD Code
97 MICROQR Micro QR Code
98 HIBC_128 HIBC Code 128
99 HIBC_39 HIBC Code 39
102 HIBC_DM HIBC Data Matrix (ECC200)
104 HIBC_QR HIBC QR Code
106 HIBC_PDF HIBC PDF417
108 HIBC_MICPDF HIBC MicroPDF417
110 HIBC_BLOCKF HIBC Codablock-F
112 HIBC_AZTEC HIBC Aztec Code
115 DOTCODE DotCode
116 HANXIN Han Xin (Chinese Sensible) Code
121 MAILMARK Royal Mail 4-State Mailmark
128 AZRUNE Aztec Runes
129 CODE32 Code 32
130 EANX_CC Composite Symbol with EAN linear component
131 GS1_128_CC Composite Symbol with GS1-128 linear component
132 DBAR_OMN_CC Composite Symbol with GS1 DataBar-14 linear component
133 DBAR_LTD_CC Composite Symbol with GS1 DataBar Limited component
134 DBAR_EXP_CC Composite Symbol with GS1 DataBar Etended component
135 UPCA_CC Composite Symbol with UPC A linear component
136 UPCE_CC Composite Symbol with UPC E linear component
137 DBAR_STK_CC Composite Symbol with GS1 DataBar-14 Stacked component
138 DBAR_OMNSTK_CC Composite Symbol with GS1 DataBar-14 Stacked Omnidirectional component
139 DBAR_EXPSTK_CC Composite Symbol with GS1 DataBar Epanded Stacked component
140 CHANNEL Channel Code
141 CODEONE Code One
142 GRIDMATRIX Grid Matrix
143 UPNQR UPNQR - Univerzalni Plačilni Nalog QR
144 ULTRA Ultracode
145 RMQR Rectanglular Micro QR Code (rMQR)

This table is also accessible from the command line by issuing zint –t

4.4 Adjusting height

The height of a symbol (except those with a fixed width-to-height ratio) can be adjusted using the --height switch. For example:

zint --height=100 -d "This Text"

This specifies a symbol height of 100 times the X-dimension of the symbol.

4.5 Adjusting whitespace

The amount of horizontal whitespace to the left and right of the generated barcode can be altered using the –w or --whitesp switch. For example:

zint -w 10 -d "This Text"

This specifies a whitespace width of 10 times the X-dimension of the symbol both to the left and to the right of the barcode.

The amount of vertical whitespace above and below the barcode can be altered using the --vwhitesp switch. For example for 3 times the X-dimension:

zint --vwhitesp 3 -d "This Text"

Note that the whitespace at the bottom appears below the text, if any.

Horizontal and vertical whitespace can of course be used together:

zint -b DATAMATRIX --whitesp 1 --vwhitesp 1 -d "This Text"

4.6 Adding boundary bars and boxes

Zint allows the symbol to be bound with 'boundary bars' (also known as 'bearer bars') using the option --bind. These bars help to prevent misreading of the symbol by corrupting a scan if the scanning beam strays off the top or bottom of the symbol. Zint can also put a border right around the symbol and its horizontal whitespace with the --box option.

The width of the boundary or box can be specified using the --border switch. For example:

zint --box --border=10 -d "This"

gives a box with a width 10 times the X-dimension of the symbol. Note that when specifying a box, horizontal whitespace is usually required in order to create a quiet zone between the barcode and the sides of the box.

Codablock-F, Code 16k and Code 49 always have boundary bars, and default to particular horizontal whitespace values. Special considerations apply to ITF-14 - see the specific section 6.1.2.6 for that symbology.

A symbol with bounding bars
A symbol with bounding bars
A symbol with a bounding box
A symbol with a bounding box

4.7 Using colour

The default colours of a symbol are a black symbol on a white background. Zint allows you to change this. The -r switch allows the default colours to be inverted so that a white symbol is shown on a black background. For example the command

zint -r -d "This"

gives an inverted Code 128 symbol. This is not practical for most symbologies but white-on-black is allowed by the Data Matrix and Aztec Code symbology specifications.

For more specific needs the foreground (ink) and background (paper) colours can be specified using the --fg= and --bg= options followed by a number in RRGGBB hexadecimal notation (the same system used in HTML). For example the command

zint --fg=004700 -d "This"

alters the symbol to a dark green as shown below.

A symbol with ink colour set to dark green
A symbol with ink colour set to dark green
A symbol with the paper colour set to pink
A symbol with the paper colour set to pink

Zint also supports RGBA colour information for some output file formats which support alpha channels (currently only PNG and SVG) in a RRGGBBAA format. For example:

zint --fg=00ff0055 -d "This"

will produce a semi-transparent green foreground with standard (white) background. Note that transparency is handled differently for raster and vector files so that...

zint --bg=ff0000 --fg=ffffff00 ...

will give different results for PNG and SVG. Experimentation is advised! Also note that these options don't work properly with MaxiCode yet.

In addition the --nobackground option will simply remove the background from PNG, GIF, SVG, EMF and EPS files.

4.8 Rotating the Symbol

The symbol can be rotated through four orientations using the --rotate= option followed by the angle of rotation as shown below.

  • --rotate=0 (default)
  • --rotate=180
  • --rotate=270
  • --rotate=90

4.9 Adjusting image size

The scale of the image can be altered using the --scale= option followed by a multiple of the default X-dimension. The scale is multiplied by 2 before being applied. The default scale is 1.

For raster output, the default X-dimension is 2 pixels (except for MaxiCode, see 4.9.2 below). For example for PNG images a scale of 5 will increase the X-dimension to 10 pixels. Scales should be given in increments of 0.5, i.e. 0.5, 1, 1.5, 2, 2.5, 3, 3.5, etc., to avoid the X-dimension varying across the symbol due to interpolation. 0.5 increments are also faster to render.

The minimum scale for non-dotty raster output is 0.5, giving a minimum X-dimension of 1 pixel, and text will not be printed for scales less than 1. The minimum scale for raster output in dotty mode is 1 (see 4.14).

The minimum scale for vector output is 0.1, giving a minimum X-dimension of 0.2.

4.9.1 Scaling example

The GS1 General Specifications Section 5.2.6.6 "Symbol dimensions at nominal size" gives an example of an EAN-13 barcode using the X-dimension of 0.33mm. To print that example as a PNG at 12 dots per mm (dpmm), the equivalent of 300 dots per inch (dpi = dpmm * 25.4), specify a scale of 2, since 0.33 * 12 = 3.96 pixels, or 4 pixels rounding to the nearest pixel:

zint -b EANX -d "501234567890" --height 69 --scale 2

This will result in output of 38.27mm x 26.08mm (WxH) at 300 dpi. The following table shows the scale to use (in 0.5 increments) depending on the dpmm desired, for a target X-dimension of 0.33mm:

dpmm dpi scale
6 150 1
8 200 1.5
12 300 2
16 400 3
24 600 4
47 1200 8
95 2400 15.5
189 4800 31

4.9.2 MaxiCode raster scaling

For MaxiCode symbols, which use hexagons, the scale for raster output is multiplied by 10 before being applied. The minimum scale is 0.2, so the minimum X-dimension is 2 pixels.

MaxiCode symbols have fixed size ranges of 24.82mm to 27.93mm in width, and 23.71mm to 26.69mm in height, excluding quiet zones. The following table shows the scale to use depending on the dpmm desired, with dpi equivalents:

dpmm dpi scale
6 150 0.5
8 200 0.7
12 300 1
16 400 1.4
24 600 2.1
47 1200 4.1
95 2400 8.2
189 4800 16.4

4.10 Input modes

By default all input data is assumed to be encoded in Unicode (UTF-8) format. Many barcode symbologies encode data using Latin-1 (ISO/IEC 8859-1) character encoding, so input is converted from UTF-8 to Latin-1 before being put in the symbol. In addition QR Code, Micro QR Code, Rectangular Micro QR Code, Han Xin Code and Grid Matrix can encode Japanese or Chinese characters which are also converted from UTF-8. If Zint encounters characters which can not be encoded using the default character encoding then it will take advantage of the ECI (Extended Channel Interpretations) mechanism to encode the data. Be aware that not all barcode readers support ECI mode, so this can sometimes lead to unreadable barcodes. If you are using characters beyond those supported by Latin-1 then you should check that the resulting barcode can be understood by your target barcode reader. Zint will generate a warning message when an ECI code that has not been explicitly requested has been inserted into a symbol.

GS1 data can be encoded in a number of symbologies. Application Identifiers should be enclosed in [square brackets] followed by the data to be encoded (see 6.1.11.3). To encode GS1 data use the --gs1 option. GS1 mode is assumed (and doesn't need to be set) for GS1-128, EAN-14, DataBar and Composite symbologies but is also available for Aztec Code, Code 16k, Code 49, Code One, Data Matrix, DotCode, QR Code and Ultracode.

HIBC data may also be encoded in the symbologies Code 39, Code 128, Codablock-F, Data Matrix, QR Code, PDF417, MicroPDF417 and Aztec Code. Within this mode, the leading '+' and the check character are automatically added, conforming to HIBC Labeler Identification Code (HIBC LIC). For HIBC Provider Applications Standard (HIBC PAS), preface the data with a slash "/".

The --binary option encodes the input data as given. Automatic code page translations to ECI pages is disabled, and no validation of the data's encoding takes place. This may be used for raw binary or binary encrypted data. This switch plays together with the built-in ECI logic and examples may be found below.

The --fullmultibyte option uses the multibyte modes of QR Code, Micro QR Code, Rectangular Micro QR Code, Han Xin Code and Grid Matrix for binary and Latin data, maximizing density. This is achieved by using compression designed for Kanji/Hanzi characters, however some decoders take blocks which are encoded this way and interpret them as Kanji/Hanzi characters, typically by applying a transformation to UTF-8 and thus causing data corruption. Symbols encoded with this option should be checked against decoders before they are used. The popular open-source ZXing decoder is known to exhibit this behaviour.

If your data contains non ISO-Latin-1 characters, you may encode it using an ECI-aware symbology and an ECI value from the table below. The ECI information is added to your code symbol as prefix data.

The ECI value may be specified with the --eci switch, followed by the value in the column "ECI Code". The ECI value of 0 does not encode any ECI information in the code symbol. In this case, the default encoding applies for the data which is "ISO/IEC 8859-1 - Latin alphabet No. 1".

The first row of the table (ECI code 3) is the default value and does not lead to any ECI information being included in the symbol.

The input data should be UTF-8 formatted. Zint automatically translates the data into the target encoding.

The row marked with a star (*) translates GB 2312 codepoints, except when using Han Xin Code, which translates GB 18030 codepoints, a superset of GB 2312.

Note: the "--eci 3" specification should only be used for special purposes. Using this parameter, the ECI information is explicitly added to the code symbol. Nevertheless, for ECI Code 3, this is not required, as this is the default encoding, which is also active without any ECI information.

ECI Code Character Encoding Scheme
3 ISO/IEC 8859-1 - Latin alphabet No. 1
4 ISO/IEC 8859-2 - Latin alphabet No. 2
5 ISO/IEC 8859-3 - Latin alphabet No. 3
6 ISO/IEC 8859-4 - Latin alphabet No. 4
7 ISO/IEC 8859-5 - Latin/Cyrillic alphabet
8 ISO/IEC 8859-6 - Latin/Arabic alphabet
9 ISO/IEC 8859-7 - Latin/Greek alphabet
10 ISO/IEC 8859-8 - Latin/Hebrew alphabet
11 ISO/IEC 8859-9 - Latin alphabet No. 5 (Turkish)
12 ISO/IEC 8859-10 - Latin alphabet No. 6 (Nordic)
13 ISO/IEC 8859-11 - Latin/Thai alphabet
15 ISO/IEC 8859-13 - Latin alphabet No. 7 (Baltic)
16 ISO/IEC 8859-14 - Latin alphabet No. 8 (Celtic)
17 ISO/IEC 8859-15 - Latin alphabet No. 9
18 ISO/IEC 8859-16 - Latin alphabet No. 10
20 Shift JIS (JIS X 0208 and JIS X 0201)
21 Windows 1250 - Latin 2 (Central Europe)
22 Windows-1251 - Cyrillic
23 Windows 1252 - Latin 1
24 Windows 1256 - Arabic
25 UCS-2BE (High order byte first) (Unicode BMP)
26 UTF-8 (Unicode)
27 ISO/IEC 646:1991 7-bit character set (ASCII)
28 Big5 (Taiwan) Chinese Character Set
29 * GB (PRC) Chinese Character Set
30 Korean Character Set EUC-KR (KS X 1001:2002)
899 8-bit binary data

Three examples:

Example 1

The Euro sign U+20AC can be encoded in ISO/IEC 8859-15. The Euro sign has the ISO/IEC 8859-15 codepoint hex A4. It is encoded in UTF-8 as the hex sequence: E2 82 AC. Those 3 bytes are contained in the file "utf8euro.txt". This command will generate the corresponding code:

zint -b 71 --square --scale 10 --eci 17 -i utf8euro.txt

This is equivalent to the commands (using the --esc switch):

zint -b 71 --square --scale 10 --eci 17 --esc -d "\xE2\x82\xAC"
zint -b 71 --square --scale 10 --eci 17 --esc -d "\u20AC"

and to the command:

zint -b 71 --square --scale 10 --eci 17 -d "€"
Example 2

The Chinese character with Unicode codepoint U+5E38 can be encoded in Big5 encoding. The Big5 representation of this character is the two hex bytes: B1 60 (contained in the file big5char.txt). The generation command for Data Matrix is:

zint -b 71 --square --scale 10 --eci 28 --binary -i big5char.txt

This is equivalent to the command (using the --esc switch):

zint -b 71 --square --scale 10 --eci 28 --binary --esc -d "\xB1\x60"

and to the commands (no --binary switch so conversion occurs):

zint -b 71 --square --scale 10 --eci 28 --esc -d "\u5E38"
zint -b 71 --square --scale 10 --eci 28 -d "常"
Example 3

Some decoders (in particular mobile app ones) for QR Code assume UTF-8 encoding by default and do not support ECI. In this case supply UTF-8 data and use the --binary switch so that the data will be encoded as UTF-8 without conversion:

zint -b 58 --binary -d "UTF-8 data"

4.11 Batch processing

Data can be batch processed by reading from a text file and producing a separate barcode image for each line of text in that file. To do this use the --batch switch. To select the input file from which to read data use the –i option. Zint will automatically detect the end of a line of text (in either Unix or Windows formatted text files) and produce a symbol each time it finds this. Input files should end with a line feed character – if this is not present then Zint will not encode the last line of text, and will warn you that there is a problem.

By default Zint will output numbered filenames starting with 00001.png, 00002.png etc. To change this behaviour use the –o option in combination with --batch using special characters in the output file name as shown in the table below:

Input Character Interpretation
~ Insert a number or ‘0’
# Insert a number or space
@ Insert a number or “*”
Any other Insert literally

The following table shows some examples to clarify this method:

Input Finenames Generated
-o file~~~.svg
  • file001.svg
  • file002.
  • svg, file003.svg
-o @@@@bar.png
  • ***1.png
  • ***2.png
  • ***3.png
-o my~~~bar.eps
  • my001.bar.eps
  • my002.bar.eps
  • my003bar.eps
-o t@es~t~.png
  • t*es0t1.png
  • t*es0t2.png
  • t*es0t3.png

4.12 Direct output

The finished image files can be output directly to stdout for use as part of a pipe by using the --direct option. By default --direct will output data as a PNG image, but this can be altered by supplementing the --direct option with a --filetype= option followed by the suffix of the file type required. For example:

zint -b 84 --direct --filetype=pcx -d "Data to encode"

This command will output the symbol as a PCX file to stdout. The currently supported output file formats are shown in the following table:

Abbreviation File format
BMP Windows Bitmap
EMF Enhanced Metafile
EPS Encapsulated PostScript
GIF Graphics Interchange Format
PCX ZSoft Paintbrush image
PNG Portable Network Graphic
SVG Scalable Vector Graphic
TIF Tagged Image File Format
TXT Text file (see 4.16)

CAUTION: Outputting binary files to the command shell without catching that data in a pipe can have unpredictable results. Use with care!

4.13 Automatic filenames

The --mirror option instructs Zint to use the data to be encoded as an indicator of the filename to be used. This is particularly useful if you are processing batch data. For example the input data "1234567" will result in a file named 1234567.png.

There are restrictions, however, on what characters can be stored in a file name, so the file name may vary from the data if the data includes non- printable characters, for example, and may be shortened if the data input is long.

To set the output file format use the --filetype= option as detailed in section 4.12.

4.14 Working with Dots

Matrix codes can be rendered as a series of dots or circles rather than the normal squares by using the --dotty option. This option is only available for matrix symbologies, and is automatically selected for DotCode. The size of the dots can be adjusted using the --dotsize= option followed by the radius of the dot, where that radius is given as a multiple of the X-dimension. The minimum dot size is 0.01, the maximum is 20.

The default and minimum scale for raster output in dotty mode is 1.

4.15 Help options

There are three help options which give information about how to use the command line. The -h or --help option will display a list of all of the valid options available, and also gives the exact version of the software.

The -t or --types option gives the table of symbologies along with the symbol ID numbers and names.

The -e or --ecinos option gives a list of the ECI codes.

4.16 Other output options

For linear barcodes the text present in the output image can be removed by using the --notext option.

The text can be set to bold using the --bold option, or a smaller font can be substituted using the --small option. The --bold and --small options can be used together if required.

Zint can output a representation of the symbol data as a set of hexadecimal values if asked to output to a text file (*.txt) or if given the option --filetype=txt. This can be used for test and diagnostic purposes.

The --cmyk option is specific to output in encapsulated PostScript and TIF, and converts the RGB colours used to the CMYK colour space. Setting custom colours at the command line will still need to be done in RRGGBB format.

Additional options are available which are specific to certain symbologies. These may, for example, control the amount of error correction data or the size of the symbol. These options are discussed in section 6 of this guide.