二维码的一些参数记录set_data_code_2d_param

set_data_code_2d_param

set_data_code_2d_param算子用于设置或更改二维数据码模型的不同参数，以使模型适应特定的符号外观。所有参数也可以在使用create_data_code_2d_model创建二维数据码模型时进行设置。可以使用get_data_code_2d_param查询数据码模型的当前配置。通过query_data_code_2d_params返回可以为给定的二维数据码类型设置的所有参数名称的列表。
关于二维数据码读取器的概念，请参见“识别/数据码”章节的介绍。
请注意，GS1 DataMatrix、GS1 QR Code、GS1 Aztec Code和GS1 DotCode的符号结构分别与Data Matrix ECC 200、QR Code、Aztec Code和DotCode的结构相同。因此，适用于Data Matrix ECC 200、QR Code、Aztec Code或DotCode的所有特定符号参数也适用于它们对应的GS1变体。在以下内容中，为了便于阅读，省略了对任何特定GS1代码的参数的明确列举。相反，可以从对应非GS1代码类型的参数中推断出相关参数名称，或者可以通过带有参数’set_model_params’的query_data_code_2d_params显式查询。
以下概述列出了不同的通用参数及其各自的价值范围和标准模式（“standard_recognition”）下的默认值。如果增强模式（“enhanced_recognition”）下的默认值与标准模式下的不同，则会额外列出。同样，如果最大模式“maximum_recognition”下的默认值与增强模式下的不同，也会列出：

注意：在调用set_data_code_2d_param更改符号的大小或形状后，参数将按给定顺序进行评估。在每个参数之后，会检查当前设置的一致性，并在必要时调整当前设置。因此，进行更改的顺序可能会影响最终设置。

symbol_cols_min：
符号中模块列的最小数量。
取值范围：[10, 12, 14, … 144]
注意：更改symbol_cols_min会将symbol_shape设置为“any”。如果当前符号的大小仅与一种形状类型一致，则symbol_shape将被限制为“rectangle”或“square”。
默认值：10

symbol_cols_max：
符号中模块列的最大数量。
取值范围：[10, 12, 14, … 144]
注意：更改symbol_cols_max会将symbol_shape设置为“any”。如果当前符号的大小仅与一种形状类型一致，则symbol_shape将被限制为“rectangle”或“square”。
默认值：144

symbol_rows_min：
符号中模块行的最小数量。
取值范围：[8, 10, 12, … 144]
注意：更改symbol_rows_min会将symbol_shape设置为“any”。如果当前符号的大小仅与一种形状类型一致，则symbol_shape将被限制为“rectangle”或“square”。
默认值：8

symbol_rows_max：
符号中模块行的最大数量。
取值范围：[8, 10, 12, … 144]
注意：更改symbol_rows_max会将symbol_shape设置为“any”。如果当前符号的大小仅与一种形状类型一致，则symbol_shape将被限制为“rectangle”或“square”。
默认值：144

symbol_cols：
将symbol_cols_min和symbol_cols_max设置为给定值。
取值范围：[10, 12, 14, … 144]
注意：更改symbol_cols会将symbol_shape设置为“any”。如果当前符号的大小仅与一种形状类型一致，则symbol_shape将被限制为“rectangle”或“square”。

symbol_rows：
将symbol_rows_min和symbol_rows_max设置为给定值。
取值范围：[8, 10, 12, … 144]
注意：更改symbol_rows会将symbol_shape设置为“any”。如果当前符号的大小仅与一种形状类型一致，则symbol_shape将被限制为“rectangle”或“square”。

symbol_shape：
对模块形状的可能限制（“rectangle”和/或“square”）。
注意：设置符号形状时，之前关于符号大小的所有限制可能会改变。对于“square”，将使用symbol_cols_min和symbol_rows_min的最小值以及symbol_cols_max和symbol_rows_max的最大值。其他限制可以在下表中看到：

此外，如果symbol_cols_min大于symbol_rows_max，则忽略symbol_shape的设置，并将其值设置为“rectangle”。
如果finder_pattern_tolerance设置为“low”，则两种形状使用相同的搜索算法。因此，在这种情况下，symbol_shape对符号搜索没有影响。然而，如果finder_pattern_tolerance设置为“high”或“any”，则将symbol_shape设置为“rectangle”或“square”可能会显著加快符号搜索的速度。
取值：‘rectangle’（矩形）、‘square’（正方形）、‘any’（任意）

symbol_size_min：
将symbol_cols_min和symbol_rows_min设置为给定值，并将symbol_shape设置为“square”。

symbol_size_max：
将symbol_cols_max和symbol_rows_max设置为给定值，并将symbol_shape设置为“square”。

symbol_size：
将symbol_cols_min、symbol_cols_max、symbol_rows_min和symbol_rows_max设置为给定值，并将symbol_shape设置为“square”。

polarity：
描述图像中符号的极性，即该参数确定符号是在深色背景上呈现为亮色，还是在亮色背景上呈现为深色。
取值：‘dark_on_light’（深色在亮色上）、‘light_on_dark’（亮色在深色上）、‘any’（任意）。
默认值：‘dark_on_light’（默认：深色在亮色上，增强模式下：任意）

mirrored：
描述符号是否被镜像（这相当于交换符号的行和列）。
取值：‘no’（否）、‘yes’（是）、‘any’（任意）
默认值：‘any’（任意）

contrast_min：
符号前景与背景之间的最小对比度（以灰度值差异指定）。这一度量与符号前景与背景之间的最小梯度相对应，因此也取决于图像的清晰度。
取值范围：[1 … 255]
默认值：30（增强模式下：10）

module_size_min：
图像中模块的最小尺寸，以像素为单位。请注意，为了获得最佳读取性能，建议模块尺寸至少为3-4像素。
取值范围：[1 … 100]
默认值：6（增强模式下：2，最大模式下：1）
对于DotCode：
默认值：4（增强模式和最大模式下：2）

module_size_max：
图像中模块的最大尺寸，以像素为单位。
取值范围：[2 … 100]
默认值：20（增强模式下：100）
对于DotCode：
默认值：100

module_size：
将module_size_min和module_size_max设置为相同的值。
可以通过以下段落中解释的module_gap*参数来设置模块之间的间隔：
可以指定相邻的前景模块是否相连，或者它们之间是否存在或可能存在间隙。如果前景模块相连并完全填充模块空间，则可以将间隙参数设置为“no”。如果两个模块之间存在非常小的间隙，即小于模块尺寸的10%，则可以将参数设置为“small”。如果间隙更大（相对于模块尺寸：<50%），则可以设置为“big”。最后两种设置也可能适用于前景模块虽然相连，但看起来比其应有的空间更细的情况（例如，由于明亮的照明源导致的光晕效应）。如果前景模块仅显示为非常小的点，则通常需要对图像进行适当的预处理，以便检测或放大模块（例如，通过gray_erosion_shape或gray_dilation_shape）。

module_gap_min：
最小间隙。
取值：‘no’（无）、‘small’（小）、‘big’（大）（'big’对DotCode不可用）
默认值：‘no’

module_gap_max：
最大间隙。
取值：‘no’（无）、‘small’（小）、‘big’（大）
默认值（Data Matrix ECC 200）：‘no’（默认：无，增强模式下：‘small’，最大模式下：‘big’）
默认值（DotCode）：‘no’（默认：无，增强模式下：‘small’，最大模式下：‘small’）
默认值（Aztec Code、Micro QR Code、QR Code）：‘small’（默认：小，增强模式下：‘big’）

module_gap：
将module_gap_min和module_gap_max设置为相同的值。

slant_max：
L形定位图案角度相对于（理想）直角的最大偏差（角度以弧度为单位指定，对应于符号打印或图像采集过程中可能出现的失真）。
取值范围：[0.0 … 0.5235]
默认值：0.1745（约等于10度）（增强模式下：0.5235，约等于30度）

finder_pattern_tolerance：
搜索时对于有缺陷或部分被遮挡的定位图案的容差。定位图案包括L形的一侧以及对面交替的一侧。根据此参数，在find_data_code_2d的符号搜索过程中会使用不同的算法。在一种情况下（“low”），假定定位图案高度存在且几乎不受干扰。在另一种情况下（“high”），定位图案可能存在缺陷或部分被遮挡，但不影响符号的识别和读取。不过，需要注意的是，在这种模式下，应尽可能通过使用set_data_code_2d_param来限制符号搜索的参数，否则find_data_code_2d的运行时间可能会显著增加。还需要注意的是，这两种算法在稳健性方面略有不同。这可能会导致即使符号的定位图案没有受到干扰，根据finder_pattern_tolerance的值也会产生不同的结果。例如，如果选择“high”，则只能找到具有等距模块网格的符号（见下文），因此对透视失真的稳健性会降低。最后，如果将finder_pattern_tolerance设置为“any”，则会应用这两种算法。
取值：‘low’、‘high’、‘any’

slant_max：
L形定位图案角度相对于（理想）直角的最大偏差（角度以弧度为单位指定，对应于符号打印或图像采集过程中可能出现的失真）。
取值范围：[0.0 … 0.5235]
默认值：0.1745（增强模式下：0.5235）

contrast_tolerance：
描述搜索对于局部对比度变化的容差（例如，在存在眩光或反射的情况下）。根据该参数的值，会应用两种不同的算法。如果将contrast_tolerance设置为“high”，则在存在强烈局部对比度变化的情况下，稳健性会得到提高。如果将contrast_tolerance设置为“low”，则算法在强烈局部对比度变化的情况下不够稳健，但它速度更快，并且在正常情况下仍能处理对比度变化，因此应在大多数情况下使用。如果将contrast_tolerance设置为“any”，则会应用这两种算法。
取值：‘low’、‘high’、‘any’
默认值：‘low’（增强模式下：‘low’，最大模式下：‘any’）

module_grid：
描述模块的大小是否可以在特定范围内变化，或者是否固定不变。根据此参数，用于计算模块中心位置的不同算法会被使用。如果设置为“fixed”，则使用等距网格。允许模块大小变化（“variable”），则网格仅与定位图案的交替边对齐。“any”选项会依次测试这两种方法。请注意，如果“finder_pattern_tolerance”设置为“high”，则会忽略“module_grid”的值。在这种情况下，假定使用等距网格。
取值：‘fixed’（固定）、‘variable’（可变）、‘any’（任意）
默认值：‘fixed’（默认：固定，增强模式下：任意）

persistence：
控制使用find_data_code_2d进行符号搜索时的某些中间结果是临时存储还是持久存储在模型中。如果数据是临时存储的（默认设置），find_data_code_2d的内存需求会显著减少。另一方面，通过使用持久存储，可以在搜索符号后出于调试原因访问某些数据，例如，调查为什么某个符号无法被读取。通过将“persistence”设置为-1，可以进一步减少find_data_code_2d的内存需求，这样只有解码数据所需的必要数据会与模型一起存储。请注意，只有在这种“persistence”设置下，才能对Data Matrix ECC 200符号进行印刷质量检测。
取值：-1（仅解码数据），0（临时），1（持久）
默认值：0

discard_undecoded_candidates：
控制那些未能成功解码的候选对象是否存储在模型中。将此参数设置为“yes”可以减少模型所占用的内存量。请注意，在这种情况下，无法使用get_data_code_2d_objects或get_data_code_2d_results查询有关未解码候选对象的信息。
取值：‘yes’（是），‘no’（否）
默认值：‘no’

strict_model：
控制find_data_code_2d在检测可以读取但不符合模型对符号大小限制的符号时的行为。这些符号可以被拒绝（严格模型，设置为“yes”），或者作为结果返回，无论其大小和模型中指定的大小如何（宽松模型，设置为“no”）。请注意，即使将“strict_model”设置为“yes”，对于DotCode符号，也不会检查模块大小限制（“module_size_min”和“module_size_max”）。
取值：‘yes’（严格），‘no’（不严格）
默认值：‘yes’

string_encoding：
设置符号中编码的字符串的预期字符串编码。可以在UTF-8、Latin-1和当前区域设置的字符串编码之间切换。如有必要，字符串将相应地进行转码。在原始模式下，字符串将不经过更改地传递。
取值：‘utf8’，‘locale’，‘latin1’，‘raw’
默认值：‘latin1’

timeout：
通过使用此参数，可以在定义的毫秒数后终止find_data_code_2d。这在需要确保最大循环时间的情况下特别有用。在超时之前获得的所有结果都可以通过get_data_code_2d_results访问。传递小于或等于零的值意味着禁用超时（默认）。
时间精度大约为10毫秒。这取决于多个因素，包括计算机的速度、图像大小以及通过set_system设置的“timer_mode”。
即使发生超时，find_data_code_2d也不会引发异常。要检查find_data_code_2d是否被中断，可以检查get_data_code_2d_results中的“aborted”参数。
请注意，如果find_data_code_2d以训练模式运行，则会忽略超时。
典型值：‘false’，-1，20 … 100
默认值：‘false’

abort：
使用此选项，可以从另一个线程终止find_data_code_2d。当使用set_data_code_2d_param调用“abort”时，会请求另一个线程中运行的find_data_code_2d实例（使用模型DataCodeHandle）终止。如果没有使用此模型运行的find_data_code_2d，则不会发生任何操作。
find_data_code_2d可能不会立即返回。它需要到达一个取消点，以确保适当的清理。根据不同的因素，如计算机性能，这可能需要长达10毫秒。
直到这一刻解码的所有结果仍然会返回。请注意，如果find_data_code_2d以训练模式运行，则会忽略此参数。
注意：这是唯一可以在不同线程中使用而无需额外同步的数据代码句柄操作。
默认值：‘true’（该值不会被处理。）

strict_quiet_zone：
控制find_data_code_2d在检测可以读取但其静区存在缺陷的符号时的行为。如果将strict_quiet_zone设置为“yes”，则所有解码符号的静区将类似于印刷质量检测中使用的方法进行验证。静区等级较差的符号不会作为结果返回。它们的“status”会被设置为“静区缺失”。如果将strict_quiet_zone设置为“no”（这是默认情况），则所有可读的符号都会作为结果返回。
取值：‘yes’（是），‘no’（否）
默认值：‘no’

quality_isoiec15415_aperture_size：
用于评估符号对比度、调制、反射率边缘和固定图案损坏质量等级的参考图像，是通过对原始图像应用合成光圈（圆形均值滤波器）获得的。此参数确定滤波器大小作为模块大小的一部分。根据标准，应根据应用情况在0.5到0.8之间选择此值。
有关选择光圈的进一步指导，请参见ISO/IEC 15415:2011附录D.2。
取值范围：[0 … 1]
默认值：0.8

quality_isoiec15415_reflectance_reference：
用于评估符号对比度质量等级的对比度是通过一个反射率的参考灰度值进行归一化的。此值可以通过使用硫酸钡或氧化镁样本等获得，详见ISO/IEC 15415:2011第7.3节。取值范围：[1 … 255]
默认值：255

quality_isoiec15415_smallest_module_size：
用于确定合成光圈大小的模块大小。这可以是一个固定的像素值，也可以是“adaptive”。在后一种情况下，使用前面find_data_code_2d获得的模块大小。最终滤波器的直径是通过将quality_isoiec15415_aperture_size与此大小相乘得到的。详见ISO/IEC 15415:2011第7.3.3节。取值范围：>= 0
默认值：‘adaptive’

quality_isoiec15415_decode_algorithm：
质量等级的计算是基于为印刷质量分级确定的模块网格。使用此参数选择用于获取此网格的算法。
robust：
适用于没有基于ISO/IEC 15415:2011的校准相机和照明设置的过程控制事项。返回的质量等级以及分级参数的计算符合国际标准ISO/IEC 15415:2011。为了弥补由于硬件设置灵活性导致的差异，使用解码过程中收集的额外信息以及对硬件设置的假设来增加质量检测的稳健性。
reference：
适用于印刷质量的验证。根据国际标准ISO/IEC 15415:2011，验证需要特定的相机校准以及照明设置，以返回符合标准的分级结果。与标准不同的是，我们在计算常数时，明确应用了20%的相对光圈因子的下限。此外，如果模块大小（由前面的find_data_code_2d调用确定）降至4像素以下，则无法使用该算法，所有等级均报告为-1。这些规定的下限有助于为参考解码算法定义一个合理的应用范围。最后，如果在模块网格确定过程中算法失败，所有等级将被设置为-1。
默认值：‘robust’

candidate_selection：
控制用于符号检测的候选区域的选择。将此参数设置为“extensive”会增加生成的候选区域的数量，从而增加检测到代码的可能性。然而，更多的候选区域可能会导致运行时间增加。如果将“candidate_selection”设置为“default”，则使用较少的候选区域。在大多数情况下，这个较小的候选区域集合已经足够。
取值：‘default’（默认），‘extensive’（广泛）
默认值：‘default’（默认：‘default’，增强模式下：‘extensive’）

decoding_scheme：
控制Data Matrix ECC 200的解码步骤。将其设置为“raw”时，可以读取外观和错误校正步骤符合ISO/IEC 16022:2006，但编码是自定义的符号。解码后的数据是经过错误校正的数据，可以通过get_data_code_2d_results的“decoded_data”参数获取，并且必须由用户进一步处理。
取值：‘default’（默认），‘raw’（原始）
默认值：‘default’