Mercurial > hgrepos > Python2 > PyMuPDF
diff mupdf-source/thirdparty/zint/docs/manual.txt @ 2:b50eed0cc0ef upstream
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4.
The directory name has changed: no version number in the expanded directory now.
| author | Franz Glasner <fzglas.hg@dom66.de> |
|---|---|
| date | Mon, 15 Sep 2025 11:43:07 +0200 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mupdf-source/thirdparty/zint/docs/manual.txt Mon Sep 15 11:43:07 2025 +0200 @@ -0,0 +1,5617 @@ +Zint Barcode Generator and Zint Barcode Studio User Manual +Version 2.13.0.9 +December 2024 + +******************************************************************************* +* For reference the following is a text-only version of the Zint manual, * +* generated from "docs/manual.pmd" by pandoc. * +* A HTML version can be accessed at https://zint.org.uk/manual/ * +* however this text file is more likely to be up-to-date. * +******************************************************************************* + +- 1. Introduction + - 1.1 Glossary +- 2. Installing Zint + - 2.1 Linux + - 2.2 BSD + - 2.3 Microsoft Windows + - 2.4 Apple macOS + - 2.5 Zint Tcl Backend +- 3. Using Zint Barcode Studio + - 3.1 Main Window and Data Tab + - 3.2 GS1 Composite Groupbox + - 3.3 Additional ECI/Data Segments Groupbox + - 3.4 Symbology-specific Groupbox + - 3.5 Symbology-specific Tab + - 3.6 Appearance Tab + - 3.7 Data Dialog + - 3.8 Sequence Dialog + - 3.9 Export Dialog + - 3.10 CLI Equivalent Dialog +- 4. Using the Command Line + - 4.1 Inputting Data + - 4.2 Directing Output + - 4.3 Selecting Barcode Type + - 4.4 Adjusting Height + - 4.5 Adjusting Whitespace + - 4.6 Adding Boundary Bars and Boxes + - 4.7 Using Colour + - 4.8 Rotating the Symbol + - 4.9 Adjusting Image Size (X-dimension) + - 4.9.1 Scaling by X-dimension and Resolution + - 4.9.2 Scaling Example + - 4.9.3 MaxiCode Raster Scaling + - 4.10 Human Readable Text (HRT) Options + - 4.11 Input Modes + - 4.11.1 Unicode, Data, and GS1 Modes + - 4.11.2 Input Modes and ECI + - 4.11.2.1 Input Modes and ECI Example 1 + - 4.11.2.2 Input Modes and ECI Example 2 + - 4.11.2.3 Input Modes and ECI Example 3 + - 4.12 Batch Processing + - 4.13 Direct Output to stdout + - 4.14 Automatic Filenames + - 4.15 Working with Dots + - 4.16 Multiple Segments + - 4.17 Structured Append + - 4.18 Help Options + - 4.19 Other Options +- 5. Using the API + - 5.1 Creating and Deleting Symbols + - 5.2 Encoding and Saving to File + - 5.3 Encoding and Printing Functions in Depth + - 5.4 Buffering Symbols in Memory (raster) + - 5.5 Buffering Symbols in Memory (vector) + - 5.6 Buffering Symbols in Memory (memfile) + - 5.7 Setting Options + - 5.8 Handling Errors + - 5.9 Specifying a Symbology + - 5.10 Adjusting Output Options + - 5.11 Setting the Input Mode + - 5.12 Multiple Segments + - 5.13 Scaling Helpers + - 5.14 Verifying Symbology Availability + - 5.15 Checking Symbology Capabilities + - 5.16 Zint Version +- 6. Types of Symbology + - 6.1 One-Dimensional Symbols + - 6.1.1 Code 11 + - 6.1.2 Code 2 of 5 + - 6.1.2.1 Standard Code 2 of 5 + - 6.1.2.2 IATA Code 2 of 5 + - 6.1.2.3 Industrial Code 2 of 5 + - 6.1.2.4 Interleaved Code 2 of 5 (ISO 16390) + - 6.1.2.5 Code 2 of 5 Data Logic + - 6.1.2.6 ITF-14 + - 6.1.2.7 Deutsche Post Leitcode + - 6.1.2.8 Deutsche Post Identcode + - 6.1.3 UPC (Universal Product Code) (ISO 15420) + - 6.1.3.1 UPC Version A + - 6.1.3.2 UPC Version E + - 6.1.4 EAN (European Article Number) (ISO 15420) + - 6.1.4.1 EAN-2, EAN-5, EAN-8 and EAN-13 + - 6.1.4.2 SBN, ISBN and ISBN-13 + - 6.1.5 Plessey + - 6.1.5.1 UK Plessey + - 6.1.5.2 MSI Plessey + - 6.1.6 Telepen + - 6.1.6.1 Telepen Alpha + - 6.1.6.2 Telepen Numeric + - 6.1.7 Code 39 + - 6.1.7.1 Standard Code 39 (ISO 16388) + - 6.1.7.2 Extended Code 39 + - 6.1.7.3 Code 93 + - 6.1.7.4 PZN (Pharmazentralnummer) + - 6.1.7.5 LOGMARS + - 6.1.7.6 Code 32 + - 6.1.7.7 HIBC Code 39 + - 6.1.7.8 Vehicle Identification Number (VIN) + - 6.1.8 Codabar (EN 798) + - 6.1.9 Pharmacode + - 6.1.10 Code 128 + - 6.1.10.1 Standard Code 128 (ISO 15417) + - 6.1.10.2 Code 128 Suppress Code Set C (Code Sets A and B only) + - 6.1.10.3 GS1-128 + - 6.1.10.4 EAN-14 + - 6.1.10.5 NVE-18 (SSCC-18) + - 6.1.10.6 HIBC Code 128 + - 6.1.10.7 DPD Code + - 6.1.10.8 UPU S10 + - 6.1.11 GS1 DataBar (ISO 24724) + - 6.1.11.1 GS1 DataBar Omnidirectional and GS1 DataBar Truncated + - 6.1.11.2 GS1 DataBar Limited + - 6.1.11.3 GS1 DataBar Expanded + - 6.1.12 Korea Post Barcode + - 6.1.13 Channel Code + - 6.1.14 BC412 (SEMI T1-95) + - 6.2 Stacked Symbologies + - 6.2.1 Basic Symbol Stacking + - 6.2.2 Codablock-F + - 6.2.3 Code 16K (EN 12323) + - 6.2.4 PDF417 (ISO 15438) + - 6.2.5 Compact PDF417 (ISO 15438) + - 6.2.6 MicroPDF417 (ISO 24728) + - 6.2.7 GS1 DataBar Stacked (ISO 24724) + - 6.2.7.1 GS1 DataBar Stacked + - 6.2.7.2 GS1 DataBar Stacked Omnidirectional + - 6.2.7.3 GS1 DataBar Expanded Stacked + - 6.2.8 Code 49 + - 6.3 GS1 Composite Symbols (ISO 24723) + - 6.3.1 CC-A + - 6.3.2 CC-B + - 6.3.3 CC-C + - 6.4 Two-Track Symbols + - 6.4.1 Two-Track Pharmacode + - 6.4.2 POSTNET + - 6.4.3 PLANET + - 6.4.4 Brazilian CEPNet + - 6.4.5 DX Film Edge Barcode + - 6.5 4-State Postal Codes + - 6.5.1 Australia Post 4-State Symbols + - 6.5.1.1 Customer Barcodes + - 6.5.1.2 Reply Paid Barcode + - 6.5.1.3 Routing Barcode + - 6.5.1.4 Redirect Barcode + - 6.5.2 Dutch Post KIX Code + - 6.5.3 Royal Mail 4-State Customer Code (RM4SCC) + - 6.5.4 Royal Mail 4-State Mailmark + - 6.5.5 USPS Intelligent Mail + - 6.5.6 Japanese Postal Code + - 6.5.7 DAFT Code + - 6.6 Matrix Symbols + - 6.6.1 Data Matrix (ISO 16022) + - 6.6.2 Royal Mail 2D Mailmark (CMDM) (Data Matrix) + - 6.6.3 QR Code (ISO 18004) + - 6.6.4 Micro QR Code (ISO 18004) + - 6.6.5 Rectangular Micro QR Code (rMQR) (ISO 23941) + - 6.6.6 UPNQR (Univerzalnega Plačilnega Naloga QR) + - 6.6.7 MaxiCode (ISO 16023) + - 6.6.8 Aztec Code (ISO 24778) + - 6.6.9 Aztec Runes (ISO 24778) + - 6.6.10 Code One + - 6.6.11 Grid Matrix + - 6.6.12 DotCode + - 6.6.13 Han Xin Code (ISO 20830) + - 6.6.14 Ultracode + - 6.7 Other Barcode-Like Markings + - 6.7.1 Facing Identification Mark (FIM) + - 6.7.2 Flattermarken +- 7. Legal and Version Information + - 7.1 License + - 7.2 Patent Issues + - 7.3 Version Information + - 7.4 Sources of Information + - 7.5 Standards Compliance + - 7.5.1 Symbology Standards + - 7.5.2 General Standards +- Annex A. Character Encoding + - A.1 ASCII Standard + - A.2 Latin Alphabet No. 1 (ISO/IEC 8859-1) +- Annex B. Qt Backend QZint +- Annex C. Tcl Backend Binding +- Annex D. Man Page ZINT(1) + - NAME + - SYNOPSIS + - DESCRIPTION + - OPTIONS + - EXIT STATUS + - EXAMPLES + - BUGS + - SEE ALSO + - CONFORMING TO + - COPYRIGHT + - AUTHOR + +1. Introduction + +The Zint project aims to provide a complete cross-platform open source barcode +generating solution. The package currently consists of a Qt-based GUI, a CLI +command line executable and a library with an API to allow developers access to +the capabilities of Zint. It is hoped that Zint provides a solution which is +flexible enough for professional users while at the same time takes care of as +much of the processing as possible to allow easy translation from input data to +barcode image. + +The library which forms the main component of the Zint project is currently able +to encode data in over 50 barcode symbologies (types of barcode), for each of +which it is possible to translate that data from either UTF-8 (Unicode) or a raw +8-bit data stream. The image can be rendered as a + +- Windows Bitmap (BMP), +- Enhanced Metafile Format (EMF), +- Encapsulated PostScript (EPS), +- Graphics Interchange Format (GIF), +- ZSoft Paintbrush (PCX) image, +- Portable Network Graphic (PNG) image, +- Tagged Image File Format (TIF), or a +- Scalable Vector Graphic (SVG). + +Many options are available for setting the characteristics of the output image +including the size and colour of the image, the amount of error correction used +in the symbol and the orientation of the image. + +1.1 Glossary + +Some of the words and phrases used in this document are specific to barcoding, +and so a brief explanation is given to help understanding: + +symbol + + A symbol is an image which encodes data according to one of the standards. + This encompasses barcodes (linear symbols) as well as any of the other + methods of representing data used in this program. + +symbology + + A method of encoding data to create a certain type of symbol. + +linear + + A linear or one-dimensional symbol is one which consists of bars and spaces, + and is what most people associate with the term ‘barcode’. Examples include + Code 128. + +stacked + + A stacked symbol consists of multiple linear symbols placed one above + another and which together hold the message, usually alongside some error + correction data. Examples include PDF417. + +matrix + + A matrix symbol is one based on a (usually square) grid of elements called + modules. Examples include Data Matrix, but MaxiCode and DotCode are also + considered matrix symbologies. + +composite + + A composite symbology is one which is made up of elements which are both + linear and stacked. Those currently supported are made up of a linear + ‘primary’ message above which is printed a stacked component based on the + PDF417 symbology. These symbols also have a separator which separates the + linear and the stacked components. The stacked component is most often + referred to as the 2D (two-dimensional) component. + +X-dimension + + The X-dimension of a symbol is the size (usually the width) of the smallest + element. For a linear symbology this is the width of the smallest bar. For + matrix symbologies it is the width of the smallest module (usually a + square). Barcode widths and heights are expressed in X-dimensions. Most + linear symbologies can have their height varied whereas most matrix + symbologies have a fixed width-to-height ratio where the height is + determined by the width. + +GS1 data + + This is a structured way of representing information which consists of + ‘chunks’ of data, each of which starts with an Application Identifier (AI). + The AI identifies what type of information is being encoded. + +Reader Initialisation (Programming) + + Some symbologies allow a special character to be included which can be + detected by the scanning equipment as signifying that the data is used to + program or change settings in that equipment. This data is usually not + passed on to the software which handles normal input data. This feature + should only be used if you are familiar with the programming codes relevant + to your scanner. + +ECI + + The Extended Channel Interpretations (ECI) mechanism allows for + multi-language data to be encoded in symbols which would usually support + only Latin-1 (ISO/IEC 8859-1 plus ASCII) characters. This can be useful, for + example, if you need to encode Cyrillic characters, but should be used with + caution as not all scanners support this method. + +Two other concepts that are important are raster and vector. + +raster + + A low level bitmap representation of an image. BMP, GIF, PCX, PNG and TIF + are raster file formats. + +vector + + A high level command- or data-based representation of an image. EMF, EPS and + SVG are vector file formats. They require renderers to turn them into + bitmaps. + +2. Installing Zint + +2.1 Linux + +The easiest way to configure compilation is to take advantage of the CMake +utilities. You will need to install CMake and libpng-dev first. For instance on +apt systems: + + sudo apt install git cmake build-essential libpng-dev + +If you want to take advantage of Zint Barcode Studio you will also need to have +Qt and its component "Desktop gcc 64-bit" installed, as well as mesa. For +details see "README.linux" in the project root directory. + +Once you have fulfilled these requirements unzip the source code tarball or +clone the latest source + + git clone https://git.code.sf.net/p/zint/code zint + +and follow these steps in the top directory: + + mkdir build + cd build + cmake .. + make + sudo make install + +The CLI command line program can be accessed by typing + + zint [options] + +The GUI can be accessed by typing + + zint-qt + +To test that the installation has been successful a shell script is included in +the "frontend" sub-directory. To run the test type + + ./test.sh + +This should create numerous files in the sub-directory "frontend/test_sh_out" +showing the many modes of operation which are available from Zint. + +2.2 BSD + +The latest Zint CLI, libzint library and GUI can be installed from the zint +package on FreeBSD: + + su + pkg install zint + exit + +and on OpenBSD (where the GUI is in a separate zint-gui package): + + su + pkg_add zint zint-gui + exit + +To build from source (including for NetBSD) see "README.bsd" in the project root +directory. + +2.3 Microsoft Windows + +For Microsoft Windows, Zint is distributed as a binary executable. Simply +download the ZIP file, then right-click on the ZIP file and "Extract All". A new +folder will be created within which are two binary files: + +- qtZint.exe - Zint Barcode Studio +- zint.exe - Command Line Interface + +For fresh releases you will get a warning message from Microsoft Defender +SmartScreen that this is an ‘unrecognised app’. This happens because Zint is a +free and open-source software project with no advertising and hence no income, +meaning we are not able to afford the $664 per year to have the application +digitally signed by Microsoft. + +To build Zint on Windows from source, see "win32/README". + +2.4 Apple macOS + +The latest Zint CLI and libzint can be installed using Homebrew.[1] To install +Homebrew input the following line into the macOS terminal + + /bin/bash -c "$(curl -fsSL \ + https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + +Once Homebrew is installed use the following command to install the CLI and +library + + brew install zint + +To build from source (and install the GUI) see "README.macos" in the project +root directory. + +2.5 Zint Tcl Backend + +The Tcl backend in the "backend_tcl" sub-directory may be built using the +provided TEA (Tcl Extension Architecture) build on Linux, Windows, macOS and +Android. For Windows, an MSVC6 makefile is also available. See Annex C. Tcl +Backend Binding for further details. + +3. Using Zint Barcode Studio + +Zint Barcode Studio is the graphical user interface for Zint. If you are +starting from a command line interface you can start the GUI by typing + + zint-qt + +or on Windows + + qtZint.exe + +See the note in section 2.3 Microsoft Windows about Microsoft Defender +SmartScreen. + +Below is a brief guide to Zint Barcode Studio. + +3.1 Main Window and Data Tab + +[Zint Barcode Studio on startup - main window with Data tab] + +This is the main window of Zint Barcode Studio. The top of the window shows a +preview of the barcode that the current settings would create. These settings +can be changed using the controls below. The text box in the "Data to Encode" +groupbox on this first Data tab allows you to enter the data to be encoded. When +you are happy with your settings you can use the "Save..." button to save the +resulting image to a file. + +The "Symbology" drop-down box gives access to all of the symbologies supported +by Zint shown in alphabetical order. The text box to its right can filter the +drop-down to only show matching symbologies. For instance typing "mail" will +only show barcodes in the drop-down whose names contain the word "mail". Each +word entered will match. So typing "mail post" will show barcodes whose names +contain "mail" or "post" (or both). + +The ellipsis button "..." to the right of the data text box invokes the Data +Dialog - see 3.7 Data Dialog for details. The delete button [delete] next to it +will clear the data text box and the ECI (Extended Channel Interpretations) +drop-down if set. + +To set the barcode as a Programming Initialisation symbol click the +"Reader Init" checkbox. The "1234.." button to its right invokes the Sequence +Dialog - see 3.8 Sequence Dialog. The zap button [zap] will clear all data and +reset all settings for the barcode to defaults. + +The "BMP" and "SVG" buttons at the bottom will copy the image to the clipboard +in BMP format and SVG format respectively. Further copy-to-clipboard formats are +available by clicking the "Menu" button, along with "CLI Equivalent...", +"Save As...", "Factory Reset...", "Help", "About..." and "Quit" options. Most of +the options are also available in a context menu by right-clicking the preview. + +[Zint Barcode Studio main menu (left) and context menu (right)] + +3.2 GS1 Composite Groupbox + +[Zint Barcode Studio encoding GS1 Composite data] + +In the middle of the Data tab is an area for creating composite symbologies +which appears when the currently selected symbology is supported by the GS1 +Composite symbology standard. GS1 data can then be entered with square brackets +used to separate Application Identifier (AI) information from data as shown +here. For details, see 6.3 GS1 Composite Symbols (ISO 24723). + +3.3 Additional ECI/Data Segments Groupbox + +[Zint Barcode Studio encoding multiple segments] + +For symbologies that support ECIs (Extended Channel Interpretations) the middle +of the Data tab is an area for entering additional data segments with their own +ECIs. Up to 4 segments (including the main "Data to Encode" as segment 0) may be +specified. See 4.16 Multiple Segments for details. + +3.4 Symbology-specific Groupbox + +[Zint Barcode Studio showing Code 2 of 5 Interleaved settings] + +Many symbologies have extra options to change the content, format and appearance +of the symbol generated. For those with few additional options (and no support +for GS1 data or ECIs), the middle of the Data tab is an area for setting those +options. + +Here is shown the check digit options for an Interleaved Code 2 of 5 symbol (see +6.1.2.4 Interleaved Code 2 of 5 (ISO 16390)). + +Symbologies with more than a few options (or support for GS1 data or ECIs) have +a second Symbology-specific tab, shown next. + +3.5 Symbology-specific Tab + +[Zint Barcode Studio showing Aztec Code options] + +A second tab appears for those symbologies with more than a few extra options. + +Here is shown the options available for an Aztec Code symbol. + +You can adjust its size or error correction level (see 6.6.8 Aztec Code (ISO +24778)), select how its data is to be treated (see 4.11 Input Modes), and set it +as part of a Structured Append sequence of symbols (see 4.17 Structured Append). + +3.6 Appearance Tab + +[Zint Barcode Studio showing Appearance tab options] + +The Appearance tab can be used to adjust the dimensions and other properties of +the symbol. + +The "Height" value affects the height of symbologies which do not have a fixed +width-to-height ratio, i.e. those other than matrix symbologies. For such +symbologies the "Automatic Height" checkbox will be enabled - uncheck this to +manually adjust the height. The "Compliant Height" checkbox applies to +symbologies that define a standard height - see 4.4 Adjusting Height. + +Boundary bars can be added with the "Border Type" drop-down and their size +adjusted with "Border Width", and whitespace can be adjusted both horizontally +(first spinbox) and vertically (second spinbox), and also through the +"Quiet Zones" checkbox if standard quiet zones are defined for the symbology. + +The size of the saved image can be specified with "Printing Scale", and also by +clicking the [scaling] icon to invoke the Set Printing Scale Dialog - see 4.9 +Adjusting Image Size (X-dimension) for further details. + +[Adjusting the Print Size] + +The foreground and background colours can be set either using the text boxes +which accept "RRGGBBAA" hexadecimal values and "C,M,Y,K" decimal percentage +values, or by clicking the foreground eye [eye] and background eye [eye] buttons +which invoke a colour picker. + +[The colour picker tool] + +(Note that to change the colours visually, the luminence slider, the long narrow +column on the right, must be adjusted.) The color picker only deals in RGB(A), +and will overwrite any CMYK values with RGB(A) values once "OK" is selected. + +Back in the Appearance tab, the colours can be reset to black-on-white using the +"Reset" button, and exchanged one for the other using the swap [swap] button +next to it. + +3.7 Data Dialog + +[Entering longer text input] + +Clicking on the ellipsis "..." button next to the "Data to Encode" text box in +the Data tab opens a larger window which can be used to enter longer strings of +text. You can also use this window to load data from a file. + +The dialog is also available for additional ECI/Data segments by clicking the +ellipsis button to the right of their data text boxes. + +Note that if your data contains line feeds (LF) then the data will be split into +separate lines in the dialog box. On saving the data back to the main text box +any separate lines in the data will be escaped as '\n' and the "Parse Escapes" +checkbox will be set. This only affects line feeds, not carriage returns (CR) or +CR+LF pairs, and behaves the same on both Windows and Unix. (For details on +escape sequences, see 4.1 Inputting Data.) + +3.8 Sequence Dialog + +[Creating a sequence of barcode symbols] + +Clicking on the sequence button (labelled "1234..") in the Data tab opens the +Sequence Dialog. This allows you to create multiple barcode images by entering a +sequence of data inputs in the right hand panel. Sequences can also be +automatically generated by entering parameters on the left hand side or by +importing the data from a file. Zint will generate a separate barcode image for +each line of text in the right hand panel. The format field determines the +format of the automatically generated sequence where characters have the +meanings as given below: + + Character Effect + --------------------- -------------------------- + $ Insert leading zeroes + # Insert leading spaces + * Insert leading asterisks + Any other character Interpreted literally + + Table : Sequence Format Characters + +Once you’re happy with the Sequence Data, click the "Export..." button to bring +up the Export Dialog, discussed next. + +3.9 Export Dialog + +[Setting filenames for an exported sequence of barcode symbols] + +The Export Dialog invoked by pressing the "Export..." button in the Sequence +Dialog sets the parameters for exporting the sequence of barcode images. Here +you can set the output directory, the format of the output filenames and what +their image type will be. Note that the symbology, colour and other formatting +information are taken from the main window. + +3.10 CLI Equivalent Dialog + +[CLI Equivalent Dialog] + +The CLI Equivalent Dialog can be invoked from the main menu or the context menu +and displays the CLI command that will reproduce the barcode as currently +configured in the GUI. Press the "Copy" button to copy the command to the +clipboard, which can then be pasted into the command line. + +4. Using the Command Line + +This section describes how to encode data using the command line frontend (CLI) +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.11 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. + + ---------------------------------------------------------------------------- + Escape ASCII Name Interpretation + Sequence Equivalent + ----------- ------------ ------- ------------------------------------------- + \0 0x00 NUL Null character + + \E 0x04 EOT End of Transmission + + \a 0x07 BEL Bell + + \b 0x08 BS Backspace + + \t 0x09 HT Horizontal Tab + + \n 0x0A LF Line Feed + + \v 0x0B VT Vertical Tab + + \f 0x0C FF Form Feed + + \r 0x0D CR Carriage Return + + \e 0x1B ESC Escape + + \G 0x1D GS Group Separator + + \R 0x1E RS Record Separator + + \\ 0x5C \ Backslash + + \dNNN NNN Any 8-bit character where NNN is decimal + (000-255) + + \oNNN 0oNNN Any 8-bit character where NNN is octal + (000-377) + + \xNN 0xNN Any 8-bit character where NN is hexadecimal + (00-FF) + + \uNNNN Any 16-bit Unicode BMP[2] character where + NNNN is hexadecimal (0000-FFFF) + + \UNNNNNN Any 21-bit Unicode character where NNNNNN + is hexadecimal (000000-10FFFF) + ---------------------------------------------------------------------------- + + Table : Escape Sequences + +(Special escape sequences are available for Code 128 only to manually switch +Code Sets and insert special FNC1 characters - see 6.1.10.1 Standard Code 128 +(ISO 15417) for details.) + +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 option replaces the use of the -d switch. + + zint -i somefile.txt + +To read from stdin specify a single hyphen "-" as the input file. + +Note that except when batch processing (see 4.12 Batch Processing below), the +file (or stdin) 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" + +The currently supported output file formats are shown in the following table. + + Extension File format + ----------- ------------------------------------ + bmp Windows Bitmap + emf Enhanced Metafile Format + 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.19 Other Options) + + Table : Output File Formats + +The filename can contain directories and sub-directories also, which will be +created if they don’t already exist: + + zint -o "dir/subdir/filename.eps" -d "This Text" + +Note that on Windows, filenames are assumed to be UTF-8 encoded. + +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. + + ------------------------------------------------------------------------------ + Numeric Name[3] Barcode Name + Value + --------- ------------------------- ------------------------------------------ + 1 BARCODE_CODE11 Code 11 + + 2* BARCODE_C25STANDARD Standard Code 2 of 5 + + 3 BARCODE_C25INTER Interleaved 2 of 5 + + 4 BARCODE_C25IATA Code 2 of 5 IATA + + 6 BARCODE_C25LOGIC Code 2 of 5 Data Logic + + 7 BARCODE_C25IND Code 2 of 5 Industrial + + 8 BARCODE_CODE39 Code 3 of 9 (Code 39) + + 9 BARCODE_EXCODE39 Extended Code 3 of 9 (Code 39+) + + 13 BARCODE_EANX EAN (EAN-2, EAN-5, EAN-8 and EAN-13) + + 14 BARCODE_EANX_CHK EAN + Check Digit + + 16* BARCODE_GS1_128 GS1-128 (UCC.EAN-128) + + 18 BARCODE_CODABAR Codabar + + 20 BARCODE_CODE128 Code 128 (automatic Code Set switching) + + 21 BARCODE_DPLEIT Deutsche Post Leitcode + + 22 BARCODE_DPIDENT Deutsche Post Identcode + + 23 BARCODE_CODE16K Code 16K + + 24 BARCODE_CODE49 Code 49 + + 25 BARCODE_CODE93 Code 93 + + 28 BARCODE_FLAT Flattermarken + + 29* BARCODE_DBAR_OMN GS1 DataBar Omnidirectional (including GS1 + DataBar Truncated) + + 30* BARCODE_DBAR_LTD GS1 DataBar Limited + + 31* BARCODE_DBAR_EXP GS1 DataBar Expanded + + 32 BARCODE_TELEPEN Telepen Alpha + + 34 BARCODE_UPCA UPC-A + + 35 BARCODE_UPCA_CHK UPC-A + Check Digit + + 37 BARCODE_UPCE UPC-E + + 38 BARCODE_UPCE_CHK UPC-E + Check Digit + + 40 BARCODE_POSTNET POSTNET + + 47 BARCODE_MSI_PLESSEY MSI Plessey + + 49 BARCODE_FIM FIM + + 50 BARCODE_LOGMARS LOGMARS + + 51 BARCODE_PHARMA Pharmacode One-Track + + 52 BARCODE_PZN PZN + + 53 BARCODE_PHARMA_TWO Pharmacode Two-Track + + 54 BARCODE_CEPNET Brazilian CEPNet + + 55 BARCODE_PDF417 PDF417 + + 56* BARCODE_PDF417COMP Compact PDF417 (Truncated PDF417) + + 57 BARCODE_MAXICODE MaxiCode + + 58 BARCODE_QRCODE QR Code + + 60 BARCODE_CODE128AB Code 128 (Suppress Code Set C) + + 63 BARCODE_AUSPOST Australia Post Standard Customer + + 66 BARCODE_AUSREPLY Australia Post Reply Paid + + 67 BARCODE_AUSROUTE Australia Post Routing + + 68 BARCODE_AUSDIRECT Australia Post Redirection + + 69 BARCODE_ISBNX ISBN (EAN-13 with verification stage) + + 70 BARCODE_RM4SCC Royal Mail 4-State Customer Code (RM4SCC) + + 71 BARCODE_DATAMATRIX Data Matrix (ECC200) + + 72 BARCODE_EAN14 EAN-14 + + 73 BARCODE_VIN Vehicle Identification Number + + 74 BARCODE_CODABLOCKF Codablock-F + + 75 BARCODE_NVE18 NVE-18 (SSCC-18) + + 76 BARCODE_JAPANPOST Japanese Postal Code + + 77 BARCODE_KOREAPOST Korea Post + + 79* BARCODE_DBAR_STK GS1 DataBar Stacked + + 80* BARCODE_DBAR_OMNSTK GS1 DataBar Stacked Omnidirectional + + 81* BARCODE_DBAR_EXPSTK GS1 DataBar Expanded Stacked + + 82 BARCODE_PLANET PLANET + + 84 BARCODE_MICROPDF417 MicroPDF417 + + 85* BARCODE_USPS_IMAIL USPS Intelligent Mail (OneCode) + + 86 BARCODE_PLESSEY UK Plessey + + 87 BARCODE_TELEPEN_NUM Telepen Numeric + + 89 BARCODE_ITF14 ITF-14 + + 90 BARCODE_KIX Dutch Post KIX Code + + 92 BARCODE_AZTEC Aztec Code + + 93 BARCODE_DAFT DAFT Code + + 96 BARCODE_DPD DPD Code + + 97 BARCODE_MICROQR Micro QR Code + + 98 BARCODE_HIBC_128 HIBC Code 128 + + 99 BARCODE_HIBC_39 HIBC Code 39 + + 102 BARCODE_HIBC_DM HIBC Data Matrix ECC200 + + 104 BARCODE_HIBC_QR HIBC QR Code + + 106 BARCODE_HIBC_PDF HIBC PDF417 + + 108 BARCODE_HIBC_MICPDF HIBC MicroPDF417 + + 110 BARCODE_HIBC_BLOCKF HIBC Codablock-F + + 112 BARCODE_HIBC_AZTEC HIBC Aztec Code + + 115 BARCODE_DOTCODE DotCode + + 116 BARCODE_HANXIN Han Xin (Chinese Sensible) Code + + 119 BARCODE_MAILMARK_2D Royal Mail 2D Mailmark (CMDM) (Data + Matrix) + + 121 BARCODE_MAILMARK_4S Royal Mail 4-State Mailmark + + 128 BARCODE_AZRUNE Aztec Runes + + 129 BARCODE_CODE32 Code 32 + + 130 BARCODE_EANX_CC GS1 Composite Symbol with EAN linear + component + + 131* BARCODE_GS1_128_CC GS1 Composite Symbol with GS1-128 linear + component + + 132* BARCODE_DBAR_OMN_CC GS1 Composite Symbol with GS1 DataBar + Omnidirectional linear component + + 133* BARCODE_DBAR_LTD_CC GS1 Composite Symbol with GS1 DataBar + Limited linear component + + 134* BARCODE_DBAR_EXP_CC GS1 Composite Symbol with GS1 DataBar + Expanded linear component + + 135 BARCODE_UPCA_CC GS1 Composite Symbol with UPC-A linear + component + + 136 BARCODE_UPCE_CC GS1 Composite Symbol with UPC-E linear + component + + 137* BARCODE_DBAR_STK_CC GS1 Composite Symbol with GS1 DataBar + Stacked component + + 138* BARCODE_DBAR_OMNSTK_CC GS1 Composite Symbol with GS1 DataBar + Stacked Omnidirectional component + + 139* BARCODE_DBAR_EXPSTK_CC GS1 Composite Symbol with GS1 DataBar + Expanded Stacked component + + 140 BARCODE_CHANNEL Channel Code + + 141 BARCODE_CODEONE Code One + + 142 BARCODE_GRIDMATRIX Grid Matrix + + 143 BARCODE_UPNQR UPNQR (Univerzalnega Plačilnega Naloga QR) + + 144 BARCODE_ULTRA Ultracode + + 145 BARCODE_RMQR Rectangular Micro QR Code (rMQR) + + 146 BARCODE_BC412 IBM BC412 (SEMI T1-95) + + 147 BARCODE_DXFILMEDGE DX Film Edge Barcode + ------------------------------------------------------------------------------ + + Table : Barcode Types (Symbologies) + +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 50.0X, 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 50.0X. +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 + +[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, in integral multiples +of the X-dimension. 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, in integral multiples of the X-dimension. 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, in integral multiples of the +X-dimension, must be specified using the --border switch. For example: + + zint --box --border=10 -w 10 -d "This Text" + +[zint --border=10 --box -d "This Text" -w 10] + +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. To add a boundary bar +to the top only use --bindtop. + +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. + +[zint -b QRCODE --border=1 --box -d "This Text" --quietzones] + +Codablock-F, Code 16K and Code 49 always have boundary bars, and default to +particular horizontal whitespace values. Special considerations apply to ITF-14 +and DPD - see 6.1.2.6 ITF-14 and 6.1.10.7 DPD Code for those symbologies. + +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, DotCode, 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) or in "C,M,Y,K" decimal +percentages format (the latter normally used with the --cmyk option - see +below). For example the command + + zint --fg=00FF00 -d "This Text" + +alters the symbol to a bright green. + +[zint -d "This Text" --fg=00FF00] + +Zint also supports RGBA colour information for those output file formats which +support alpha channels (currently only GIF, PCX, PNG, SVG and TIF, with GIF +supporting either a background or foreground alpha but not both) in a "RRGGBBAA" +format. For example: + + zint --fg=00ff0055 -d "This Text" + +[zint -d "This Text" --fg=00FF0055] + +will produce a semi-transparent green foreground with a standard (white) +background. Note that transparency is treated differently by raster and vector +(SVG) output formats, as for vector output the background will “shine through” a +transparent foreground. For instance + + zint --bg=ff0000 --fg=ffffff00 ... + +will give different results for PNG and SVG. Experimentation is advised! + +In addition the --nobackground option will remove the background from all output +formats except BMP.[4] + +The --cmyk option is specific to output in Encapsulated PostScript (EPS) and +TIF, and selects the CMYK colour space. Custom colours should then usually be +given in the comma-separated "C,M,Y,K" format, where C, M, Y and K are expressed +as decimal percentage values from 0 to 100. RGB values may still be used, in +which case they will be converted formulaically to CMYK approximations. + +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 + +[zint -d "This Text" --rotate=90] + +4.9 Adjusting Image Size (X-dimension) + +The size of the image can be altered using the --scale option, which sets the +X-dimension. The default scale is 1.0. + +The scale is multiplied by 2 (with the exception of MaxiCode) before being +applied to the X-dimension. For MaxiCode, it is multiplied by 10 for raster +output, by 40 for EMF vector output, and by 2 otherwise (non-EMF vector output). + +For non-MaxiCode raster output, the default scale of 1 results in an X-dimension +of 2 pixels. For example for non-MaxiCode PNG images a scale of 5 will increase +the X-dimension to 10 pixels. For MaxiCode, see 4.9.3 MaxiCode Raster Scaling +below. + +Scales for non-MaxiCode 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-MaxiCode raster output in non-dotty mode is 0.5, +giving a minimum X-dimension of 1 pixel. For MaxiCode, it is 0.2. The minimum +scale for raster output in dotty mode is 1 (see 4.15 Working with Dots). For +raster output, text will not be printed for scales less than 1. + +The minimum scale for vector output is 0.1, giving a minimum X-dimension of 0.2 +(or for MaxiCode EMF output, 4). The maximum scale for both raster and vector is +200. + +To summarize the more intricate details: + + ------------------------------------------------------------------- + MaxiCode? Output Multiplier Min. Scale Min. Scale + (non-dotty) (dotty) + ----------- ----------------- ------------ ------------- ---------- + No Raster 2 0.5 1 + + No Vector 2 0.1 0.1 + + Yes Raster 10 0.2 N/A + + Yes Vector (non-EMF) 2 0.1 N/A + + Yes EMF 40 0.1 N/A + ------------------------------------------------------------------- + + Table : Scaling Multipliers and Minima + +4.9.1 Scaling by X-dimension and Resolution + +An alternative way to specify the scale, which takes the above details into +account, is to specify measurable units using the --scalexdimdp option, which +has the format + + --scalexdimdp=X[,R] + +where X is the X-dimension (in mm by default) and R is the resolution (in dpmm, +dots per mm, by default). R is optional, and defaults to 12 dpmm, and X may be +zero, in which case it uses a symbology-specific default. The units may be given +in inches for X by appending "in", and in dpi (dots per inch) for R by appending +"dpi". For example + + zint -d "1234" --scalexdimdp=0.013in,300dpi + +Explicit metric units may also be given by appending "mm" and "dpmm" as +appropriate, and may be mixed with U.S. units: + + zint -d "1234" --scalexdimdp=0.33mm,300dpi + +4.9.2 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 dpmm, the approximate equivalent of 300 dpi +(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 37.29mm x 25.56mm (WxH) at 12 dpmm. The same +result can be achieved using the --scalexdimdp option with + + zint -b EANX -d "501234567890" --compliantheight --scalexdimdp=0 + +as 0.33mm is the default X-dimension for EAN, and 12 dpmm the default +resolution. + +4.9.3 MaxiCode Raster Scaling + +For MaxiCode symbols, which use hexagons, the scale for raster output is +multiplied by 10 before being applied. The 0.5 increment recommended for normal +raster output does not apply. + +The minimum scale is 0.2, so the minimum X-dimension is 2 pixels. However scales +below 0.5 are not recommended and may produce symbols that are not within the +following size ranges. + +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 default X-dimension is +0.88mm. For example, to output at the default X-dimension at 600 dpi specify: + + zint -b MAXICODE -d "MaxiCode (19 chars)" --scalexdimdp=0,600dpi + +4.10 Human Readable Text (HRT) Options + +For linear barcodes the text present in the output image can be removed by using +the --notext option. Note also that for raster output text will not be printed +for scales less than 1 (see 4.9 Adjusting Image Size (X-dimension)). + +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 --bold -d "This Text" --small] + +The gap between the barcode and the text can be adjusted using the --textgap +option, where the gap is given in X-dimensions, and may be negative (minimum +-5.0X, maximum 10.0X). The default gap is 1X. Note that a very small gap may +cause accented texts to overlap with the barcode: + +[zint -d "Áccent" --textgap=0.1] + +For SVG output, the font preferred by Zint (monospaced “OCR-B” for EAN/UPC, +“Arimo” - a proportional sans-serif font metrically compatible with “Arial” - +for all others) can be embedded in the file for portability using the +--embedfont option: + +[zint -d "Áccent" --embedfont] + +4.11 Input Modes + +4.11.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). + + Symbology Default character sets Alternate if input not Latin-1 + --------------- -------------------------- -------------------------------- + Aztec Code Latin-1 None + Codablock-F Latin-1 None + Code 128 Latin-1 None + Code 16K Latin-1 None + Code One Latin-1 None + Data Matrix Latin-1 None + DotCode Latin-1 None + Grid Matrix GB 2312 (includes ASCII) N/A + Han Xin Latin-1 GB 18030 (includes ASCII) + MaxiCode Latin-1 None + MicroPDF417 Latin-1 None + Micro QR Code Latin-1 Shift JIS (includes ASCII[5]) + PDF417 Latin-1 None + QR Code Latin-1 Shift JIS (see above) + rMQR Latin-1 Shift JIS (see above) + Ultracode Latin-1 None + UPNQR Latin-2 N/A + All others ASCII N/A + + Table : Default Character Sets + +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.11.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 GS1 +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 by Zint, 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.11.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 +: ECI Codes below. The ECI information is added to your code symbol as prefix +data. The symbologies that support ECI are + + ------------- -------------- ----------- + Aztec Code Grid Matrix PDF417 + Code One Han Xin Code QR Code + Data Matrix MaxiCode rMQR + DotCode MicroPDF417 Ultracode + ------------- -------------- ----------- + + Table : ECI-Aware Symbologies + +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. + + ECI Code Character Encoding Scheme (ISO/IEC 8859 schemes include ASCII) + ---------- ---------------------------------------------------------------- + 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 UTF-16BE (High order byte first) + 26 UTF-8 + 27 ASCII (ISO/IEC 646 IRV) + 28 Big5 (Taiwan) Chinese Character Set + 29 GB 2312 (PRC) Chinese Character Set + 30 Korean Character Set EUC-KR (KS X 1001:2002) + 31 GBK Chinese Character Set + 32 GB 18030 Chinese Character Set + 33 UTF-16LE (Low order byte first) + 34 UTF-32BE (High order bytes first) + 35 UTF-32LE (Low order bytes first) + 170 ISO/IEC 646 Invariant[6] + 899 8-bit binary data + + Table : ECI Codes + +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 : Default Character Sets 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.16 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.11.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 "€" + +[zint -b DATAMATRIX --eci=17 -d "€"] + +4.11.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 "常" + +[zint -b DATAMATRIX --eci=28 -d "\u5E38" --esc] + +4.11.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" + +[zint -b QRCODE --binary -d "\xE2\x82\xAC\xE5\xB8\xB8" --esc] + +4.12 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 together with -i to select the input file from which to read data. For +example + + zint -b EANX --batch -i ean13nos.txt + +where "ean13nos.txt" contains a list of EAN-13 numbers (GTINs), each on its own +line. 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 specify the -o option using special +characters in the output filename as shown in the table below: + + Input Character Interpretation + ----------------- ---------------------------------------- + ~ Insert a number or 0 + # Insert a number or space + @ Insert a number or * (or + on Windows) + Any other Insert literally + + Table : Batch Filename Formatting + +For instance + + zint -b EANX --batch -i ean13nos.txt -o file~~~.svg + +The following table shows some examples to clarify this method: + + Input Filenames Generated + ----------------- ----------------------------------------------------- + -o file~~~.svg "file001.svg", "file002.svg", "file003.svg" + -o @@@@bar.png "***1.png", "***2.png", "***3.png" (except Windows) + -o @@@@bar.png "+++1.png", "+++2.png", "+++3.png" (on Windows) + -o my~~~bar.eps "my001bar.eps", "my002bar.eps", "my003bar.eps" + -o t#es~t~.png "t es0t1.png", "t es0t2.png", "t es0t3.png" + + Table : Batch Filename Examples + +The special characters can span directories also, which is useful when creating +a large number of barcodes: + + Input Filenames Generated + --------------------- --------------------------------------------- + -o dir~/file~~~.svg "dir0/file001.svg", "dir0/file002.svg", … + , "dir0/file999.svg", "dir1/file000.svg", … + + Table : Batch Directory Examples + +For an alternative method of naming output files see the --mirror option in 4.14 +Automatic Filenames below. + +4.13 Direct Output to stdout + +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. For the supported +output file formats see Table : Output File Formats. + +-------------------------------------------------------------------------------- + +CAUTION: Outputting binary files to the command shell without catching that data +in a pipe can have unpredictable results. Use with care! + +-------------------------------------------------------------------------------- + +4.14 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.13 Direct Output to stdout. To output to a specific directory use the -o +option giving the name of the directory (any filename will be ignored, unless +--filetype is not specified, in which case the filename’s extension will be +used). + +4.15 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 in X-dimensions. 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. + +[zint -b CODEONE -d "123456789012345678" --dotty --vers=9] + +4.16 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 : ECI Codes) 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. + +Naturally the symbology must be ECI-aware (see Table : ECI-Aware Symbologies). + +[zint -b AZTEC --eci=9 -d "Κείμενο" --seg1=7,"Текст" --seg2=20,"文章"] + +ECIs of zero may be given, in which case Zint will automatically determine an +ECI if necessary, as described in section 4.11.2 Input Modes and ECI. + +Multiple segments are not currently supported for use with GS1 data. + +4.17 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] + +[zint -b DATAMATRIX -d "2nd of 3" --structapp="2,3,5006"] + +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.18 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.19 Other Options + +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. + +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. + +5. Using the API + +Zint has been written using the C language and has an API for use with C/C++ +language programs. A Qt interface (see Annex B. Qt Backend QZint) is available +in the "backend_qt" sub-directory, and a Tcl interface is available in the +"backend_tcl" sub-directory (see Annex C. Tcl Backend Binding). + +The libzint API has been designed to be very similar to that used by the GNU +Barcode package. This allows easy migration from GNU Barcode to Zint. Zint, +however, uses none of the same function names or option names as GNU Barcode. +This allows you to use both packages in your application without conflict if you +wish. + +5.1 Creating and Deleting Symbols + +The symbols manipulated by Zint are held in a zint_symbol structure defined in +"zint.h". These symbol structures are created with the ZBarcode_Create() +function and deleted using the ZBarcode_Delete() function. For example the +following code creates and then deletes a symbol: + + #include <zint.h> + #include <stdio.h> + int main() + { + struct zint_symbol *my_symbol; + my_symbol = ZBarcode_Create(); + if (my_symbol != NULL) { + printf("Symbol successfully created!\n"); + ZBarcode_Delete(my_symbol); + } + return 0; + } + +When compiling this code it will need to be linked with the libzint library +using the -lzint option: + + gcc -o simple simple.c -lzint + +5.2 Encoding and Saving to File + +To encode data in a barcode use the ZBarcode_Encode() function. To write the +symbol to a file use the ZBarcode_Print() function. For example the following +code takes a string from the command line and outputs a Code 128 symbol to a PNG +file named "out.png" (or a GIF file "out.gif" if libpng is not present) in the +current working directory: + + #include <zint.h> + int main(int argc, char **argv) + { + struct zint_symbol *my_symbol; + my_symbol = ZBarcode_Create(); + ZBarcode_Encode(my_symbol, argv[1], 0); + ZBarcode_Print(my_symbol, 0); + ZBarcode_Delete(my_symbol); + return 0; + } + +This can also be done in one stage using the ZBarcode_Encode_and_Print() +function as shown in the next example: + + #include <zint.h> + int main(int argc, char **argv) + { + struct zint_symbol *my_symbol; + my_symbol = ZBarcode_Create(); + ZBarcode_Encode_and_Print(my_symbol, argv[1], 0, 0); + ZBarcode_Delete(my_symbol); + return 0; + } + +Note that when using the API, the input data is assumed to be 8-bit binary +unless the input_mode member of the zint_symbol structure is set - see 5.11 +Setting the Input Mode for details. + +5.3 Encoding and Printing Functions in Depth + +The functions for encoding and printing barcodes are defined as: + + int ZBarcode_Encode(struct zint_symbol *symbol, + const unsigned char *source, int length); + + int ZBarcode_Encode_File(struct zint_symbol *symbol, + const char *filename); + + int ZBarcode_Print(struct zint_symbol *symbol, int rotate_angle); + + int ZBarcode_Encode_and_Print(struct zint_symbol *symbol, + const unsigned char *source, int length, int rotate_angle); + + int ZBarcode_Encode_File_and_Print(struct zint_symbol *symbol, + const char *filename, int rotate_angle); + +In these definitions length can be used to set the length of the input string. +This allows the encoding of NUL (ASCII 0) characters in those symbologies which +allow this. A value of 0 (or less than 0) will disable this usage and Zint will +encode data up to the first NUL character in the input string, which must be +present. + +The rotate_angle value can be used to rotate the image when outputting. Valid +values are 0, 90, 180 and 270. + +The ZBarcode_Encode_File() and ZBarcode_Encode_File_and_Print() functions can be +used to encode data read directly from a text file where the filename is given +in the NUL-terminated filename string. The special filename "-" (single hyphen) +can be used to read from stdin. Note that on Windows, filenames are assumed to +be UTF-8 encoded. + +If printing more than one barcode, the zint_symbol structure may be re-used by +calling the ZBarcode_Clear() function after each barcode to free any output +buffers allocated. The zint_symbol input members must be reset. To fully restore +zint_symbol to its default state, call ZBarcode_Reset() instead. + +5.4 Buffering Symbols in Memory (raster) + +In addition to saving barcode images to file Zint allows you to access a +representation of the resulting bitmap image in memory. The following functions +allow you to do this: + + int ZBarcode_Buffer(struct zint_symbol *symbol, int rotate_angle); + + int ZBarcode_Encode_and_Buffer(struct zint_symbol *symbol, + const unsigned char *source, int length, int rotate_angle); + + int ZBarcode_Encode_File_and_Buffer(struct zint_symbol *symbol, + const char *filename, int rotate_angle); + +The arguments here are the same as above, and rotation and colour options can be +used with the buffer functions in the same way as when saving to a file. The +difference is that instead of saving the image to a file it is placed in a byte +(unsigned char) array pointed to by the bitmap member, with bitmap_width set to +the number of columns and bitmap_height set to the number of rows. + +The RGB channels are split into 3 consecutive red, green, blue bytes per pixel, +and there are bitmap_width pixels per row and bitmap_height rows, so the total +size of the bitmap array is 3 * bitmap_width * bitmap_height. + +If the background and/or foreground are RGBA then the byte array alphamap will +also be set, with a single alpha value for each pixel. Its total size will be +bitmap_width * bitmap_height. + +The pixel data can be extracted from the array (or arrays) by the method shown +in the example below, where render_rgb() and render_rgba() are assumed to be +functions for drawing an RGB and RGBA pixel on the screen implemented by the +client application: + + int row, col, i = 0, j = 0; + int red, blue, green, alpha; + + for (row = 0; row < my_symbol->bitmap_height; row++) { + for (col = 0; col < my_symbol->bitmap_width; col++) { + red = (int) my_symbol->bitmap[i]; + green = (int) my_symbol->bitmap[i + 1]; + blue = (int) my_symbol->bitmap[i + 2]; + if (my_symbol->alphamap) { + alpha = (int) my_symbol->alphamap[j]; + render_rgba(row, col, red, green, blue, alpha); + j++; + } else { + render_rgb(row, col, red, green, blue); + } + i += 3; + } + } + +Where speed is important, the buffer can be returned instead in a more compact +intermediate form using the output option OUT_BUFFER_INTERMEDIATE. Here each +byte is an ASCII value: '1' for foreground colour and '0' for background colour, +except for Ultracode, which also uses colour codes: 'W' for white, 'C' for cyan, +'B' for blue, 'M' for magenta, 'R' for red, 'Y' for yellow, 'G' for green, and +'K' for black. Alpha values are not reported (alphamap will always be NULL). The +loop for accessing the data is then: + + int row, col, i = 0; + + for (row = 0; row < my_symbol->bitmap_height; row++) { + for (col = 0; col < my_symbol->bitmap_width; col++) { + render_pixel(row, col, my_symbol->bitmap[i]); + i++; + } + } + +5.5 Buffering Symbols in Memory (vector) + +Symbols can also be saved to memory in a vector representation as well as a +bitmap one. The following functions, exactly analogous to the ones above, allow +you to do this: + + int ZBarcode_Buffer_Vector(struct zint_symbol *symbol, int rotate_angle); + + int ZBarcode_Encode_and_Buffer_Vector(struct zint_symbol *symbol, + const unsigned char *source, int length, int rotate_angle); + + int ZBarcode_Encode_File_and_Buffer_Vector(struct zint_symbol *symbol, + const char *filename, int rotate_angle); + +Here the vector member is set to point to a zint_vector header structure which +contains pointers to lists of structures representing the various elements of +the barcode: rectangles, hexagons, strings and circles. To draw the barcode, +each of the element types is iterated in turn, and using the information stored +is drawn by a rendering system. For instance, to draw a barcode using a +rendering system with prepare_canvas(), draw_rect(), draw_hexagon(), +draw_string(), and draw_circle() routines available: + + struct zint_vector_rect *rect; + struct zint_vector_hexagon *hex; + struct zint_vector_string *string; + struct zint_vector_circle *circle; + + prepare_canvas(my_symbol->vector->width, my_symbol->vector->height, + my_symbol->scale, my_symbol->fgcolour, my_symbol->bgcolour, + rotate_angle); + + for (rect = my_symbol->vector->rectangles; rect; rect = rect->next) { + draw_rect(rect->x, rect->y, rect->width, rect->height, + rect->colour); + } + for (hex = my_symbol->vector->hexagons; hex; hex = hex->next) { + draw_hexagon(hex->x, hex->y, hex->diameter, hex->rotation); + } + for (string = my_symbol->vector->strings; string; string = string->next) { + draw_string(string->x, string->y, string->fsize, + string->rotation, string->halign, + string->text, string->length); + } + for (circle = my_symbol->vector->circles; circle; circle = circle->next) { + draw_circle(circle->x, circle->y, circle->diameter, circle->width); + } + +5.6 Buffering Symbols in Memory (memfile) + +Symbols can also be stored as “in-memory” file buffers by giving the +BARCODE_MEMORY_FILE option to the output_options member, which saves the print +output to member memfile instead of to the output file outfile. The length of +the buffer is given in memfile_size. For instance: + + #include <zint.h> + #include <stdio.h> + #include <string.h> + int main(int argc, char **argv) + { + struct zint_symbol *my_symbol; + my_symbol = ZBarcode_Create(); + my_symbol->output_options |= BARCODE_MEMORY_FILE; + /* Only the extension is used, to determine output format */ + strcpy(my_symbol->outfile, "mem.svg"); + ZBarcode_Encode_and_Print(my_symbol, argv[1], 0, 0); + /* `my_symbol->memfile` now contains the SVG output */ + fwrite(my_symbol->memfile, 1, my_symbol->memfile_size, stdout); + ZBarcode_Delete(my_symbol); + return 0; + } + +will print the SVG output to stdout (the file “mem.svg” is not created). This is +particularly useful for the textual formats EPS and SVG,[7] allowing the output +to be manipulated and processed by the client. + +5.7 Setting Options + +So far our application is not very useful unless we plan to only make Code 128 +symbols and we don’t mind that they only save to "out.png" (or to memory, as +above). As with the CLI program, of course, these options can be altered. The +way this is done is by altering the contents of the zint_symbol structure +between the creation and encoding stages. The zint_symbol structure consists of +the following members: + + ------------------------------------------------------------------------------ + Member Name Type Meaning Default Value + -------------------- ------------ -------------------------- ----------------- + symbology integer Symbol to use - see 5.9 BARCODE_CODE128 + Specifying a Symbology. + + height float Symbol height in Symbol dependent + X-dimensions, excluding + fixed width-to-height + symbols.[8] + + scale float Scale factor for adjusting 1.0 + size of image (sets + X-dimension). + + whitespace_width integer Horizontal whitespace 0 + width in X-dimensions. + + whitespace_height integer Vertical whitespace height 0 + in X-dimensions. + + border_width integer Border width in 0 + X-dimensions. + + output_options integer Set various output 0 (none) + parameters - see 5.10 + Adjusting Output Options. + + fgcolour character Foreground (ink) colour as "000000" + string RGB/RGBA hexadecimal + string or "C,M,Y,K" + decimal percentages + string, with a terminating + NUL. + + bgcolour character Background (paper) colour "ffffff" + string as RGB/RGBA hexadecimal + string or "C,M,Y,K" + decimal percentages + string, with a terminating + NUL. + + fgcolor pointer Points to fgcolour + allowing alternate + spelling. + + bgcolor pointer Points to bgcolour + allowing alternate + spelling. + + outfile character Contains the name of the "out.png" + string file to output a resulting + barcode symbol to. Must + end in .png, .gif, .bmp, + .emf, .eps, .pcx, .svg, + .tif or .txt followed by a + terminating NUL.[9] + + primary character Primary message data for "" (empty) + string more complex symbols, with + a terminating NUL. + + option_1 integer Symbol specific options. -1 + + option_2 integer Symbol specific options. 0 + + option_3 integer Symbol specific options. 0 + + show_hrt integer Set to 0 to hide Human 1 + Readable Text (HRT). + + input_mode integer Set encoding of input DATA_MODE + data - see 5.11 Setting + the Input Mode. + + eci integer Extended Channel 0 (none) + Interpretation code. + + dpmm float Resolution of output in 0 (none) + dots per mm (BMP, EMF, + PCX, PNG and TIF only). + + dot_size float Diameter of dots used in 0.8 + dotty mode (in + X-dimensions). + + text_gap float Gap between barcode and 1.0 + text (HRT) in + X-dimensions. + + guard_descent float Height of guard bar 5.0 + descent (EAN/UPC only) in + X-dimensions. + + structapp Structured Mark a symbol as part of a count 0 + Append sequence of symbols. (disabled) + structure + + debug integer Debugging flags. 0 + + warn_level integer Affects error/warning WARN_DEFAULT + value returned by Zint + API - see 5.8 Handling + Errors. + + text unsigned Human Readable Text, which "" (empty) + character usually consists of input (output only) + string data plus one more check + digit. Uses UTF-8 + formatting, with a + terminating NUL. + + rows integer Number of rows used by the (output only) + symbol. + + width integer Width of the generated (output only) + symbol. + + encoded_data array of Representation of the (output only) + unsigned encoded data. + character + arrays + + row_height array of Heights of each row. (output only) + floats + + errtxt character Error message in the event (output only) + string that an error occurred, + with a terminating NUL - + see 5.8 Handling Errors. + + bitmap pointer to Pointer to stored bitmap (output only) + unsigned image - see 5.4 Buffering + character Symbols in Memory + array (raster). + + bitmap_width integer Width of stored bitmap (output only) + image (in pixels) - see + bitmap member. + + bitmap_height integer Height of stored bitmap (output only) + image (in pixels) - see + bitmap member. + + alphamap pointer to Pointer to array (output only) + unsigned representing alpha channel + character of stored bitmap image (or + array NULL if no alpha channel + used) - see bitmap member. + + vector pointer to Pointer to vector header (output only) + vector containing pointers to + structure vector elements - see 5.5 + Buffering Symbols in + Memory (vector). + + memfile pointer to Pointer to in-memory file (output only) + unsigned buffer if + character BARCODE_MEMORY_FILE set in + array output_options - see 5.6 + Buffering Symbols in + Memory (memfile). + + memfile_size integer Length of in-memory file (output only) + buffer. + ------------------------------------------------------------------------------ + + : Table : API Structure zint_symbol + +To alter these values use the syntax shown in the example below. This code has +the same result as the previous example except the output is now taller and +plotted in green. + + #include <zint.h> + #include <string.h> + int main(int argc, char **argv) + { + struct zint_symbol *my_symbol; + my_symbol = ZBarcode_Create(); + strcpy(my_symbol->fgcolour, "00ff00"); + my_symbol->height = 400.0f; + ZBarcode_Encode_and_Print(my_symbol, argv[1], 0, 0); + ZBarcode_Delete(my_symbol); + return 0; + } + +Note that background removal for all outputs except BMP can be achieved by +setting the background alpha to "00" where the values for R, G and B will be +ignored: + + strcpy(my_symbol->bgcolour, "55555500"); + +This is what the CLI option --nobackground does - see 4.7 Using Colour. + +5.8 Handling Errors + +If errors occur during encoding a non-zero integer value is passed back to the +calling application. In addition the errtxt member is set to a message detailing +the nature of the error. The errors generated by Zint are: + + ------------------------------------------------------------------------------ + Return Value Meaning + ------------------------------ ----------------------------------------------- + ZINT_WARN_HRT_TRUNCATED The Human Readable Text returned in text was + truncated (maximum 255 bytes). + + ZINT_WARN_INVALID_OPTION One of the values in zint_struct was set + incorrectly but Zint has made a guess at what + it should have been and generated a barcode + accordingly. + + ZINT_WARN_USES_ECI Zint has automatically inserted an ECI + character. The symbol may not be readable with + some readers. + + ZINT_WARN_NONCOMPLIANT The symbol was created but is not compliant + with certain standards set in its specification + (e.g. height, GS1 AI data lengths). + + ZINT_ERROR Marks the divide between warnings and errors. + For return values greater than or equal to this + no symbol (or only an incomplete symbol) is + generated. + + ZINT_ERROR_TOO_LONG The input data is too long or too short for the + selected symbology. No symbol has been + generated. + + ZINT_ERROR_INVALID_DATA The data to be encoded includes characters + which are not permitted by the selected + symbology (e.g. alphabetic characters in an EAN + symbol). No symbol has been generated. + + ZINT_ERROR_INVALID_CHECK Data with an incorrect check digit has been + entered. No symbol has been generated. + + ZINT_ERROR_INVALID_OPTION One of the values in zint_struct was set + incorrectly and Zint was unable (or unwilling) + to guess what it should have been. No symbol + has been generated. + + ZINT_ERROR_ENCODING_PROBLEM A problem has occurred during encoding of the + data. This should never happen. Please contact + the developer if you encounter this error. + + ZINT_ERROR_FILE_ACCESS Zint was unable to open the requested output + file. This is usually a file permissions + problem. + + ZINT_ERROR_MEMORY Zint ran out of memory. This should only be a + problem with legacy systems. + + ZINT_ERROR_FILE_WRITE Zint failed to write all contents to the + requested output file. This should only occur + if the output device becomes full. + + ZINT_ERROR_USES_ECI Returned if warn_level set to WARN_FAIL_ALL and + ZINT_WARN_USES_ECI occurs. + + ZINT_ERROR_NONCOMPLIANT Returned if warn_level set to WARN_FAIL_ALL and + ZINT_WARN_NONCOMPLIANT occurs. + + ZINT_ERROR_HRT_TRUNCATED Returned if warn_level set to WARN_FAIL_ALL and + ZINT_WARN_HRT_TRUNCATED occurs. + ------------------------------------------------------------------------------ + + Table : API Warning and Error Return Values + +To catch errors use an integer variable as shown in the code below: + + #include <zint.h> + #include <stdio.h> + #include <string.h> + int main(int argc, char **argv) + { + struct zint_symbol *my_symbol; + int error; + my_symbol = ZBarcode_Create(); + /* Set invalid foreground colour */ + strcpy(my_symbol->fgcolour, "nonsense"); + error = ZBarcode_Encode_and_Print(my_symbol, argv[1], 0, 0); + if (error != 0) { + /* Some warning or error occurred */ + printf("%s\n", my_symbol->errtxt); + if (error >= ZINT_ERROR) { + /* Stop now */ + ZBarcode_Delete(my_symbol); + return 1; + } + } + /* Otherwise carry on with the rest of the application */ + ZBarcode_Delete(my_symbol); + return 0; + } + +This code will exit with the appropriate message: + + Error 881: Malformed foreground RGB colour 'nonsense' (hexadecimal only) + +To treat all warnings as errors, set symbol->warn_level to WARN_FAIL_ALL. + +5.9 Specifying a Symbology + +Symbologies can be specified by number or by name as shown in the Table +: Barcode Types (Symbologies). For example + + symbol->symbology = BARCODE_LOGMARS; + +means the same as + + symbol->symbology = 50; + +5.10 Adjusting Output Options + +The output_options member can be used to adjust various aspects of the output +file. To select more than one option from the table below simply OR them +together when adjusting this value: + + my_symbol->output_options |= BARCODE_BIND | READER_INIT; + + ------------------------------------------------------------------------------ + Value Effect + -------------------------- --------------------------------------------------- + 0 No options selected. + + BARCODE_BIND_TOP Boundary bar above the symbol only.[10] + + BARCODE_BIND Boundary bars above and below the symbol and + between rows if stacking multiple symbols.[11] + + BARCODE_BOX Add a box surrounding the symbol and whitespace. + + BARCODE_STDOUT Output the file to stdout. + + READER_INIT Create as a Reader Initialisation (Programming) + symbol. + + SMALL_TEXT Use a smaller font for the Human Readable Text. + + BOLD_TEXT Embolden the Human Readable Text. + + CMYK_COLOUR Select the CMYK colour space option for + Encapsulated PostScript and TIF files. + + BARCODE_DOTTY_MODE Plot a matrix symbol using dots rather than + squares. + + GS1_GS_SEPARATOR Use GS (Group Separator) instead of FNC1 as GS1 + separator (Data Matrix only). + + OUT_BUFFER_INTERMEDIATE Return the bitmap buffer as ASCII values instead of + separate colour channels - see 5.4 Buffering + Symbols in Memory (raster). + + BARCODE_QUIET_ZONES Add compliant quiet zones (additional to any + specified whitespace).[12] + + BARCODE_NO_QUIET_ZONES Disable quiet zones, notably those with defaults. + + COMPLIANT_HEIGHT Warn if height specified not compliant, or use + standard height (if any) as default. + + EANUPC_GUARD_WHITESPACE Add quiet zone indicators (“<” and/or “>”) to HRT + whitespace (EAN/UPC). + + EMBED_VECTOR_FONT Embed font in vector output - currently available + for SVG output only. + + BARCODE_MEMORY_FILE Write output to in-memory buffer symbol->memfile + instead of to outfile file. + ------------------------------------------------------------------------------ + + : Table : API output_options Values + +5.11 Setting the Input Mode + +The way in which the input data is encoded can be set using the input_mode +member. Valid values are shown in the table below. + + ------------------------------------------------------------------------------ + Value Effect + ------------------- ---------------------------------------------------------- + DATA_MODE Uses full 8-bit range interpreted as binary data. + + UNICODE_MODE Uses UTF-8 input. + + GS1_MODE Encodes GS1 data using FNC1 characters. + + The above are exclusive, the following optional and OR-ed. + + ESCAPE_MODE Process input data for escape sequences. + + GS1PARENS_MODE Parentheses (round brackets) used in GS1 data instead of + square brackets to delimit Application Identifiers + (parentheses must not otherwise occur in the data). + + GS1NOCHECK_MODE Do not check GS1 data for validity, i.e. suppress checks + for valid AIs and data lengths. Invalid characters (e.g. + control characters, extended ASCII characters) are still + checked for. + + HEIGHTPERROW_MODE Interpret the height member as per-row rather than as + overall height. + + FAST_MODE Use faster if less optimal encodation or other shortcuts + if available (affects DATAMATRIX, MICROPDF417, PDF417, + QRCODE and UPNQR only). + + EXTRA_ESCAPE_MODE Process special symbology-specific escape sequences + (CODE128 only). + ------------------------------------------------------------------------------ + + : Table : API input_mode Values + +The default mode is DATA_MODE. (Note that this differs from the default for the +CLI and GUI, which is UNICODE_MODE.) + +DATA_MODE, UNICODE_MODE and GS1_MODE are mutually exclusive, whereas +ESCAPE_MODE, GS1PARENS_MODE, GS1NOCHECK_MODE, HEIGHTPERROW_MODE, FAST_MODE and +EXTRA_ESCAPE_MODE are optional. So, for example, you can set + + my_symbol->input_mode = UNICODE_MODE | ESCAPE_MODE; + +or + + my_symbol->input_mode = GS1_MODE | GS1PARENS_MODE | GS1NOCHECK_MODE; + +whereas + + my_symbol->input_mode = DATA_MODE | GS1_MODE; + +is not valid. + +Permissible escape sequences (ESCAPE_MODE) are listed in Table +: Escape Sequences, and the special Code 128-only EXTRA_ESCAPE_MODE escape +sequences are given in 6.1.10.1 Standard Code 128 (ISO 15417). An example of +GS1PARENS_MODE usage is given in section 6.1.10.3 GS1-128. + +GS1NOCHECK_MODE is for use with legacy systems that have data that does not +conform to the current GS1 standard. Printable ASCII input is still checked for, +as is the validity of GS1 data specified without AIs (e.g. linear data for GS1 +DataBar Omnidirectional/Limited/etc.). Also checked is GS1 DataBar Expanded and +GS1 Composite input that is not in the GS1 encodable character set 82 (see GS1 +General Specifications Figure 7.11.1 ‘GS1 AI encodable character set 82’), +otherwise encodation would fail. + +For HEIGHTPERROW_MODE, see --heightperrow in section 4.4 Adjusting Height. The +height member should be set to the desired per-row value on input (it will be +set to the overall height on output). + +FAST_MODE causes a less optimal encodation scheme to be used for Data Matrix, +MicroPDF417 and PDF417. For QR Code and UPNQR, it affects Zint’s automatic mask +selection - see 6.6.3 QR Code (ISO 18004) for details. + +5.12 Multiple Segments + +For input data requiring multiple ECIs, the following functions may be used: + + int ZBarcode_Encode_Segs(struct zint_symbol *symbol, + const struct zint_seg segs[], const int seg_count); + + int ZBarcode_Encode_Segs_and_Print(struct zint_symbol *symbol, + const struct zint_seg segs[], const int seg_count, int rotate_angle); + + int ZBarcode_Encode_Segs_and_Buffer(struct zint_symbol *symbol, + const struct zint_seg segs[], const int seg_count, int rotate_angle); + + int ZBarcode_Encode_Segs_and_Buffer_Vector(struct zint_symbol *symbol, + const struct zint_seg segs[], const int seg_count, int rotate_angle); + +These are direct analogues of the previously mentioned ZBarcode_Encode(), +ZBarcode_Encode_and_Print(), ZBarcode_Encode_and_Buffer() and +ZBarcode_Encode_and_Buffer_Vector() respectively, where instead of a pair +consisting of "source, length", a pair consisting of "segs, seg_count" is given, +with segs being an array of struct zint_seg segments and seg_count being the +number of elements it contains. The zint_seg structure is of the form: + + struct zint_seg { + unsigned char *source; /* Data to encode */ + int length; /* Length of `source`. If 0, `source` must be + NUL-terminated */ + int eci; /* Extended Channel Interpretation */ + }; + +The symbology must support ECIs (see Table : ECI-Aware Symbologies). For +example: + + #include <zint.h> + int main(int argc, char **argv) + { + struct zint_seg segs[] = { + { "Κείμενο", 0, 9 }, + { "Текст", 0, 7 }, + { "文章", 0, 20 } + }; + struct zint_symbol *my_symbol; + my_symbol = ZBarcode_Create(); + my_symbol->symbology = BARCODE_AZTEC; + my_symbol->input_mode = UNICODE_MODE; + ZBarcode_Encode_Segs(my_symbol, segs, 3); + ZBarcode_Print(my_symbol, 0); + ZBarcode_Delete(my_symbol); + return 0; + } + +A maximum of 256 segments may be specified. Use of multiple segments with GS1 +data is not currently supported. + +5.13 Scaling Helpers + +To help with scaling the output, the following three function are available: + + float ZBarcode_Default_Xdim(int symbol_id); + + float ZBarcode_Scale_From_XdimDp(int symbol_id, float x_dim_mm, float dpmm, + const char *filetype) { + + float ZBarcode_XdimDP_From_Scale(int symbol_id, float scale, + float x_dim_mm_or_dpmm, const char *filetype); + +The first ZBarcode_Default_Xdim() returns the default X-dimension suggested by +Zint for symbology symbol_id. + +The second ZBarcode_Scale_From_XdimDp() returns the scale to use to output to a +file of type filetype with X-dimension x_dim_mm at dpmm dots per mm. The given +X-dimension must be non-zero and less than or equal to 10mm, however dpmm may be +zero and defaults to 12 dpmm, and filetype may be NULL or empty in which case a +GIF filetype is assumed. For raster output (BMP/GIF/PCX/PNG/TIF) the scale is +rounded to half-integer increments. + +For example: + + /* Royal Mail 4-State Customer Code */ + my_symbol->symbology = BARCODE_RM4SCC; + my_symbol->dpmm = 600.0f / 25.4f; /* 600 dpi */ + my_symbol->scale = ZBarcode_Scale_From_XdimDp( + my_symbol->symbology, + ZBarcode_Default_Xdim(my_symbol->symbology), + my_symbol->dpmm, "PNG"); /* Returns 7.5 */ + +The third function ZBarcode_XdimDP_From_Scale() is the “reverse” of +ZBarcode_Scale_From_XdimDp(), returning the X-dimension (in mm) or the dot +density (in dpmm) given a scale scale. Both scale and x_dim_mm_or_dpmm must be +non-zero. The returned value is bound to the maximum value of dpmm (1000), so +must be further bound to 10 on return if the X-dimension is sought. + +Note that the X-dimension to use is application dependent, and varies not only +due to the symbology, resolution and filetype but also due to the type of +scanner used, the intended scanning distance, and what media (“substrates”) the +barcode appears on. + +5.14 Verifying Symbology Availability + +An additional function available in the API is: + + int ZBarcode_ValidID(int symbol_id); + +which allows you to check whether a given symbology is available, returning a +non-zero value if so. For example: + + if (ZBarcode_ValidID(BARCODE_PDF417) != 0) { + printf("PDF417 available\n"); + } else { + printf("PDF417 not available\n"); + } + +Another function that may be useful is: + + int ZBarcode_BarcodeName(int symbol_id, char name[32]); + +which copies the name of a symbology into the supplied name buffer, which should +be 32 characters in length. The name is NUL-terminated, and zero is returned on +success. For instance: + + char name[32]; + if (ZBarcode_BarcodeName(BARCODE_PDF417, name) == 0) { + printf("%s\n", name); + } + +will print BARCODE_PDF417. + +5.15 Checking Symbology Capabilities + +It can be useful for frontend programs to know the capabilities of a symbology. +This can be determined using another additional function: + + unsigned int ZBarcode_Cap(int symbol_id, unsigned int cap_flag); + +by OR-ing the flags below in the cap_flag argument and checking the return to +see which are set. + + ------------------------------------------------------------------------------ + Value Meaning + --------------------------- -------------------------------------------------- + ZINT_CAP_HRT Can the symbology print Human Readable Text? + + ZINT_CAP_STACKABLE Is the symbology stackable? + + ZINT_CAP_EANUPC[13] Is the symbology EAN/UPC? + + ZINT_CAP_COMPOSITE Does the symbology support composite data? (see + 6.3 GS1 Composite Symbols (ISO 24723) below) + + ZINT_CAP_ECI Does the symbology support Extended Channel + Interpretations? + + ZINT_CAP_GS1 Does the symbology support GS1 data? + + ZINT_CAP_DOTTY Can the symbology be outputted as dots? + + ZINT_CAP_QUIET_ZONES Does the symbology have default quiet zones? + + ZINT_CAP_FIXED_RATIO Does the symbology have a fixed width-to-height + (aspect) ratio? + + ZINT_CAP_READER_INIT Does the symbology support Reader Initialisation? + + ZINT_CAP_FULL_MULTIBYTE Is the ZINT_FULL_MULTIBYTE option applicable? + + ZINT_CAP_MASK Is mask selection applicable? + + ZINT_CAP_STRUCTAPP Does the symbology support Structured Append? + + ZINT_CAP_COMPLIANT_HEIGHT Does the symbology have a compliant height + defined? + ------------------------------------------------------------------------------ + + Table : API Capability Flags + +For example: + + unsigned int cap; + cap = ZBarcode_Cap(BARCODE_PDF417, ZINT_CAP_HRT | ZINT_CAP_ECI); + if (cap & ZINT_CAP_HRT) { + printf("PDF417 supports HRT\n"); + } else { + printf("PDF417 does not support HRT\n"); + } + if (cap & ZINT_CAP_ECI) { + printf("PDF417 supports ECI\n"); + } else { + printf("PDF417 does not support ECI\n"); + } + +5.16 Zint Version + +Whether the Zint library linked to was built with PNG support may be determined +with: + + int ZBarcode_NoPng(); + +which returns 1 if no PNG support is available, else zero. + +Lastly, the version of the Zint library linked to is returned by: + + int ZBarcode_Version(); + +The version parts are separated by hundreds. For instance, version "2.9.1" is +returned as "20901". + +6. Types of Symbology + +6.1 One-Dimensional Symbols + +One-dimensional or linear symbols are what most people associate with the term +barcode. They consist of a number of bars and a number of spaces of differing +widths. + +6.1.1 Code 11 + +[zint -b CODE11 -d "9212320967"] + +Developed by Intermec in 1977, Code 11 is similar to Code 2 of 5 Matrix and is +primarily used in telecommunications. The symbol can encode data consisting of +the digits 0-9 and the dash character (-) up to a maximum of 140 characters. Two +modulo-11 check digits are added by default. To add just one check digit, set +--vers=1 (API option_2 = 1). To add no check digits, set --vers=2 (API +option_2 = 2). + +6.1.2 Code 2 of 5 + +Code 2 of 5 is a family of one-dimensional symbols, 8 of which are supported by +Zint. Note that the names given to these standards alters from one source to +another so you should take care to ensure that you have the right barcode type +before using these standards. + +6.1.2.1 Standard Code 2 of 5 + +[zint -b C25STANDARD -d "9212320967"] + +Also known as Code 2 of 5 Matrix, this is a self-checking code used in +industrial applications and photo development. Standard Code 2 of 5 will encode +numeric input (digits 0-9) up to a maximum of 112 digits. No check digit is +added by default. To add a check digit, set --vers=1 (API option_2 = 1). To add +a check digit but not show it in the Human Readable Text, set --vers=2 (API +option_2 = 2). + +6.1.2.2 IATA Code 2 of 5 + +[zint -b C25IATA -d "9212320967"] + +Used for baggage handling in the air-transport industry by the International Air +Transport Agency, this self-checking code will encode numeric input (digits 0-9) +up to a maximum of 80 digits. No check digit is added by default, but can be set +the same as for 6.1.2.1 Standard Code 2 of 5. + +6.1.2.3 Industrial Code 2 of 5 + +[zint -b C25IND -d "9212320967"] + +Industrial Code 2 of 5 can encode numeric input (digits 0-9) up to a maximum of +79 digits. No check digit is added by default, but can be set the same as for +6.1.2.1 Standard Code 2 of 5. + +6.1.2.4 Interleaved Code 2 of 5 (ISO 16390) + +[zint -b C25INTER --compliantheight -d "9212320967"] + +This self-checking symbology encodes pairs of numbers, and so can only encode an +even number of digits (0-9). If an odd number of digits is entered a leading +zero is added by Zint. A maximum of 62 pairs (124 digits) can be encoded. No +check digit is added by default, but can be set the same as for 6.1.2.1 Standard +Code 2 of 5. + +6.1.2.5 Code 2 of 5 Data Logic + +[zint -b C25LOGIC -d "9212320967"] + +Data Logic does not include a check digit by default and can encode numeric +input (digits 0-9) up to a maximum of 113 digits. Check digit options are the +same as for 6.1.2.1 Standard Code 2 of 5. + +6.1.2.6 ITF-14 + +[zint -b ITF14 --compliantheight -d "9212320967145"] + +ITF-14, also known as UPC Shipping Container Symbol or Case Code, is based on +Interleaved Code 2 of 5 and requires a 13-digit numeric input (digits 0-9). One +modulo-10 check digit is added by Zint. + +If no border option is specified Zint defaults to adding a bounding box with a +border width of 5. This behaviour can be overridden by using the --bind option +(API output_options |= BARCODE_BIND). Similarly the border width can be +overridden using --border (API border_width). If a symbol with no border is +required this can be achieved by explicitly setting the border type to box (or +bind or bindtop) and leaving the border width 0. + +[zint -b ITF14 --box --compliantheight -d "9212320967145"] + +6.1.2.7 Deutsche Post Leitcode + +[zint -b DPLEIT -d "9212320967145"] + +Leitcode is based on Interleaved Code 2 of 5 and is used by Deutsche Post for +routing purposes. Leitcode requires a 13-digit numerical input to which Zint +adds a check digit. + +6.1.2.8 Deutsche Post Identcode + +[zint -b DPIDENT -d "91232096712"] + +Identcode is based on Interleaved Code 2 of 5 and is used by Deutsche Post for +identification purposes. Identcode requires an 11-digit numerical input to which +Zint adds a check digit. + +6.1.3 UPC (Universal Product Code) (ISO 15420) + +6.1.3.1 UPC Version A + +[zint -b UPCA --compliantheight -d "72527270270"] + +UPC-A is used in the United States for retail applications. The symbol requires +an 11-digit article number. The check digit is calculated by Zint. In addition +EAN-2 and EAN-5 add-on symbols can be added using the + character. For example, +to draw a UPC-A symbol with the data 72527270270 with an EAN-5 add-on showing +the data 12345 use the command: + + zint -b UPCA -d "72527270270+12345" + +or using the API encode a data string with the + character included: + + my_symbol->symbology = BARCODE_UPCA; + error = ZBarcode_Encode_and_Print(my_symbol, "72527270270+12345", 0, 0); + +[zint -b UPCA --compliantheight -d "72527270270+12345"] + +If your input data already includes the check digit symbology BARCODE_UPCA_CHK +(35) can be used which takes a 12-digit input and validates the check digit +before encoding. + +A quiet zone indicator can be added to the HRT by setting --guardwhitespace (API +output_options |= EANUPC_GUARD_WHITESPACE). For UPC, this is only relevant when +there is add-on: + + zint -b UPCA -d "72527270270+12345" --guardwhitespace + +or using the API: + + my_symbol->symbology = BARCODE_UPCA; + my_symbol->output_options |= EANUPC_GUARD_WHITESPACE; + error = ZBarcode_Encode_and_Print(my_symbol, "72527270270+12345", 0, 0); + +[zint -b UPCA --compliantheight -d "72527270270+12345" --guardwhitespace] + +You can adjust the gap between the main symbol and an add-on in integral +multiples of the X-dimension by setting --addongap (API option_2) to a value +between 9 (default) and 12. The height in X-dimensions that the guard bars +descend below the main bars can be adjusted by setting --guarddescent (API +guard_descent) to a value between 0.0 and 20.0 (default 5.0). + +6.1.3.2 UPC Version E + +[zint -b UPCE --compliantheight -d "1123456"] + +UPC-E is a zero-compressed version of UPC-A developed for smaller packages. The +code requires a 6-digit article number (digits 0-9). The check digit is +calculated by Zint. EAN-2 and EAN-5 add-on symbols can be added using the + +character as with UPC-A. In addition Zint also supports Number System 1 encoding +by entering a 7-digit article number starting with the digit 1. For example: + + zint -b UPCE -d "1123456" + +or + + my_symbol->symbology = BARCODE_UPCE; + error = ZBarcode_Encode_and_Print(my_symbol, "1123456", 0, 0); + +If your input data already includes the check digit symbology BARCODE_UPCE_CHK +(38) can be used which takes a 7 or 8-digit input and validates the check digit +before encoding. + +As with UPC-A, a quiet zone indicator can be added when there is an add-on by +setting --guardwhitespace (API output_options |= EANUPC_GUARD_WHITESPACE): + + zint -b UPCE -d "1123456+12" --guardwhitespace + +[zint -b UPCE --compliantheight -d "1123456+12" --guardwhitespace] + +You can adjust the gap between the main symbol and an add-on in integral +multiples of the X-dimension by setting --addongap (API option_2) to a value +between 7 (default) and 12. The height in X-dimensions that the guard bars +descend below the main bars can be adjusted by setting --guarddescent (API +guard_descent) to a value between 0.0 and 20.0 (default 5.0). + +6.1.4 EAN (European Article Number) (ISO 15420) + +6.1.4.1 EAN-2, EAN-5, EAN-8 and EAN-13 + +[zint -b EANX --compliantheight -d "4512345678906"] + +The EAN system is used in retail across Europe and includes standards for EAN-2, +EAN-5, EAN-8 and EAN-13 which encode 2, 5, 7 or 12-digit numbers respectively. +Zint will decide which symbology to use depending on the length of the input +data. In addition EAN-2 and EAN-5 add-on symbols can be added to EAN-8 and +EAN-13 symbols using the + character as with UPC symbols. For example: + + zint -b EANX -d "54321" + +[zint -b EANX --compliantheight -d "54321"] + +will encode a stand-alone EAN-5, whereas + + zint -b EANX -d "7432365+54321" + +will encode an EAN-8 symbol with an EAN-5 add-on. As before these results can be +achieved using the API: + + my_symbol->symbology = BARCODE_EANX; + + error = ZBarcode_Encode_and_Print(my_symbol, "54321", 0, 0); + + error = ZBarcode_Encode_and_Print(my_symbol, "7432365+54321", 0, 0); + +[zint -b EANX --compliantheight -d "7432365+54321"] + +All of the EAN symbols include check digits which are added by Zint. + +If you are encoding an EAN-8 or EAN-13 symbol and your data already includes the +check digit then you can use symbology BARCODE_EANX_CHK (14) which takes an 8 or +13-digit input and validates the check digit before encoding. + +Options to add quiet zone indicators and to adjust the add-on gap and the guard +bar descent height are the same as for 6.1.3.2 UPC Version E. For instance: + + zint -b EANX_CHK -d "74323654" --guardwhitespace + +[zint -b EANX_CHK --compliantheight -d "74323654" –guardwhitespace] + +6.1.4.2 SBN, ISBN and ISBN-13 + +[zint -b ISBNX --compliantheight -d "9789295055124"] + +EAN-13 symbols (also known as Bookland EAN-13) can also be produced from 9-digit +SBN, 10-digit ISBN or 13-digit ISBN-13 data. The relevant check digit needs to +be present in the input data and will be verified before the symbol is +generated. + +As with EAN-13, a quiet zone indicator can be added using --guardwhitespace: + +[zint -b ISBNX --compliantheight -d "9789295055124" --guardwhitespace] + +EAN-2 and EAN-5 add-on symbols can be added using the + character, and there are +options to adjust the add-on gap and the guard bar descent height - see 6.1.3.2 +UPC Version E. + +6.1.5 Plessey + +6.1.5.1 UK Plessey + +[zint -b PLESSEY -d "C64"] + +Also known as Plessey Code, this symbology was developed by the Plessey Company +Ltd. in the UK. The symbol can encode data consisting of digits (0-9) or letters +A-F up to a maximum of 67 characters and includes a hidden CRC check digit. + +6.1.5.2 MSI Plessey + +[zint -b MSI_PLESSEY -d "6502" --vers=2] + +Based on Plessey and developed by MSI Data Corporation, MSI Plessey can encode +numeric (digits 0-9) input of up to 92 digits. It has a range of check digit +options that are selectable by setting --vers (API option_2), shown in the table +below: + + Value Check Digits + ------- ----------------------------- + 0 None + 1 Modulo-10 (Luhn) + 2 Modulo-10 & Modulo-10 + 3 Modulo-11 (IBM) + 4 Modulo-11 (IBM) & Modulo-10 + 5 Modulo-11 (NCR) + 6 Modulo-11 (NCR) & Modulo-10 + + Table : MSI Plessey Check Digit Options + +To not show the check digit or digits in the Human Readable Text, add 10 to the +--vers value. For example --vers=12 (API option_2 = 12) will add two hidden +modulo-10 check digits. + +6.1.6 Telepen + +6.1.6.1 Telepen Alpha + +[zint -b TELEPEN --compliantheight -d "Z80"] + +Telepen Alpha was developed by SB Electronic Systems Limited and can encode +ASCII text input, up to a maximum of 69 characters. Telepen includes a hidden +modulo-127 check digit, added by Zint. + +6.1.6.2 Telepen Numeric + +[zint -b TELEPEN_NUM --compliantheight -d "466X33"] + +Telepen Numeric allows compression of numeric data into a Telepen symbol. Data +can consist of pairs of numbers or pairs consisting of a numerical digit +followed an X character. For example: 466333 and 466X33 are valid codes whereas +46X333 is not (the digit pair "X3" is not valid). Up to 136 digits can be +encoded. Telepen Numeric includes a hidden modulo-127 check digit which is added +by Zint. + +6.1.7 Code 39 + +6.1.7.1 Standard Code 39 (ISO 16388) + +[zint -b CODE39 --compliantheight -d "1A" --vers=1] + +Standard Code 39 was developed in 1974 by Intermec. Input data can be up to 86 +characters in length and can include the characters 0-9, A-Z, dash (-), full +stop (.), space, asterisk (*), dollar ($), slash (/), plus (+) and percent (%). +The standard does not require a check digit but a modulo-43 check digit can be +added if desired by setting --vers=1 (API option_2 = 1). To add a check digit +but not show it in the Human Readable Text, set --vers=2 (API option_2 = 2). + +6.1.7.2 Extended Code 39 + +[zint -b EXCODE39 --compliantheight -d "123.45$@fd"] + +Also known as Code 39e and Code39+, this symbology expands on Standard Code 39 +to provide support for the full 7-bit ASCII character set. The check digit +options are the same as for 6.1.7.1 Standard Code 39 (ISO 16388). + +6.1.7.3 Code 93 + +[zint -b CODE93 --compliantheight -d "C93"] + +A variation of Extended Code 39, Code 93 also supports full ASCII text, +accepting up to 123 characters. Two check characters are added by Zint. By +default these check characters are not shown in the Human Readable Text, but may +be shown by setting --vers=1 (API option_2 = 1). + +6.1.7.4 PZN (Pharmazentralnummer) + +[zint -b PZN --compliantheight -d "2758089"] + +PZN is a Code 39 based symbology used by the pharmaceutical industry in Germany. +PZN encodes a 7-digit number to which Zint will add a modulo-11 check digit +(PZN8). Input less than 7 digits will be zero-filled. An 8-digit input can be +supplied in which case Zint will validate the check digit. + +To encode a PZN7 (obsolete since 2013) instead set --vers=1 (API option_2 = 1) +and supply up to 7 digits. As with PZN8, a modulo-11 check digit will be added +or if 7 digits supplied the check digit validated. + +6.1.7.5 LOGMARS + +[zint -b LOGMARS --compliantheight -d "12345/ABCDE" --vers=1] + +LOGMARS (Logistics Applications of Automated Marking and Reading Symbols) is a +variation of the Code 39 symbology used by the U.S. Department of Defense. +LOGMARS encodes the same character set as 6.1.7.1 Standard Code 39 (ISO 16388), +and the check digit options are also the same. Input is restricted to a maximum +of 30 characters. + +6.1.7.6 Code 32 + +[zint -b CODE32 --compliantheight -d "14352312"] + +A variation of Code 39 used by the Italian Ministry of Health (“Ministero della +Sanità”) for encoding identifiers on pharmaceutical products. This symbology +requires a numeric input up to 8 digits in length. A check digit is added by +Zint. + +6.1.7.7 HIBC Code 39 + +[zint -b HIBC_39 --compliantheight -d "14352312"] + +This variant adds a leading '+' character and a trailing modulo-49 check digit +to a standard Code 39 symbol as required by the Health Industry Barcode +standards. + +6.1.7.8 Vehicle Identification Number (VIN) + +[zint -b VIN -d "2FTPX28L0XCA15511" --vers=1] + +A variation of Code 39 that for vehicle identification numbers used in North +America (first character '1' to '5') has a check character verification stage. A +17 character input (0-9, and A-Z excluding 'I', 'O' and 'Q') is required. An +invisible Import character prefix 'I' can be added by setting --vers=1 (API +option_2 = 1). + +6.1.8 Codabar (EN 798) + +[zint -b CODABAR --compliantheight -d "A37859B"] + +Also known as NW-7, Monarch, ABC Codabar, USD-4, Ames Code and Code 27, this +symbology was developed in 1972 by Monarch Marketing Systems for retail +purposes. The American Blood Commission adopted Codabar in 1977 as the standard +symbology for blood identification. Codabar can encode up to 103 characters +starting and ending with the letters A-D and containing between these letters +the numbers 0-9, dash (-), dollar ($), colon (:), slash (/), full stop (.) or +plus (+). No check character is generated by default, but a modulo-16 one can be +added by setting --vers=1 (API option_2 = 1). To have the check character appear +in the Human Readable Text, set --vers=2 (API option_2 = 2). + +6.1.9 Pharmacode + +[zint -b PHARMA --compliantheight -d "130170"] + +Developed by Laetus, Pharmacode is used for the identification of +pharmaceuticals. The symbology is able to encode whole numbers between 3 and +131070. + +6.1.10 Code 128 + +6.1.10.1 Standard Code 128 (ISO 15417) + +[zint -b CODE128 --bind -d "130170X178"] + +One of the most ubiquitous one-dimensional barcode symbologies, Code 128 was +developed in 1981 by Computer Identics. This symbology supports full ASCII text +and uses a three-Code Set system to compress the data into a smaller symbol. +Zint automatically switches between Code Sets A, B and C (but see below) and +adds a hidden modulo-103 check digit. + +Code 128 is the default barcode symbology used by Zint. In addition Zint +supports the encoding of ISO/IEC 8859-1 (non-English) characters in Code 128 +symbols. The ISO/IEC 8859-1 character set is shown in Annex A.2 Latin Alphabet +No. 1 (ISO/IEC 8859-1). + +Manual switching of Code Sets is possible using the --extraesc option (API +input_mode |= EXTRA_ESCAPE_MODE), which apart from processing normal escape +sequences also processes the Code 128-specific escapes \^A, \^B, \^C and \^@ +(the latter turns off manual Code Set selection). For instance the following +will force switching to Code Set B for the data "5678" (normally Code Set C +would be used throughout): + + zint -b CODE128 -d "1234\^B5678" --extraesc + +The manually selected Code Set will apply until the next Code Set escape +sequence or until a \^@, with the exception that data that cannot be represented +in that Code Set will be switched as appropriate. If the data contains an extra +escape sequence, it can be escaped by doubling the caret (^). For instance + + zint -b CODE128 -d "\^AABC\^^BDEF" --extraesc + +will encode the data "ABC\^BDEF" in Code Set A. + +There is also the extra escape \^1, which will encode a special Function Code 1 +character (FNC1) anywhere you chose in the data, for instance + + zint -b CODE128 -d "A\^1BC\^1DEF" --extraesc + +Zint can encode a maximum of 102 symbol characters, which allows for e.g. 202 +all-numeric or 101 all-uppercase characters. Sizes above 120 digits (60 +alphanumerics) are not recommended. + +6.1.10.2 Code 128 Suppress Code Set C (Code Sets A and B only) + +[zint -b CODE128AB -d "130170X178"] + +It is sometimes advantageous to stop Code 128 from using Code Set C which +compresses numerical data. The BARCODE_CODE128AB[14] variant (symbology 60) +suppresses Code Set C in favour of Code Sets A and B. + +Note that the special extra escapes mentioned above are not available for this +variant (nor for any other). + +6.1.10.3 GS1-128 + +[zint -b GS1_128 --compliantheight -d "[01]98898765432106[3202]012345[15]991231" +] + +A variation of Code 128 previously known as UCC/EAN-128, this symbology is +defined by the GS1 General Specifications. Application Identifiers (AIs) should +be entered using [square bracket] notation. These will be converted to +parentheses (round brackets) for the Human Readable Text. This will allow round +brackets to be used in the data strings to be encoded. + +For compatibility with data entry in other systems, if the data does not include +round brackets, the option --gs1parens (API input_mode |= GS1PARENS_MODE) may be +used to signal that AIs are encased in round brackets instead of square ones. + +Fixed length data should be entered at the appropriate length for correct +encoding. GS1-128 does not support extended ASCII (ISO/IEC 8859-1) characters. +Check digits for GTIN data AI (01) are not generated and need to be included in +the input data. The following is an example of a valid GS1-128 input: + + zint -b 16 -d "[01]98898765432106[3202]012345[15]991231" + +or using the --gs1parens option: + + zint -b 16 --gs1parens -d "(01)98898765432106(3202)012345(15)991231" + +6.1.10.4 EAN-14 + +[zint -b EAN14 --compliantheight -d "9889876543210"] + +A shorter version of GS1-128 which encodes GTIN data only. A 13-digit number is +required. The GTIN check digit and HRT-only AI “(01)” are added by Zint. + +6.1.10.5 NVE-18 (SSCC-18) + +[zint -b NVE18 --compliantheight -d "37612345000001003"] + +A variation of Code 128 the ‘Nummer der Versandeinheit’ standard, also known as +SSCC-18 (Serial Shipping Container Code), includes both a visible modulo-10 and +a hidden modulo-103 check digit. NVE-18 requires a 17-digit numerical input. +Check digits and HRT-only AI “(00)” are added by Zint. + +6.1.10.6 HIBC Code 128 + +[zint -b HIBC_128 -d "A123BJC5D6E71"] + +This option adds a leading '+' character and a trailing modulo-49 check digit to +a standard Code 128 symbol as required by the Health Industry Barcode standards. + +6.1.10.7 DPD Code + +[zint -b DPD --compliantheight -d "000393206219912345678101040"] + +Another variation of Code 128 as used by DPD (Deutscher Paketdienst). Requires a +27 or 28 character input. For 28 character input, the first character is an +identification tag (Barcode ID), which should usually be "%" (ASCII 37). If 27 +characters are supplied, "%" will be prefixed by Zint (except if marked as a +“relabel”, see below). The rest of the 27-character input must be alphanumeric, +and is of the form: + + ----------------------------------------------------------------------- + Destination Post Tracking Number Service Destination Country + Code Code Code + ------------------ ------------------- ----------- -------------------- + PPPPPPP (7 TTTTTTTTTTTTTT (14 SSS (3 CCC (3-digit ISO + alphanumerics) alphanumerics) digits) 3166-1) + + ----------------------------------------------------------------------- + + Table : DPD Input Fields + +A warning will be generated if the Service Code, the Destination Country Code, +or the last 10 characters of the Tracking Number are non-numeric. + +Zint formats the Human Readable Text as specified by DPD, leaving out the +identication tag, and adds a modulo-36 check character to the text (not to the +barcode itself), thus: + +PPPP PPP TTTT TTTT TTTT TT SSS CCC D + +By default a top boundary bar is added, with default width 3X. The width can be +overridden using --border (API border_width). For a symbol with no top boundary +bar, explicitly set the border type to bindtop (or bind or box) and leave the +border width 0. + +A DPD Code can be marked as a “relabel” by specifying --vers=1 (API +option_2 = 1), which omits the identification tag and prints the barcode at half +height. In this case, an input of 27 alphanumeric characters is required. + +6.1.10.8 UPU S10 + +[zint -b UPU_S10 --compliantheight -d "EE876543216CA"] + +The Universal Postal Union S10 variant of Code 128 encodes 13 characters in the +format "SSNNNNNNNNXCC", where "SS" is a two-character alphabetic service +indicator, "NNNNNNNN" is an 8-digit serial number, "X" is a modulo-11 check +digit, and "CC" is a two-character ISO 3166-1 country code. + +The check digit may be omitted in which case Zint will add it. Warnings will be +generated if the service indicator is non-standard or the country code is not +ISO 3361-1. + +6.1.11 GS1 DataBar (ISO 24724) + +Previously known as RSS (Reduced Spaced Symbology), these symbols are due to +replace GS1-128 symbols in accordance with the GS1 General Specifications. If a +GS1 DataBar symbol is to be printed with a 2D component as specified in ISO/IEC +24723 set --mode=2 (API option_1 = 2). See 6.3 GS1 Composite Symbols (ISO 24723) +to find out how to generate DataBar symbols with 2D components. + +6.1.11.1 GS1 DataBar Omnidirectional and GS1 DataBar Truncated + +[zint -b DBAR_OMN --compliantheight -d "0950110153001"] + +Previously known as RSS-14 this standard encodes a 13-digit item code. A check +digit and HRT-only Application Identifier of “(01)” are added by Zint. (A +14-digit code that appends the check digit may be given, in which case the check +digit will be verified.) + +GS1 DataBar Omnidirectional symbols should have a height of 33 or greater. To +produce a GS1 DataBar Truncated symbol set the symbol height to a value between +13 and 32. Truncated symbols may not be scannable by omnidirectional scanners. + +[zint -b DBAR_OMN -d "0950110153001" --height=13] + +6.1.11.2 GS1 DataBar Limited + +[zint -b DBAR_LTD --compliantheight -d "0950110153001"] + +Previously known as RSS Limited this standard encodes a 13-digit item code and +can be used in the same way as GS1 DataBar Omnidirectional above. GS1 DataBar +Limited, however, is limited to data starting with digits 0 and 1 (i.e. numbers +in the range 0 to 1999999999999). As with GS1 DataBar Omnidirectional a check +digit and HRT-only Application Identifier of “(01)” are added by Zint, and a +14-digit code may be given in which case the check digit will be verified. + +6.1.11.3 GS1 DataBar Expanded + +[zint -b DBAR_EXP --compliantheight -d "[01]98898765432106[3202]012345[15]991231 +"] + +Previously known as RSS Expanded this is a variable length symbology capable of +encoding data from a number of AIs in a single symbol. AIs should be encased in +[square brackets] in the input data, which will be converted to parentheses +(round brackets) before being included in the Human Readable Text attached to +the symbol. This method allows the inclusion of parentheses in the data to be +encoded. If the data does not include parentheses, the AIs may alternatively be +encased in parentheses using the --gs1parens switch. See 6.1.10.3 GS1-128. + +GTIN data AI (01) should also include the check digit data as this is not +calculated by Zint when this symbology is encoded. Fixed length data should be +entered at the appropriate length for correct encoding. The following is an +example of a valid GS1 DataBar Expanded input: + + zint -b 31 -d "[01]98898765432106[3202]012345[15]991231" + +6.1.12 Korea Post Barcode + +[zint -b KOREAPOST -d "923457"] + +The Korean Postal Barcode is used to encode a 6-digit number and includes one +check digit. + +6.1.13 Channel Code + +[zint -b CHANNEL -d "453678" --compliantheight] + +A highly compressed symbol for numeric data. The number of channels in the +symbol can be between 3 and 8 and this can be specified by setting the value of +the --vers option (API option_2). It can also be determined by the length of the +input data: e.g. a three character input string generates a 4 channel code by +default. + +The maximum values permitted depend on the number of channels used as shown in +the table below: + + Channels Minimum Value Maximum Value + ---------- --------------- --------------- + 3 00 26 + 4 000 292 + 5 0000 3493 + 6 00000 44072 + 7 000000 576688 + 8 0000000 7742862 + + Table : Channel Value Ranges + +6.1.14 BC412 (SEMI T1-95) + +[zint -b BC412 -d "AQ45670" --compliantheight] + +Designed by IBM for marking silicon wafers, each BC412 character is represented +by 4 bars of a single size, interleaved with 4 spaces of varying sizes that +total 8 (hence 4 bars in 12). Zint implements the SEMI T1-95 standard, where +input must be alphanumeric, excluding the letter O, and must be from 7 to 18 +characters in length. A single check character is added by Zint, appearing in +the 2nd character position. Lowercase input is automatically made uppercase. + +6.2 Stacked Symbologies + +6.2.1 Basic Symbol Stacking + +An early innovation to get more information into a symbol, used primarily in the +vehicle industry, is to simply stack one-dimensional codes on top of each other. +This can be achieved at the command prompt by giving more than one set of input +data. For example + + zint -d "This" -d "That" + +will draw two Code 128 symbols, one on top of the other. The same result can be +achieved using the API by executing the ZBarcode_Encode() function more than +once on a symbol. For example: + + my_symbol->symbology = BARCODE_CODE128; + + error = ZBarcode_Encode(my_symbol, "This", 0); + + error = ZBarcode_Encode(my_symbol, "That", 0); + + error = ZBarcode_Print(my_symbol); + +[zint -d "This" -d "That"] + +Note that the Human Readable Text will be that of the last data, so it’s best to +use the option --notext (API show_hrt = 0). + +The stacked barcode rows can be separated by row separator bars by specifying +--bind (API output_options |= BARCODE_BIND). The height of the row separator +bars in integral multiples of the X-dimension (minimum and default 1, maximum 4) +can be set by --separator (API option_3): + + zint --bind --notext --separator=2 -d "This" -d "That" + +[zint --notext --bind --separator=2 -d "This" -d "That"] + +A more sophisticated method is to use some type of line indexing which indicates +to the barcode reader which order the stacked symbols should be read in. This is +demonstrated by the symbologies below. + +6.2.2 Codablock-F + +[zint -b CODABLOCKF -d "CODABLOCK F Symbology" --rows=3] + +This is a stacked symbology based on Code 128 which can encode Latin-1 data up +to a maximum length of 2726 symbol characters, meaning for instance up to 2726 +all ASCII characters, or 5452 all numeric, or up to 1363 all extended ASCII +(ISO/IEC 8859-1). + +The width of the Codablock-F symbol can be set using the --cols option (API +option_2), to a value between 9 and 67. The height (number of rows) can be set +using the --rows option (API option_1), with a maximum of 44. Zint does not +currently support encoding of GS1 data in Codablock-F symbols. + +A separate symbology ID (BARCODE_HIBC_BLOCKF) can be used to encode Health +Industry Barcode (HIBC) data which adds a leading '+' character and a modulo-49 +check digit to the encoded data. + +6.2.3 Code 16K (EN 12323) + +[zint -b CODE16K --compliantheight -d "ab0123456789"] + +Code 16K uses a Code 128 based system which can stack up to 16 rows in a block. +This gives a maximum data capacity of 77 characters or 154 numerical digits and +includes two modulo-107 check digits. Code 16K also supports ISO/IEC 8859-1 +character encoding in the same manner as Code 128. GS1 data encoding is also +supported. The minimum number of rows to use can be set using the --rows option +(API option_1), with values from 2 to 16. + +6.2.4 PDF417 (ISO 15438) + +[zint -b PDF417 -d "PDF417"] + +Heavily used in the parcel industry, the PDF417 symbology can encode a vast +amount of data into a small space. Zint supports encoding up to the ISO standard +maximum symbol size of 925 codewords which (at error correction level 0) allows +a maximum data size of 1850 text characters, or 2710 digits. + +The width of the generated PDF417 symbol can be specified at the command line +using the --cols switch (API option_2) followed by a number between 1 and 30, +the number of rows using the --rows switch (API option_3) followed by a number +between 3 and 90, and the amount of error correction information can be +specified by using the --secure switch (API option_1) followed by a number +between 0 and 8 where the number of codewords used for error correction is +determined by 2^(value + 1). The default level of error correction is determined +by the amount of data being encoded. + +This symbology uses Latin-1 character encoding by default but also supports the +ECI encoding mechanism. A separate symbology ID (BARCODE_HIBC_PDF) can be used +to encode Health Industry Barcode (HIBC) data. + +For a faster but less optimal encoding, the --fast option (API +input_mode |= FAST_MODE) may be used. + +PDF417 supports Structured Append of up to 99,999 symbols and an optional +numeric ID of up to 30 digits, which can be set by using the --structapp option +(see 4.17 Structured Append) (API structapp). The ID consists of up to 10 +triplets, each ranging from "000" to "899". For instance "123456789" would be a +valid ID of 3 triplets. However "123456900" would not, as the last triplet "900" +exceeds "899". The triplets are 0-filled, for instance "1234" becomes "123004". +If an ID is not given, no ID is encoded. + +6.2.5 Compact PDF417 (ISO 15438) + +[zint -b PDF417COMP -d "PDF417"] + +Previously known as Truncated PDF417, Compact PDF417 omits some per-row overhead +to produce a narrower but less robust symbol. Options are the same as for PDF417 +above. + +6.2.6 MicroPDF417 (ISO 24728) + +[zint -b MICROPDF417 -d "12345678"] + +A variation of the PDF417 standard, MicroPDF417 is intended for applications +where symbol size needs to be kept to a minimum. 34 predefined symbol sizes are +available with 1 - 4 columns and 4 - 44 rows. The maximum amount a MicroPDF417 +symbol can hold is 250 alphanumeric characters or 366 digits. The amount of +error correction used is dependent on symbol size. The number of columns used +can be determined using the --cols switch (API option_2) as with PDF417. + +This symbology uses Latin-1 character encoding by default but also supports the +ECI encoding mechanism. A separate symbology ID (BARCODE_HIBC_MICPDF) can be +used to encode Health Industry Barcode (HIBC) data. MicroPDF417 supports +FAST_MODE and Structured Append the same as PDF417, for which see details. + +6.2.7 GS1 DataBar Stacked (ISO 24724) + +6.2.7.1 GS1 DataBar Stacked + +[zint -b DBAR_STK --compliantheight -d "9889876543210"] + +A stacked variation of the GS1 DataBar Truncated symbol requiring the same input +(see 6.1.11.1 GS1 DataBar Omnidirectional and GS1 DataBar Truncated), this +symbol is the same as the following GS1 DataBar Stacked Omnidirectional symbol +except that its height is reduced and its central separator is a single row, +making it suitable for small items when omnidirectional scanning is not +required. It can be generated with a two-dimensional component to make a +composite symbol. + +6.2.7.2 GS1 DataBar Stacked Omnidirectional + +[zint -b DBAR_OMNSTK --compliantheight -d "9889876543210"] + +A stacked variation of the GS1 DataBar Omnidirectional symbol requiring the same +input (see 6.1.11.1 GS1 DataBar Omnidirectional and GS1 DataBar Truncated). The +data is encoded in two rows of bars with a central 3-row separator. This symbol +can be generated with a two-dimensional component to make a composite symbol. + +6.2.7.3 GS1 DataBar Expanded Stacked + +[zint -b DBAR_EXPSTK --compliantheight -d "[01]98898765432106[3202]012345[15]991 +231"] + +A stacked variation of the GS1 DataBar Expanded symbol for smaller packages. +Input is the same as for GS1 DataBar Expanded (see 6.1.11.3 GS1 DataBar +Expanded). In addition the width of the symbol can be altered using the --cols +switch (API option_2). In this case the number of columns (values 1 to 11) +relates to the number of character pairs on each row of the symbol. +Alternatively the --rows switch (API option_3) can be used to specify the +maximum number of rows (values 2 to 11), and the number of columns will be +adjusted accordingly. This symbol can be generated with a two-dimensional +component to make a composite symbol. For symbols with a 2D component the number +of columns must be at least 2. + +6.2.8 Code 49 + +[zint -b CODE49 --compliantheight -d "MULTIPLE ROWS IN CODE 49"] + +Developed in 1987 at Intermec, Code 49 is a cross between UPC and Code 39. It is +one of the earliest stacked symbologies and influenced the design of Code 16K a +few years later. It supports full 7-bit ASCII input up to a maximum of 49 +characters or 81 numeric digits. GS1 data encoding is also supported. The +minimum number of rows to use can be set using the --rows option (API option_1), +with values from 2 to 8. + +6.3 GS1 Composite Symbols (ISO 24723) + +GS1 Composite symbols employ a mixture of components to give more comprehensive +information about a product. The permissible contents of a composite symbol is +determined by the terms of the GS1 General Specifications. Composite symbols +consist of a linear component which can be an EAN, UPC, GS1-128 or GS1 DataBar +symbol, a two-dimensional (2D) component which is based on PDF417 or +MicroPDF417, and a separator pattern. The type of linear component to be used is +determined using the -b or --barcode switch (API symbology) as with other +encoding methods. Valid values are shown below. + + ---------------------------------------------------------------------------- + Numeric Name Barcode Name + Value + --------- ------------------------- ---------------------------------------- + 130 BARCODE_EANX_CC GS1 Composite Symbol with EAN linear + component + + 131 BARCODE_GS1_128_CC GS1 Composite Symbol with GS1-128 linear + component + + 132 BARCODE_DBAR_OMN_CC GS1 Composite Symbol with GS1 DataBar + Omnidirectional linear component + + 133 BARCODE_DBAR_LTD_CC GS1 Composite Symbol with GS1 DataBar + Limited linear component + + 134 BARCODE_DBAR_EXP_CC GS1 Composite Symbol with GS1 DataBar + Expanded linear component + + 135 BARCODE_UPCA_CC GS1 Composite Symbol with UPC-A linear + component + + 136 BARCODE_UPCE_CC GS1 Composite Symbol with UPC-E linear + component + + 137 BARCODE_DBAR_STK_CC GS1 Composite Symbol with GS1 DataBar + Stacked component + + 138 BARCODE_DBAR_OMNSTK_CC GS1 Composite Symbol with GS1 DataBar + Stacked Omnidirectional component + + 139 BARCODE_DBAR_EXPSTK_CC GS1 Composite Symbol with GS1 DataBar + Expanded Stacked component + ---------------------------------------------------------------------------- + + Table : GS1 Composite Symbology Values + +The data to be encoded in the linear component of a composite symbol should be +entered into a primary string with the data for the 2D component being entered +in the normal way. To do this at the command prompt use the --primary switch +(API primary). For example: + + zint -b EANX_CC --mode=1 --primary=331234567890 -d "[99]1234-abcd" + +This creates an EAN-13 linear component with the data "331234567890" and a 2D +CC-A (see below) component with the data "(99)1234-abcd". The same results can +be achieved using the API as shown below: + + my_symbol->symbology = BARCODE_EANX_CC; + + my_symbol->option_1 = 1; + + strcpy(my_symbol->primary, "331234567890"); + + ZBarcode_Encode_and_Print(my_symbol, "[99]1234-abcd", 0, 0); + +EAN-2 and EAN-5 add-on data can be used with EAN and UPC symbols using the + +symbol as described in sections 6.1.3 UPC (Universal Product Code) (ISO 15420) +and 6.1.4 EAN (European Article Number) (ISO 15420). + +The 2D component of a composite symbol can use one of three systems: CC-A, CC-B +and CC-C, as described below. The 2D component type can be selected +automatically by Zint dependent on the length of the input string. Alternatively +the three methods can be accessed using the --mode prompt (API option_1) +followed by 1, 2 or 3 for CC-A, CC-B or CC-C respectively. + +6.3.1 CC-A + +[zint -b EANX_CC --compliantheight -d "[99]1234-abcd" --mode=1 --primary=3312345 +67890] + +This system uses a variation of MicroPDF417 which is optimised to fit into a +small space. The size of the 2D component and the amount of error correction is +determined by the amount of data to be encoded and the type of linear component +which is being used. CC-A can encode up to 56 numeric digits or an alphanumeric +string of shorter length. To select CC-A use --mode=1 (API option_1 = 1). + +6.3.2 CC-B + +[zint -b EANX_CC --compliantheight -d "[99]1234-abcd" --mode=2 --primary=3312345 +67890] + +This system uses MicroPDF417 to encode the 2D component. The size of the 2D +component and the amount of error correction is determined by the amount of data +to be encoded and the type of linear component which is being used. CC-B can +encode up to 338 numeric digits or an alphanumeric string of shorter length. To +select CC-B use --mode=2 (API option_1 = 2). + +6.3.3 CC-C + +[zint -b GS1_128_CC --compliantheight -d "[99]1234-abcd" --mode=3 --primary="[01 +]03312345678903"] + +This system uses PDF417 and can only be used in conjunction with a GS1-128 +linear component. CC-C can encode up to 2361 numeric digits or an alphanumeric +string of shorter length. To select CC-C use --mode=3 (API option_1 = 3). + +6.4 Two-Track Symbols + +6.4.1 Two-Track Pharmacode + +[zint -b PHARMA_TWO --compliantheight -d "29876543"] + +Developed by Laetus, Pharmacode Two-Track is an alternative system to Pharmacode +One-Track (see 6.1.9 Pharmacode) used for the identification of pharmaceuticals. +The symbology is able to encode whole numbers between 4 and 64570080. + +6.4.2 POSTNET + +[zint -b POSTNET --compliantheight -d "12345678901"] + +Used by the United States Postal Service until 2009, the POSTNET barcode was +used for encoding zip-codes on mail items. POSTNET uses numerical input data and +includes a modulo-10 check digit. While Zint will encode POSTNET symbols of up +to 38 digits in length, standard lengths as used by USPS were PostNet6 (5-digit +ZIP input), PostNet10 (5-digit ZIP + 4-digit user data) and PostNet12 (5-digit +ZIP + 6-digit user data), and a warning will be issued if the input length is +not one of these. + +6.4.3 PLANET + +[zint -b PLANET --compliantheight -d "4012345235636"] + +Used by the United States Postal Service until 2009, the PLANET (Postal Alpha +Numeric Encoding Technique) barcode was used for encoding routing data on mail +items. PLANET uses numerical input data and includes a modulo-10 check digit. +While Zint will encode PLANET symbols of up to 38 digits in length, standard +lengths used by USPS were Planet12 (11-digit input) and Planet14 (13-digit +input), and as with POSTNET a warning will be issued if the length is not one of +these. + +6.4.4 Brazilian CEPNet + +[zint -b CEPNET --compliantheight -d "12345678"] + +Based on POSTNET, the CEPNet symbol is used by Correios, the Brazilian postal +service, to encode CEP (Código de Endereçamento Postal) numbers on mail items. +Input should consist of eight digits with the check digit being automatically +added by Zint. + +6.4.5 DX Film Edge Barcode + +[zint -b DXFILMEDGE --compliantheight -d "112-1/10A"] + +Introduced by Kodak in the 1980s, the DX (Digital Index) barcode is printed on +the bottom edge of 35mm film to aid in the reordering and post-processing of +prints. + +The data can be in two parts. The first part (required) is the “DX number”, +identifying the manufacturer and film type - the National Association of +Photographic Manufacturers (NAPM) number. The second part, which is optional and +if present is separated from the first by a slash (/), gives the frame number. + +The DX number is in either of two formats. The first format is a number of 1 to +4 digits (“DX Extract”) or 6 digits (“DX Full”), but for the 6-digit version the +first and last digit are ignored, leaving a 4-digit DX Extract number in any +case, which must be in the range 16 to 2047. The second format “NNN-NN” +represents the DX Extract as two numbers separated by a dash (-), the first +number being 1 to 3 digits (range 1 to 127) and the second 1 to 2 digits (range +0 to 15).[15] + +The optional frame number is a number in the range 0 to 63, and may have a half +frame indicator “A” appended. Special character sequences (with or without a +half frame indicator appended) may also be used: “S” or “X” means frame number +62, “K” or “00” means frame number 63, and “F” means frame number 0. + +A parity bit is automatically added by Zint. + +6.5 4-State Postal Codes + +6.5.1 Australia Post 4-State Symbols + +6.5.1.1 Customer Barcodes + +[zint -b AUSPOST --compliantheight -d "96184209"] + +Australia Post Standard Customer Barcode, Customer Barcode 2 and Customer +Barcode 3 are 37-bar, 52-bar and 67-bar specifications respectively, developed +by Australia Post for printing Delivery Point ID (DPID) and customer information +on mail items. Valid data characters are 0-9, A-Z, a-z, space and hash (#). A +Format Control Code (FCC) is added by Zint and should not be included in the +input data. Reed-Solomon error correction data is generated by Zint. Encoding +behaviour is determined by the length of the input data according to the formula +shown in the following table. + + --------------------------------------------------------------- + Input Required Input Format Symbol FCC Encoding + Length Length Table + --------- --------------------------- -------- ----- ---------- + 8 99999999 37-bar 11 None + + 13 99999999AAAAA 52-bar 59 C + + 16 9999999999999999 52-bar 59 N + + 18 99999999AAAAAAAAAA 67-bar 62 C + + 23 99999999999999999999999 67-bar 62 N + --------------------------------------------------------------- + + Table : Australia Post Input Formats + +6.5.1.2 Reply Paid Barcode + +[zint -b AUSREPLY --compliantheight -d "12345678"] + +A Reply Paid version of the Australia Post 4-State Barcode (FCC 45) which +requires an 8-digit DPID input. + +6.5.1.3 Routing Barcode + +[zint -b AUSROUTE --compliantheight -d "34567890"] + +A Routing version of the Australia Post 4-State Barcode (FCC 87) which requires +an 8-digit DPID input. + +6.5.1.4 Redirect Barcode + +[zint -b AUSREDIRECT --compliantheight -d "98765432"] + +A Redirection version of the Australia Post 4-State Barcode (FCC 92) which +requires an 8-digit DPID input. + +6.5.2 Dutch Post KIX Code + +[zint -b KIX --compliantheight -d "2500GG30250"] + +This symbology is used by Royal Dutch TPG Post (Netherlands) for Postal code and +automatic mail sorting. Data input can consist of numbers 0-9 and letters A-Z +and needs to be 11 characters in length. No check digit is included. + +6.5.3 Royal Mail 4-State Customer Code (RM4SCC) + +[zint -b RM4SCC --compliantheight -d "W1J0TR01"] + +The RM4SCC standard is used by the Royal Mail in the UK to encode postcode and +customer data on mail items. Data input can consist of numbers 0-9 and letters +A-Z and usually includes delivery postcode followed by house number. For example +"W1J0TR01" for 1 Piccadilly Circus in London. Check digit data is generated by +Zint. + +6.5.4 Royal Mail 4-State Mailmark + +[zint -b MAILMARK_4S --compliantheight -d "1100000000000XY11"] + +Developed in 2014 as a replacement for RM4SCC this 4-state symbol includes Reed- +Solomon error correction. Input is a pre-formatted alphanumeric string of 22 +(for Barcode C) or 26 (for Barcode L) characters, producing a symbol with 66 or +78 bars respectively. The rules for the input data are complex, as summarized in +the following table. + + ---------------------------------------------------------------------------- + Format Version Class Supply Chain ID Item ID Destination+DPS + ID + -------- --------- ------------ ---------------- --------- ----------------- + 1 digit 1 digit 1 alphanum. 2 digits (C) or 8 digits 9 alphanumerics + (0-4) (0-3) (0-9A-E) 6 digits (L) (1 of 6 patterns) + + ---------------------------------------------------------------------------- + + Table : Royal Mail 4-State Mailmark Input Fields + + +The 6 Destination+DPS (Destination Post Code plus Delivery Point Suffix) +patterns are: + + ----------- ----------- ----------- + FNFNLLNLS FFNNLLNLS FFNNNLLNL + FFNFNLLNL FNNLLNLSS FNNNLLNLS + ----------- ----------- ----------- + + Table : Royal Mail Mailmark Destination+DPS Patterns + + +where 'F' stands for full alphabetic (A-Z), 'L' for limited alphabetic (A-Z less +'CIKMOV'), 'N' for numeric (0-9), and 'S' for space. + +Four of the permitted patterns include a number of trailing space characters - +these will be appended by Zint if not included in the input data. + +For the two-dimensional Data Matrix-based version, see 6.6.2 Royal Mail 2D +Mailmark (CMDM) (Data Matrix). + +6.5.5 USPS Intelligent Mail + +[zint -b USPS_IMAIL --compliantheight -d "01234567094987654321-01234"] + +Also known as the OneCode barcode and used in the U.S. by the United States +Postal Service (USPS), the Intelligent Mail system replaced the POSTNET and +PLANET symbologies in 2009. Intelligent Mail is a fixed length (65-bar) symbol +which combines routing and customer information in a single symbol. Input data +consists of a 20-digit tracking code, followed by a dash (-), followed by a +delivery point zip-code which can be 0, 5, 9 or 11 digits in length. For example +all of the following inputs are valid data entries: + +- "01234567094987654321" +- "01234567094987654321-01234" +- "01234567094987654321-012345678" +- "01234567094987654321-01234567891" + +6.5.6 Japanese Postal Code + +[zint -b JAPANPOST --compliantheight -d "15400233-16-4-205"] + +Used for address data on mail items for Japan Post. Accepted values are 0-9, A-Z +and dash (-). A modulo 19 check digit is added by Zint. + +6.5.7 DAFT Code + +[zint -b DAFT -d "AAFDTTDAFADTFTTFFFDATFTADTTFFTDAFAFDTF" --height=8.494 --vers= +256] + +This is a method for creating 4-state codes where the data encoding is provided +by an external program. Input data should consist of the letters 'D', 'A', 'F' +and 'T' where these refer to descender, ascender, full (ascender and descender) +and tracker (neither ascender nor descender) respectively. All other characters +are invalid. The ratio of the tracker size to full height can be given in +thousandths (permille) using the --vers option (API option_2). The default value +is 250 (25%). + +For example the following + + zint -b DAFT -d AAFDTTDAFADTFTTFFFDATFTADTTFFTDAFAFDTF --height=8.494 --vers +=256 + +produces the same barcode (see 6.5.3 Royal Mail 4-State Customer Code (RM4SCC)) +as + + zint -b RM4SCC --compliantheight -d "W1J0TR01" + +6.6 Matrix Symbols + +6.6.1 Data Matrix (ISO 16022) + +[zint -b HIBC_DM -d "/ACMRN123456/V200912190833" --fast --square] + +Also known as Semacode this symbology was developed in 1989 by Acuity CiMatrix +in partnership with the U.S. DoD and NASA. The symbol can encode a large amount +of data in a small area. Data Matrix encodes characters in the Latin-1 set by +default but also supports encoding in other character sets using the ECI +mechanism. It can also encode GS1 data. The size of the generated symbol can be +adjusted using the --vers option (API option_2) as shown in the table below. A +separate symbology ID (BARCODE_HIBC_DM) can be used to encode Health Industry +Barcode (HIBC) data. Note that only ECC200 encoding is supported, the older +standards have now been removed from Zint. + + Input Symbol Size Input Symbol Size Input Symbol Size + ------- ------------- -- ------- ------------- -- ------- ------------- + 1 10 x 10 11 36 x 36 21 104 x 104 + 2 12 x 12 12 40 x 40 22 120 x 120 + 3 14 x 14 13 44 x 44 23 132 x 132 + 4 16 x 16 14 48 x 48 24 144 x 144 + 5 18 x 18 15 52 x 52 25 8 x 18 + 6 20 x 20 16 64 x 64 26 8 x 32 + 7 22 x 22 17 72 x 72 28 12 x 26 + 8 24 x 24 18 80 x 80 28 12 x 36 + 9 26 x 26 19 88 x 88 29 16 x 36 + 10 32 x 32 20 96 x 96 30 16 x 48 + + Table : Data Matrix Sizes + +The largest version 24 (144 x 144) can encode 3116 digits, around 2335 +alphanumeric characters, or 1555 bytes of data. + +When using automatic symbol sizes you can force Zint to use square symbols +(versions 1-24) at the command line by using the option --square (API +option_3 = DM_SQUARE). + +Data Matrix Rectangular Extension (ISO/IEC 21471) codes may be generated with +the following values as before: + + Input Symbol Size Input Symbol Size + ------- ------------- -- ------- ------------- + 31 8 x 48 40 20 x 36 + 32 8 x 64 41 20 x 44 + 33 8 x 80 42 20 x 64 + 34 8 x 96 43 22 x 48 + 35 8 x 120 44 24 x 48 + 36 8 x 144 45 24 x 64 + 37 12 x 64 46 26 x 40 + 38 12 x 88 47 26 x 48 + 39 16 x 64 48 26 x 64 + + Table : DMRE Sizes + +DMRE symbol sizes may be activated in automatic size mode using the option +--dmre (API option_3 = DM_DMRE). + +GS1 data may be encoded using FNC1 (default) or GS (Group Separator, ASCII 29) +as separator. Use the option --gssep to change to GS (API +output_options |= GS1_GS_SEPARATOR). + +By default Zint uses a “de facto” codeword placement for symbols of size 144 x +144 (version 24). To override this and use the now clarified ISO/IEC standard +placement, use option --dmiso144 (API option_3 |= DM_ISO_144). + +For a faster but less optimal encoding, the --fast option (API +input_mode |= FAST_MODE) may be used. + +Data Matrix supports Structured Append of up to 16 symbols and a numeric ID +(file identifications), which can be set by using the --structapp option (see +4.17 Structured Append) (API structapp). The ID consists of 2 numbers ID1 and +ID2, each of which can range from 1 to 254, and is specified as the single +number ID1 * 1000 + ID2, so for instance ID1 "123" and ID2 "234" would be given +as "123234". Note that both ID1 and ID2 must be non-zero, so e.g. "123000" or +"000123" would be invalid IDs. If an ID is not given it defaults to "001001". + +6.6.2 Royal Mail 2D Mailmark (CMDM) (Data Matrix) + +[zint -b MAILMARK_2D -d "JGB 01Z999999900000001EC1A1AA1A0SN35TQ" --vers=30] + +This variant of Data Matrix, also known as “Complex Mail Data Mark” (CMDM), was +introduced by Royal Mail along with 6.5.4 Royal Mail 4-State Mailmark, and +offers space for customer data following an initial pre-formatted 45 character +section, as summarized below. + + Field Name Length Values + ------------------ ------------- -------------------------------- + UPU Country ID 4 "JGB " + Information Type 1 Alphanumeric + Version ID 1 "1" + Class 1 Alphanumeric + Supply Chain ID 7 Numeric + Item ID 8 Numeric + Destination+DPS 9 Alphanumeric (1 of 6 patterns) + Service Type 1 Numeric + RTS Post Code 7 Alphanumeric (1 of 6 patterns) + Reserved 6 Spaces + Customer Data 6, 45 or 29 Anything (Latin-1) + + Table : Royal Mail 2D Mailmark Input Fields + +The 6 Destination+DPS (Destination Post Code plus Delivery Point Suffix) +patterns are the same as for the 4-state - see Table +: Royal Mail Mailmark Destination+DPS Patterns. The 6 RTS (Return to Sender) +Post Code patterns are the same also except without the additional DPS 'NL', +i.e. + + --------- --------- --------- + FNFNLLS FFNNLLS FFNNNLL + FFNFNLL FNNLLSS FNNNLLS + --------- --------- --------- + + Table : Royal Mail 2D Mailmark RTS Patterns + +where 'F' is full alphabetic (A-Z), 'L' limited alphabetic (A-Z less 'CIKMOV'), +'N' numeric (0-9), and 'S' space. + +Three sizes are defined, one rectangular, with varying maximum amounts of +optional customer data: + + Name Size Customer Data Zint Version + --------- --------- --------------- -------------- + Type 7 24 x 24 6 characters 8 + Type 9 32 x 32 45 characters 10 + Type 29 16 x 48 29 characters 30 + + Table : Royal Mail 2D Mailmark Sizes + +Zint will automatically select a size based on the amount of customer data, or +it can be specified using the --vers option (API option_2), which takes the Zint +version number (one more than the Royal Mail Type number). Zint will prefix the +input data with "JGB " if it’s missing, and also space-pad the input if the +customer data is absent or falls short. As with Data Matrix, the rectangular +symbol Type 29 can be excluded from automatic size selection by using the option +--square (API option_3 = DM_SQUARE). + +GS1 data, the ECI mechanism, and Structured Append are not supported. + +6.6.3 QR Code (ISO 18004) + +[zint -b QRCODE -d "QR Code Symbol" --mask=5] + +Also known as Quick Response Code this symbology was developed by Denso. Four +levels of error correction are available using the --secure option (API +option_1) as shown in the following table. + + Input ECC Level Error Correction Capacity Recovery Capacity + ------- ----------- --------------------------- ------------------- + 1 L Approx 20% of symbol Approx 7% + 2 M Approx 37% of symbol Approx 15% + 3 Q Approx 55% of symbol Approx 25% + 4 H Approx 65% of symbol Approx 30% + + Table : QR Code ECC Levels + +The size of the symbol can be specified by setting the --vers option (API +option_2) to the QR Code version required (1-40). The size of symbol generated +is shown in the table below. + + Input Symbol Size Input Symbol Size Input Symbol Size + ------- ------------- -- ------- ------------- -- ------- ------------- + 1 21 x 21 15 77 x 77 29 133 x 133 + 2 25 x 25 16 81 x 81 30 137 x 137 + 3 29 x 29 17 85 x 85 31 141 x 141 + 4 33 x 33 18 89 x 89 32 145 x 145 + 5 37 x 37 19 93 x 93 33 149 x 149 + 6 41 x 41 20 97 x 97 34 153 x 153 + 7 45 x 45 21 101 x 101 35 157 x 157 + 8 49 x 49 22 105 x 105 36 161 x 161 + 9 53 x 53 23 109 x 109 37 165 x 165 + 10 57 x 57 24 113 x 113 38 169 x 169 + 11 61 x 61 25 117 x 117 39 173 x 173 + 12 65 x 65 26 121 x 121 40 177 x 177 + 13 69 x 69 27 125 x 125 + 14 73 x 73 28 129 x 129 + + Table : QR Code Sizes + +The maximum capacity of a QR Code symbol (version 40) is 7089 numeric digits, +4296 alphanumeric characters or 2953 bytes of data. QR Code symbols can also be +used to encode GS1 data. QR Code symbols can by default encode either characters +in the Latin-1 set or Kanji, Katakana and ASCII characters which are members of +the Shift JIS encoding scheme. In addition QR Code supports other character sets +using the ECI mechanism. Input should usually be entered as UTF-8 with +conversion to Latin-1 or Shift JIS being carried out by Zint. A separate +symbology ID (BARCODE_HIBC_QR) can be used to encode Health Industry Barcode +(HIBC) data. + +Non-ASCII data density may be maximized by using the --fullmultibyte switch (API +option_3 = ZINT_FULL_MULTIBYTE), but check that your barcode reader supports +this before using. + +QR Code has eight different masks designed to minimize unwanted patterns. The +best mask to use is selected automatically by Zint but may be manually specified +by using the --mask switch with values 0-7, or in the API by setting +option_3 = (N + 1) << 8 where N is 0-7. To use with ZINT_FULL_MULTIBYTE set + + option_3 = ZINT_FULL_MULTIBYTE | (N + 1) << 8 + +The --fast option (API input_mode |= FAST_MODE) may be used when leaving Zint to +automatically select a mask to reduce the number of masks to try to four (0, 2, +4, 7). + +QR Code supports Structured Append of up to 16 symbols and a numeric ID +(parity), which can be set by using the --structapp option (see 4.17 Structured +Append) (API structapp). The parity ID ranges from 0 (default) to 255, and for +full compliance should be set to the value obtained by XOR-ing together each +byte of the complete data forming the sequence. Currently this calculation must +be done outside of Zint. + +6.6.4 Micro QR Code (ISO 18004) + +[zint -b MICROQR -d "01234567"] + +A miniature version of the QR Code symbol for short messages, Micro QR Code +symbols can encode either Latin-1 characters or Shift JIS characters. Input +should be entered as a UTF-8 stream with conversion to Latin-1 or Shift JIS +being carried out automatically by Zint. A preferred symbol size can be selected +by using the --vers option (API option_2), as shown in the table below. Note +that versions M1 and M2 have restrictions on what characters can be encoded. + + ------------------------------------------------------------------ + Input Version Symbol Size Allowed Characters + ------- --------- ------------- ---------------------------------- + 1 M1 11 x 11 Numeric only + + 2 M2 13 x 13 Numeric, uppercase letters, space, + and the characters "$%*+-./:" + + 3 M3 15 x 15 Latin-1 and Shift JIS + + 4 M4 17 x 17 Latin-1 and Shift JIS + ------------------------------------------------------------------ + + Table : Micro QR Code Sizes + +Version M4 can encode up to 35 digits, 21 alphanumerics, 15 bytes or 9 Kanji +characters. + +Except for version M1, which is always ECC level L, the amount of ECC codewords +can be adjusted using the --secure option (API option_1); however ECC level H is +not available for any version, and ECC level Q is only available for version M4: + + ---------------------------------------------------------------------- + Input ECC Error Correction Recovery Available for + Level Capacity Capacity Versions + -------- -------- ----------------------- ------------- -------------- + 1 L Approx 20% of symbol Approx 7% M1, M2, M3, M4 + + 2 M Approx 37% of symbol Approx 15% M2, M3, M4 + + 3 Q Approx 55% of symbol Approx 25% M4 + ---------------------------------------------------------------------- + + Table : Micro QR ECC Levels + +The defaults for symbol size and ECC level depend on the input and whether +either of them is specified. + +For barcode readers that support it, non-ASCII data density may be maximized by +using the --fullmultibyte switch (API option_3 = ZINT_FULL_MULTIBYTE). + +Micro QR Code has four different masks designed to minimize unwanted patterns. +The best mask to use is selected automatically by Zint but may be manually +specified by using the --mask switch with values 0-3, or in the API by setting +option_3 = (N + 1) << 8 where N is 0-3. To use with ZINT_FULL_MULTIBYTE set + + option_3 = ZINT_FULL_MULTIBYTE | (N + 1) << 8 + +6.6.5 Rectangular Micro QR Code (rMQR) (ISO 23941) + +[zint -b RMQR -d "0123456"] + +A rectangular version of QR Code, rMQR supports encoding of GS1 data, and either +Latin-1 characters or Shift JIS characters, and other encodings using the ECI +mechanism. As with other symbologies data should be entered as UTF-8 with +conversion being handled by Zint. The amount of ECC codewords can be adjusted +using the --secure option (API option_1), however only ECC levels M and H are +valid for this type of symbol. + + Input ECC Level Error Correction Capacity Recovery Capacity + ------- ----------- --------------------------- ------------------- + 2 M Approx 37% of symbol Approx 15% + 4 H Approx 65% of symbol Approx 30% + + Table : rMQR ECC Levels + +The preferred symbol sizes can be selected using the --vers option (API +option_2) as shown in the table below. Input values between 33 and 38 fix the +height of the symbol while allowing Zint to determine the minimum symbol width. + + ------------------------------------------------------------------------------ + Input Version Symbol Size (HxW) Input Version Symbol Size (HxW) + ------- --------- ------------------ -- ------- --------- -------------------- + 1 R7x43 7 x 43 20 R13x77 13 x 77 + + 2 R7x59 7 x 59 21 R13x99 13 x 99 + + 3 R7x77 7 x 77 22 R13x139 13 x 139 + + 4 R7x99 7 x 99 23 R15x43 15 x 43 + + 5 R7x139 7 x 139 24 R15x59 15 x 59 + + 6 R9x43 9 x 43 25 R15x77 15 x 77 + + 7 R9x59 9 x 59 26 R15x99 15 x 99 + + 8 R9x77 9 x 77 27 R15x139 15 x 139 + + 9 R9x99 9 x 99 28 R17x43 17 x 43 + + 10 R9x139 9 x 139 29 R17x59 17 x 59 + + 11 R11x27 11 x 27 30 R17x77 17 x 77 + + 12 R11x43 11 x 43 31 R17x99 17 x 99 + + 13 R11x59 11 x 59 32 R17x139 17 x 139 + + 14 R11x77 11 x 77 33 R7xW 7 x automatic width + + 15 R11x99 11 x 99 34 R9xW 9 x automatic width + + 16 R11x139 11 x 139 35 R11xW 11 x automatic width + + 17 R13x27 13 x 27 36 R13xW 13 x automatic width + + 18 R13x43 13 x 43 37 R15xW 15 x automatic width + + 19 R13x59 13 x 59 38 R17xW 17 x automatic width + ------------------------------------------------------------------------------ + + Table : rMQR Sizes + +The largest version R17x139 (32) can encode up to 361 digits, 219 alphanumerics, +150 bytes, or 92 Kanji characters. + +For barcode readers that support it, non-ASCII data density may be maximized by +using the --fullmultibyte switch or in the API by setting +option_3 = ZINT_FULL_MULTIBYTE. + +6.6.6 UPNQR (Univerzalnega Plačilnega Naloga QR) + +[zint -b UPNQR -i upn_utf8.txt --quietzones] + +A variation of QR Code used by Združenje Bank Slovenije (Bank Association of +Slovenia). The size, error correction level and ECI are set by Zint and do not +need to be specified. UPNQR is unusual in that it uses Latin-2 (ISO/IEC 8859-2 +plus ASCII) formatted data. Zint will accept UTF-8 data and convert it to +Latin-2, or if your data is already Latin-2 formatted use the --binary switch +(API input_mode = DATA_MODE). + +The following example creates a symbol from data saved as a Latin-2 file: + + zint -o upnqr.png -b 143 --scale=3 --binary -i upn.txt + +A mask may be manually specified or the --fast option used as with QRCODE. + +6.6.7 MaxiCode (ISO 16023) + +[zint -b MAXICODE -d "1Z00004951\GUPSN\G06X610\G159\G1234567\G1/1\G\GY\G1 MAIN S +T\GNY\GNY\R\E" --esc --primary="152382802000000" --scmvv=96] + +Developed by UPS the MaxiCode symbology employs a grid of hexagons surrounding a +bullseye finder pattern. This symbology is designed for the identification of +parcels. MaxiCode symbols can be encoded in one of five modes. In modes 2 and 3 +MaxiCode symbols are composed of two parts named the primary and secondary +messages. The primary message consists of a Structured Carrier Message which +includes various data about the package being sent and the secondary message +usually consists of address data in a data structure. The format of the primary +message required by Zint is given in the following table. + + Characters Meaning + ------------ ----------------------------------------------------------------- + 1 - 9 Postcode data which can consist of up to 9 digits (for mode 2) + or up to 6 alphanumeric characters (for mode 3). Remaining + unused characters for mode 3 can be filled with the SPACE + character (ASCII 32) or omitted. + (adjust the following character positions according to postcode + length) + 10 - 12 Three-digit country code according to ISO 3166-1. + 13 - 15 Three-digit service code. This depends on your parcel courier. + + Table : MaxiCode Structured Carrier Message Format + +The primary message can be set at the command prompt using the --primary switch +(API primary). The secondary message uses the normal data entry method. For +example: + + zint -o test.eps -b 57 --primary="999999999840012" \ + -d "Secondary Message Here" + +When using the API the primary message must be placed in the primary string. The +secondary is entered in the same way as described in 5.2 Encoding and Saving to +File. When either of these modes is selected Zint will analyse the primary +message and select either mode 2 or mode 3 as appropriate. + +As a convenience the secondary message for modes 2 and 3 can be set to be +prefixed by the ISO/IEC 15434 Format "01" (transportation) sequence +"[)>\R01\Gvv", where vv is a 2-digit version, by using the --scmvv switch (API +option_2 = vv + 1). For example to use the common version "96" (ASC MH10/SC 8): + + zint -b 57 --primary="152382802840001" --scmvv=96 --esc -d \ + "1Z00004951\GUPSN\G06X610\G159\G1234567\G1/1\G\GY\G1 MAIN ST\GNY\GNY\R\E" + +will prefix "[)>\R01\G96" to the secondary message. (\R, \G and \E are the +escape sequences for Record Separator, Group Separator and End of Transmission +respectively - see Table : Escape Sequences.) + +Modes 4 to 6 can be accessed using the --mode switch (API option_1). Modes 4 to +6 do not have a primary message. For example: + + zint -o test.eps -b 57 --mode=4 -d "A MaxiCode Message in Mode 4" + +Mode 6 is reserved for the maintenance of scanner hardware and should not be +used to encode user data. + +This symbology uses Latin-1 character encoding by default but also supports the +ECI encoding mechanism. The maximum length of text which can be placed in a +MaxiCode symbol depends on the type of characters used in the text. + +Example maximum data lengths are given in the table below: + + ------------------------------------------------------------------------ + Mode Maximum Data Length Maximum Data Length Number of Error + for Capital Letters for Numeric Digits Correction Codewords + ------ --------------------- --------------------- --------------------- + 2* 84 126 50 + + 3* 84 126 50 + + 4 93 138 50 + + 5 77 113 66 + + 6 93 138 50 + ------------------------------------------------------------------------ + + Table : MaxiCode Data Length Maxima + +* - secondary only + +MaxiCode supports Structured Append of up to 8 symbols, which can be set by +using the --structapp option (see 4.17 Structured Append) (API structapp). It +does not support specifying an ID. + +MaxiCode uses a different scaling than other symbols for raster output, see +4.9.3 MaxiCode Raster Scaling, and also for EMF vector output, when the scale is +multiplied by 20 instead of 2. + +6.6.8 Aztec Code (ISO 24778) + +[zint -b AZTEC -d "123456789012"] + +Invented by Andrew Longacre at Welch Allyn Inc in 1995 the Aztec Code symbol is +a matrix symbol with a distinctive bullseye finder pattern. Zint can generate +Compact Aztec Code (sometimes called Small Aztec Code) as well as ‘full-range’ +Aztec Code symbols and by default will automatically select symbol type and size +dependent on the length of the data to be encoded. Error correction codewords +will normally be generated to fill at least 23% of the symbol. Two options are +available to change this behaviour: + +The size of the symbol can be specified using the --vers option (API option_2) +to a value between 1 and 36 according to the following table. The symbols marked +with an asterisk (*) in the table below are ‘compact’ symbols, meaning they have +a smaller bullseye pattern at the centre of the symbol. + + Input Symbol Size Input Symbol Size Input Symbol Size + ------- ------------- -- ------- ------------- -- ------- ------------- + 1 15 x 15* 13 53 x 53 25 105 x 105 + 2 19 x 19* 14 57 x 57 26 109 x 109 + 3 23 x 23* 15 61 x 61 27 113 x 113 + 4 27 x 27* 16 67 x 67 28 117 x 117 + 5 19 x 19 17 71 x 71 29 121 x 121 + 6 23 x 23 18 75 x 75 30 125 x 125 + 7 27 x 27 19 79 x 79 31 131 x 131 + 8 31 x 31 20 83 x 83 32 135 x 135 + 9 37 x 37 21 87 x 87 33 139 x 139 + 10 41 x 41 22 91 x 91 34 143 x 143 + 11 45 x 45 23 95 x 95 35 147 x 147 + 12 49 x 49 24 101 x 101 36 151 x 151 + + Table : Aztec Code Sizes + +Note that in symbols which have a specified size the amount of error correction +is dependent on the length of the data input and Zint will allow error +correction capacities as low as 3 codewords. + +Alternatively the amount of error correction data can be specified by setting +the --secure option (API option_1) to a value from the following table. + + Mode Error Correction Capacity + ------ --------------------------- + 1 >10% + 3 codewords + 2 >23% + 3 codewords + 3 >36% + 3 codewords + 4 >50% + 3 codewords + + Table : Aztec Code Error Correction Modes + +It is not possible to select both symbol size and error correction capacity for +the same symbol. If both options are selected then the error correction capacity +selection will be ignored. + +Aztec Code supports ECI encoding and can encode up to a maximum length of +approximately 3823 numeric or 3067 alphabetic characters or 1914 bytes of data. +A separate symbology ID (BARCODE_HIBC_AZTEC) can be used to encode Health +Industry Barcode (HIBC) data. + +Aztec Code supports Structured Append of up to 26 symbols and an optional +alphanumeric ID of up to 32 characters, which can be set by using the +--structapp option (see 4.17 Structured Append) (API structapp). The ID cannot +contain spaces. If an ID is not given, no ID is encoded. + +6.6.9 Aztec Runes (ISO 24778) + +[zint -b AZRUNE -d "125"] + +A truncated version of compact Aztec Code for encoding whole integers between 0 +and 255, as defined in ISO/IEC 24778 Annex A. Includes Reed-Solomon error +correction. It does not support Structured Append. + +6.6.10 Code One + +[zint -b CODEONE -d "1234567890123456789012"] + +A matrix symbology developed by Ted Williams in 1992 which encodes data in a way +similar to Data Matrix, Code One is able to encode the Latin-1 character set or +GS1 data, and also supports the ECI mechanism. There are two types of Code One +symbol - fixed-ratio symbols which are roughly square (versions A through to H) +and variable-width versions (versions S and T). These can be selected by using +--vers (API option_2) as shown in the table below: + + -------------------------------------------------------------- + Input Version Size (W x H) Numeric Data Alphanumeric + Capacity Data Capacity + ------- --------- ------------ --------------- --------------- + 1 A 16 x 18 22 13 + + 2 B 22 x 22 44 27 + + 3 C 28 x 28 104 64 + + 4 D 40 x 42 217 135 + + 5 E 52 x 54 435 271 + + 6 F 70 x 76 886 553 + + 7 G 104 x 98 1755 1096 + + 8 H 148 x 134 3550 2218 + + 9 S width x 8 18 N/A + + 10 T width x 16 90 55 + -------------------------------------------------------------- + + Table : Code One Sizes + +Version S symbols can only encode numeric data. The width of version S and +version T symbols is determined by the length of the input data. + +Code One supports Structured Append of up to 128 symbols, which can be set by +using the --structapp option (see 4.17 Structured Append) (API structapp). It +does not support specifying an ID. Structured Append is not supported with GS1 +data nor for Version S symbols. + +6.6.11 Grid Matrix + +[zint -b GRIDMATRIX --eci=29 -d "AAT2556 电池充电器+降压转换器 200mA至2A tel:86 019 825127 +38"] + +Grid Matrix groups modules in a chequerboard pattern, and by default supports +the GB 2312 standard set, which includes Hanzi, ASCII and a small number of +ISO/IEC 8859-1 characters. Input should be entered as UTF-8 with conversion to +GB 2312 being carried out automatically by Zint. Up to around 1529 alphanumeric +characters or 2751 digits may be encoded. The symbology also supports the ECI +mechanism. Support for GS1 data has not yet been implemented. + +The size of the symbol and the error correction capacity can be specified. If +you specify both of these values then Zint will make a ‘best-fit’ attempt to +satisfy both conditions. The symbol size can be specified using the --vers +option (API option_2), and the error correction capacity can be specified by +using the --secure option (API option_1), according to the following tables. + + Input Symbol Size Input Symbol Size + ------- ------------- -- ------- ------------- + 1 18 x 18 8 102 x 102 + 2 30 x 30 9 114 x 114 + 3 42 x 42 10 126 x 126 + 4 54 x 54 11 138 x 138 + 5 66 x 66 12 150 x 150 + 6 78 x 78 13 162 x 162 + 7 90 x 90 + + Table : Grid Matrix Sizes + + Mode Error Correction Capacity + ------ --------------------------- + 1 Approximately 10% + 2 Approximately 20% + 3 Approximately 30% + 4 Approximately 40% + 5 Approximately 50% + + Table : Grid Matrix Error Correction Modes + +Non-ASCII data density may be maximized by using the --fullmultibyte switch (API +option_3 = ZINT_FULL_MULTIBYTE), but check that your barcode reader supports +this before using. + +Grid Matrix supports Structured Append of up to 16 symbols and a numeric ID +(file signature), which can be set by using the --structapp option (see 4.17 +Structured Append) (API structapp). The ID ranges from 0 (default) to 255. + +6.6.12 DotCode + +[zint -b DOTCODE -d "[01]00012345678905[17]201231[10]ABC123456" --gs1] + +DotCode uses a grid of dots in a rectangular formation to encode characters up +to a maximum of approximately 450 characters (or 900 numeric digits). The +symbology supports ECI encoding and GS1 data encoding. By default Zint will +produce a symbol which is approximately square, however the width of the symbol +can be adjusted by using the --cols option (API option_2) (maximum 200). +Outputting DotCode to raster images (BMP, GIF, PCX, PNG, TIF) will require +setting the scale of the image to a larger value than the default (e.g. +approximately 10) for the dots to be plotted correctly. Approximately 33% of the +resulting symbol is comprised of error correction codewords. + +DotCode has two sets of 4 masks, designated 0-3 and 0’-3’, the second "prime" +set being the same as the first with corners lit. The best mask to use is +selected automatically by Zint but may be manually specified by using the --mask +switch with values 0-7, where 4-7 denote 0’-3’, or in the API by setting +option_3 = (N + 1) << 8 where N is 0-7. + +DotCode supports Structured Append of up to 35 symbols, which can be set by +using the --structapp option (see 4.17 Structured Append) (API structapp). It +does not support specifying an ID. + +6.6.13 Han Xin Code (ISO 20830) + +[zint -b HANXIN -d "Hanxin Code symbol"] + +Also known as Chinese Sensible Code, Han Xin is capable of encoding characters +in either the Latin-1 character set or the GB 18030 character set (which is a +UTF, i.e. includes all Unicode characters, optimized for Chinese characters) and +is also able to support the ECI mechanism. Support for the encoding of GS1 data +has not yet been implemented. + +The size of the symbol can be specified using the --vers option (API option_2) +to a value between 1 and 84 according to the following table. + + Input Symbol Size Input Symbol Size Input Symbol Size + ------- ------------- -- ------- ------------- -- ------- ------------- + 1 23 x 23 29 79 x 79 57 135 x 135 + 2 25 x 25 30 81 x 81 58 137 x 137 + 3 27 x 27 31 83 x 83 59 139 x 139 + 4 29 x 29 32 85 x 85 60 141 x 141 + 5 31 x 31 33 87 x 87 61 143 x 143 + 6 33 x 33 34 89 x 89 62 145 x 145 + 7 35 x 35 35 91 x 91 63 147 x 147 + 8 37 x 37 36 93 x 93 64 149 x 149 + 9 39 x 39 37 95 x 95 65 151 x 151 + 10 41 x 41 38 97 x 97 66 153 x 153 + 11 43 x 43 39 99 x 99 67 155 x 155 + 12 45 x 45 40 101 x 101 68 157 x 157 + 13 47 x 47 41 103 x 103 69 159 x 159 + 14 49 x 49 42 105 x 105 70 161 x 161 + 15 51 x 51 43 107 x 107 71 163 x 163 + 16 53 x 53 44 109 x 109 72 165 x 165 + 17 55 x 55 45 111 x 111 73 167 x 167 + 18 57 x 57 46 113 x 113 74 169 x 169 + 19 59 x 59 47 115 x 115 75 171 x 171 + 20 61 x 61 48 117 x 117 76 173 x 173 + 21 63 x 63 49 119 x 119 77 175 x 175 + 22 65 x 65 50 121 x 121 78 177 x 177 + 23 67 x 67 51 123 x 123 79 179 x 179 + 24 69 x 69 52 125 x 125 80 181 x 181 + 25 71 x 71 53 127 x 127 81 183 x 183 + 26 73 x 73 54 129 x 129 82 185 x 185 + 27 75 x 75 55 131 x 131 83 187 x 187 + 28 77 x 77 56 133 x 133 84 189 x 189 + + Table : Han Xin Sizes + +The largest version (84) can encode 7827 digits, 4350 ASCII characters, up to +2175 Chinese characters, or 3261 bytes, making it the most capacious of all the +barcodes supported by Zint. + +There are four levels of error correction capacity available for Han Xin Code +which can be set by using the --secure option (API option_1) to a value from the +following table. + + Mode Recovery Capacity + ------ ------------------- + 1 Approx 8% + 2 Approx 15% + 3 Approx 23% + 4 Approx 30% + + Table : Han Xin Error Correction Modes + +Non-ASCII data density may be maximized by using the --fullmultibyte switch (API +option_3 = ZINT_FULL_MULTIBYTE), but check that your barcode reader supports +this before using. + +Han Xin has four different masks designed to minimize unwanted patterns. The +best mask to use is selected automatically by Zint but may be manually specified +by using the --mask switch with values 0-3, or in the API by setting +option_3 = (N + 1) << 8 where N is 0-3. To use with ZINT_FULL_MULTIBYTE set + + option_3 = ZINT_FULL_MULTIBYTE | (N + 1) << 8 + +6.6.14 Ultracode + +[zint -b ULTRA -d "HEIMASÍÐA KENNARAHÁSKÓLA ÍSLANDS"] + +This symbology uses a grid of coloured elements to encode data. ECI and GS1 +modes are supported. The amount of error correction can be set using the +--secure option (API option_1) to a value as shown in the following table. + + Value EC Level Amount of symbol holding error correction data + ------- ---------- ------------------------------------------------ + 1 EC0 0% - Error detection only + 2 EC1 Approx 5% + 3 EC2 Approx 9% - Default value + 4 EC3 Approx 17% + 5 EC4 Approx 25% + 6 EC5 Approx 33% + + Table : Ultracode Error Correction Values + +Zint does not currently implement data compression by default, but this can be +initiated through the API by setting + + symbol->option_3 = ULTRA_COMPRESSION; + +With compression, up to 504 digits, 375 alphanumerics or 252 bytes can be +encoded. + +Revision 2 of Ultracode (2023) may be specified using --vers=2 (API +option_2 = 2). + +-------------------------------------------------------------------------------- + +WARNING: Revision 2 of Ultracode was only finalized December 2023 and Zint has +not yet been updated to support it. Do not use. + +-------------------------------------------------------------------------------- + +Ultracode supports Structured Append of up to 8 symbols and an optional numeric +ID (File Number), which can be set by using the --structapp option (see 4.17 +Structured Append) (API structapp). The ID ranges from 1 to 80088. If an ID is +not given, no ID is encoded. + +6.7 Other Barcode-Like Markings + +6.7.1 Facing Identification Mark (FIM) + +[zint -b FIM --compliantheight -d "C"] + +Used by the United States Postal Service (USPS), the FIM symbology is used to +assist automated mail processing. There are only 5 valid symbols which can be +generated using the characters A-E as shown in the table below. + + Code Letter Usage + ------------- ---------------------------------------------------------------- + A Used for courtesy reply mail and metered reply mail with a + pre-printed POSTNET symbol. + B Used for business reply mail without a pre-printed zip code. + C Used for business reply mail with a pre-printed zip code. + D Used for Information Based Indicia (IBI) postage. + E Used for customized mail with a USPS Intelligent Mail barcode. + + Table : Valid FIM Characters + +6.7.2 Flattermarken + +[zint -b FLAT -d "1304056"] + +Used for the recognition of page sequences in print-shops, the Flattermarken is +not a true barcode symbol and requires precise knowledge of the position of the +mark on the page. The Flattermarken system can encode numeric data up to a +maximum of 128 digits and does not include a check digit. + +7. Legal and Version Information + +7.1 License + +Zint, libzint and Zint Barcode Studio are Copyright © 2024 Robin Stuart. All +historical versions are distributed under the GNU General Public License version +3 or later. Versions 2.5 and later are released under a dual license: the +encoding library is released under the BSD (3 clause) license whereas the GUI, +Zint Barcode Studio, and the CLI are released under the GNU General Public +License version 3 or later. + +Telepen is a trademark of SB Electronic Systems Ltd. + +QR Code is a registered trademark of Denso Wave Incorporated. + +Mailmark is a registered trademark of Royal Mail Group Ltd. + +Microsoft, Windows and the Windows logo are either registered trademarks or +trademarks of Microsoft Corporation in the United States and/or other countries. + +Linux is the registered trademark of Linus Torvalds in the U.S. and other +countries. + +Mac and macOS are trademarks of Apple Inc., registered in the U.S. and other +countries. + +The Zint logo is derived from “SF Planetary Orbiter” font by ShyFoundary. + +Zint.org.uk website design and hosting provided by Robert Elliott. + +7.2 Patent Issues + +All of the code in Zint is developed using information in the public domain, +usually freely available on the Internet. Some of the techniques used may be +subject to patents and other intellectual property legislation. It is my belief +that any patents involved in the technology underlying symbologies utilised by +Zint are ‘unadopted’, that is the holder does not object to their methods being +used. + +Any methods patented or owned by third parties or trademarks or registered +trademarks used within Zint or in this document are and remain the property of +their respective owners and do not indicate endorsement or affiliation with +those owners, companies or organisations. + +7.3 Version Information + +The current stable version of Zint is 2.13.0, released on 18th December 2023. + +See "ChangeLog" in the project root directory for information on all releases. + +7.4 Sources of Information + +Below is a list of some of the sources used in rough chronological order: + +- Nick Johnson’s Barcode Specifications +- Bar Code 1 Specification Source Page +- SB Electronic Systems Telepen website +- Pharmacode specifications from Laetus +- Morovia RM4SCC specification +- Australia Post’s ‘A Guide to Printing the 4-State Barcode’ and bcsample + source code +- Plessey algorithm from GNU-Barcode v0.98 by Leonid A. Broukhis +- GS1 General Specifications v 8.0 Issue 2 +- PNG: The Definitive Guide and wpng source code by Greg Reolofs +- PDF417 specification and pdf417 source code by Grand Zebu +- Barcode Reference, TBarCode/X User Documentation and TBarCode/X + demonstration program from Tec-It +- IEC16022 source code by Stefan Schmidt et al +- United States Postal Service Specification USPS-B-3200 +- Adobe Systems Incorporated Encapsulated PostScript File Format Specification +- BSI Online Library +- Libdmtx Data Matrix ECC200 decoding library + +7.5 Standards Compliance + +Zint was developed to provide compliance with the following British and +international standards: + +7.5.1 Symbology Standards + +- ISO/IEC 24778:2008 Information technology - Automatic identification and + data capture techniques - Aztec Code bar code symbology specification +- SEMI T1-95 Specification for Back Surface Bar Code Marking of Silicon Wafers + (BC412) (1996) +- ANSI/AIM BC12-1998 - Uniform Symbology Specification Channel Code +- BS EN 798:1996 Bar coding - Symbology specifications - ‘Codabar’ +- AIM Europe ISS-X-24 - Uniform Symbology Specification Codablock-F (1995) +- ISO/IEC 15417:2007 Information technology - Automatic identification and + data capture techniques - Code 128 bar code symbology specification +- BS EN 12323:2005 AIDC technologies - Symbology specifications - Code 16K +- ISO/IEC 16388:2007 Information technology - Automatic identification and + data capture techniques - Code 39 bar code symbology specification +- ANSI/AIM BC6-2000 - Uniform Symbology Specification Code 49 +- ANSI/AIM BC5-1995 - Uniform Symbology Specification Code 93 +- AIM Uniform Symbology Specification Code One (1994) +- ISO/IEC 16022:2006 Information technology - Automatic identification and + data capture techniques - Data Matrix ECC200 bar code symbology + specification +- ISO/IEC 21471:2020 Information technology - Automatic identification and + data capture techniques - Extended rectangular data matrix (DMRE) bar code + symbology specification +- AIM TSC1705001 (v 4.0 Draft 0.15) - Information technology - Automatic + identification and data capture techniques - Bar code symbology + specification - DotCode (Revised 28th May 2019) +- ISO/IEC 15420:2009 Information technology - Automatic identification and + data capture techniques - EAN/UPC bar code symbology specification +- AIMD014 (v 1.63) - Information technology, Automatic identification and data + capture techniques - Bar code symbology specification - Grid Matrix + (Released 9th Dec 2008) +- ISO/IEC 24723:2010 Information technology - Automatic identification and + data capture techniques - GS1 Composite bar code symbology specification +- ISO/IEC 24724:2011 Information technology - Automatic identification and + data capture techniques - GS1 DataBar bar code symbology specification +- ISO/IEC 20830:2021 Information technology - Automatic identification and + data capture techniques - Han Xin Code bar code symbology specification +- ISO/IEC 16390:2007 Information technology - Automatic identification and + data capture techniques - Interleaved 2 of 5 bar code symbology + specification +- ISO/IEC 16023:2000 Information technology - International symbology + specification - MaxiCode +- ISO/IEC 24728:2006 Information technology - Automatic identification and + data capture techniques - MicroPDF417 bar code symbology specification +- ISO/IEC 15438:2015 Information technology - Automatic identification and + data capture techniques - PDF417 bar code symbology specification +- ISO/IEC 18004:2015 Information technology - Automatic identification and + data capture techniques - QR Code bar code symbology specification +- ISO/IEC 23941:2022 Information technology - Automatic identification and + data capture techniques - Rectangular Micro QR Code (rMQR) bar code + symbology specification +- AIMD/TSC15032-43 (v 0.99c) - International Technical Specification - + Ultracode Symbology (Draft) (Released 4th Nov 2015) + +A number of other specification documents have also been referenced, such as +MIL-STD-1189 Rev. B (1989) (LOGMARS), USPS DMM 300 2006 (2011) (POSTNET, PLANET, +FIM) and USPS-B-3200 (2015) (IMAIL). Those not named include postal and delivery +company references in particular. + +7.5.2 General Standards + +- AIM ITS/04-001 International Technical Standard - Extended Channel + Interpretations Part 1: Identification Schemes and Protocol (Released 24th + May 2004) +- AIM ITS/04-023 International Technical Standard - Extended Channel + Interpretations Part 3: Register (Version 2, February 2022) +- GS1 General Specifications Release 24.0 (Jan 2024) +- ANSI/HIBC 2.6-2016 - The Health Industry Bar Code (HIBC) Supplier Labeling + Standard + +Annex A. Character Encoding + +This section is intended as a quick reference to the character sets used by +Zint. All symbologies use standard ASCII input as shown in section A.1, but some +support extended characters as shown in the subsequent section A.2 Latin +Alphabet No. 1 (ISO/IEC 8859-1). + +A.1 ASCII Standard + +The ubiquitous ASCII standard is well known to most computer users. It’s +reproduced here for reference. + + Hex 0 1 2 3 4 5 6 7 + ----- ----- ----- ------- --- --- --- --- ----- + 0 NUL DLE SPACE 0 @ P ` p + 1 SOH DC1 ! 1 A Q a q + 2 STX DC2 " 2 B R b r + 3 ETX DC3 # 3 C S c s + 4 EOT DC4 $ 4 D T d t + 5 ENQ NAK % 5 E U e u + 6 ACK SYN & 6 F V f v + 7 BEL ETB ' 7 G W g w + 8 BS CAN ( 8 H X h x + 9 TAB EM ) 9 I Y i y + A LF SUB * : J Z j z + B VT ESC + ; K [ k { + C FF FS , < L \ l | + D CR GS - = M ] m } + E SO RS . > N ^ n ~ + F SI US / ? O _ o DEL + + Table : ASCII + +A.2 Latin Alphabet No. 1 (ISO/IEC 8859-1) + +ISO/IEC 8859-1 defines additional characters common in western European +languages like French, German, Italian and Spanish. This extension is the +default encoding of many barcodes (see Table : Default Character Sets) when a +codepoint above hex 9F is encoded. Note that codepoints hex 80 to 9F are not +defined. + + Hex 8 9 A B C D E F + ----- --- --- ------ --- --- --- --- --- + 0 NBSP ° À Ð à ð + 1 ¡ ± Á Ñ á ñ + 2 ¢ ² Â Ò â ò + 3 £ ³ Ã Ó ã ó + 4 ¤ ´ Ä Ô ä ô + 5 ¥ μ Å Õ å õ + 6 ¦ ¶ Æ Ö æ ö + 7 § · Ç × ç ÷ + 8 ¨ ¸ È Ø è ø + 9 © ¹ É Ù é ù + A ª º Ê Ú ê ú + B « » Ë Û ë û + C ¬ ¼ Ì Ü ì ü + D SHY ½ Í Ý í ý + E ® ¾ Î Þ î þ + F ¯ ¿ Ï ß ï ÿ + + Table : ISO/IEC 8859-1 + +Annex B. Qt Backend QZint + +Used internally by Zint Barcode Studio to display the preview, the Qt Backend +QZint renders a barcode by drawing the vector representation (see 5.5 Buffering +Symbols in Memory (vector)) provided by the Zint library libzint. + +The main class is Zint::QZint, which has getter/setter properties that +correspond to the zint_symbol structure (see 5.7 Setting Options), and a main +method render() which takes a Qt QPainter to paint with, and a QRectF +rectangular area specifying where to paint into: + + /* Encode and display barcode in `paintRect` using `painter`. + Note: legacy argument `mode` is not used */ + void render(QPainter& painter, const QRectF& paintRect, + AspectRatioMode mode = IgnoreAspectRatio); + +render() will emit one of two Qt signals - encoded on successful encoding and +drawing, or errored on failure. The client can connect and act appropriately, +for instance: + + connect(qzint, SIGNAL(encoded()), SLOT(on_encoded())); + connect(qzint, SIGNAL(errored()), SLOT(on_errored())); + +where qzint is an instance of Zint::QZint and on_encoded() and on_error() are Qt +slot methods provided by the caller. On error, the error value and message can +be retrieved by the methods getError() and lastError() respectively. + +The other main method is save_to_file(): + + /* Encode and print barcode to file `filename`. + Only sets `getError()` on error, not on warning */ + bool save_to_file(const QString& filename); // `ZBarcode_Print()` + +which takes a filename to output to. It too will emit an errored signal on +failure, returning false (but nothing on success, which just returns true). Note +that rotation is achieved through the setter method setRotateAngleValue() (as +opposed to the rotate_angle argument used by ZBarcode_Print()). + +Various other methods are available, for instance methods for testing symbology +capabilities, and utility methods such as defaultXdim() and getAsCLI(). + +For full details, see "backend_qt/qzint.h". + +Annex C. Tcl Backend Binding + +A Tcl binding is available in the "backend_tcl” sub-directory. To make on Unix: + + cd backend_tcl + autoconf + ./configure + make + sudo make install + +For Windows, a Visual Studio 6.0 project file is available at +"backend_tcl\zint_tcl.dsp". This can also be opened (and converted) by more +modern Visual Studio versions, though some fixing up of the project +configuration will likely be required. + +Once built and installed, invoke the Tcl/Tk CLI "wish": + + wish + +and ignoring the Tk window click back to the command prompt "%" and type: + + require package zint + zint help + +which will show the usage message, with options very similiar to the Zint CLI. +(One notable difference is that boolean options such as -bold take a 1 or 0 as +an argument.) + +A demonstration Tcl/Tk program which is also useful in itself is available at +"backend_tcl/demo/demo.tcl". To run type: + + wish demo/demo.tcl + +which will display the following window. + +[Tcl/Tk demonstration program window] + +You can select the symbology, enter the data to encode, and set options (which +are the same as those given in the usage message). A raster preview of the +configured barcode is displayed once the "Generate" button is pressed. + +Annex D. Man Page ZINT(1) + +% ZINT(1) Version 2.13.0.9 % % December 2024 + +NAME + +zint - encode data as a barcode image + +SYNOPSIS + +zint [-h | --help] +zint [options] + +DESCRIPTION + +zint takes input data from the command line or a file to encode in a barcode +which is then output to an image file. + +Input data is UTF-8, unless --binary is specified. + +Human Readable Text (HRT) is displayed by default for those barcodes that +support HRT, unless --notext is specified. + +The output image file (specified with -o | --output) may be in one of these +formats: Windows Bitmap (BMP), Enhanced Metafile Format (EMF), Encapsulated +PostScript (EPS), Graphics Interchange Format (GIF), ZSoft Paintbrush (PCX), +Portable Network Format (PNG), Scalable Vector Graphic (SVG), or Tagged Image +File Format (TIF). + +OPTIONS + +-h, --help + + Print usage information summarizing command line options. + +-b TYPE, --barcode=TYPE + + Set the barcode symbology that will be used to encode the data. TYPE is the + number or name of the barcode symbology. If not given, the symbology + defaults to 20 (Code 128). To see what types are available, use the -t | + --types option. Type names are case-insensitive, and non-alphanumerics are + ignored. + +--addongap=INTEGER + + For EAN/UPC symbologies, set the gap between the main data and the add-on. + INTEGER is in integral multiples of the X-dimension. The maximum gap that + can be set is 12. The minimum is 7, except for UPC-A, when the minimum is 9. + +--batch + + Treat each line of an input file specified with -i | --input as a separate + data set and produce a barcode image for each one. The barcode images are + outputted by default to numbered filenames starting with “00001.png”, + “00002.png” etc., which can be changed by using the -o | --output option. + +--bg=COLOUR + + Specify a background (paper) colour where COLOUR is in hexadecimal RRGGBB or + RRGGBBAA format or in decimal C,M,Y,K percentages format. + +--binary + + Treat input data as raw 8-bit binary data instead of the default UTF-8. + Automatic code page translation to an ECI page is disabled, and no + validation of the data’s character encoding takes place. + +--bind + + Add horizontal boundary bars (also known as bearer bars) to the symbol. The + width of the boundary bars is specified by the --border option. --bind can + also be used to add row separator bars to symbols stacked with multiple -d | + --data inputs, in which case the width of the separator bars is specified + with the --separator option. + +--bindtop + + Add a horizontal boundary bar to the top of the symbol. The width of the + boundary bar is specified by the --border option. + +--bold + + Use a bold font for the Human Readable Text (HRT). + +--border=INTEGER + + Set the width of boundary bars (--bind or --bindtop) or box borders (--box), + where INTEGER is in integral multiples of the X-dimension. The default is + zero. + +--box + + Add a box around the symbol. The width of the borders is specified by the + --border option. + +--cmyk + + Use the CMYK colour space when outputting to Encapsulated PostScript (EPS) + or TIF files. + +--cols=INTEGER + + Set the number of data columns in the symbol to INTEGER. Affects + Codablock-F, DotCode, GS1 DataBar Expanded Stacked (DBAR_EXPSTK), + MicroPDF417 and PDF417 symbols. + +--compliantheight + + Warn if the height specified by the --height option is not compliant with + the barcode’s specification, or if --height is not given, default to the + height specified by the specification (if any). + +-d, --data=DATA + + Specify the input DATA to encode. The --esc option may be used to enter + non-printing characters using escape sequences. The DATA should be UTF-8, + unless the --binary option is given, in which case it can be anything. + +--direct + + Send output to stdout, which in most cases should be re-directed to a pipe + or a file. Use --filetype to specify output format. + +--dmiso144 + + For Data Matrix symbols, use the standard ISO/IEC codeword placement for 144 + x 144 (--vers=24) sized symbols, instead of the default “de facto” placement + (which rotates the placement of ECC codewords). + +--dmre + + For Data Matrix symbols, allow Data Matrix Rectangular Extended (DMRE) sizes + when considering automatic sizes. See also --square. + +--dotsize=NUMBER + + Set the radius of the dots in dotty mode (--dotty). NUMBER is in + X-dimensions, and may be floating-point. The default is 0.8. + +--dotty + + Use dots instead of squares for matrix symbols. DotCode is always in dotty + mode. + +--dump + + Dump a hexadecimal representation of the symbol’s encodation to stdout. The + same representation may be outputted to a file by using a .txt extension + with -o | --output or by specifying --filetype=txt. + +-e, --ecinos + + Display the table of ECIs (Extended Channel Interpretations). + +--eci=INTEGER + + Set the ECI code for the input data to INTEGER. See -e | --ecinos for a list + of the ECIs available. ECIs are supported by Aztec Code, Code One, Data + Matrix, DotCode, Grid Matrix, Han Xin Code, MaxiCode, MicroPDF417, PDF417, + QR Code, rMQR and Ultracode. + +--embedfont + + For vector output, embed the font in the file for portability. Currently + only available for SVG output. + +--esc + + Process escape characters in the input data. The escape sequences are: + + \0 (0x00) NUL Null character + \E (0x04) EOT End of Transmission + \a (0x07) BEL Bell + \b (0x08) BS Backspace + \t (0x09) HT Horizontal Tab + \n (0x0A) LF Line Feed + \v (0x0B) VT Vertical Tab + \f (0x0C) FF Form Feed + \r (0x0D) CR Carriage Return + \e (0x1B) ESC Escape + \G (0x1D) GS Group Separator + \R (0x1E) RS Record Separator + \\ (0x5C) \ Backslash + \dNNN (NNN) Any 8-bit character where NNN is + decimal (000-255) + \oNNN (0oNNN) Any 8-bit character where NNN is + octal (000-377) + \xNN (0xNN) Any 8-bit character where NN is + hexadecimal (00-FF) + \uNNNN (U+NNNN) Any 16-bit Unicode BMP character + where NNNN is hexadecimal + \UNNNNNN (U+NNNNNN) Any 21-bit Unicode character + where NNNNNN is hexadecimal + +--extraesc + + For Code 128 only, as well as processing the normal escape sequences above, + process the special escape sequences \^A, \^B, \^C and \^@ that allow manual + switching of Code Sets, and the special escape sequence \^1 that inserts an + FNC1 character. The sequence \@ turns off manual switching. The sequence \^^ + can be used to encode data that contains special escape sequences. + +--fast + + Use faster if less optimal encodation or other shortcuts (affects Data + Matrix, MicroPDF417, PDF417, QRCODE & UPNQR only). + +--fg=COLOUR + + Specify a foreground (ink) colour where COLOUR is in hexadecimal RRGGBB or + RRGGBBAA format or in decimal C,M,Y,K percentages format. + +--filetype=TYPE + + Set the output file type to TYPE, which is one of BMP, EMF, EPS, GIF, PCX, + PNG, SVG, TIF, TXT. + +--fullmultibyte + + Use the multibyte modes of Grid Matrix, Han Xin and QR Code for non-ASCII + data. + +--gs1 + + Treat input as GS1 compatible data. Application Identifiers (AIs) should be + placed in square brackets "[]" (but see --gs1parens). + +--gs1nocheck + + Do not check the validity of GS1 data. + +--gs1parens + + Process parentheses "()" as GS1 AI delimiters, rather than square brackets + "[]". The input data must not otherwise contain parentheses. + +--gssep + + For Data Matrix in GS1 mode, use GS (0x1D) as the GS1 data separator instead + of FNC1. + +--guarddescent=NUMBER + + For EAN/UPC symbols, set the height the guard bars descend below the main + bars, where NUMBER is in X-dimensions. NUMBER may be floating-point. + +--guardwhitespace + + For EAN/UPC symbols, add quiet zone indicators "<" and/or ">" to HRT where + applicable. + +--height=NUMBER + + Set the height of the symbol in X-dimensions. NUMBER may be floating-point. + +--heightperrow + + Treat height as per-row. Affects Codablock-F, Code 16K, Code 49, GS1 DataBar + Expanded Stacked (DBAR_EXPSTK), MicroPDF417 and PDF417. + +-i, --input=FILE + + Read the input data from FILE. Specify a single hyphen (-) for FILE to read + from stdin. + +--init + + Create a Reader Initialisation (Programming) symbol. + +--mask=INTEGER + + Set the masking pattern to use for DotCode, Han Xin or QR Code to INTEGER, + overriding the automatic selection. + +--mirror + + Use the batch data to determine the filename in batch mode (--batch). The -o + | --output option can be used to specify an output directory (any filename + will be ignored). + +--mode=INTEGER + + For MaxiCode and GS1 Composite symbols, set the encoding mode to INTEGER. + + For MaxiCode (SCM is Structured Carrier Message, with 3 fields: postcode, + 3-digit ISO 3166-1 country code, 3-digit service code): + + 2 SCM with 9-digit numeric postcode + 3 SCM with 6-character alphanumeric postcode + 4 Enhanced ECC for the primary part of the message + 5 Enhanced ECC for all of the message + 6 Reader Initialisation (Programming) + + For GS1 Composite symbols (names end in _CC, i.e. EANX_CC, GS1_128_CC, + DBAR_OMN_CC etc.): + + 1 CC-A + 2 CC-B + 3 CC-C (GS1_128_CC only) + +--nobackground + + Remove the background colour (EMF, EPS, GIF, PNG, SVG and TIF only). + +--noquietzones + + Disable any quiet zones for symbols that define them by default. + +--notext + + Remove the Human Readable Text (HRT). + +-o, --output=FILE + + Send the output to FILE. When not in batch mode, the default is “out.png” + (or “out.gif” if zint built without PNG support). When in batch mode + (--batch), special characters can be used to format the output filenames: + + ~ Insert a number or 0 + # Insert a number or space + @ Insert a number or * (+ on Windows) + Any other Insert literally + +--primary=STRING + + For MaxiCode, set the content of the primary message. For GS1 Composite + symbols, set the content of the linear symbol. + +--quietzones + + Add compliant quiet zones for symbols that specify them. This is in addition + to any whitespace specified by -w | --whitesp or --vwhitesp. + +-r, --reverse + + Reverse the foreground and background colours (white on black). Known as + “reflectance reversal” or “reversed reflectance”. + +--rotate=INTEGER + + Rotate the symbol by INTEGER degrees, where INTEGER can be 0, 90, 270 or + 360. + +--rows=INTEGER + + Set the number of rows for Codablock-F or PDF417 to INTEGER. It will also + set the minimum number of rows for Code 16K or Code 49, and the maximum + number of rows for GS1 DataBar Expanded Stacked (DBAR_EXPSTK). + +--scale=NUMBER + + Adjust the size of the X-dimension. NUMBER may be floating-point, and is + multiplied by 2 (except for MaxiCode) before being applied. The default + scale is 1. + + For MaxiCode, the scale is multiplied by 10 for raster output, by 40 for EMF + output, and by 2 otherwise. + + Increments of 0.5 (half-integers) are recommended for non-MaxiCode raster + output (BMP, GIF, PCX, PNG and TIF). + + See also --scalexdimdp below. + +--scalexdimdp=X[,R] + + Scale the image according to X-dimension X and resolution R, where X is in + mm and R is in dpmm (dots per mm). X and R may be floating-point. R is + optional and defaults to 12 dpmm (approximately 300 dpi). X may be zero in + which case a symbology-specific default is used. + + The scaling takes into account the output filetype, and deals with all the + details mentioned above. Units may be specified for X by appending “in” + (inch) or “mm”, and for R by appending “dpi” (dots per inch) or “dpmm” - + e.g. --scalexdimdp=0.013in,300dpi. + +--scmvv=INTEGER + + For MaxiCode, prefix the Structured Carrier Message (SCM) with + "[)>\R01\Gvv", where vv is a 2-digit INTEGER. + +--secure=INTEGER + + Set the error correction level (ECC) to INTEGER. The meaning is specific to + the following matrix symbols (all except PDF417 are approximate): + + Aztec Code 1 to 4 (10%, 23%, 36%, 50%) + Grid Matrix 1 to 5 (10% to 50%) + Han Xin 1 to 4 (8%, 15%, 23%, 30%) + Micro QR 1 to 3 (7%, 15%, 25%) (L, M, Q) + PDF417 0 to 8 (2^(INTEGER + 1) codewords) + QR Code 1 to 4 (7%, 15%, 25%, 30%) (L, M, Q, H) + rMQR 2 or 4 (15% or 30%) (M or H) + Ultracode 1 to 6 (0%, 5%, 9%, 17%, 25%, 33%) + +--segN=ECI,DATA + + Set the ECI & DATA content for segment N, where N is 1 to 9. -d | --data + must still be given, and counts as segment 0, its ECI given by --eci. + Segments must be consecutive. + +--separator=INTEGER + + Set the height of row separator bars for stacked symbologies, where INTEGER + is in integral multiples of the X-dimension. The default is zero. + +--small + + Use a smaller font for Human Readable Text (HRT). + +--square + + For Data Matrix symbols, exclude rectangular sizes when considering + automatic sizes. See also --dmre. + +--structapp=I,C[,ID] + + Set Structured Append info, where I is the 1-based index, C is the total + number of symbols in the sequence, and ID, which is optional, is the + identifier that all symbols in the sequence share. Structured Append is + supported by Aztec Code, Code One, Data Matrix, DotCode, Grid Matrix, + MaxiCode, MicroPDF417, PDF417, QR Code and Ultracode. + +-t, --types + + Display the table of barcode types (symbologies). The numbers or names can + be used with -b | --barcode. + +--textgap=NUMBER + + Adjust the gap between the barcode and the Human Readable Text (HRT). NUMBER + is in X-dimensions, and may be floating-point. Maximum is 10 and minimum is + -5. The default is 1. + +--vers=INTEGER + + Set the symbol version (size, check digits, other options) to INTEGER. The + meaning is symbol-specific. + + For most matrix symbols, it specifies size: + + Aztec Code 1 to 36 (1 to 4 compact) + 1 15x15 13 53x53 25 105x105 + 2 19x19 14 57x57 26 109x109 + 3 23x23 15 61x61 27 113x113 + 4 27x27 16 67x67 28 117x117 + 5 19x19 17 71x71 29 121x121 + 6 23x23 18 75x75 30 125x125 + 7 27x27 19 79x79 31 131x131 + 8 31x31 20 83x83 32 135x135 + 9 37x37 21 87x87 33 139x139 + 10 41x41 22 91x91 34 143x143 + 11 45x45 23 95x95 35 147x147 + 12 49x49 24 101x101 36 151x151 + + Code One 1 to 10 (9 and 10 variable width) (WxH) + 1 16x18 6 70x76 + 2 22x22 7 104x98 + 3 28x28 8 148x134 + 4 40x42 9 Wx8 + 5 52x54 10 Wx16 + + Data Matrix 1 to 48 (31 to 48 DMRE) (HxW) + 1 10x10 17 72x72 33 8x80 + 2 12x12 18 80x80 34 8x96 + 3 14x14 19 88x88 35 8x120 + 4 16x16 20 96x96 36 8x144 + 5 18x18 21 104x104 37 12x64 + 6 20x20 22 120x120 38 12x88 + 7 22x22 23 132x132 39 16x64 + 8 24x24 24 144x144 40 20x36 + 9 26x26 25 8x18 41 20x44 + 10 32x32 26 8x32 42 20x64 + 11 36x36 28 12x26 43 22x48 + 12 40x40 28 12x36 44 24x48 + 13 44x44 29 16x36 45 24x64 + 14 48x48 30 16x48 46 26x40 + 15 52x52 31 8x48 47 26x48 + 16 64x64 32 8x64 48 26x64 + + Grid Matrix 1 to 13 + 1 18x18 6 78x78 11 138x138 + 2 30x30 7 90x90 12 150x150 + 3 42x42 8 102x102 13 162x162 + 4 54x54 9 114x114 + 5 66x66 10 126x126 + + Han Xin 1 to 84 + 1 23x23 29 79x79 57 135x135 + 2 25x25 30 81x81 58 137x137 + 3 27x27 31 83x83 59 139x139 + 4 29x29 32 85x85 60 141x141 + 5 31x31 33 87x87 61 143x143 + 6 33x33 34 89x89 62 145x145 + 7 35x35 35 91x91 63 147x147 + 8 37x37 36 93x93 64 149x149 + 9 39x39 37 95x95 65 151x151 + 10 41x41 38 97x97 66 153x153 + 11 43x43 39 99x99 67 155x155 + 12 45x45 40 101x101 68 157x157 + 13 47x47 41 103x103 69 159x159 + 14 49x49 42 105x105 70 161x161 + 15 51x51 43 107x107 71 163x163 + 16 53x53 44 109x109 72 165x165 + 17 55x55 45 111x111 73 167x167 + 18 57x57 46 113x113 74 169x169 + 19 59x59 47 115x115 75 171x171 + 20 61x61 48 117x117 76 173x173 + 21 63x63 49 119x119 77 175x175 + 22 65x65 50 121x121 78 177x177 + 23 67x67 51 123x123 79 179x179 + 24 69x69 52 125x125 80 181x181 + 25 71x71 53 127x127 81 183x183 + 26 73x73 54 129x129 82 185x185 + 27 75x75 55 131x131 83 187x187 + 28 77x77 56 133x133 84 189x189 + + Micro QR 1 to 4 (M1, M2, M3, M4) + 1 11x11 3 15x15 + 2 13x13 4 17x17 + + QR Code 1 to 40 + 1 21x21 15 77x77 29 133x133 + 2 25x25 16 81x81 30 137x137 + 3 29x29 17 85x85 31 141x141 + 4 33x33 18 89x89 32 145x145 + 5 37x37 19 93x93 33 149x149 + 6 41x41 20 97x97 34 153x153 + 7 45x45 21 101x101 35 157x157 + 8 49x49 22 105x105 36 161x161 + 9 53x53 23 109x109 37 165x165 + 10 57x57 24 113x113 38 169x169 + 11 61x61 25 117x117 39 173x173 + 12 65x65 26 121x121 40 177x177 + 13 69x69 27 125x125 + 14 73x73 28 129x129 + + rMQR 1 to 38 (33 to 38 automatic width) (HxW) + 1 7x43 14 11x77 27 15x139 + 2 7x59 15 11x99 28 17x43 + 3 7x77 16 11x139 29 17x59 + 4 7x99 17 13x27 30 17x77 + 5 7x139 18 13x43 31 17x99 + 6 9x43 19 13x59 32 17x139 + 7 9x59 20 13x77 33 7xW + 8 9x77 21 13x99 34 9xW + 9 9x99 22 13x139 35 11xW + 10 9x139 23 15x43 36 13xW + 11 11x27 24 15x59 37 15xW + 12 11x43 25 15x77 38 17xW + 13 11x59 26 15x99 + + For a number of linear symbols, it specifies check character options (“hide” + or “hidden” means don’t show in HRT, “visible” means do display in HRT): + + C25IATA 1 or 2 (add visible or hidden check digit) + C25IND ditto + C25INTER ditto + C25LOGIC ditto + C25STANDARD ditto + Codabar 1 or 2 (add hidden or visible check digit) + Code 11 0 to 2 (2 visible check digits to none) + 0 (default 2 visible check digits) + 1 (1 visible check digit) + 2 (no check digits) + Code 39 1 or 2 (add visible or hidden check digit) + Code 93 1 (hide the default check characters) + EXCODE39 1 or 2 (add visible or hidden check digit) + LOGMARS 1 or 2 (add visible or hidden check digit) + MSI Plessey 0 to 6 (none to various visible options) + 1, 2 (mod-10, mod-10 + mod-10) + 3, 4 (mod-11 IBM, mod-11 IBM + mod-10) + 5, 6 (mod-11 NCR, mod-11 NCR + mod-10) + +10 (hide) + + For a few other symbologies, it specifies other characteristics: + + Channel Code 3 to 8 (no. of channels) + DAFT 50 to 900 (permille tracker ratio) + DPD 1 (relabel) + PZN 1 (PZN7 instead of default PZN8) + Ultracode 2 (revision 2) + VIN 1 (add international prefix) + +-v, --version + + Display zint version. + +--vwhitesp=INTEGER + + Set the height of vertical whitespace above and below the barcode, where + INTEGER is in integral multiples of the X-dimension. + +-w, --whitesp=INTEGER + + Set the width of horizontal whitespace either side of the barcode, where + INTEGER is in integral multiples of the X-dimension. + +--werror + + Convert all warnings into errors. + +EXIT STATUS + +0 + Success (including when given informational options -h | --help, -e | + --ecinos, -t | --types, -v | --version). + +1 + Human Readable Text was truncated (maximum 199 bytes) + (ZINT_WARN_HRT_TRUNCATED) + +2 + Invalid option given but overridden by Zint (ZINT_WARN_INVALID_OPTION) + +3 + Automatic ECI inserted by Zint (ZINT_WARN_USES_ECI) + +4 + Symbol created not compliant with standards (ZINT_WARN_NONCOMPLIANT) + +5 + Input data wrong length (ZINT_ERROR_TOO_LONG) + +6 + Input data incorrect (ZINT_ERROR_INVALID_DATA) + +7 + Input check digit incorrect (ZINT_ERROR_INVALID_CHECK) + +8 + Incorrect option given (ZINT_ERROR_INVALID_OPTION) + +9 + Internal error (should not happen) (ZINT_ERROR_ENCODING_PROBLEM) + +10 + Error opening output file (ZINT_ERROR_FILE_ACCESS) + +11 + Memory allocation (malloc) failure (ZINT_ERROR_MEMORY) + +12 + Error writing to output file (ZINT_ERROR_FILE_WRITE) + +13 + Error counterpart of warning if --werror given (ZINT_ERROR_USES_ECI) + +14 + Error counterpart of warning if --werror given (ZINT_ERROR_NONCOMPLIANT) + +15 + Error counterpart of warning if --werror given (ZINT_ERROR_HRT_TRUNCATED) + +EXAMPLES + +Create “out.png” (or “out.gif” if zint built without PNG support) in the current +directory, as a Code 128 symbol. + + zint -d 'This Text' + +Create “qr.svg” in the current directory, as a QR Code symbol. + + zint -b QRCode -d 'This Text' -o 'qr.svg' + +Use batch mode to read from an input file “ean13nos.txt” containing a list of +13-digit GTINs, each on a separate line, to create a series of EAN-13 barcodes, +formatting the output filenames to “ean001.gif”, “ean002.gif” etc. using the +special character “~”. + + zint -b EANX --batch -i 'ean13nos.txt' -o 'ean~~~.gif' + +BUGS + +Please send bug reports to https://sourceforge.net/p/zint/tickets/. + +SEE ALSO + +Full documention for zint (and the API libzint and the GUI zint-qt) is available +from + + https://zint.org.uk/manual/ + +and at + + https://sourceforge.net/p/zint/docs/manual.txt + +CONFORMING TO + +Zint is designed to be compliant with a number of international standards, +including: + +ISO/IEC 24778:2008, ANSI/AIM BC12-1998, EN 798:1996, AIM ISS-X-24 (1995), +ISO/IEC 15417:2007, EN 12323:2005, ISO/IEC 16388:2007, ANSI/AIM BC6-2000, +ANSI/AIM BC5-1995, AIM USS Code One (1994), ISO/IEC 16022:2006, ISO/IEC +21471:2019, ISO/IEC 15420:2009, AIMD014 (v 1.63) (2008), ISO/IEC 24723:2010, +ISO/IEC 24724:2011, ISO/IEC 20830:2021, ISO/IEC 16390:2007, ISO/IEC 16023:2000, +ISO/IEC 24728:2006, ISO/IEC 15438:2015, ISO/IEC 18004:2015, ISO/IEC 23941:2022, +AIM ITS/04-023 (2022) + +COPYRIGHT + +Copyright © 2024 Robin Stuart. Released under GNU GPL 3.0 or later. + +AUTHOR + +Robin Stuart robin@zint.org.uk + +[1] See the Homebrew website https://brew.sh. + +[2] In Unicode contexts, BMP stands for Basic Multilingual Plane, the plane 0 +codeset from U+0000 to U+D7FF and U+E000 to U+FFFF (i.e. excluding surrogates). +Not to be confused with the Windows Bitmap file format BMP! + +[3] The symbologies marked with an asterisk (*) in Table +: Barcode Types (Symbologies) above used different names in Zint before version +2.9.0. For example, symbology 29 used the name BARCODE_RSS14. These names are +now deprecated but are still recognised by Zint and will continue to be +supported in future versions. + +[4] The background is omitted for vector outputs EMF, EPS and SVG when +--nobackground is given. For raster outputs GIF, PCX, PNG and TIF, the +background’s alpha channel is set to zero (fully transparent). + +[5] Shift JIS (JIS X 0201 Roman) re-maps two ASCII characters: backslash (\) to +the yen sign (¥), and tilde (~) to overline (U+203E). + +[6] ISO/IEC 646 Invariant is a subset of ASCII with 12 characters undefined: #, +$, @, [, \, ], ^, `, {, |, }, ~. + +[7] BARCODE_MEMORY_FILE textual formats EPS and SVG will have Unix newlines (LF) +on both Windows and Unix, i.e. not CR+LF on Windows. + +[8] The height value is ignored for Aztec (including HIBC and Aztec Rune), Code +One, Data Matrix (including HIBC), DotCode, Grid Matrix, Han Xin, MaxiCode, QR +Code (including HIBC, Micro QR, rMQR and UPNQR), and Ultracode - all of which +have a fixed width-to-height ratio (or, in the case of Code One, a fixed +height). + +[9] For Windows, outfile is assumed to be UTF-8 encoded. + +[10] The BARCODE_BIND_TOP flag is set by default for DPD - see 6.1.10.7 DPD +Code. + +[11] The BARCODE_BIND flag is always set for Codablock-F, Code 16K and Code 49. +Special considerations apply to ITF-14 - see 6.1.2.6 ITF-14. + +[12] Codablock-F, Code 16K, Code 49, EAN-2 to EAN-13, ISBN, ITF-14, UPC-A and +UPC-E have compliant quiet zones added by default. + +[13] ZINT_CAP_EANUPC was previously named ZINT_CAP_EXTENDABLE, which is still +recognised. + +[14] BARCODE_CODE128AB previously used the name BARCODE_CODE128B, which is still +recognised. + +[15] The DX Number may be looked up in The (Modified) Big Film Database at +https://thebigfilmdatabase.merinorus.com.