Mirrors/zint
1
0
Fork 0
mirror of https://git.code.sf.net/p/zint/code synced 2026-01-26 05:15:57 +00:00
Code Issues Projects Releases Wiki Activity

Integrate GS1 Syntax Engine

Browse Source
This commit is contained in:
gitlost
2025-09-12 04:20:55 +01:00
parent ad95d8f2b0
commit 0650d5798e
32 changed files with 2109 additions and 723 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
docs/manual.txt
View File

@@ -328,14 +328,15 @@ vector
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
utilities. You will need to install CMake, and libpng-dev first. For instance on
apt systems:
sudo apt install git cmake build-essential libpng-dev
If you want to take advantage of Zint Barcode Studio you will also need to have
Qt and its component "Desktop gcc 64-bit" installed, as well as mesa. For
details see "README.linux" in the project root directory.
Qt and its component "Desktop gcc 64-bit" installed, as well as mesa. Other
steps are required to avail of the GS1 Syntax Engine.[1] 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
@@ -403,7 +404,7 @@ 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
The latest Zint CLI and libzint can be installed using Homebrew.[2] To install
Homebrew input the following line into the macOS terminal
/bin/bash -c "$(curl -fsSL \
@@ -719,7 +720,7 @@ sequences are shown in the table below.
\xNN 0xNN Any 8-bit character where NN is hexadecimal
(00-FF)
\uNNNN Any 16-bit Unicode BMP[2] character where
\uNNNN Any 16-bit Unicode BMP[3] character where
NNNN is hexadecimal (0000-FFFF)
\UNNNNNN Any 21-bit Unicode character where NNNNNN is
@@ -797,7 +798,7 @@ Names are treated case-insensitively by the CLI, and the BARCODE_ prefix and any
underscores are optional.
-----------------------------------------------------------------------------
Numeric Name[3] Barcode Name
Numeric Name[4] Barcode Name
Value
--------- --------------------------- ---------------------------------------
1 BARCODE_CODE11 Code 11
@@ -1164,7 +1165,7 @@ transparent foreground. For instance
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]
formats except BMP.[5]
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
@@ -1283,7 +1284,7 @@ MaxiCode symbols have fixed size ranges of 24.82mm to 27.93mm in width, and
4.10 Human Readable Text (HRT) Options
For linear barcodes the text present[5] in the output image can be removed by
For linear barcodes the text present[6] 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)).
@@ -1335,7 +1336,7 @@ Latin-2 (ISO/IEC 8859-2 plus ASCII).
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[6])
Micro QR Code Latin-1 Shift JIS (includes ASCII[7])
PDF417 Latin-1 None
QR Code Latin-1 Shift JIS (see above)
rMQR Latin-1 Shift JIS (see above)
@@ -1352,10 +1353,12 @@ Interpretations) mechanism to encode the data if the symbology supports it - see
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.
(see 6.1.10.3 GS1-128). GS1 Digital Link URIs are also supported. To encode GS1
data use the --gs1 option. Also recommended is the --gs1strict option, which
verifies the GS1 data. 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
@@ -1437,7 +1440,7 @@ formatted. Zint automatically translates the data into the target encoding.
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[7]
170 ISO/IEC 646 Invariant[8]
899 8-bit binary data
Table : ECI Codes
@@ -1945,7 +1948,7 @@ the buffer is given in memfile_size. For instance:
}
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,[8] allowing the output
particularly useful for the textual formats EPS and SVG,[9] allowing the output
to be manipulated and processed by the client.
5.7 Setting Options
@@ -1966,7 +1969,7 @@ the following members:
height float Symbol height in Symbol dependent
X-dimensions, excluding
fixed width-to-height
symbols.[9]
symbols.[10]
scale float Scale factor for adjusting 1.0
size of image (sets
@@ -2013,7 +2016,7 @@ the following members:
end in .png, .gif, .bmp,
.emf, .eps, .pcx, .svg,
.tif or .txt followed by a
terminating NUL.[10]
terminating NUL.[11]
primary character Primary message data for "" (empty)
string more complex symbols, with
@@ -2292,10 +2295,10 @@ together when adjusting this value:
-------------------------- ---------------------------------------------------
0 No options selected.
BARCODE_BIND_TOP Boundary bar above the symbol only.[11]
BARCODE_BIND_TOP Boundary bar above the symbol only.[12]
BARCODE_BIND Boundary bars above and below the symbol and
between rows if stacking multiple symbols.[12]
between rows if stacking multiple symbols.[13]
BARCODE_BOX Add a box surrounding the symbol and whitespace.
@@ -2322,7 +2325,7 @@ together when adjusting this value:
Symbols in Memory (raster).
BARCODE_QUIET_ZONES Add compliant quiet zones (additional to any
specified whitespace).[13]
specified whitespace).[14]
BARCODE_NO_QUIET_ZONES Disable quiet zones, notably those with defaults.
@@ -2350,47 +2353,51 @@ 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.
Value Effect
----------------------- ------------------------------------------------------
DATA_MODE Uses full 8-bit range interpreted as binary data.
UNICODE_MODE Uses UTF-8 input.
UNICODE_MODE Uses UTF-8 input.
GS1_MODE Encodes GS1 data using FNC1 characters.
GS1_MODE Encodes GS1 data using FNC1 characters.
The above are exclusive, the following optional and OR-ed.
The above are exclusive, the following optional and
OR-ed.
ESCAPE_MODE Process input data for escape sequences.
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 in the data must be escaped and ESCAPE_MODE
selected).
GS1PARENS_MODE Parentheses (round brackets) used in GS1 data instead
of square brackets to delimit Application Identifiers
(parentheses in the data must be escaped).
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.
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.
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).
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).
EXTRA_ESCAPE_MODE Process special symbology-specific escape sequences
(CODE128 only).
GS1SYNTAXENGINE_MODE Use the GS1 Syntax Engine (if available) to strictly
validate GS1 input.
------------------------------------------------------------------------------
: Table  : API input_mode Values
The default mode is DATA_MODE. (Note that this differs from the default for the
CLI and GUI, which is UNICODE_MODE.)
The default mode is DATA_MODE (CLI option --binary). (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
ESCAPE_MODE, GS1PARENS_MODE, GS1NOCHECK_MODE, HEIGHTPERROW_MODE, FAST_MODE,
EXTRA_ESCAPE_MODE and GS1SYNTAXENGINE_MODE are optional. So, for example, you
can set
my_symbol->input_mode = UNICODE_MODE | ESCAPE_MODE;
@@ -2409,13 +2416,19 @@ Permissible escape sequences (ESCAPE_MODE) are listed in Table
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.
GS1NOCHECK_MODE (CLI --gs1nocheck) 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.
In contrast GS1SYNTAXENGINE_MODE (CLI --gs1strict) enables the use the GS1
Syntax Engine to strictly validate GS1 data, including GS1 Digital Link URIs (by
default ZINT does not validate Digital Links at all). It requires that the
gs1encoders library was present when Zint was built, otherwise the default
built-in validation will be used.
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
@@ -2570,7 +2583,7 @@ see which are set.
ZINT_CAP_STACKABLE Is the symbology stackable? Note that stacked
symbologies are not stackable.
ZINT_CAP_EANUPC[14] Is the symbology EAN/UPC?
ZINT_CAP_EANUPC[15] Is the symbology EAN/UPC?
ZINT_CAP_COMPOSITE Does the symbology support composite data? (see
6.3 GS1 Composite Symbols (ISO 24723) below)
@@ -2628,7 +2641,7 @@ option_2 and option_3 members will be set to the values used by Zint to create
the barcode. This is useful for feedback if the values were left as defaults or
were overridden by Zint.
In particular for symbologies that have masks,[15] option_3 will contain the
In particular for symbologies that have masks,[16] option_3 will contain the
mask used as (N + 1) << 8, N being the mask. Also Aztec Code will return the
actual ECC percentage used in option_1 as P << 8, where P is the integer
percentage, the low byte containing the values given in Table
@@ -2644,7 +2657,7 @@ in raw_seg_count - which will always be at least one.
The source, length and eci members of zint_seg will be set accordingly - the
unconverted data in source, the data length in length, and the character set the
data was converted to in eci. Any check characters encoded will be included,[16]
data was converted to in eci. Any check characters encoded will be included,[17]
and for GS1 data any FNC1 separators will be represented as GS (ASCII 29)
characters. UPC-A and UPC-E data will be expanded to EAN-13, as will EAN-8 but
only if it has an add-on (otherwise it will remain at 8 digits), and any add-ons
@@ -2660,7 +2673,7 @@ two helper functions discussed next.
5.17 UTF-8 to ECI convenience functions
As a convenience the conversion done by Zint from UTF-8 to ECIs is exposed in
two helper functions (compatible with the libzueci[17] functions
two helper functions (compatible with the libzueci[18] functions
zueci_utf8_to_eci() and zueci_dest_len_eci()):
int ZBarcode_UTF8_To_ECI(int eci, const unsigned char *source, int length,
@@ -3194,7 +3207,7 @@ alphanumerics) are not recommended.
[zint -b CODE128AB -d "130170X178"]
It is sometimes advantageous to stop Code 128 from using Code Set C which
compresses numerical data. The BARCODE_CODE128AB[18] variant (symbology 60)
compresses numerical data. The BARCODE_CODE128AB[19] 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
@@ -3753,7 +3766,7 @@ 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).[19]
0 to 15).[20]
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
@@ -5019,7 +5032,7 @@ configured barcode is updated when the "Generate" button is pressed.
Annex D. Man Page ZINT(1)
% ZINT(1) Version 2.15.0.9 % % April 2025
% ZINT(1) Version 2.15.0.9 % % September 2025
NAME
@@ -5258,6 +5271,11 @@ OPTIONS
"[]". If the AI data contains parentheses, they must be backslashed ("\(" or
"\)") and the --esc option selected.
--gs1strict
Uses the GS1 Syntax Engine (if available) to strictly verify GS1 data.
Ignored if --gs1nocheck also given.
--gssep
For Data Matrix in GS1 mode, use GS (0x1D) as the GS1 data separator instead
@@ -5731,24 +5749,28 @@ AUTHOR
Robin Stuart robin@zint.org.uk
[1] See the Homebrew website https://brew.sh.
[1] The GS1 Syntax Engine (gs1encoders library), which is officially sanctioned
by GS1, offers strict validation of GS1 data, including GS1 Digital Link URIs -
see “GS1 Barcode Syntax Engine” at https://github.com/gs1/gs1-syntax-engine.
[2] In Unicode contexts, BMP stands for Basic Multilingual Plane, the plane 0
[2] See the Homebrew website https://brew.sh.
[3] In Unicode contexts, BMP stands for Basic Multilingual Plane, the plane 0
codeset from U+0000 to U+D7FF and U+E000 to U+FFFF (i.e. excluding surrogates).
Not to be confused with the Windows Bitmap file format BMP!
[3] The symbology names marked with an asterisk (*) in Table
[4] The symbology names marked with an asterisk (*) in Table
: Barcode Types (Symbologies) above used different names in previous versions of
Zint. These names are now deprecated but are still recognised by Zint. Those
marked with a dagger (†) are replacements for BARCODE_EANX (13),
BARCODE_EANX_CHK (14) and BARCODE_EANX_CC (130), which are still recognised by
Zint.
[4] The background is omitted for vector outputs EMF, EPS and SVG when
[5] The background is omitted for vector outputs EMF, EPS and SVG when
--nobackground is given. For raster outputs GIF, PCX, PNG and TIF, the
background’s alpha channel is set to zero (fully transparent).
[5] For linear barcodes, Human Readable Text (HRT) is not shown for the postal
[6] For linear barcodes, Human Readable Text (HRT) is not shown for the postal
codes Australia Post (all variants), USPS Intelligent Mail, POSTNET and PLANET,
Brazilian CEPNet, Royal Mail 4-State Customer Code and 4-State Mailmark, Dutch
Post KIX Code, Japanese Postal Code, DAFT Code and FIM, the pharma codes
@@ -5756,46 +5778,46 @@ Pharmacode One-Track and Pharmacode Two-Track, and the specialist codes DX Film
Edge Barcode and Flattermarken. Note that HRT is never shown for stacked and
matrix barcodes.
[6] Shift JIS (JIS X 0201 Roman) re-maps two ASCII characters: backslash (\) to
[7] Shift JIS (JIS X 0201 Roman) re-maps two ASCII characters: backslash (\) to
the yen sign (¥), and tilde (~) to overline (U+203E).
[7] ISO/IEC 646 Invariant is a subset of ASCII with 12 characters undefined: #,
[8] ISO/IEC 646 Invariant is a subset of ASCII with 12 characters undefined: #,
$, @, [, \, ], ^, `, {, |, }, ~ (tilde).
[8] BARCODE_MEMORY_FILE textual formats EPS and SVG will have Unix newlines (LF)
[9] 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.
[9] The height value is ignored for Aztec (including HIBC and Aztec Rune), Code
[10] 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).
[10] For Windows, outfile is assumed to be UTF-8 encoded.
[11] For Windows, outfile is assumed to be UTF-8 encoded.
[11] The BARCODE_BIND_TOP flag is set by default for DPD - see 6.1.10.7 DPD
[12] The BARCODE_BIND_TOP flag is set by default for DPD - see 6.1.10.7 DPD
Code.
[12] The BARCODE_BIND flag is always set for Codablock-F, Code 16K and Code 49.
[13] 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.
[13] Codablock-F, Code 16K, Code 49, EAN-13, EAN-8, EAN/UPC add-ons, ISBN,
[14] Codablock-F, Code 16K, Code 49, EAN-13, EAN-8, EAN/UPC add-ons, ISBN,
ITF-14, UPC-A and UPC-E have compliant quiet zones added by default.
[14] ZINT_CAP_EANUPC was previously named ZINT_CAP_EXTENDABLE, which is still
[15] ZINT_CAP_EANUPC was previously named ZINT_CAP_EXTENDABLE, which is still
recognised.
[15] DotCode, Han Xin, Micro QR Code, QR Code and UPNQR have variable masks.
[16] DotCode, Han Xin, Micro QR Code, QR Code and UPNQR have variable masks.
Rectangular Micro QR Code has a fixed mask (4).
[16] Except for Japanese Postal Code, whose check character is not truly
[17] Except for Japanese Postal Code, whose check character is not truly
representable in the encoded data.
[17] The library libzueci, which can convert both to and from UTF-8 and ECI, is
[18] The library libzueci, which can convert both to and from UTF-8 and ECI, is
available at https://sourceforge.net/projects/libzueci/.
[18] BARCODE_CODE128AB previously used the name BARCODE_CODE128B, which is still
[19] BARCODE_CODE128AB previously used the name BARCODE_CODE128B, which is still
recognised.
[19] The DX number may be looked up in The (Modified) Big Film Database at
[20] The DX number may be looked up in The (Modified) Big Film Database at
https://thebigfilmdatabase.merinorus.com.