Halcon set_system算子解析

Halcon版本：18.11

目录

Graphic:

Image Processing:

Parallelization:

File:

Directories:

Other:

参考文章：

---

并行化信息：请注意，这些参数中的一些是以独占方式设置的，这意味着它们会阻止其他线程，直到没有其他操作符访问HALCON库。              

1. 以*)标记的参数：全局有效，且排外

2. 无*)标记且不以tsp_为前缀：全局有效，且非排外。即不会阻塞其它调用操作

3. tsp_前缀：

      1). 无tsp_前缀，对当前线程以及在该操作之后启动的线程均有效，但在调用之前启动的线程无效

      2). 有tsp_前缀，仅对当前线程有效。其它已经运行的线程不受影响

Graphic:

'flush_graphic':

在每一个有图形输出的HALCON算子执行之后，一个flush操作将被执行，以便于输出图形能够被立即的显示到图形窗口。这个操作并不是对所有程序都是必须的。在这种情况下，参数"flush_graphic"可以被设置为false，以提高系统运行效率。

注意：由于在HALCON13及其以后的版本中使用"flush_graphic"，可能产生无法预料的结果。因此，不推荐使用。作为替代，可以使用SetWindowParam操作，设置其"flush"属性为"false"。在需要显示图形的时候调用FlushBuffer操作获取显示。

"int2_bits":

int2类型的图像使用的有效位数。该值在缩放灰度值的时候使用。如果该值设置为-1，灰度值将被自动地进行缩放。

"backing_store":

在窗口重叠的时候是否执行窗口内容的刷新。

"icon_name":

图形窗口的名称

"default_font" *):

图形与文本窗口的默认字体。可以利用 query_font算子查询可用字体。

"update_lut":

HALCON的颜色表是否自适应环境

"use_window_thread":

"graphic_stack_size":

当使用AttachDrawingObjectToWindow或AttachBackgroundToWindow添加一个DrawingObject或Image到窗口，所有的显示对象将被存储在一个栈中。这个栈的大小是有限的。图形变量的数目超过该限制尺寸，最先进栈的图形变量将被移出，新的图像变量进入。可以通过设置该参数为一个大的整型值或者0。设置为0，表示该栈的到校是没有限制的。该设置只对在该设置命令执行之后的窗口有效，对已经打开的窗口无效。

"x_package":

通过网络输出图像数据可能会由于计算机或网络上的负载过大而导致错误。为了避免这种情况，数据以小包传输。如果显示器是在本地使用（而不是通过网络使用），这些单元可以随意放大。这可以显著提高输出性能。

Image Processing:

'neighborhood', 'tsp_neighborhood':

4联通还是8联通

 'init_new_image', 'tsp_init_new_image':

'no_object_result', 'tsp_no_object_result':

确定当对象元组为空（没有对象）时，处理图标对象的操作将如何反应。

 'empty_region_result', 'tsp_empty_region_result':

同上

 'store_empty_region', 'tsp_store_empty_region':

很多算子会创建具有空区域（没有图像点）的对象。此参数确定是否将返回带有空区域的对象作为结果（“true”）还是将忽略该对象（不返回任何结果）（“false”）。

 'clip_region', 'tsp_clip_region':

是否将区域剪裁为当前使用的图像大小

'int_zooming':

当缩放图像时使用浮点数还是整数运算

 'pregenerate_shape_models':

 'border_shape_models':

 'opengl_context_cache_enable':

此参数确定是否缓存操作符render_object_model_3d中使用的图形卡上下文，以便将来使用此运算符。缓存加速了该运算符的未来使用，但需要额外的资源。若要显式删除上下文，请将“opengl_context_cache_enable”设置为“false”，并调用render_object_model_3d一次如果图形卡支持三维对象模型的渲染，则opengl上下文缓存启用只能设置为“true”。

 'opengl_hidden_surface_removal_enable':

'opengl_compatibility_mode_enable':

'image_dpi':

 'width', 'tsp_width'

系统的内部图像宽度。如果操作符没有进一步的图像信息，则该大小用于剪裁区域或实现内存大小的假设。此大小被解释为所有HALCON图像对象的最大宽度。如果随后实例化更大宽度的图像，则该值将增加。另请参见重置目标数据库。请注意，HDevelop中的默认值是512（如果导出代码），否则为128。

 'height', 'tsp_height'

同上

 'current_runlength_number', 'tsp_current_runlength_number':

Parallelization:

'parallelize_operators' *)

确定HALCON是否使用自动并行化来加速多处理器计算机上运算符的处理。通过将“parallelize_operators”设置为“false”，可以关闭此功能。即使这样，HALCON仍将保持可重入（和线程安全），除非通过set_system将参数“reentrant”设置为“false”。更改“parallelize_operators”的值可能会有所帮助，例如，如果HALCON运算符由多线程应用程序调用，该应用程序也会自动执行运算符和数据的调度和负载平衡。然后，HALCON可能会执行额外的并行化步骤，这可能会干扰应用程序的调度和负载平衡概念。为了更详细地控制自动并行化，可以打开和关闭单一的数据并行化方法，"split_tuple“启用元组并行化方法，“split_channel”启用图像通道上的并行化，“split_domain”启用图像域上的并行化，“split_partial”启用运算符的部分内部并行化。前面的“~”将禁用相应的方法。方法字符串也可以在控制元组中传递，以便一次打开或关闭自动数据并行化方法。E、 g.，[“split_tuple”、“split_channel”、“split_domain”、“split_partial”]等同于“true”。

 'reentrant' *)

确定HALCON是否必须可重入才能在并行编程环境（例如，多线程应用程序）中使用。如果设置为'true'，HALCON在内部使用同步机制来保护共享数据对象免受并发访问。尽管这对于任何有效的并行工作应用程序都是不可避免的，但是如果在纯粹按顺序工作的应用程序中使用，则可能会导致不希望的开销。后一种情况可以通过将“reentrant”设置为“false”来表示。这将关闭所有内部同步机制，从而减少开销。当然，HALCON不再是线程安全的，这会导致另一个副作用：HALCON将不再使用操作符的内部并行化，因为这需要可重入性。将“reentrant”设置为“true”会将HALCON重置为其默认状态，即它是可重入的（并且是线程安全的），并且它使用自动并行化来加快多处理器计算机上运算符的处理速度。

 'thread_num' *), 'tsp_thread_num'

设置HALCON自动运算符并行化（aop）使用的线程数。该数量包括调用线程，出于效率考虑，它仅限于处理器的数量。如果处理器除了自动并行化的线程之外还被用户工作线程占用，那么减少线程的数量是很有帮助的。这样，处理线程的数量可以根据处理器的数量进行调整，以获得最佳效率。如果为HALCON进程设置了处理器相关性，则参数值“default”会将线程数重置为分配的处理器数。否则，'default'将线程数设置为处理器的数量。如果使用特定于线程的变量，HALCON将为调用线程专门保留指定数量的线程。如果到目前为止没有为特定线程设置线程号，get_system将为参数值“tsp_thread_num”返回值-1。所有线程特定的保留aop线程的总和不能超过由“thread_num”设置的线程数。指定线程编号1将关闭自动并行化（指定时为特定于线程）。

 'thread_pool' *)

指示HALCON是始终为自动并行化创建新线程（“false”）还是使用现有线程池（“true”）。使用线程池对于自动并行化更有效。当永久关闭自动并行化时，停用线程池可以节省操作系统的资源。

File:

'flush_file':

此参数确定运算符fwrite_string的输出字符是否直接显示在输出媒体上。如果设置为“false”，则只有在输入运算符fnew_line后才会刷新字符。

 'ocr_trainf_version'

此参数确定保存OCR训练文件的格式

 'filename_encoding':

 'write_halcon_files_encoding':

从HALCON 18.05开始，所有存储用户定义字符串的专有HALCON文件在数据序列化或写入文件时使用UTF-8作为默认字符串编码。编码主要涉及HALCON元组以及OCR和OCV分类器、训练数据和样本标识符，它们都存储用户定义的类或字符名。这允许在不同的操作系统、国家和地区之间轻松地共享这些文件。如果使用旧版HALCON（早于HALCON 18.05）构建的应用程序应使用此类具有特殊字符的文件，并依赖于字符串的区域设置编码，则可以使用此选项强制HALCON使用当前区域设置系统编码而不是UTF-8编写其文件。请注意，更改后的编码仅涉及存储带有特殊字符的字符串（即非纯ASCII字符）的文件。此外，此选项不影响可以使用“打开的文件”打开的用户文件。

'read_halcon_files_encoding_fallback':

默认情况下，使用区域设置系统编码读取旧的专有HALCON文件（HALCON 18.05之前）。如果旧的HALCON文件是用UTF-8编写的，则可以使用此参数更改读取的编码。这主要涉及HALCON元组以及OCR和OCV分类器、训练数据和示例标识符，它们都存储用户定义的类或字符名。请注意，此选项对读取新的HALCON文件和仅包含纯ASCII字符的文件没有影响。此外，此选项不影响可以使用“打开的文件”打开的用户文件。

'tuple_string_operator_mode', 'tsp_tuple_string_operator_mode':

Version:1.0 StartHTML:0000000105 EndHTML:0000008287 StartFragment:0000000127 EndFragment:0000008269

Directories:

'halcon_dir' *):

Halcon安装的根目录

'example_dir' *):

HDevelop示例程序（例如，通过浏览HDevelop程序示例对话框或通过参考手册中的HDevelop示例部分加载）将在“example_dir”目录中查找。请注意，如果将“example_dir”设置为不包含已安装的HDevelop示例程序的目录，则上述加载HDevelop示例程序的机制将失败。

'image_dir' *):

图像文件（例如，通过read_Image和read_sequence获取）将在当前使用的目录和“Image_dir”（如果没有指定绝对路径）中查找。可以指定多个目录名（搜索路径），用分号（Windows）或冒号（类Unix系统）分隔。也可以使用环境变量HALCONIMAGES来确定路径。

'3d_model_dir' *):

三维对象模型文件（例如，通过read_object_model_3D获取）将在当前使用的目录和“3D_model_dir”（如果没有指定绝对路径）中查找。可以指定多个目录名（搜索路径），用分号（Windows）或冒号（类Unix系统）分隔。

'lut_dir' *):

作为ASCII文件实现的颜色表（set_lut）将在当前使用的目录和“lut_dir”（如果没有指定绝对路径）中查找。默认情况下，HALCON将搜索子目录“lut”中的颜色表。

'help_dir' *):

联机文本文件{German or English}.hlp、.sta、.key.num和.idx将在当前使用的目录或“help”指定的路径中查找。例如，当使用运算符get_operator_info和get_param_info时，此系统参数是必需的。它也可以在初始化HALCON之前由环境变量HALCONROOT设置。在这种情况下，变量必须指示帮助目录上方的目录（即HALCON主目录）。

Version:1.0 StartHTML:0000000105 EndHTML:0000073781 StartFragment:0000000127 EndFragment:0000073763

Other:

'disabled_operators'

此参数允许禁用特定的HALCON运算符。如果程序允许运行用户创建的HDevelop脚本，但出于安全原因，不应允许某些操作员（例如system_call运算符），则此选项很有用。任何试图执行禁用运算符的操作都将引发异常H\u ERR_OP_disabled（9055）。请注意，一旦一个操作符被禁用，它就不能在进程的剩余生命周期内重新启用。

此参数的值是一个元组，包含要禁用的所有运算符的名称。

'do_low_error'

确定有关HALCON低级错误的行为

'cancel_draw_result', 'tsp_cancel_draw_result':

'seed_rand'

设置运算符tuple_rand、add_noise_white、add_noise_distribution、gen_random_region和add_noise_white_contour_xld中使用的线程特定随机生成器的种子。如果没有设置种子，随机生成器将在第一次调用上面列出的运算符时使用当前系统时间进行种子设定。然后可以使用get_system查询用作种子的值。

'cudnn_deterministic'

确定用于深度学习的cuDNN库是否使用确定性算法来在不同的体系结构中强制位的可再现性。请注意，在某些架构上使用确定性算法会减慢计算速度。

'clock_mode'

使用count_seconds算子时，时间间隔的测量模式。

“performance_counter”以最好的高精度测量经过的系统时间。HALCON使用操作系统提供的最精确的时间测量方法。如果没有高精度的测量方法，则使用较低分辨率的方法。在Windows系统上，使用性能计数器。有关Windows上性能计数器的详细信息，请参阅Microsoft Developer Network（MSDN）文档。性能计数器提供最高精度（低于1毫秒）。但是，由于能量管理和/或多线程问题，它可能无法在某些系统上正常工作。如果操作系统不支持性能计数器，则应用“multimedia_timer”设置。在类Unix的系统（例如Linux和macOS）上，精度通常也低于1毫秒，并且可能会受到由于能量管理和/或多线程处理而产生的问题的影响。如果遇到此类问题，应使用“elapsed_time”设置。

“elapsed_time”测量已用系统时间，与设置“performance_counter”类似。不同之处在于，使用的测量方法精度较低，但不会受到能量管理和/或多线程问题的太大影响。精度一般为1毫秒。如果使用“performance_counter”进行的测量不可靠且可以接受精度为1毫秒，则应使用此设置。

“multimedia_timer”使用Windows上的多媒体计时器测量经过的系统时间。有关多媒体计时器的详细信息，请参阅Microsoft Developer Network（MSDN）文档。这种方法的分辨率一般为1毫秒。如果您的系统无法实现这样的分辨率，您可以使用Windows函数“timerBeginPeriod”和“timerEndPeriod”来提高精度（请参阅MSDN）。在类Unix的系统上没有多媒体计时器，因此设置“performance_counter”适用。

“processor_time”测量正在运行的HALCON进程占用CPU的时间。这种测量时间与其他进程引起的CPU负载无关，但它在大多数系统上的分辨率较低，因此在较小的时间间隔内精度较低。请注意，许多应用程序的运行时间不仅受CPU处理时间的影响。很多应用程序都会受到输入/输出或内存管理的影响。对于此类应用，应使用设置“performance_counter”或“elapsed_time”。

请注意，设置“performance_counter”和“elapsed_time”度量已用系统时间。测量的时间间隔受系统负载的影响。如果这些设置用于度量给定应用程序的运行时，则应确保其他进程不会影响度量。

'timer_mode'

确定支持超时的算子使用的测量模式

'max_connection'

connection返回的最大区域数。如果值为0，则返回所有区域

'extern_alloc_funct'

'extern_free_funct' *)

'image_cache_capacity' *)

为了加快新图像的分配，HALCON不释放图像对象的图像内存，而是将其缓存以重新使用。通过这个参数，您可以为这个HALCON图像缓存设置一个以字节为单位的上限。只要未达到上限，就会缓存释放的图像。可以通过将“图像缓存容量”设置为0来关闭此功能。

'global_mem_cache'

全局内存的高速缓存模式，即在运算符之外可见的内存。它指定未使用的全局内存是缓存（“shared”）还是释放（“idle”）。通常，缓存以消耗内存为代价加快内存分配和处理。此外，HALCON还提供了为每个线程单独缓存全局内存的选项（“exclusive”）。这种模式还可以以较高的内存消耗为代价来加速处理。使用参数“cleanup”，缓存内存块可以再次物理释放。

'temporary_mem_cache' *), 'tsp_temporary_mem_cache'

此参数控制临时内存缓存的操作模式。临时内存缓存用于通过缓存在执行运算符期间临时使用的内存来加速应用程序。对于大多数应用程序，默认设置（'exclusive'）将产生最佳结果。支持以下模式：

“idle”临时内存缓存被关闭。此模式将使用最少的内存，但与其他模式相比，也会降低性能。

“shared”所有临时内存全局缓存在临时内存库中。与“独占”模式相比，此模式使用的内存更少，但通常也会提供更少的性能。

“exclusive”为每个线程本地缓存所有临时内存。此模式将使用最多的内存，但通常也会提供最佳性能。

“aggregate”临时内存块大于使用“alloctmp_max_blocksize”参数设置的阈值，这些临时内存块将缓存在全局内存库中，而所有较小的内存块将聚合到单个块中，该块在本地为每个线程缓存。如果全局内存库被禁用，则会释放大的块。聚合块的大小将根据线程到目前为止看到的临时内存使用情况进行调整，但不会大于“alloctmp_max_blocksize”（如果设置）或小于“alloctmp_min_blocksize”（如果设置）。此模式可平衡内存使用和速度，但需要为应用程序的内存使用模式正确设置“alloctmp_min_blocksize”和“alloctmp_max_blocksize”，以提高效率。

请注意，缓存模式“idle”设置为独占运行模式，而其他模式设置为可重入模式。

为了向后兼容，还接受值“false”和“true”；它们分别对应于“idle”和“exclusive”。

'temporary_mem_reservoir', 'tsp_temporary_mem_reservoir'

如果设置为“true”，则启用全局临时内存库。如果它被设置为'false'，它将被禁用，所有放入存储库的内存块都将被释放。

任何需要一个新的临时内存块作为其临时内存缓存的线程将首先检查存储库是否有可用的块，如果没有，则只从系统中分配更多内存。块是由线程以“shared”或“aggregate”模式操作其缓存而放入库中的。

请注意，此参数的全局设置会覆盖特定于线程的设置，即，如果“temporary”设置为“false”，“tsp”将不起作用。

'temporary_mem_reservoir_size'

全局临时内存库可以缓存的最大内存量，以字节为单位。如果设置为-1，则缓存仅受可用内存量的限制。

'alloctmp_min_blocksize', 'tsp_alloctmp_min_blocksize'

临时内存缓存使用的最小内存块大小（字节）。（如果“临时内存缓存”==“空闲”，则无效。在默认设置为-1的情况下，HALCON将使用基于当前图像大小的启发式方法来确定一个合理的块大小。对于大多数应用，这将是最佳选择。如果HALCON的值大于0，则将使用大于此值的HALCON。请注意，如果运算符需要大于“alloctmp_min_blocksize”的临时内存对象，它将忽略此参数。

'alloctmp_max_blocksize', 'tsp_alloctmp_max_blocksize'

同上

'database' *)

确定实例化的图标对象是否应列在HALCON数据库的五个关系（gray-value data, region data, XLDs, iconic objects and object tuples）之一中。这些关系可用于调试等目的。另请参阅 count_relation, reset_obj_db.。请注意，在线程之间传递图标对象时，收集数据库信息不是线程安全的，这意味着删除不同线程中的对象而不是生成对象。

'mmx_enable'

'sse_enable'

'sse2_enable'

'sse3_enable'

'ssse3_enable'

'sse41_enable'

'sse42_enable'

'avx_enable'

'avx2_enable'

'avx512f_enable'

'avx512dq_enable'

'avx512bw_enable'

'avx512er_enable'

'avx512cd_enable'

'language' *)

用于错误消息的语言

'add_progress_callback'

'remove_progress_callback'

'legacy_handle_mode', 'tsp_legacy_handle_mode':

用于激活或停用传统句柄模式的标志。如果启用，则HALCON运算符返回的所有句柄都将转换为整数，并且所有HALCON运算符都接受整数作为句柄。请注意，如果启用传统句柄模式，则句柄在被覆盖时不再自动清除。相反，必须调用clear_handle或句柄类型的相应clear运算符。

还请注意，遗留句柄模式仅用于运行遗留代码。不建议在新代码中激活它。新的运算符或语言功能可能无法在旧版句柄模式下工作。

参考文章：

https://blog.csdn.net/zhy29563/article/details/82691046

https://blog.csdn.net/gukewee/article/details/105286326