4. Using the Command Line

This section describes how to encode data using the command line frontend program. The examples given are for the Unix 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 Unix 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'

Some examples use backslash (\) to continue commands onto the next line. For Windows, use caret (^) instead.

Certain options that take values have short names as well as long ones, namely -b (--barcode), -d (--data), -i (--input), -o (--output) and -w (--whitesp). For these a space should be used to separate the short name from its value, to avoid ambiguity. For long names a space or an equals sign may be used. For instance:

zint -d "This Text"
zint --data="This Text"
zint --data "This Text"

The examples use a space separator for short option names, and an equals sign for long option names.

4.1 Inputting Data

The data to encode can be entered at the command line using the -d or --data 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 UTF-8 (Unicode) 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 4.10 Input Modes below.

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

Input data can be read directly from file using the -i or --input switch as shown below. The input file is assumed to be 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 (see 4.11 Batch Processing 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 or --output 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 filename 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"

Names are treated case-insensitively by the CLI, and the BARCODE_ prefix and any underscores are optional.

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.

The default height of most linear barcodes is 50X, but this can be changed for barcodes whose specifications give a standard height by using the switch --compliantheight. For instance

zint -b LOGMARS -d "This Text" --compliantheight

will produce a barcode of height 45.455X instead of the normal default of 50X. The flag also causes Zint to return a warning if a non-compliant height is given:

zint -b LOGMARS -d "This Text" --compliantheight --height=6.2
Warning 247: Height not compliant with standards

Another switch is --heightperrow, which can be useful for symbologies that have a variable number of linear rows, namely Codablock-F, Code 16K, Code 49, GS1 DataBar Expanded Stacked, MicroPDF417 and PDF417, as it changes the treatment of the height value from overall height to per-row height, allowing you to specify a consistent height for each linear row without having to know how many there are. For instance

zint -b PDF417 -d "This Text" --height=4 --heightperrow

will produce a barcode of height 32X, with each of the 8 rows 4X high.

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"

A --quietzones option is also available which adds quiet zones compliant with the symbology’s specification. This is in addition to any whitespace specified with the --whitesp or --vwhitesp switches.

Note that Codablock-F, Code 16K, Code 49, ITF-14, EAN-2 to EAN-13, ISBN, UPC-A and UPC-E have compliant quiet zones added by default. This can be disabled with the option --noquietzones.

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 bars or box borders must be specified using the --border switch. For example:

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

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.

For linear symbols, horizontal boundary bars appear tight against the barcode, inside any vertical whitespace (or text). For matrix symbols, however, where they are decorative rather than functional, boundary bars appear outside any whitespace.

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 6.1.2.6 ITF-14 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 or --reverse switch allows the default colours to be inverted so that a white symbol is shown on a black background (known as “reflectance reversal” or “reversed reflectance”). For example the command

zint -r -d "This Text"

gives an inverted Code 128 symbol. This is not practical for most symbologies but white-on-black is allowed by the Aztec Code, Data Matrix, Han Xin Code, Grid Matrix and QR 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=00FF00 -d "This Text"

alters the symbol to a bright green.

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

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

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!

In addition the --nobackground option will simply remove the background from EMF, EPS, GIF, PNG, SVG and TIF 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=90
--rotate=180
--rotate=270

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 (with the exception of MaxiCode) before being applied. The default scale is 1.

For MaxiCode, the scale is multiplied by 10 for raster output, by 20 for EMF vector output, and by 2 otherwise (non-EMF vector output).

For raster output, the default X-dimension is 2 pixels (except for MaxiCode, see 4.9.2 MaxiCode Raster Scaling below). For example for PNG images a scale of 5 will increase the X-dimension to 10 pixels. Scales for raster output 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 Working with Dots).

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

The maximum scale for both raster and vector is 100.

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" --compliantheight --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:

Note that the 0.5 increment recommended for normal raster output does not apply. Scales below 0.5 are not recommended and may produce symbols that are not within the minimum/maximum size ranges.

4.10 Input Modes

4.10.1 Unicode, Data, and GS1 Modes

By default all CLI input data is assumed to be encoded in UTF-8 format. Many barcode symbologies encode data using the Latin-1 (ISO/IEC 8859-1 plus ASCII) character set, so input is converted from UTF-8 to Latin-1 before being put in the symbol. In addition QR Code and its variants and Han Xin Code can by default encode Japanese (Kanji) or Chinese (Hanzi) characters which are also converted from UTF-8.

There are two exceptions to the Latin-1 default: Grid Matrix, whose default character set is GB 2312 (Chinese); and UPNQR, whose default character set is Latin-2 (ISO/IEC 8859-2 plus ASCII).

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 if the symbology supports it - see 4.10.2 Input Modes and ECI below.

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

Health Industry Barcode (HIBC) data may also be encoded in the symbologies Aztec Code, Codablock-F, Code 128, Code 39, Data Matrix, MicroPDF417, PDF417 and QR 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 translation to an ECI page 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 non-ASCII 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, 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.

4.10.2 Input Modes and ECI

If your data contains characters that are not in the default character set, you may encode it using an ECI-aware symbology and an ECI value from Table below. The ECI information is added to your code symbol as prefix data. The symbologies that support ECI are

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 the default character set then you should check that the resulting barcode can be understood by your target barcode reader.

The ECI value may be specified with the --eci switch, followed by the value in the column "ECI Code" in the table below. The input data should be UTF-8 formatted. Zint automatically translates the data into the target encoding.

An ECI value of 0 does not encode any ECI information in the code symbol (unless the data contains non-default character set characters). In this case, the default character set applies (see Table above).

If no ECI is specified or a value of 0 is given, and the data does contain characters other than in the default character set, then Zint will automatically insert the appropriate single-byte ECI if possible (ECIs 3 to 24, excluding ECI 20), or failing that ECI 26 (UTF-8). A warning will be generated. This mechanism is not applied if the --binary option is given.

Multiple ECIs can be specified using the --segN options - see 4.15 Multiple Segments.

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

4.10.2.1 Input Modes and ECI 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 --scale=10 --eci=17 -i utf8euro.txt

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

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

zint -b 71 --scale=10 --eci=17 --esc -d "\u20AC"

and to the command:

zint -b 71 --scale=10 --eci=17 -d "€"

4.10.2.2 Input Modes and ECI Example 2

The Chinese character with the 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 --scale=10 --eci=28 --binary -i big5char.txt

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

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

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

zint -b 71 --scale=10 --eci=28 --esc -d "\xE5\xB8\xB8"

zint -b 71 --scale=10 --eci=28 --esc -d "\u5E38"

zint -b 71 --scale=10 --eci=28 -d "常"

4.10.2.3 Input Modes and ECI 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 filename as shown in the table below:

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 (or GIF image if libpng is not present), 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:

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 filename, so the filename 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 above in 4.12 Direct Output.

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 diameter of the dot, where that diameter is given as a multiple of the X-dimension. The minimum dot size is 0.01, the maximum is 20. The default size is 0.8.

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

4.15 Multiple Segments

If you need to specify different ECIs for different sections of the input data, the --seg1 to --seg9 options can be used. Each option is of the form --segN=ECI,data where ECI is the ECI code (see Table ) and data is the data to which this applies. This is in addition to the ECI and data specified using the --eci and -d options which must still be present and which in effect constitute segment 0. For instance

zint -b AZTEC_CODE --eci=9 -d "Κείμενο" --seg1=7,"Текст" --seg2=20,"文章"

specifies 3 segments: segment 0 with ECI 9 (Greek), segment 1 with ECI 7 (Cyrillic), and segment 2 with ECI 20 (Shift JIS). Segments must be consecutive.

The symbology must be ECI-aware (see Table ).

ECIs of zero may be given, in which case Zint will automatically determine an ECI if necessary, as described in section 4.10.2 Input Modes and ECI.

Multiple segments are not currently supported for use with GS1 data.

4.16 Structured Append

Structured Append is a method of splitting data among several symbols so that they form a sequence that can be scanned and re-assembled in the correct order on reading, and is available for Aztec Code, Code One, Data Matrix, DotCode, Grid Matrix, MaxiCode, MicroPDF417, PDF417, QR Code and Ultracode.

The --structapp option marks a symbol as part of a Structured Append sequence, and has the format

--structapp=I,C[,ID]

where I is the index (position) of the symbol in the Structured Append sequence, C is the count or total number of symbols in the sequence, and ID is an optional identifier (not available for Code One, DotCode or MaxiCode) that is the same for all symbols belonging to the same sequence. The index is 1-based and goes from 1 to count. Count must be 2 or more. See the individual symbologies for further details.

4.17 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 version by itself can be displayed with -v or --version).

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.18 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, but only for vector output.

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. Types of Symbology of this guide.