PDF417 条形码编码器类库和演示应用程序 Ver. 2.2
5.00/5 (20投票s)
PDF417 条形码编码器类库是用 C# 编写的。目标框架为 .NET Framework (net462) 和 .NET Standard (netstandard2.0)。该编码器库允许您从文本字符串或二进制 (字节) 数组创建 PDF417 条形码图像。随附两个演示/测试应用程序。
引言
PDF417 条形码编码器类库是用 C# 编写的。这是开源代码。目标框架为 .NET Framework (net462) 和 .NET Standard (netstandard2.0)。该编码器库允许您从文本字符串或二进制 (字节) 数组创建 PDF417 条形码图像。随附两个演示/测试应用程序。Windows 窗体应用程序和控制台应用程序，目标框架为 .NET Framework (net462) 和 .NET Core (netcoreapp2.2)。两者都允许您探索该库并生成 PDF417 条形码。
NET Core 和 .NET Standard 均不支持 System.Drawing 程序集中的 Bitmap 类。该库包含一个 PNG 图像生成器，可在 .NET Standard 和 .NET Core 环境中运行。此图像非常高效。它利用了 PNG 标准的压缩和过滤功能。使用此软件保存 564 x 232 像素的条形码图像仅需 617 字节。使用 Bitmap 并指定 PNG 文件类型需要 16,865 字节。使用 Bitmap 并指定 JPEG 文件类型需要 21,121 字节。
PDF417 是一种二维条形码。您可以在以下网站找到条形码文档和规范：Wikipedia 提供了对 PDF417 的良好介绍。点击此处访问该页面。 PDF417 标准可从 ISO 组织购买，在此网站上购买。 规范的早期版本可免费下载，在此网站上下载。 如果您想完全理解编码选项，我强烈建议下载此文档。
PDF417 条形码将文本或字节二进制数组编码为黑白条的图像。随附的软件将文本或二进制数组转换为 PDF417 条形码 Bitmap 图像。如果输入数据是文本 string，它将首先使用 ISO 8859-n 标准 在此处定义 转换为字节数组。字节二进制数组被转换为字码。每个字码的范围是 0 到 928。此转换过程将输入字节分成多个段。有三种类型的段：文本、字节和数字。每种段类型都会被压缩：文本每个字码 2 个数据字符，字节每个字码 1.2 个数据字符，数字每个字码 2.93 个数据字符。为确保条形码的完整性，会在数据字码后附加纠错和检测字码。共有 9 个纠错级别。字码被分为行和列。每个字码被转换为一个符号，即交替的四条黑条和四条白条。一个窄条称为一个模块。每个字码总共有 17 个模块。条的宽度从一个模块到六个模块不等。每个字码会翻译成三种符号之一。符号 1 用于第 1、4、7 行等；符号 2 用于第 2、5、8 行等；符号 3 用于第 3、6、9 行等。
本文附带的软件是 PDF417 编码器库和两个演示/测试程序。本文解释了如何安装该软件。如何将编码器库集成到您的应用程序中并生成条形码图像。以及如何使用演示/测试程序。
将 PDF417 条形码添加到您的应用程序概览
将 PDF417 条形码添加到您的 PDF 文档必须遵循以下步骤。
选项 1：使用 Pdf417Encoder 类
- 创建
Pdf417Encoder对象。 - 设置编码选项。所有编码选项均具有默认值。
- 编码文本数据字符串或二进制数据字节数组。
- 检查生成的图像宽度和图像高度。或检查数据列数和数据行数。确保图像尺寸或纵横比适合您的应用程序。如果不是，请调整布局。
- 创建 PNG 文件或条形码的
Bitmap图像。
选项 2：使用 Pdf417CommandLine 类
使用命令行类通过一个输入文本字符串创建 PNG 文件来设置所有选项。
使用选项 1 创建 PDF417 条形码的简单示例
// test string to be encoded
string Text = "Pdf417EncoderDemo - Rev 2.0.0 - 2019-05-07 \u00a9 2019 Uzi Granot.
All rights reserved.";
// create PDF417 barcode object
Pdf417Encoder Encoder = new Pdf417Encoder();
// change default data columns
Encoder.DefaultDataColumns = 4;
// encode barcode data
Encoder.Encode(Text);
// save barcode image to PNG file
Encoder.SaveBarcodeToPngFile(“path\\FileName.png”);
使用选项 2 创建 PDF417 条形码的简单示例
// InputTextFile is the text file to encode
// OutputImage.png is the result
CommandLine.Encode(“/col=4 /t path\\InputTextFile path\\OutputImage.png”);
将 PDF417Encoder 类添加到您的应用程序详细信息
下面将描述所有 public 属性和方法。它们按照处理的逻辑顺序进行组织。
PDF417Barcode 对象
创建 PDF417 条形码对象。此对象可以连续重用以生成多个条形码。
// create PDF417 barcode object
Pdf417Encoder Encoder = new Pdf417Encoder();
编码控制 (默认自动)
PDF417 编码器将输入字节编码为字码。有三种类型的字码：字节、文本和数字。程序有一个算法将数据输入分割成段。每个段属于这三种类型之一。每个段都会被压缩以减小条形码尺寸。默认值为自动。但是，您可以将分段限制为仅字节或仅文本和字节。
// all three segments types are in consideration
Encoder.EncodingControl = EncodingControl.Auto;
// all input is one segment and it is bytes
Encoder.EncodingControl = EncodingControl.ByteOnly;
// input is divided into text and byte segments
Encoder.EncodingControl = EncodingControl.TextAndByte;
纠错级别 (默认自动普通)
PDF417 添加纠错字码来检测和纠正错误。更多的纠错字码可以提高条形码的可靠性。但是，它会使条形码变大。纠错级别允许您控制条形码的质量。ErrorCorrectionLevel 枚举有两种类型的值。固定级别从 0 到 8。以及相对级别，这是基于数据字码数量的推荐值。有关更多详细信息，请参阅 PDF417 规范中的表 6 和表 7。
Encoder.ErrorCorrection = ErrorCorrectionLevel.Level_0; // up to Level_8
// or
Encoder.ErrorCorrection = ErrorCorrectionLevel.AutoNormal; // default
// or
Encoder.ErrorCorrection = ErrorCorrectionLevel.AutoLow; // one less than normal
// or
Encoder.ErrorCorrection = ErrorCorrectionLevel.AutoMedium; // one more than normal
// or
Encoder.ErrorCorrection = ErrorCorrectionLevel.AutoHigh; // two more than normal
窄条宽度 (默认 2)
窄条形码条的像素宽度。在规范中也称为模块。如果更改此值，程序将确保 RowHeight 至少是该值的 3 倍。并且 QuietZone 至少是该值的 2 倍。如果您预计条形码将由相机扫描，并且条形码相对于相机图像坐标可能发生旋转，我建议窄条宽度至少为 4。
Encoder.NarrowBarWidth = value;
行高 (默认 6)
一行的像素高度。此值必须大于或等于 NarrowBarWidth 值的 3 倍。
Encoder.RowHeight = value;
静区 (默认 4)
条形码周围静区的宽度。静区是白色的。此值必须大于或等于 NarrowBarWidth 值的 2 倍。
Encoder.QuietZone = value;
默认数据列数 (默认 3)
默认数据列值。该值必须在 1 到 30 之间。输入数据编码后，软件会将数据列数设置为默认数据列数，并计算数据行数。如果数据行数超过允许的最大值 (90)，软件会将行数设置为允许的最大值，并重新计算数据列数。如果结果大于允许的最大列数，则会抛出异常。
Encoder.DefaultDataColumns = value;
全局标签 ID 字符集 (默认 null)
将全局标签 ID 字符集设置为 ISO 8859-part 标准。part 可以是 1 到 9，或 13，或 15。如果 string 为 null，此值将不会成为条形码数据的一部分。但是，大多数解码器会将其视为 ISO-8859-1。语言支持在此定义。
// n must be 1 to 9 or 13 or 15
Encoder.GlobalLabelIDCharacterSet = "ISO-8859-n";
全局标签 ID 用户自定义 (默认 0)
设置全局标签 ID 用户自定义值。如果用户自定义值为零，则不包含在条形码中。用户自定义值必须在 810900 和 811799 之间。存储在条形码中的值将是上述范围的 0 到 899。换句话说：stored_value = value – 810900;。我的建议是，除非您知道预期的解码器可以处理它，否则不要设置此值。
Encoder.GlobalLabelIDUserDefined = value;
全局标签 ID 通用 (默认 0)
设置全局标签 ID 通用值。如果通用值为零，则不包含在条形码中。通用值必须在 900 和 810899 之间。该值将存储在两个字码中。第一个是 Value / 900 – 1。第二个是 Value % 900。我的建议是，除非您知道预期的解码器可以处理它，否则不要设置此值。
Encoder.GlobalLabelIDGeneralPurpose = value;
编码数据
有两种编码方法。一种接受文本 string 作为输入参数，另一种接受字节数组作为输入参数。
// encoding text string
Encoder.Encode(string StringData);
// encoding binary byte array
Encoder.Encode(byte[] BinaryData);
条形码是为二进制数据设计的。因此，上述第一种方法必须将 string 从 16 位字符转换为字节数组。Encode(string) 方法具有以下转换逻辑。全局标签 ID 字符集属性控制转换。如果您的转换需要 ISO-8859-n (n 非 1)，则必须在调用 encode 方法之前设置字符集属性。转换分两步进行。第一步，将 string 转换为 UTF8 字节数组。第二步，将 UTF8 字节数组转换为 ISO-8859-n 字节数组。例如，如果您想编码希伯来文本，应该将字符集设置为 ISO-8859-8。
// This is the source code of the Encode(string) method.
// It is provided here in case you want to modify it to suit your special need.
public void Encode(string StringData)
{
// convert string to UTF8 byte array
byte[] UtfBytes = Encoding.UTF8.GetBytes(StringData);
// convert UTF8 byte array to ISO-8859-n byte array
Encoding ISO = Encoding.GetEncoding(_GlobalLabelIDCharacterSet ?? "ISO-8859-1");
byte[] IsoBytes = Encoding.Convert(Encoding.UTF8, ISO, UtfBytes);
// call the encode binary data method
Encode(IsoBytes);
Return;
}
条形码尺寸和纵横比
数据编码完成且条形码图像创建之前，您可以检查条形码的整体尺寸。如果条形码尺寸或纵横比不符合您的要求，您可以进行修改以满足您的需求。Pdf417Encoder 提供了四个属性值
Encoder.ImageWidth(像素，包括静区)Encoder.ImageHeight(像素，包括静区)Encoder.DataColumns(不包括起始符、终止符以及左右行指示符)Encoder.DataRows
如果您想调整条形码的布局，可以使用以下方法之一。此外，您可以重新调整可选参数：NarrowBarWidth、RowHeight 或 QuietZone 值。
宽度与高度比
此方法将计算数据行数和数据列数以达到所需的宽度与高度比。该比率包括静区。结果将等于或接近您的要求。检查返回值以确认成功。
bool Encoder.WidthToHeightRatio(double Ratio);
设置数据列数
此方法将根据所需的数据列数计算数据行数。检查返回值以确认成功。
bool Encoder.SetDataColumns(int Columns);
设置数据行数
此方法将根据所需的数据行数计算数据列数。检查返回值以确认成功。
bool Encoder.SetDataRows(int Rows);
将 PDF417 条形码保存到 PNG 文件或流
// save the barcode to a disk file
Encoder.SaveBarcodeToPngFile(“FileName”);
// or
// save the barcode to an Output Stream
Encoder.SaveBarcodeToPngFile(OutputStream);
将 PDF417 条形码保存到 Bitmap 文件或流
// save the barcode to a disk file
// ImageFormat such as PNG, BMP, JPEG
Encoder.SaveBarcodeToFile(“FileName”, ImageFormat);
// or
// save the barcode to an Output Stream
// ImageFormat such as PNG, BMP, JPEG
Encoder.SaveBarcodeToFile(OutputStream, ImageFormat);
创建 PDF417 条形码 Bitmap 图像
// Create Bitmap object
Bitmap Image = Encoder.CreateBarcodeBitmap();
// or
// Create Bitmap image with white and black brushes
// This allows you to change the color of the background
// and the bars
Bitmap Image = Encoder.CreateBarcodeBitmap(WhiteBrush, BlackBrush);
创建 PDF417 布尔矩阵，其中每个元素代表一个像素
// Boolean image
// Black is true
// White is false
bool[,] ConvertBarcodeMatrixToPixels();
创建 PDF417 布尔矩阵，其中每个元素代表一个条
此方法会自动为上述每种方法执行。
// Boolean image
// Black is true
// White is false
bool[,] CreateBarcodeMatrix();
使用 CommandLine 类创建 PNG 图像文件
命令行参数如下所述。更详细的每个选项的描述在上面给出。
Command line arguments format
[optional arguments] input-file output-file
Output file must have .png extension
Options format /code:value or -code:value (the : can be =)
Encoding control. code=[encode|n], value=[auto|a|byte|b|text|t], default=a
Error correction level. code=[error|e], value=[0-8|low|l|normal|n|medium|m|high|h], default=n
Narrow bar width. code=[width|w], value=[1-100], default=2
Row height. code=[height|h], value=[3-300], default=6, min=3*width
Quiet zone. code=[quiet|q], value=[2-200], default=4, min=2*width
Layout options. Only one of data columns, data rows or image ratio
Data columns. code=[col|c], value=[1-30], default=3
Data rows. code=[row|r], value=[3-90], no default
Image ratio (width/height). code=[ratio|o], value=[decimal > 0], no default
Text file format. code=[text|t], value=iso-8859-n, see notes below
Input file is binary unless text file option is specified
If input file format is text or t with no value, character set is iso-8859-1
If input file format is text or t value must be iso-8859-n and n must be 1-9, 13, 15
演示/测试程序
Pdf417EncoderDemo 项目旨在演示和测试 PDF417 Encoder Library 的所有功能。它可以用作代码示例的来源。
在左上角，您可以设置所有编码选项。在底部，按钮上方，输入要编码的文本。该程序内置了不同语言的文本示例。右下角的组合框允许您选择其中一个示例。“加载文件”按钮允许您从文件中加载自己的示例。
按“编码”按钮会将屏幕上的文本转换为 PDF417 条形码。条形码将被显示。注意：您可以调整屏幕大小以更详细地查看它。
如果您想更改条形码的纵横比，请按“调整布局”。将显示以下屏幕。选择其中一个选项来设置行和列。单击确定。将显示新的布局。
按“保存 PNG”将条形码以 PNG 格式保存到磁盘文件。这种保存图像的方法比使用 Bitmap 保存要高效得多。
按“保存”将条形码保存到磁盘。将显示以下屏幕。如果您想按原样保存条形码，请按“保存”并选择文件名和文件夹。
如果您想在背景上保存条形码，请选择“画笔”单选按钮或“图像”单选按钮。对于画笔背景，您可以选择颜色和纹理。对于图像背景，您必须加载自己的图片。在这两种情况下，您都可以设置条形码的位置。您可以旋转条形码。并且可以以透视方式显示它。这些选项加上错误点是为了测试 PDF417 解码器而包含的。
下面给出两个条形码在背景上的示例。在第一个示例中，条形码已旋转。
在第二个示例中，条形码以透视方式查看。
源代码
内部代码可分为以下几个部分
- 将输入数据编码为字码。主方法是
DataEncoding。数据编码算法在 USS-PDF-417 文档 的附录 D (信息性) 数据编码中进行了描述。 - 计算纠错和检测字码数组。主方法是
CalculateErrorCorrection。 - 将组合数据数组和纠错数组转换为黑白布尔矩阵。主方法是
CreateBarcodeMatrix。每个元素代表一个窄条。黑色为 true，白色为 false。 - 将条形码矩阵保存到 PNG 文件，而不使用
Bitmap类。主方法是SaveBarcodeToPngFile。此方法在将图像压缩到文件方面非常高效。它利用了 PNG 标准的过滤和压缩功能。
安装
随附的 Visual Studio 解决方案源文件包含三个项目
Pdf417EncoderLibrary- 编码器库由多个类组成。主类是Pdf417Encoder。Pdf417EncoderDemo- 演示程序允许您测试编码器并尝试所有可用的控件选项。您可以使用 Save PNG 按钮或 Save 按钮保存结果。除了普通保存外，演示程序还可以生成带背景的图像、旋转图像和透视图像。您可以添加错误点。这些功能是为了测试 Pdf417 解码器而设计的。PdfConsoleDemo- 控制台演示程序设计用于测试 .NET Core 环境。
将 Pdf417EncoderLibrary 集成到您的应用程序。
将 Pdf417EncoderLibrary.dll 类库包含到您的项目中。如果您的项目是 Visual Basic，您必须这样做。将附带的 Pdf417EncoderLibrary.dll 文件安装到您的开发区域。启动 Visual Studio。打开您的应用程序。转到解决方案资源管理器。右键单击“引用”并选择“添加引用”。选择“浏览”选项卡，然后导航到已安装 Pdf417EncoderLibrary.dll 的位置。发布应用程序时，必须将 Pdf417EncoderLibrary.dll 文件包含在可执行文件 (.exe) 所在的同一文件夹中。
Pdf471Encoder 类的命名空间是 Pdf417BarcodeLibrary。在引用此库的所有源文件中添加一个“using”语句：或者，将命名空间更改为您自己的命名空间。
历史
- 2019/04/01：版本 1.0 - 原始版本
- 2019/04/15：版本 1.1 - 修复 Visual Studio 2019 安全阻止问题
- 2019/05/07：版本 2.0 - 主要更改以支持 .NET Core 和 .NET Standard。以及在不使用
Bitmap类的情况下将图像保存为 PNG 格式 - 2019/05/15：版本 2.1 - 对源代码进行微小更改
- 2020/09/08：版本 2.2 - 修复内存不足错误