Solution Guide II-C 2D Data Codes

Chapter 5
Problem Handling

The previous section proposed a selection of preprocessing steps for common problems when working with 2D data codes. Now, we will go deeper into the handling of problems.
        • In section 5.1 we introduce you to the debugging of the operator find_data_code_2d, which on the one hand helps to enhance the run time of successfully decoded symbols and on the other hand is used for locating problems with symbols that are not decoded. To identify a problem often leads to ideas how an undecoded symbol can be preprocessed.
        • Some situations exist where a preprocessing yields no success. These situations and tips how to avoid them are presented in section 5.2.
        • In section 5.3, the requirements and limitations for the 2D data code reader are summarized concisely.

        前一节提出了处理2D数据代码时常见问题的预处理步骤选择。现在，我们将更深入地讨论问题的处理。

        •在5.1节中，我们将向您介绍操作符find_data_code_2d的调试，这一方面有助于提高成功解码符号的运行时间，另一方面用于定位未解码符号的问题。识别问题通常会引出如何对解码后的符号进行预处理。

        •存在一些预处理不成功的情况。5.2节会介绍这些情况以及如何避免它们的技巧。

        •在第5.3节中，对2D数据代码阅读器的要求和限制进行了简要总结。

5.1 Data Access for Debugging

5.1 调试数据访问

        在操作符find_data_code_2d的搜索过程中，除了解码的数据字符串和成功解码的符号的XLD轮廓之外，还可以得到各种结果。这些结果提供了一些提示，说明如何在运行时间方面增强搜索过程，或者为什么无法找到或者解码符号。HDevelop程序%HALCONEXAMPLES%\ HDevelop \Identification\Data-Code\2d_data_codes_data_access.hdev 显示如何基于各种原因访问结果。下面几节将详细描述该程序的各个步骤。特别介绍了：

        •一般的数据访问，以及对所有调试目的有用的结果的选择(见5.1.1节)，

        •在面对解码成功但缓慢的符号时有用的结果选择(参见5.1.2节),

        •选择的结果可能会提示为什么符号没有被解码(见5.1.3节)。

        该程序集中在ECC 200。PDF417、QR码、Micro QR码、Aztec码和DotCode的一些与所给出结果不一致的特性将在第36页5.1.3节中介绍。

5.1.1 General Information About Data Access

5.1.1数据访问的基本信息

        从操作符find_data_code_2d获得的结果分为图标结果和字母数字结果。图标结果，即像图像或区域这样的对象，可以使用操作符get_data_code_2d_objects进行查询，输入参数是DataCodeHandle，CandidateHandle和ObjectName。字母数字结果由操作符get_data_code_2d_results获得，输入参数是DataCodeHandle、CandidateHandle和ResultNames。图标和字母数字结果所需的候选句柄指定一个符号的单个候选句柄或一组候选句柄，为其查询结果或对象。在单个操作符调用中，您可以将一组候选与单个结果或单个候选与结果元组组合在一起。所有预定义的候选组以及每个SymbolType的所有可用对象和结果名称的列表可以在参考手册中各个操作符的描述处找到。

        程序\hdevelop\Identification\Data-Code\2d_data_codes_data_access.hdev中，我们首先指定一般设置，即为' data Matrix ECC 200 '类型的符号创建一个2D数据编码模型，并将默认参数设置为增强模式，以便所有未损坏的符号都可以解码。默认情况下，一些结果仅临时存储在2D数据代码模型中。因此，我们将模型参数“persistence”设置为1，以将所有中间结果保存在内存中(参见第21页3.3.4节)。

        可用的字母数字结果名称和图标对象名称的列表由操作符query_data_code_2d_params获得，参数为' get_result_params '和' get_result_objects '(另见第14页3.2.2节)。

        读取图像后，应用操作符find_data_code_2d，该操作符存储所有中间结果，以便我们可以进一步研究它们。

        对于一组字母数字结果，我们区分一般结果和与特定候选符号或一组候选符号相关的结果。一般结果被使用，例如，用于获得与每组候选人相关的候选人数量的信息。在程序中，我们将CandidateHandle设置为' general '，并传递一个包含所有可用的通用ResultNames的元组。详细地说，我们想要访问搜索符号(' min_search_level '和' max_search_level ')的最低和最高金字塔级别、已完成的传递数(' pass_num ')、所有成功解码的符号数(' result_num ')、所有被调查的候选数(' candidate_num ')、被识别为符号但无法读取的候选数(' undecoded_num ')，以及不能被识别为有效候选的数量(' aborted_num ')。前三个值为我们提供了关于搜索过程性能的信息。所有存储在变量“GenResult”中的结果值都显示在HDevelop的变量窗口中。为了更好地检查，我们将它们显示在一个新的图形窗口中(参见图5.1)。

        如果找到候选程序，程序将查询并显示搜索过程的两个图像结果，即搜索图像和过程图像。搜索图像是在其中找到候选对象的金字塔图像，而过程图像是在其中更仔细地调查候选对象的金字塔图像。对搜索图像和过程图像的视觉检查通常会产生 为什么一个符号没有被发现或解码，或者为什么解码过程花费太多时间 的思考。

        图5.2显示了我们在第27页4.3节中已经尝试读取的图像的搜索图像和处理图像。在低分辨率搜索图像中，安静区噪声条纹无法与符号区分的原因比在高分辨率原始图像中更加明显。

        使用每个候选组中候选数的信息，我们现在讨论两种不同的情况。一方面，我们研究成功解码的符号，以获得有关它们当前参数值的信息，以便增强运行时间(参见第5.1.2节)。另一方面，我们研究未解码的符号，以找出它们未解码的原因，以及特定的预处理步骤是否合适(参见5.1.3节)。

5.1.2 Parameters to Access for Successfully Decoded Symbols

5.1.2成功解码符号的访问参数

        对成功解码的符号进行调试的主要原因是增强搜索过程的运行时间，即减少所需的传递次数。为此，您必须将2D数据代码模型的参数值的范围限制到最小(参见第13页第3.2节和第15页第3.3节)。为了确定特定应用程序的合理范围，可以使用操作符get_data_code_2d_results查询符号的当前参数值。通过比较自适应前后的完成次数（第30页第5.1.1节），可以判断模型自适应是否成功。在程序2d_data_codes_data_access.hdev 中我们查询一个元组的结果，它提供了关于符号外观的信息和关于成功搜索过程的附加信息(见图5.3)。

        后者包括生成和处理符号的实际通道(' pass ')、状态消息(' status ')和解码后的数据字符串(' decoded_string ')。状态消息为您提供了一个符号是否解码成功、为什么解码成功以及在评估过程的哪个点停止了对特定候选的搜索的信息。在这里，我们查询成功解码符号的结果，因此元组' VariousResults '中的状态消息是’successfully decoded’。

        为了控制在搜索过程中确定的模块的分类，程序查询两个不同的区域数组，特别是前景和背景模块的图标表示(' module_1_rois '和' module_0_rois ')。返回的区域元组('前景'和'背景')显示在图5.4中。

        当处理相当大的代码时，您可以通过将结果名称' decoded_data '传递给操作符get_data_code_2d_results来查询一个不受限制的元组，其中包含解码数据的所有单独数字和字符。在程序中，生成的元组' ResultASCIICode '以格式化的形式显示在图形窗口中，以便更好地查看(参见图5.5)。

5.1.3 Parameters to Access for Symbols that are not Decoded

5.1.3未解码符号的访问参数

        对于未解码的符号，进一步区分找到但未解码的符号和未被分类为有效符号的候选符号。如果不设置模块的最小尺寸，模块本身常常被确定为候选。为了减少候选的数量，从而使调查更加简洁，我们在将2D数据代码阅读器应用于有问题的图像(索引“index”)之前，将模型调整为最小模块大小。

        另一种减少候选对象数量的方法，特别是当图像包含其他具有直角的物体时，是将图像的域减小到包含完整符号的ROI(包括其安静区域)。要创建ROI，请参见第21页的3.4.1节。

        为了访问所有已找到但未解码的候选符号，我们通过将候选句柄' all_undecoded '和结果名' handle '传递给操作符get_data_code_2d_results来创建句柄' HandlesUndecoded '。

        然后，我们查询XLD轮廓线和对应的未编码符号候选状态消息。这些信息提供了关于为什么没有找到或解码候选的原因的重要信息。对于成功解码的符号，我们通过操作符find_data_code_2d显式接收XLD轮廓。对于未解码的符号，我们必须使用操作符get_data_code_2d_objects查询XLD轮廓，结果名为' candidate_xld '。

        此外，我们可视化模块的区域，这一次是为了检查，例如，是否缺少大量的模块，或者模块是否偏离了规则的网格。也许是模块太小了，或者安静的区域被条纹扭曲了。在这些情况下，获得的网格可以相对于符号进行平移。小模块的问题可以通过调整参数' small_modules_robustness '来解决(DotCode符号除外)。其他问题通常可以通过对图像进行预处理来解决，如第25页第4节所述。

        除了图标结果外，还可以得到模块的字母数字信息。在搜索过程中，将逐行读取模块。值0定义后台模块，值100定义前景模块。通常，模块的值介于两者之间。一个自动选择的阈值将前景模块与背景模块分开。通过检查这些值，或者更准确地说，检查它们与0或100之间的偏差，可以评估模块分类的质量。

        图5.6显示了具有非常小模块的符号的一部分。由于模块小于指定的最小模块大小，计算网格不能正确地拟合到符号，并且每个计算区域包含几个模块的部分，即各个区域同时包含暗部分和亮部分。

        存储在元组' ResultBinModules '(见图5.7)中的所有区域的二进制值确认了视觉印象，因为对于大多数区域，其值严重偏离0或100。因此，判断一个区域属于前景还是背景是不可靠的。如前所述，由小模块大小引起的问题可以通过调整参数' small_modules_robustness'来解决。

        对于未被检测为有效符号的候选符号，将无法获得任何模块区域。因此，在为' all_aborted '候选对象创建一个名为' HandlesAborted '的句柄之后，调试信息被简化为每个候选对象的状态消息和XLD轮廓线。

        例如，状态消息告诉我们不能调整查找器元素的x边界。图5.8显示了这样一个候选人的说教性说明。通过观察相应的XLD等高线，很明显，由于x边界附近安静区域的扰动条纹，它不能被调整。为了清楚地区分条纹和符号，我们必须像第27页4.3节所描述的那样去除噪声。

        有时根本找不到候选项。如果出现这种情况，请检查是否出现了第25页第4节中介绍的一些问题。也许模块之间的间隙太大，以至于2D数据代码阅读器无法识别单个模块之间的连接，或者符号噪声太大，以至于模块之间无法相互分离。在这些情况下，您应该尝试通过应用建议的预处理步骤来解决问题。有时符号被损坏，根本无法读取。其中一些情况以及如何在图像采集时避免这些情况的提示将在5.2节中介绍。

        在程序中，我们集中讨论了数据矩阵ECC 200常见的一些重要结果。如果使用PDF417、QR码、Micro QR码或Aztec码，结果会有所不同。一个与调试结果截然不同的例子涉及倾斜符号。对于我们已经在第25页第4.1节中介绍的数据矩阵ECC 200符号，2D数据码阅读器搜索矩形查找器模式。因为符号是倾斜的，所以丢失了直角，状态消息说明了与符号的边界或查找器模式有关的问题。图5.9显示了一个演示示例来可视化这种情况。由于没有识别有效的查找器模式，所有候选符号都将被中止。

        对于图5.10中的PDF417代码，没有搜索矩形查找器模式。因此，找到几个候选符号，并根据符号的开始或停止模式进行调整。因为这些是退化的，与实际符号的轮廓不对应，所以没有找到数据模块，也没有解码符号。

        对于QR码，可能会出现类似的困难。图5.11显示了一个演示示例来可视化这种情况。同样，找到了几个候选符号，因为至少找到了三个位置检测模式中的两个。然而，由于候选符号是相对于这两个位置检测模式进行调整的，因此候选符号并不适合倾斜的符号。在这里，至少检测到一些模块，并将不正确的候选符号的平方可视化。由于在候选对象中，模块位于错误的位置，因此错误纠正失败。

        此外，还可以获得进一步的结果，例如PDF417和QR码的实际错误纠正级别，可以通过get_data_code_2d_results和参数' error_correction_level '查询。对于PDF417，可以获得0到8之间的值。0表示只检测到错误，而不纠正错误。1 ~ 8表示纠错能力的增加。对于QR码和微QR码，可增加级别“L”，“M”和“Q”。“H”级别适用于QR码，但不适用于Micro QR码。如前所述，每个符号类型的结果的完整列表可以在参考手册的操作符get_data_code_2d_results 和 get_data_code_2d_objects的描述中找到。要了解更多关于纠错级别的信息，也可参考相应的标准ISO/IEC CD 18004，信息技术-自动识别和数据捕获技术- QR Code 2005条形码符号规范。

5.2 Selected Problems and Tips to Avoid Them

5.2选择的问题和避免问题的技巧

        HALCON的二维数据码阅读器是一个相当强大的工具，它可以用来读取部分扭曲的符号。但有时一个符号被扭曲得太厉害了，即使在对图像进行预处理之后也无法解码。有些失真是由于符号损坏造成的，例如，符号没有正确打印，或者由于各种原因缺少大量模块。其他失真发生在图像采集过程中。这些都可以通过适当的获取条件来避免。在下面的例子中，我们将向你介绍两种情况造成的扭曲

        •糟糕的几何形状，即符号的模块没有放置在规则的网格上(参见第5.2.1节)，

        •糟糕的辐射测量，即由于糟糕的照明条件，单个模块无法正确分类(见第5.2.2节)。

        我们建议通过将符号平展到水平表面并在图像采集时使用漫射光来避免这两种情况。

5.2.1 Geometric Distortions

5.2.1几何畸变

        理想符号的模块放置在规则网格上。对于矩阵编码，网格必须在整个符号中是规则的，而对于PDF417，网格只需要在各个列中是规则的。在搜索符号时，操作符find_data_code_2d搜索指定符号的查找器模式(或PDF417的开始和停止模式)。如果找到，它将近似于模块的网格，该网格将根据查找器模式进行调整。一些错误，即模块与网格的小偏差(对于Data Matrix ECC 200，最大位移为半个模块大小，当' module_grid '设置为' variable '时，最大位移为整个模块大小)，可以处理。对于更大的偏差，2D数据代码读取失败。HDevelop 例程 %HALCONEX-AMPLES%\hdevelop\Identification\DataCode\2d_data_codes_arbitrary_distortions. Hdev 读取各种扭曲的符号。如图5.12所示，纸上印着6个符号。纸张被揉皱了，因此符号会发生任意的扭曲，其中四个模块与常规网格相差甚远，以至于无法解码。

        与第25页第4.1节中可以通过修正来消除的规则扭曲不同，这里的扭曲是任意和不规则的。因此，不能提出任何预处理步骤。在获取图像时，你必须注意到符号是尽可能平坦的，以防止这种情况的发生。如果你的符号是印在像纸这样有弹性的表面上，你可以用玻璃板把它们压平。但是，你必须非常小心，并考虑合适的照明条件。否则，您可能会因为下一节所描述的反射而遇到问题。

5.2.2 Radiometric Distortions

5.2.2辐射畸变

        除了符号网格的正确几何形状外，符号模块的对比度和统一外观，特别是它们的极性，对于二维数据码的解码至关重要。HDevelop 例程2d_data_codes_arbitrary_distortions.hdev搜索另外两个图像的符号。这些包含印在反射面上的符号。图5.13所示的图像反射非常强，以至于符号的某些部分的对比度接近0，也就是说，关于这些部分的模块的信息不再可用。因此，符号不能通过预处理重构，2D数据码读取失败。

        图5.14说明了由于光照条件差而产生的另一个问题。在这里，由于反射，两个符号的极性发生了变化。这就导致了一些问题，因为在大多数情况下，符号中模块外观的改变是无法处理的。

        对于这两种情况，没有预处理可以合理地改善图像，使符号再次可读。因此，在图像采集时使用漫射光避免强反射尤为重要。

5.3 Requirements and Limitations

5.3要求和限制

        为了成功地读取2D数据代码，符号的表示必须满足一定的要求。其中一些已在前几节中说明。通常，不应超过为单个参数指定的值范围。大多数限制是软的，也就是说，有时可以读取符号，尽管它们的参数值并不完全在指定的范围内。但由于不能保证这一点，您应该尽量遵守第5.3.1节总结的规则。第5.3.2节给出了与符号大小和外观相关的参数组允许的值范围的简明列表。

5.3.1 Main Rules to Follow

5.3.1主要规则遵循

所有符号类型:

        •符号(如果需要，包括安静区)必须完全包含在图像中。

       •模块必须适合一个规则的网格，因此应该有大致相同的大小。对于矩阵码，网格沿着整个符号必须是规则的，而对于PDF417码，它只需要在单个列内是规则的。一些错误高达半个模块大小的位移(当` module_grid `设置为` variable `时，数据矩阵ECC 200高达整个模块大小)可以处理，而查找器模式的错误比数据模块的错误更糟糕

       •一个符号的模块的外观应该是统一的。特别是符号内的极性不能改变。

       •虽然允许最小对比度为1，但为了稳定的结果，符号的前景和背景之间的对比度应最小为10。

PDF417:

        •为了稳定的结果，模块的最小宽度不应该低于3像素。

        •在符号的边界，每个方向上应该有一个至少2个模块宽度的安静区。

        •模块之间不允许有间隙。

ECC 200:

        •为了稳定的结果，模块的最小大小不应该低于4像素。

        •在符号的边界，每个方向上都应该有一个至少一个模块宽度的安静区。

        •模块之间允许有间隙，但不应超过模块尺寸的50%。

        •虽然理论上允许，但不应超过最大倾斜角度0.5235(30度)。

二维码:QR Code：

        •为了稳定的结果，模块的最小大小不应该低于4像素。

        •在符号的边界，每个方向上应该有一个至少4个模块宽度的安静区。

        •模块之间允许有间隙，但不应超过模块尺寸的50%。

        •三个位置检测模式中至少有两个必须是可见的。

Micro QR Code:

        •为了稳定的结果，模块的最小大小不应该低于4像素。

        •在符号的边界，每个方向上应该有一个至少2个模块宽度的安静区。

        •模块之间允许有间隙，但不应超过模块尺寸的50%。

        •位置检测模式必须是可见的。

Aztec Code:

        •为了稳定的结果，模块的最小大小不应该低于4像素。

        •在标志的边界处不需要设置安静区。

        •模块之间允许有间隙，但不应超过模块尺寸的50%。

DotCode:

        •为了稳定的结果，模块的最小大小不应该低于4像素。

        •在符号的边界，每个方向上都应该有一个至少3个模块宽度的安静区。

        •模块之间允许有间隙，但不应超过模块尺寸的10%。

5.3.2 Valid Parameter Ranges

5.3.2有效参数范围

        下面的列表简要总结了与单个符号类型的大小和外观相关的参数组的有效值范围。属于每个组的参数名的完整列表可以在参考手册中set_data_code_2d_param操作符的描述中找到。

注意，在增强模式下(参见第11页3.1节)，2D数据码阅读器检查上述所有值的范围，除了以下参数:

        •所有符号类型的最小对比度(允许范围:1 - 100，默认增强模式:10)，

        •矩阵代码的最大模块大小(允许范围:2 - 200，增强模式默认:100)，

        •PFD417的模块宽高比(允许范围:0.5 - 20，最小模块宽高比默认增强模式:1.0，最大模块宽高比默认增强模式:10)，

        •数据矩阵ECC200的最大倾斜(允许范围:0 - 0.7，增强模式默认:0.5235)，

        •小模块鲁棒性(允许范围: low, high, 增强模式默认:low)，

        •查找器模式容差的ECC 200符号(允许范围: low, high, any,默认在增强模式:low)。

        •ECC 200符号的对比度公差(允许范围: low, high, any，默认增强模式:low)。

为了获得稳定的结果，建议不要超过增强参数集指定的值范围。