Mercurial > hgrepos > Python2 > PyMuPDF
diff mupdf-source/thirdparty/zint/docs/manual.pmd @ 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.pmd Mon Sep 15 11:43:07 2025 +0200 @@ -0,0 +1,5067 @@ +% Zint Barcode Generator and Zint Barcode Studio User Manual +% Version 2.13.0.9 +% December 2024 + +# 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: + +```bash +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 + +```bash +git clone https://git.code.sf.net/p/zint/code zint +``` + +and follow these steps in the top directory: + +```bash +mkdir build +cd build +cmake .. +make +sudo make install +``` + +The CLI command line program can be accessed by typing + +```bash +zint [options] +``` + +The GUI can be accessed by typing + +```bash +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 + +```bash +./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: + +```bash +su +pkg install zint +exit +``` + +and on OpenBSD (where the GUI is in a separate `zint-gui` package): + +```bash +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 + +```bash +/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 + +```bash +brew install zint +``` + +To build from source (and install the GUI) see `"README.macos"` in the project +root directory. + +[^1]: See the Homebrew website [https://brew.sh](https://brew.sh). + +## 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 + +```bash +zint-qt +``` + +or on Windows + +```bash +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 + +{.win} + +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 +{.btn} 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 +{.btn} 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. + +{.win} + +## 3.2 GS1 Composite Groupbox + +{.win} + +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 + +{.win} + +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 + +{.win} + +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 + +{.win} + +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 + +{.win} + +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 {.btn} icon to invoke the Set +Printing Scale Dialog - see [4.9 Adjusting Image Size (X-dimension)] for further +details. + +{.pop} + +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 {.btn} +and background eye {.btn} buttons which invoke a +colour picker. + +{.pop} + +(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 +{.btn} button next to it. + +## 3.7 Data Dialog + +{.pop} + +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 + +{.pop} + +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: {#tbl:sequence_format_characters tag=": 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 + +{.pop} + +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 + +{.pop} + +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.: + +```bash +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: + +```bash +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: + +```bash +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 + +```bash +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: {#tbl:escape_sequences tag=": Escape Sequences"} + +[^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! + +(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. + +```bash +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: + +```bash +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: + +```bash +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: {#tbl:output_file_formats tag=": Output File Formats"} + +The filename can contain directories and sub-directories also, which will be +created if they don't already exist: + +```bash +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: + +```bash +zint -b 71 -o datamatrix.png -d "Data to encode" +``` + +or + +```bash +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: {#tbl:barcode_types tag=": Barcode Types (Symbologies)"} + +[^3]: The symbologies marked with an asterisk (`*`) in Table +{@tbl:barcode_types} 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.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: + +```bash +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 + +```bash +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: + +```bash +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 + +```bash +zint -b PDF417 -d "This Text" --height=4 --heightperrow +``` + +{.lin} + +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: + +```bash +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: + +```bash +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: + +```bash +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: + +```bash +zint --box --border=10 -w 10 -d "This Text" +``` + +{.lin} + +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. + +{.i2d} + +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 + +```bash +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 + +```bash +zint --fg=00FF00 -d "This Text" +``` + +alters the symbol to a bright green. + +{.lin} + +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: + +```bash +zint --fg=00ff0055 -d "This Text" +``` + +{.lin} + +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 + +```bash +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]: 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). + +## 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 +``` + +{.lin} + +\clearpage + +## 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: {#tbl:scaling_multiplers tag=": 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 + +```bash +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: + +```bash +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: + +```bash +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 + +```bash +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: + +```bash +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. + +{.lin} + +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: + +{.lin} + +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: + +{.lin} + +## 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: {#tbl:default_character_sets tag=": Default Character Sets"} + +[^5]: Shift JIS (JIS X 0201 Roman) re-maps two ASCII characters: backslash (`\`) +to the yen sign (¥), and tilde (`~`) to overline (U+203E). + +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 +{@tbl: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: {#tbl:eci_aware_symbologies tag=": 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: {#tbl:eci_codes tag=": ECI Codes"} + +[^6]: ISO/IEC 646 Invariant is a subset of ASCII with 12 characters undefined: +`#`, `$`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `|`, `}`, `~`. + +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 @tbl: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: + +```bash +zint -b 71 --scale=10 --eci=17 -i utf8euro.txt +``` + +This is equivalent to the commands (using the `--esc` switch): + +```bash +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: + +```bash +zint -b 71 --scale=10 --eci=17 -d "€" +``` + +{.i2d} + +#### 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: + +```bash +zint -b 71 --scale=10 --eci=28 --binary -i big5char.txt +``` + +This is equivalent to the command (using the `--esc` switch): + +```bash +zint -b 71 --scale=10 --eci=28 --binary --esc -d "\xB1\x60" +``` + +and to the commands (no `--binary` switch so conversion occurs): + +```bash +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 "常" +``` + +{.i2d} + +#### 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: + +```bash +zint -b 58 --binary -d "UTF-8 data" +``` + +{.i2d} + +## 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 + +```bash +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: {#tbl:batch_filename_formatting tag=": Batch Filename Formatting"} + +For instance + +```bash +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: {#tbl:batch_filename_examples tag=": 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: {#tbl:batch_dir_examples tag=": 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: + +```bash +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 {@tbl: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. + +{.dotty} + +## 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 {@tbl: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 + +```bash +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 +{@tbl:eci_aware_symbologies}). + +{.i2d} + +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] +``` + +{.i2d} + +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: + +```c +#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: + +```bash +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: + +```c +#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: + +```c +#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: + +```c +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: + +```c +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: + +```c +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: + +```c +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: + +```c +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: + +```c +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: + +```c +#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. + +[^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. + +## 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 1.0 + adjusting size of image + (sets X-dimension). + +`whitespace_width` integer Horizontal whitespace 0 + width in X-dimensions. + +`whitespace_height` integer Vertical whitespace 0 + height 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) `"000000"` + string colour as RGB/RGBA + hexadecimal string or + `"C,M,Y,K"` decimal + percentages string, with + a terminating `NUL`. + +`bgcolour` character Background (paper) `"ffffff"` + string colour 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 count 0 + Append a 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, `""` (empty) + character which usually consists of (output only) + string input data plus one more + check digit. Uses UTF-8 + formatting, with a + terminating `NUL`. + +`rows` integer Number of rows used by (output only) + the 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 (output only) + string event 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 + character Buffering Symbols in + array Memory (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 + character channel of stored bitmap + array image (or `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 (output only) + unsigned file buffer if + character `BARCODE_MEMORY_FILE` + array set in `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` {#tbl:api_structure_zint_symbol tag="$ $"} + +[^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. + +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. + +```c +#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: + +```c + 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: {#tbl:api_warnings_errors tag=": API Warning and Error Return Values"} + +To catch errors use an integer variable as shown in the code below: + +```c +#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 +{@tbl:barcode_types}. For example + +```c +symbol->symbology = BARCODE_LOGMARS; +``` + +means the same as + +```c +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: + +```c +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 {#tbl:api_output_options tag="$ $"} + +[^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. + +## 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 {#tbl:api_input_mode tag="$ $"} + +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 + +```c +my_symbol->input_mode = UNICODE_MODE | ESCAPE_MODE; +``` + +or + +```c +my_symbol->input_mode = GS1_MODE | GS1PARENS_MODE | GS1NOCHECK_MODE; +``` + +whereas + +```c +my_symbol->input_mode = DATA_MODE | GS1_MODE; +``` + +is not valid. + +Permissible escape sequences (`ESCAPE_MODE`) are listed in Table +{@tbl: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: + +```c +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: + +```c +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 {@tbl:eci_aware_symbologies}). For +example: + +```c +#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: + +```c +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: + +```c +/* 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: + +```c +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: + +```c +if (ZBarcode_ValidID(BARCODE_PDF417) != 0) { + printf("PDF417 available\n"); +} else { + printf("PDF417 not available\n"); +} +``` + +Another function that may be useful is: + +```c +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: + +```c +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: + +```c +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: {#tbl:api_cap tag=": API Capability Flags"} + +[^13]: `ZINT_CAP_EANUPC` was previously named `ZINT_CAP_EXTENDABLE`, which is +still recognised. + +For example: + +```c +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: + +```c +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: + +```c +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 + +{.lin} + +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 + +{.lin} + +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 + +{.lin} + +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 + +{.lin} + +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) + +{.lin} + +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 + +{.lin} + +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 + +{.lin} + +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. + +{.lin} + +#### 6.1.2.7 Deutsche Post Leitcode + +{.lin} + +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 + +{.lin} + +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. + +\clearpage + +### 6.1.3 UPC (Universal Product Code) (ISO 15420) + +#### 6.1.3.1 UPC Version A + +{.upcean} + +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: + +```bash +zint -b UPCA -d "72527270270+12345" +``` + +or using the API encode a data string with the + character included: + +```c +my_symbol->symbology = BARCODE_UPCA; +error = ZBarcode_Encode_and_Print(my_symbol, "72527270270+12345", 0, 0); +``` + +{.upcean} + +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: + +```bash +zint -b UPCA -d "72527270270+12345" --guardwhitespace +``` + +or using the API: + +```c +my_symbol->symbology = BARCODE_UPCA; +my_symbol->output_options |= EANUPC_GUARD_WHITESPACE; +error = ZBarcode_Encode_and_Print(my_symbol, "72527270270+12345", 0, 0); +``` + +{.upcean} + +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 + +{.upcean} + +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: + +```bash +zint -b UPCE -d "1123456" +``` + +or + +```c +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`): + +```bash +zint -b UPCE -d "1123456+12" --guardwhitespace +``` + +{.upcean} + +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 + +{.upcean} + +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: + +```bash +zint -b EANX -d "54321" +``` + +{.upcean} + +will encode a stand-alone EAN-5, whereas + +```bash +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: + +```c +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); +``` + +{.upcean} + +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: + +```bash +zint -b EANX_CHK -d "74323654" --guardwhitespace +``` + +{.upcean} + +#### 6.1.4.2 SBN, ISBN and ISBN-13 + +{.upcean} + +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`: + +{.upcean} + +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 + +{.lin} + +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 + +{.lin} + +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: {#tbl:msi_plessey_check_digits tag=": 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 + +{.lin} + +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 + +{.lin} + +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) + +{.lin} + +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`). + +\clearpage + +#### 6.1.7.2 Extended Code 39 + +{.lin} + +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 + +{.lin} + +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) + +{.lin} + +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 + +{.lin} + +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 + +{.lin} + +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 + +{.lin} + +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) + +{.lin} + +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) + +{.lin} + +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 + +{.lin} + +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) + +{.lin} + +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): + +```bash +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 + +```bash +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 + +```bash +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) + +{.lin} + +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). + +[^14]: `BARCODE_CODE128AB` previously used the name `BARCODE_CODE128B`, which is +still recognised. + +#### 6.1.10.3 GS1-128 + +![`zint -b GS1_128 --compliantheight -d +"[01]98898765432106[3202]012345[15]991231"`](images/gs1_128.svg){.lin} + +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: + +```bash +zint -b 16 -d "[01]98898765432106[3202]012345[15]991231" +``` + +or using the `--gs1parens` option: + +```bash +zint -b 16 --gs1parens -d "(01)98898765432106(3202)012345(15)991231" +``` + +#### 6.1.10.4 EAN-14 + +{.lin} + +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) + +{.lin} + +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 + +{.lin} + +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 + +{.lin} + +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 TTTTTTTTTTTTTT SSS CCC +(7 alphanumerics) (14 alphanumerics) (3 digits) (3-digit ISO 3166-1) +----------------------------------------------------------------------- + +Table: {#tbl:dpd_input_fields tag=": 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. + +\clearpage + +#### 6.1.10.8 UPU S10 + +{.lin} + +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 + +{.lin} + +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. + +{.lin} + +#### 6.1.11.2 GS1 DataBar Limited + +{.lin} + +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"`](images/dbar_exp.svg){.lin} + +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: + +```bash +zint -b 31 -d "[01]98898765432106[3202]012345[15]991231" +``` + +### 6.1.12 Korea Post Barcode + +{.lin} + +The Korean Postal Barcode is used to encode a 6-digit number and includes one +check digit. + +### 6.1.13 Channel Code + +{.lin} + +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: {#tbl:channel_maxima tag=": Channel Value Ranges"} + +### 6.1.14 BC412 (SEMI T1-95) + +{.lin} + +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. + +\clearpage + +## 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 + +```bash +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: + +```c +my_symbol->symbology = BARCODE_CODE128; + +error = ZBarcode_Encode(my_symbol, "This", 0); + +error = ZBarcode_Encode(my_symbol, "That", 0); + +error = ZBarcode_Print(my_symbol); +``` + +{.lin} + +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`): + +```bash +zint --bind --notext --separator=2 -d "This" -d "That" +``` + +{.lin} + +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 + +{.lin} + +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) + +{.lin} + +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) + +{.lin} + +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) + +{.lin} + +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) + +{.lin} + +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 + +{.lin} + +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 + +{.lin} + +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]991231"`](images/dbar_expstk.svg){.lin} + +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 + +{.lin} + +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. + +\clearpage + +## 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: {#tbl:composite_symbologies tag=": 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: + +```bash +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][6.3.1 CC-A]) component with the data `"(99)1234-abcd"`. The +same results can be achieved using the API as shown below: + +```c +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=331234567890`](images/eanx_cc_a.svg){.upcean} + +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=331234567890`](images/eanx_cc_b.svg){.upcean} + +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"`](images/gs1_128_cc_c.svg){.upcean} + +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`). + +\clearpage + +## 6.4 Two-Track Symbols + +### 6.4.1 Two-Track Pharmacode + +{.trk} + +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 + +{.trk} + +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 + +{.trk} + +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 + +{.trk} + +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 + +{.trk} + +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. + +[^15]: The DX Number may be looked up in The (Modified) Big Film Database at +[https://thebigfilmdatabase.merinorus.com]( +https://thebigfilmdatabase.merinorus.com). + +\clearpage + +## 6.5 4-State Postal Codes + +### 6.5.1 Australia Post 4-State Symbols + +#### 6.5.1.1 Customer Barcodes + +{.trk} + +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: {#tbl:auspost_input_formats tag=": Australia Post Input Formats"} + +#### 6.5.1.2 Reply Paid Barcode + +{.trk} + +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 + +{.trk} + +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 + +{.trk} + +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 + +{.trk} + +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) + +{.trk} + +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 + +{.trk} + +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: {#tbl:mailmark_4s_input_fields +tag=": 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: {#tbl:mailmark_destination_dps +tag=": 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 + +{.trk} + +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 + +{.trk} + +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 + +{.trk} + +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 + +```bash +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 + +```bash +zint -b RM4SCC --compliantheight -d "W1J0TR01" +``` + +\clearpage + +## 6.6 Matrix Symbols + +### 6.6.1 Data Matrix (ISO 16022) + +{.i2dbig} + +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: {#tbl:datamatrix_sizes tag=": 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: {#tbl:dmre_sizes tag=": 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) + +{.i2dbig} + +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: {#tbl:mailmark_2d_input_fields +tag=": 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 +{@tbl:mailmark_destination_dps}. 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: {#tbl:mailmark_2d_rts +tag=": 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: {#tbl:mailmark_2d_sizes tag=": 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) + +{.i2dbig} + +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: {#tbl:qrcode_eccs tag=": 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: {#tbl:qrcode_sizes tag=": 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 +```c +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) + +{.i2dbig} + +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: {#tbl:micrqr_sizes tag=": 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: {#tbl:micrqr_eccs tag=": 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 +```c +option_3 = ZINT_FULL_MULTIBYTE | (N + 1) << 8 +``` + +### 6.6.5 Rectangular Micro QR Code (rMQR) (ISO 23941) + +{.i2dbig} + +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: {#tbl:rmqr_eccs tag=": 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: {#tbl:rmqr_sizes tag=": 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) + +{.i2d} + +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: + +```bash +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) + +{.i2d} + +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: {#tbl:maxicode_scm tag=": 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: + +```bash +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): + +```bash +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 {@tbl: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: + +```bash +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: {#tbl:maxicode_data_length_maxima tag=": 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) + +{.i2d} + +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: {#tbl:aztec_sizes tag=": 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: {#tbl:aztec_eccs tag=": 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) + +{.i2d} + +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 + +{.i2d} + +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 Numeric Alphanumeric + (W x H) Data 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: {#tbl:codeone_sizes tag=": 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 + +{.i2d} + +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: {#tbl:gridmatrix_sizes tag=": Grid Matrix Sizes"} + +Mode Error Correction Capacity +---- ------------------------- +1 Approximately 10% +2 Approximately 20% +3 Approximately 30% +4 Approximately 40% +5 Approximately 50% + +Table: {#tbl:gridmatrix_eccs tag=": 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`](images/dotcode.svg){.i2d} + +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) + +{.i2d} + +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: {#tbl:hanxin_sizes tag=": 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: {#tbl:hanxin_eccs tag=": 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 +```c +option_3 = ZINT_FULL_MULTIBYTE | (N + 1) << 8 +``` + +### 6.6.14 Ultracode + +{.ultra} + +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: {#tbl:ultra_eccs tag=": Ultracode Error Correction Values"} + +Zint does not currently implement data compression by default, but this can be +initiated through the API by setting + +```c +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. + +\clearpage + +## 6.7 Other Barcode-Like Markings + +### 6.7.1 Facing Identification Mark (FIM) + +{.trk} + +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: {#tbl:fim_characters tag=": Valid FIM Characters"} + +### 6.7.2 Flattermarken + +{.lin} + +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: {#tbl:ascii tag=": 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 @tbl: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: {#tbl:iso_iec_8869_1 tag=": 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: + +```c++ +/* 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: + +```c++ +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()`: + +```c++ +/* 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: + +```bash +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"`: + +```bash +wish +``` + +and ignoring the Tk window click back to the command prompt `"%"` and type: + +```bash +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: + +```bash +wish demo/demo.tcl +``` +which will display the following window. + +{.pop} + +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)