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|
|\E||004||EOT||End of Transmission|
|\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"
zint -b DATAMATRIX -o datamatrix.png -d "Data to encode"
|Numeric Value||Name (case - insensitive)||Barcode Name|
|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|
|20||CODE128||Code 128 (automatic subset switching)|
|21||DPLEIT||Deutshe Post Leitcode|
|22||DPIDENT||Deutshe Post Identcode|
|29||DBAR_OMN||GS1 DataBar Omnidirectional (including GS1 DataBar Truncated)|
|30||DBAR_LTD||GS1 DataBar Limited|
|31||DBAR_EXT||GS1 DataBar Etended|
|35||UPCA_CHK||UPC-A + Check Digit|
|38||UPCE_CHK||UPC-E + Check Digit|
|56||PDF417COMP||Compact PDF417 (Truncated PDF417)|
|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)|
|73||VIN||Vehicle Identification Number (America)|
|76||JAPANPOST||Japanese Postal Code|
|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|
|85||USPS_IMAIL||USPS Intelligent Mail (OneCode)|
|90||KIX||Dutch Post KIX 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|
|112||HIBC_AZTEC||HIBC Aztec Code|
|116||HANXIN||Han Xin (Chinese Sensible) Code|
|121||MAILMARK||Royal Mail 4-State Mailmark|
|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|
|143||UPNQR||UPNQR - Univerzalni Plačilni Nalog QR|
|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 188.8.131.52 for that symbology.
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.
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)
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 184.108.40.206 "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:
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:
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 220.127.116.11). 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)|
|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|
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 "€"
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 "常"
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:
|~||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:
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:
|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.