| Operators |
set_system — Set HALCON system parameters.
set_system( : : SystemParameter, Value : )
The operator set_system allows to change different system parameters.
Parallelization information: Note that some of these parameters are set exclusively only, meaning they block other threads until no other operators are accessing the HALCON library.
Parameters marked by a *) are globally valid and are set exclusively.
Parameters without the mark *) and without the prefix 'tsp_' are also globally valid but are not set exclusively, i.e., the operator call does not block other operator calls.
Parameters with 'tsp_' variant are thread specific.
Without 'tsp_', they are set for all threads that are started after this call as well as for the current thread. Threads that are already running will not be affected.
Parameters called with 'tsp_' are only set for the current thread. Other threads that are already running will not be affected.
Available system parameters:
Graphic:
After each HALCON operation which creates a graphic output, a flush operation will be executed in order to display the data immediately on screen. This is not necessary for all programs, e.g., if everything is done with the help of the mouse. In this case 'flush_graphic' can be set to 'false' to improve the runtime. Note that this parameter has no effect on Unix-like systems because there, the window managers flush the display buffer automatically.
Note that using 'flush_graphic' is no longer recommended with HALCON 13 or later versions, since it can lead to unexpected results. Instead, please set the parameter 'flush' of set_window_param to 'false' and call flush_buffer to transfer the buffer to the graphics window.
Value: 'true' or 'false'
Default: 'true'
Number of significant bits of int2 images. This number is used when scaling the gray values. If the value is set to -1 the gray values will be scaled automatically (default).
Value: -1 or 9..16
Default: -1
Determines whether the window content will be refreshed in case of overlapping of the windows. Some implementations of X Windows are faulty; in order to avoid these errors, the storing of contents can be deactivated. In some cases it may be advisable to deactivate the security mechanism, if e.g., performance / memory is critical.
Value: 'true' or 'false'
Default: 'true'
Name of iconified graphics windows under X Windows. By default the number of the graphics window is displayed.
Value: Name of iconified graphics window.
Default: 'default'
Default font for text output in text and graphic windows. Available fonts can be queried with query_font. The syntax of possible fontnames in Value is described at set_font.
Value: Name of Font.
Default: 'fixed'
Determines whether the HALCON color tables are adapted according to their environment or not.
Value: 'true' or 'false'
Default: 'false'
On Microsoft Windows systems, calling any of the HALCON graphics operators from a thread other than the one that created the output window requires that there be an active message loop for that window. Setting this parameter to 'true' will automatically open all top-level HALCON graphics and text windows in a special window thread that will handle the message loop; all graphics operators directed at these windows will also be executed by that thread automatically. This parameter has no effect on non-Windows systems.
Value: 'true' or 'false'
Default: 'false'
Once a drawing object or an image is attached to a HALCON window with attach_drawing_object_to_window or attach_background_to_window, all displayed objects are internally stored in a stack. The size of this stack is limited per default. As soon as the number of displayed objects reaches the limit, the oldest entries in the stack are removed and substituted by the new objects. One can change this behavior by setting this limit to a bigger number or to zero. In the latter case the stack is unlimited, i.e., it will store as many objects as necessary. Calling clear_window empties the stack. Setting the limit only applies to windows opened after calling set_system, i.e., it does not apply to already opened windows.
Value: Size of the graphic stack
Default: 50
The output of image data via the network may cause errors due to the heavy load on the computer or on the network. In order to avoid this, the data are transmitted in small packages. If the display is used locally (as opposed to using it via network), these units can be enlarged at will. This can lead to a recognizably improved output performance. On X Window systems the maximum request size is queried when the first window is opened.
Value: Package size (in bytes).
Default: 131072
Image Processing:
This parameter checks either four pixels (in horizontal and vertical direction) or all eight neighboring pixels around one pixel. It is used with all operators that examine neighborhood relations: connection, get_region_contour, get_region_polygon, get_region_thickness, boundary, paint_region, disp_region, fill_up, contlength, shape_histo_all.
Value: 4 or 8
Default: 8
| (1) | (2) |
Determines whether new images shall be set to 0 before using filters and thus to make sure that the values returned by a filtering are consistent if the program is executed repeatedly on systems with the same configuration. Note that this is not necessary if always the whole image is filtered or if the data of unfiltered image areas is unimportant.
Value: 'true' or 'false'
Default: 'true'
Determines how operations processing iconic objects shall react if the object tuple is empty (= no objects).
Available values for
'true': The error will be ignored.
'exception': An exception is raised.
Default: 'true'
Controls the reaction of operators concerning input objects with empty regions which actually are not useful for such objects (e.g., certain region features, segmentation, etc.).
Available values for
'true': The error will be ignored if possible.
'exception': An exception is raised.
Default: 'true'
Quite a number of operations will lead to the creation of objects with an empty region (= no image points) (e.g., intersection,threshold, etc.). This parameter determines whether the object with an empty region will be returned as a result ('true') or whether it will be ignored ('false') that is no result will be returned.
Value: 'true' or 'false'
Default: 'true'
Determines whether the regions of iconic objects will be clipped to the currently used image size or not. This parameter can be used with operators that have a region as output, for example, gen_circle, gen_rectangle1 or dilation1.
See also: reset_obj_db
Value: 'true' or 'false'
Default: 'true'
Determines if the zooming of images is performed with integer arithmetic ('true') or with floating point arithmetic.
Value: 'true' or 'false'
Default: 'true'
This parameter determines whether the shape models created with create_shape_model or create_scaled_shape_model are completely pregenerated ('true') if this is explicitly specified in one of these operators. This parameter mainly serves to achieve a switch between the two modes with minimal code changes. Normally, only one line needs to be inserted or changed.
Value: 'true' or 'false'
Default: 'false'
This parameter determines whether the shape models to be found with find_component_model, find_shape_model, find_shape_models, find_scaled_shape_model, find_scaled_shape_models, find_aniso_shape_model, find_aniso_shape_models, find_planar_uncalib_deformable_model, find_planar_calib_deformable_model, or find_local_deformable_model may lie partially outside the image (i.e., whether they may cross the image border).
Value: 'true' or 'false'
Default: 'false'
This parameter determines if the graphic card context used in the operator render_object_model_3d is cached for future uses of this operator. The caching speeds up future uses of this operator but requires additional resources. To explicitly delete the context, set 'opengl_context_cache_enable' to 'false' and call render_object_model_3d once. 'opengl_context_cache_enable' can only be set to 'true' if the graphic card supports the rendering of 3D object models.
Value: 'true' oder 'false'
Default: 'true' if supported by the graphics card.
This parameter determines if the graphics card accelerated hidden surface removal is used in create_shape_model_3d, find_shape_model_3d, project_shape_model_3d, and project_object_model_3d. 'opengl_hidden_surface_removal_enable' can only be set to 'true' if the graphics card supports the acceleration of the hidden surface removal algorithm. The minimum requirements are OpenGL 2.0 and the extensions GL_EXT_framebuffer_object and GL_ARB_texture_float. Use get_system with the parameter Query set to 'opengl_hidden_surface_removal_available' to determine if these requirements are fulfilled. Please note that these features are not available via Windows Remote Desktop or X11 forwarding.
Value: 'true' or 'false'
Default: 'true' if supported by the graphics card.
This parameter determines if the visualization of 3D object models via disp_object_model_3d uses advanced OpenGL features or OpenGL 1.1 features only. If set to 'false' HALCON determines the capabilities of the graphics card automatically. Set this parameter to 'true', if you face visualization problems.
Value: 'true' or 'false'
Default: 'false'.
This parameter determines the DPI resolution that is stored in image files written with write_image in a format that supports the storing of the DPI resolution.
Value: Resolution in DPI.
Default: 300
Determines the internal image width of the system. This size is used for clipping regions or implementing an assumption of memory sizes, if an operator has no further image information. This size is interpreted as maximum width of all HALCON image objects. It will be increased, if images of greater width will subsequently be instantiated. See also reset_obj_db.
Value: Internal image width.
Default: 128
Determines the internal image height of the system. This size is used for clipping regions or implementing an assumption of memory sizes, if an operator has no further image information. This size is interpreted as maximum height of all HALCON image objects. It will be increased if images of greater height will subsequently be instantiated. See also reset_obj_db.
Value: Internal image height.
Default: 128
Regions will be stored internally in a certain runlength code. This parameter can determine the maximum number of chords which may be used for representing a region. Please note that some operators raise the number automatically if necessary.
The value can be enlarged as well as reduced.
Value: Maximum number of chords.
Default: 50000
Parallelization:
Determines whether HALCON uses an automatic parallelization to speed up the processing of operators on multiprocessor machines. This feature can be switched off by setting 'parallelize_operators' to 'false'. Even then, HALCON will remain reentrant (and thread-safe), unless the parameter 'reentrant' is set to 'false' via set_system. Changing the value for 'parallelize_operators' can be helpful, for example, if HALCON operators are called by a multithreaded application that also automatically performs the scheduling and load balancing of operators and data. Then, it may be undesired that HALCON performs additional parallelization steps, which may disturb the application's scheduling and load balancing concepts. For a more detailed control of automatic parallelization, single methods of data parallelization can be switched on and off. 'split_tuple' enables the tuple parallelization method, 'split_channel' the parallelization on image channels, 'split_domain' the parallelization on the image domain, and 'split_partial' the partial, internal parallelization of an operator. A preceding '~' disables the corresponding method. The method strings can also be passed within a control tuple to switch on or off methods of automatic data parallelization at once. E.g., ['split_tuple','split_channel', 'split_domain', 'split_partial'] is equivalent to 'true'.
The methods supported by a specific operator can be viewed in this reference manual or obtained via the operator get_operator_info with the parameter value 'parallel_method'.
Value: 'true', 'false', 'split_tuple', 'split_channel', 'split_domain', 'split_partial', '~split_tuple', '~split_channel', '~split_domain', '~split_partial'
Default: 'true'
Determines whether HALCON must be reentrant for being used within a parallel programming environment (e.g., a multithreaded application). If it is set to 'true', HALCON internally uses synchronization mechanisms to protect shared data objects from concurrent accesses. Though this is inevitable with any effectively parallel working application, it may cause undesired overhead, if used within an application which works purely sequentially. The latter case can be signaled by setting 'reentrant' to 'false'. This switches off all internal synchronization mechanisms and thus reduces overhead. Of course, HALCON is then no longer thread-safe, which causes another side-effect: HALCON will as a consequence no longer use the internal parallelization of operators, because this requires reentrancy. Setting 'reentrant' to 'true' resets HALCON to its default state, i.e., it is reentrant (and thread-safe) and it uses the automatic parallelization to speed up the processing of operators on multiprocessor machines.
Value: 'true' or 'false'
Default: 'true'
Sets the number of threads used by the automatic operator parallelization (aop) of HALCON. The number includes the calling thread and is restricted to the number of processors for efficiency reasons. Decreasing the number of threads is helpful if processors are occupied by user worker threads besides the threads of the automatic parallelization. With this, the number of processing threads can be adapted to the number of processors for best efficiency. If a processor affinity was set for the HALCON process, the parameter value 'default' resets the number of threads to the number of assigned processors. Else, 'default' sets the number of threads to the number of processors. If the thread-specific variant is used, HALCON reserves the specified number of threads exclusively for the calling thread. If no thread number was set so far for a specific thread, get_system returns value -1 for parameter value 'tsp_thread_num'. The sum of all thread-specific reserved aop threads can not exceed the number of threads, set by 'thread_num'. Specifying thread number 1 switches off the automatic parallelization (thread-specific when indicated).
Value: 1 <= Value <= 'processor_num', 'default'
Default: 'default'
Denotes whether HALCON always creates new threads for automatic parallelization ('false') or uses an existing pool of threads ('true'). Using a pool is more efficient for automatic parallelization. When switching off automatic parallelization permanently, deactivating the pool can save resources of the operating system.
Value: 'true', 'false'
Default: 'true'
File:
This parameter determines whether the output characters of the operator fwrite_string are displayed directly on the output medium. If set to 'false' the characters will be flushed only after entering the operator fnew_line.
Value: 'true' or 'false'
Default: 'true'
This parameter determines the format that is used for writing an OCR training file. The operators write_ocr_trainf, write_ocr_trainf_image and concat_ocr_trainf write training data in ASCII format for version number 1 or in binary format for version number 2 and 3. Version number 3 stores images of type byte and uint2. The binary version is faster in reading and writing data and stores training files more packed. The ASCII format is compatible to older HALCON releases. Depending on the file version, the OCR training files can be read by the following HALCON releases:
1 - All HALCON releases
2 - 7.0.2 and higher
3 - 7.1 and higher
Value: 1, 2, 3
Default: 3
This parameter determines how the HALCON library interprets string values. As the name implies, it was historically introduced to support handling of special characters in file and directory names.
As of now, the handling of file and directory names, textual output in graphics window, and interpretation of data in QR codes only work properly if the 'filename_encoding' matches the encoding of the parameters which are passed and interpreted.
In addition, this parameter controls the encoding of strings that are passed to the HALCON library from within HDevelop or via HALCON/.NET. The effect is that strings in these environments always match the expected encoding and work correctly regardless of the setting. However, only the 'utf8' setting allows to use characters not supported by the local encoding, e.g., to display Japanese characters on an English Windows system.
When passing strings via HALCON/C or HALCON/C++, there is no automatic conversion since there is no knowledge of the input encoding. The user is responsible for passing the correct encoding.
Except for the topics mentioned above, the HALCON library is not yet encoding-aware. This means that functionality that interprets string contents as characters such as string operations and regular expressions only work reliably for plain ASCII encodings.
In addition, any functionality that treats strings as bit streams (e.g., writing to file, sending via socket, converting to byte tuple) does not control the output encoding and the results depend on the input string encoding. This also includes the encoding of symbol names for OCR characters. Therefore, special characters in classifiers or training files may be displayed incorrectly when used with different settings or exchanged between different environments.
In particular, note that due to the differences in environments regarding automatic conversion, there may be differences in behavior between code executed in HDevelop and exported code.
Value: 'locale' or 'utf8'
Default: 'locale'
Starting with HALCON 18.05 all proprietary HALCON files which store user defined strings use UTF-8 as the default string encoding when the data is serialized or written into a file. The encoding concerns mainly HALCON tuples as well as OCR and OCV classifiers, training data, and sample identifiers, which all store user defined class or character names. This allows to share these files easily between different operating systems, countries, and locales. If such a file with special characters should be used by an application that was built with an older HALCON version (before HALCON 18.05) and relies on the locale encoding of the strings, this option can be used to force HALCON to write its files with the current locale system encoding instead of UTF-8. Note that the changed encoding concerns only files that store strings with special characters, i.e. characters that are not plain ASCII. In addition, this option does not affect user files which can be opened with open_file.
Value: 'locale' or 'utf8'
Default: 'utf8'
Older proprietary HALCON files (before HALCON 18.05) are read by default with the locale system encoding. If an old HALCON file was written with UTF-8 instead, this parameter can be used to change the encoding for reading. This concerns mainly the HALCON tuples as well as OCR and OCV classifiers, training data, and sample identifiers, which all store user defined class or character names. Note that this option has no effect on reading new HALCON files and on files which contain only plain ASCII characters. In addition, this option does not affect user files which can be opened with open_file.
Value: 'locale' or 'utf8'
Default: 'locale'
Directories:
This parameter returns the root directory of the HALCON installation.
Value: Name of the directory.
HDevelop example programs (e.g., loaded via the Browse HDevelop Program Examples dialog or via the HDevelop examples sections in the reference manual) will be looked for in the directory 'example_dir'. Note that if you set 'example_dir' to a directory that does not contain the installed HDevelop example programs, the above mentioned mechanisms to load HDevelop example programs will fail.
Value: Name of the directory.
Image files (e.g., acquired via read_image and read_sequence) will be looked for in the currently used directory and in 'image_dir' (if no absolute paths are indicated). More than one directory name can be indicated (search paths), separated by semicolons (Windows) or colons (Unix-like systems). The path can also be determined using the environment variable HALCONIMAGES.
Value: Name of the directory.
3D object model files (e.g., acquired via read_object_model_3d) will be looked for in the currently used directory and in '3d_model_dir' (if no absolute paths are indicated). More than one directory name can be indicated (search paths), separated by semicolons (Windows) or colons (Unix-like systems).
Value: Name of the directory.
Color tables (set_lut) which are realized as an ASCII-file will be looked for in the currently used directory and in 'lut_dir' (if no absolute paths are indicated). As default, HALCON will search the color tables in the sub-directory 'lut'.
Value: Name of the directory.
The online text files {German or English}.hlp, .sta, .key .num and .idx will be looked for in the currently used directory or in the path specified by 'help_dir'. This system parameter is necessary for instance when using the operators get_operator_info and get_param_info. It can also be set by the environment variable HALCONROOT before initializing HALCON. In this case the variable must indicate the directory above the help directories (that is the HALCON home directory).
Value: Name of the directory.
Other:
Determines the behavior regarding HALCON low level errors.
If the parameter 'do_low_error' is set to 'false', then no low level errors are thrown. However, the low level error messages still appear in the output console (a window containing a log of the most recent messages) that can be opened via the window menu.
If the parameter 'do_low_error' is set to 'disabled', the low level errors are suppressed and are not listed in the output console.
If the parameter is set to 'stderr', the corresponding low level error message is printed to standard error.
If it is set to 'message_box', then a message box containing the error text is opened (this functionality is implemented on Windows systems only).
The parameter value 'callback' can be used to determine a callback function, which should be called in case of a low level error. The address of this callback function is specified in the second index entry of the parameter Value.
The signature of the callback function is the following:
Herror LowErrorCallbackProc(const char* err_text)On Windows 32 bit systems, the __stdcall naming convention is used:
Herror (__stdcall LowErrorCallbackProc)(const char* err_text)
The parameter value 'callback' can be used in HDevelop only if the callback procedure is set to 0, in which case the output of low level error messages is omitted.
If low level error messages should be printed to file, then the parameter value 'file' should be used together with a file handle referring to a corresponding file previously opened via open_file.
The parameter values 'callback' and 'file' can be used only in combination with a corresponding procedure and file handle, respectively.
With the exception of the parameter value 'false', the parameter 'do_low_error' can be assigned multiple values. In case of a low level error, the corresponding actions are executed in the order of the values as passed in the input parameter tuple. If the tuple contains a certain parameter value multiple times, then only the first occurrence of the value in the tuple is taken into account, i.e., it is not possible to execute the same action multiple times in case of a low level error . If 'do_low_error' is assigned multiple values or either the value 'file' or 'callback', then it cannot be set in combination with other system parameters in the same call of set_system.
Every setting of 'do_low_error' via set_system overrides the previous setting of the parameter.
The single parameter value 'true' corresponds to the parameter value 'message_box' on Windows systems and 'stderr' on Unix-like systems.
Value: 'true', 'false', 'disabled', 'stderr', 'message_box', 'callback', 'file'
Default: 'false'
Many draw operators (like, e.g., draw_region or draw_rectangle1) can be canceled by ending the drawing with the right mouse button without new objects being drawn or existing objects being modified. The stop button of HDevelop can also be used to abort draw operators. The aborted draw operators return empty objects or empty tuples, respectively. 'cancel_draw_result' controls the behavior of aborted draw operators.
The following values are available for
'true': The draw operator returns no error.
'exception': An exception is raised.
Default: 'true'
Sets the seed of the thread specific random generator used in the operators tuple_rand, add_noise_white, add_noise_distribution, gen_random_region, and add_noise_white_contour_xld. If no seed has been set, the random generator is seeded with the current system time on the first call of one of the operators listed above. Afterwards the value used as seed can be queried with get_system.
This parameter accepts integer values or the string 'default' to re-establish the default behavior.
Determines the mode of the measurement of time intervals with count_seconds.
'performance_counter' measures the elapsed system time with preferably high precision. HALCON uses the most accurate time measurement method provided by the operating system. If no high precision measurement method is available, a lower resolution method is used. On Windows systems the Performance Counter is used. For more information about the Performance Counter on Windows refer to the Microsoft Developer Network (MSDN) documentation. The Performance Counter provides the highest precision (below one millisecond). However, it may not work correctly on some systems due to issues with energy management and/or multithreading. If the Performance Counter is not supported by the operating system, the setting 'multimedia_timer' applies. On Unix-like systems (e.g. Linux and macOS) the precision is also generally below one millisecond, and it may also be affected by problems due to energy management and/or multithreading. If you encounter such problems you should use the 'elapsed_time' setting.
'elapsed_time' measures the elapsed system time similar to the setting 'performance_counter'. The difference is that other measurement methods are used which are less accurate but generally not much affected by problems due to energy management and/or multithreading. The precision is in general one millisecond. This setting should be used, if the measurements using 'performance_counter' are unreliable and a precision of one millisecond is acceptable.
'multimedia_timer' measures the elapsed system time using Multimedia Timers on Windows. Please refer to the Microsoft Developer Network (MSDN) documentation for more information on Multimedia Timers. This method has in general a resolution of one millisecond. If such a resolution cannot be achieved on your system you may use the Windows functions 'timerBeginPeriod' and 'timerEndPeriod' in order to increase the precision (see MSDN). On Unix-like systems there are no Multimedia Timers and therefor the setting 'performance_counter' applies.
'processor_time' measures the time the running HALCON process occupies the CPU. This kind of measuring time is independent of the CPU load caused by other processes, but it features a lower resolution on most systems and is therefore less accurate for smaller time intervals. Please note that the runtime of many applications is not only affected by CPU processing time. A lot of applications will be affected by input/output or memory management. For such applications the setting 'performance_counter' or 'elapsed_time' should be used instead.
Default: 'performance_counter'
Please note that the settings 'performance_counter' and 'elapsed_time' measure the elapsed system time. As a consequence the measured time intervals are affected by the system load while measuring. If these settings are used to measure the runtime of a given application it should be ensured that other processes do not affect the measurement.
Determines the mode of measurement used by the operators supporting timeouts.
'elapsed_time': see description in section 'clock_mode'
'multimedia_timer': see description in section 'clock_mode'
'performance_counter': see description in section 'clock_mode'
Default: 'multimedia_timer' on Windows systems, 'elapsed_time' on Linux systems
Determines the maximum number of regions returned by connection. For Value=0, all regions are returned.
Value: >=0
Default: 0
Pointer to external function for memory allocation of result images. This function should have the following signature: 'void* ExternAllocFunc(size_t)'. If 0 is passed the HALCON allocation function will be used.
Value: Function pointer.
Default: 0
Pointer to external function for memory deallocation of result images. This function should have the following signature: 'void ExternFreeFunct(void*)'. If 0 is passed the HALCON deallocation function will be used.
Value: Function pointer.
Default: 0
To speed up allocation of new images, HALCON does not free image memory of image objects but caches it to reuse it. With this parameter, you can set an upper limit in bytes for this HALCON image cache. Freed images are cached as long as the upper limit is not reached. This functionality can be switched off by setting 'image_cache_capacity' to 0.
Value: Limit for HALCON image cache.
Default: 16777216 (16MByte)
Cache mode of global memory, i.e., memory that is visible beyond an operator. It specifies whether unused global memory should be cached ('shared') or freed ('idle'). Generally, caching speeds up memory allocation and processing at the cost of memory consumption. Additionally, HALCON offers the option to cache global memory for each thread separately ('exclusive'). This mode can also accelerate processing at the cost of higher memory consumption. With the action parameter 'cleanup', cached memory blocks can be freed physically again.
Value: 'idle','exclusive','shared','cleanup'
Default: 'exclusive'
This parameter controls the operating mode of the temporary memory cache. The temporary memory cache is used to speed up an application by caching memory used temporarily during the execution of an operator. For most applications the default setting ('exclusive') will produce the best results. The following modes are supported:
'idle' The temporary memory cache is turned off. This mode will use the least memory, but will also reduce performance compared to the other modes.
'shared' All temporary memory is cached globally in the temporary memory reservoir. This mode will use less memory than 'exclusive' mode, but will also generally offer less performance.
'exclusive' All temporary memory is cached locally for each thread. This mode will use the most memory, but will generally also offer the best performance.
'aggregate' Temporary memory blocks that are larger than the threshold set with the 'alloctmp_max_blocksize' parameter are cached in the global memory reservoir, while all smaller blocks are aggregated into a single block that is cached locally for each thread. If the global memory reservoir is disabled, the large blocks are freed instead. The aggregated block will be sized according to the temporary memory usage the thread has seen so far, but it will not be larger than 'alloctmp_max_blocksize' (if set) or smaller than 'alloctmp_min_blocksize' (if set). This mode balances memory usage and speed, but requires correctly setting 'alloctmp_min_blocksize' and 'alloctmp_max_blocksize' for the application's memory usage pattern for effectiveness.
Note that cache mode 'idle' is set in exclusive run mode, whereas the other modes are set in reentrant mode.
For backward compatibility, the values 'false' and 'true' are also accepted; they correspond to 'idle' and 'exclusive', respectively.
Value: 'idle', 'shared', 'exclusive', or 'aggregate'
Default: 'exclusive'
If set to 'true', the global temporary memory reservoir is enabled. If it is set to 'false', it is disabled and any memory blocks put into the reservoir are freed instead.
Any thread that needs a new temporary memory block for its temporary memory cache will first check if the reservoir has a block available and only allocate more memory from the system if it does not. Blocks are put into the reservoir by threads operating their caches in the 'shared' or 'aggregate' modes.
Note that the global setting of this parameter overrides the thread-specific setting, i.e., if 'temporary_mem_reservoir' is set to 'false', 'tsp_temporary_mem_reservoir' will have no effect.
Value: 'false' or 'true'
Default: 'true'
The maximum amount of memory the global temporary memory reservoir may cache, in bytes. If set to -1, the cache is limited only by the amount of available memory.
Value: -1 or >= 0
Default: -1
Minimum size of memory blocks used by the temporary memory cache, in bytes. (No effect if 'temporary_mem_cache' == 'idle'). With the default setting -1, HALCON will use a heuristic based on the current image size to determine a sensible block size. For most applications this will be the best choice. If the parameter is set to a value greater than or equal to zero, HALCON will use this size instead. Note that if an operator requires temporary memory objects larger than the 'alloctmp_min_blocksize', it will ignore this parameter.
Value: -1 or >= 0
Default: -1
Maximum size of memory blocks used by the temporary memory cache, in bytes. (No effect if 'temporary_mem_cache' == 'idle'). This parameter can be used to limit the size of temporary memory cache blocks determined by a heuristic when 'alloctmp_min_blocksize' is set to -1. In general, it should not be necessary to set this parameter unless the temporary cache mode 'aggregate' is used. In 'aggregate' mode, this parameter additionally limits the size of the aggregated cache block, and determines the size threshold for blocks to be placed into the temporary memory reservoir. Value: -1 or >= 0
Default: -1
Determines whether instantiated iconic objects should be listed in one of the five relations (gray-value data, region data, XLDs, iconic objects and object tuples) of the HALCON database. The relations can be used for, e.g., debugging purposes. See also count_relation, reset_obj_db. Note that collecting database information is not threadsafe when passing iconic objects between threads, meaning when deleting objects in a different thread than generating them.
Value: 'true' or 'false'
Default: 'false'
Flag, if MMX operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'mmx_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports MMX, else 'false'
Flag, if SSE operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'sse_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports SSE, else 'false'
Flag, if SSE2 operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'sse2_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports SSE2, else 'false'
Flag, if SSE3 operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'sse3_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports SSE3, else 'false'
Flag, if SSSE3 operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'ssse3_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports SSSE3, else 'false'
Flag, if SSE41 operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'sse41_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports SSE41, else 'false'
Flag, if SSE42 operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'sse42_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports SSE42, else 'false'
Flag, if AVX operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'avx_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports AVX, else 'false'
Flag, if AVX2 operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'avx2_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports AVX2, else 'false'
Flag, if AVX-512F operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'avx512f_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports AVX-512F, else 'false'
Flag, if AVX-512DQ operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'avx512dq_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports AVX-512DQ, else 'false'
Flag, if AVX-512BW operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'avx512bw_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports AVX-512BW, else 'false'
Flag, if AVX-512ER operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'avx512er_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports AVX-512ER, else 'false'
Flag, if AVX-512CD operations are used to accelerate selected image processing operators ('true') or not ('false'). (No effect, if 'avx512cd_supported' == 'false', see also operator get_system)
Value: 'true' or 'false'
Default: 'true' if CPU supports AVX-512CD, else 'false'
Language used for error messages.
Value: 'english' or 'german'.
Default: 'english'
Adds or removes a callback function for operator progress and messages. The callback function is called by some operators in irregular intervals to signal their progress or a message to the application.
The signature of the callback is
void HProgressBarCallback(Hlong id,
const char *operator_name,
double progress,
const char *message)
On Windows 32 bit systems, the __stdcall naming convention is used:
void (__stdcall HProgressBarCallback)(Hlong id,
const char *operator_name,
double progress,
const char *message)
A corresponding delegate HalconAPI.HProgressBarCallback is defined for HALCON/.NET. Note that in order to pass a delegate to set_system you will need to call Marshal.GetFunctionPointerForDelegate and make sure the delegate is not garbage collected as long as the pointer remains in use.
public delegate void HProgressBarCallback(IntPtr id,
string operatorName,
double progress,
string message)
The parameters are:
'id': Thread-ID from which the operator was originally called. If the automatic operator parallelization is active, the callback might happen in a thread that is different from the one that was originally used to start the operator. Applications which display the progress in a GUI might have to consider this.
'operator_name': Name of the currently executed operator.
'progress': The interpretation of this parameter depends on its value. Between 0 and 1: The approximate current progress of the operator. -1: The operator shows only a message and does not set the progress. This parameter should be ignored. -2: The operator completed execution. This is the last callback for this operator and a chance for the application to perform cleanups. Note that this call happens only for operators that have called the callback at least once to set a progress or a message.
'message': Optional message in english that usually describes the progress of the operator such as the current error when training classifiers. If the operator has no message to show, this parameter can be NULL.
Flag to activate or deactivate the legacy handle mode. If enabled, all handles returned by HALCON operators are converted into integers, and all HALCON operators accept integers as handles. Note that if the legacy handle mode is enabled, handles are no longer automatically cleared when they are overwritten. Instead, clear_handle or the corresponding clear operator of the handle type must be called.
Also note that the legacy handle mode is solely provided for running legacy code. It is not recommended to activate it in new code. New operators or language features might not work in legacy handle mode.
Value: 'true' or 'false'
Default: 'false'
Note that despite the information under 'Parallelization' concerning the multithreading type, not all parameters are reentrant. Operators that are followed by '*)' are set exclusively only.
Name of the system parameter to be changed.
Default value: 'init_new_image'
List of values: '3d_model_dir', 'add_progress_callback', 'alloctmp_max_blocksize', 'alloctmp_min_blocksize', 'avx2_enable', 'avx512bw_enable', 'avx512cd_enable', 'avx512dq_enable', 'avx512er_enable', 'avx512f_enable', 'avx_enable', 'backing_store', 'border_shape_models', 'cancel_draw_result', 'clip_region', 'clock_mode', 'current_runlength_number', 'database', 'default_font', 'do_low_error', 'empty_region_result', 'example_dir', 'extern_alloc_funct', 'extern_free_funct', 'filename_encoding', 'flush_file', 'flush_graphic', 'global_mem_cache', 'graphic_stack_size', 'height', 'help_dir', 'icon_name', 'image_cache_capacity', 'image_dir', 'image_dpi', 'init_new_image', 'int2_bits', 'int_zooming', 'language', 'legacy_handle_mode', 'lut_dir', 'max_connection', 'mmx_enable', 'neighborhood', 'no_object_result', 'ocr_trainf_version', 'opengl_compatibility_mode_enable', 'opengl_context_cache_enable', 'opengl_hidden_surface_removal_enable', 'parallelize_operators', 'pregenerate_shape_models', 'read_halcon_files_encoding_fallback', 'reentrant', 'remove_progress_callback', 'seed_rand', 'sse2_enable', 'sse3_enable', 'sse41_enable', 'sse42_enable', 'sse_enable', 'ssse3_enable', 'store_empty_region', 'temporary_mem_cache', 'temporary_mem_reservoir', 'temporary_mem_reservoir_size', 'thread_num', 'thread_pool', 'timer_mode', 'tsp_alloctmp_max_blocksize', 'tsp_alloctmp_min_blocksize', 'tsp_cancel_draw_result', 'tsp_clip_region', 'tsp_current_runlength_number', 'tsp_empty_region_result', 'tsp_height', 'tsp_init_new_image', 'tsp_legacy_handle_mode', 'tsp_neighborhood', 'tsp_no_object_result', 'tsp_store_empty_region', 'tsp_temporary_mem_cache', 'tsp_temporary_mem_reservoir', 'tsp_thread_num', 'tsp_width', 'update_lut', 'use_window_thread', 'width', 'write_halcon_files_encoding', 'x_package'
New value of the system parameter.
Default value: 'true'
Suggested values: 'true', 'false', 0, 4, 8
The operator set_system returns the value 2 (H_MSG_TRUE) if the parameters are correct. Otherwise an exception will be raised.
reset_obj_db, get_system, set_check
get_system, set_check, count_seconds
Foundation
| Operators |