4. Using the Command Line

This section describes how to encode data using the command line front end program. The examples given are for the Linux platform, but the same options are available for Windows - just rememer to include the executable file extension. i.e.:

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 -d switch and the input data should always be the last entry on the command line input. Any options given after this will be ignored.

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

Non-printing characters can be entered on the command line using the backslash (\) as an escape character. Permissible characters are shown in the table below. Note that this only applies on the command line.

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 and should similarly be the last option given.

zint -i ./somefile.txt

4.2 Directing Output

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

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

This draws a Code 128 barcode in the file here.png. If an encapsulated Post Script 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 in the following table. For example to create a Data Matrix symbol you could use:

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

4.4 Adjusting height

The height of a linear symbol can be adjusted using the --height switch. For eample:

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 whitespace to the left and right of the generated barcode can be altered using the –w switch. For example:

zint -w 10 -d "This Text"

This specifies a whitespace width of 10 times the x-dimension of the symbol.

4.6 Adding boundary bars and boxes

Zint allows the symbol to be bound with 'boundary 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 whitespace with the --box option. This option is automatically selected for ITF-14 symbols.

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-resolution of the symbol.

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 headecimal 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.

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. This option is only available with raster image (PNG, BMP, GIF and PCX) output.

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. For example for PNG images a scale of 5 will increase the x-dimension to 10 pixels.

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-8851-1) character encoding, so input is converted from Unicode to Latin-1 before being put in the symbol. In addition QR Code, Micro QR Code, rectangular QR Code, Han in Code and Grid Matrix standards can encode Japanese or Chinese characters which are also converted from Unicode. 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 ECI codes have 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 5.1.12.3). To encode GS1 data use the --gs1 option. GS1 mode is assumed (and doesn't need to be set) for EAN-128, DataBar and Composite symbologies but is also available for Code 16k, Data Matrix, Aztec Code, DotCode and QR Code.

HIBC data may also be encoded in the symbologies Code 39, Code128, Codablock-F, Data Matrix, QR Code, PDF417 and Aztec Code. Within this mode, the leading '+' and the check character are automatically added.

The --binary option prevents Zint from performing any convertion of the data before placing in the barcode symbol and should be used if you are encoding raw binary or encrypted data.

The --binary option encodes the input data as given. Automatic code page translations to ECI pages is disabled. This may be used for raw binary or binary encrypted data. This switch plays together with the build-in ECI logic and examples may be found in that section.

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 characters, however some decoders take blocks which are encoded this way and interpret them as Kanji characters, typically by applying a transformation to UTF8 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-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 included into the symbol.

The input data should be utf-8 formatted. Zint automatically translates the data into the target encoding. The rows marked with a star (*); do not do this transformation. The data must be specified as binary data (--binary switch) with the data in the encoding given by the "Character Encoding Scheme" column.

The row marked with a double star (**) only does this transformation for QR Code, Micro QR Code and Rectangular Micro QR Code.

The row marked with a triple star (***) only does this transformation for Han Xin Code and Grid Matrix. Han Xin Code can encode GB 18030. Grid Matrix can encode the subset GB 2312.

Note: the "--eci 3" specification may 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.

Ex1: The Euro sign can be encoded in ISO-8859-15. The Euro-Sign has the ISO8859-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.exe -b 71 --square --scale 10 --eci 17 -i utf8euro.txt

Ex2: The Chinese character with Unicode codepoint hex 5e38 can be encoded in big5 encoding. The big5 ECI is marked in the upper table to require input data in Big5 instead of utf-8. The big5 representation of this character are the two hex bytes: 9C 75 (contained in the file big5char.txt). The generation command for Data Matrix is:
zint.exe -b 71 --square --scale 10 --eci 28 --binary -i big5char.txt

Ex3: 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: 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 return 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:

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 supplimenting the --direct option with a --filetype= option followed by the suffix of the file type required. For example:

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 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.

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.

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

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 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.