| Table of Contents / System / Parameters | Operators |
set_system — Set HALCON system parameters.
set_system( : : SystemParameter, Value : )
The operator set_system allows to change different system parameters. 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 operating systems because Unix window managers flush the display buffer automatically.
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'
Whenever a window is opened, a font, the 'default_font', will be set for the text output. If the preset font cannot be found, another font name can be set before opening the window.
Value: File name of the font.
Default: 'fixed'
Determines whether the HALCON color tables are adapted according to their environment or not.
Value: 'true' or 'false'
Default: 'false'
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
Number of colors to be reserved under X Windows to allow the output of gray values (disp_channel) on a machine with 4 bitplanes (16 colors).
Attention! This value may only be changed before the first window has been opened.
Value: 2 - 12
Default: 8
Number of colors to be reserved under X Windows to allow the output of gray values (disp_channel) on a machine with 6 bitplanes (64 colors).
Attention! This value may only be changed before the first window has been opened.
Value: 2 - 62
Default: 50
Number of colors to be reserved under X Windows to allow the output of gray values (disp_channel) on a machine with 8 bitplanes (256 colors).
Attention! This value may only be changed before the first window has been opened.
Value: 2 - 254
Default: 140
Under X Windows HALCON reserves a part of the available colors for the representation of gray values (disp_channel). This is supposed to affect X applications as little as possible. However, if HALCON does not succeed in reserving a in Value specified percentage of the required colors on the X server, a certain amount of the look-up table will be claimed for the HALCON gray values regardless of the consequences. This may result in undesired color shifts when switching between HALCON windows and windows of other applications, or (outside HALCON) if a window-dump is generated. The number of the real gray values to be reserved depends on the number of available bitplanes on the output machine (see also 'num_gray_*'). Obviously, no colors will be reserved on monochrome machines - the gray values will instead be dithered when displayed. If gray value-displays are used, only different shades of gray will be applied. 'num_gray_percentage' is only used on machines with 8 bit pseudo-color displays. For machines with 16 bits or more displays (true color machines), no colors are reserved for the display of gray values in this case.
Note: This value may only be changed before the first window has been opened. Before opening the first window on a machine with x bitplanes, 'num_gray_x' indicates the number of colors that have to be reserved for displaying gray values. Afterwards, however, it will indicate the number of colors which have actually been reserved.
Value: 0 - 100
Default: 30
Similar to 'num_gray_percentage', 'num_graphic_percentage' determines how many graphic colors (for use with set_color) should be reserved in the look-up table (LUT) on an 8 bit pseudo-color display under X Windows.
Value: Number of colors.
Default: 60
Number of the graphic colors to be reserved by HALCON under X Windows (concerning operators like disp_region) on a machine with 2 bitplanes (4 colors).
Attention: This value may only be changed before the first window has been opened on the machine.
Value: 0 - 2
Default: 2
Number of the graphic colors to be reserved by HALCON under X Windows (concerning operators like disp_region) on a machine with 4 bitplanes (16 colors).
Attention: This value may only be changed before the first window has been opened on the machine.
Value: 0 - 14
Default: 5
Number of the graphic colors to be reserved by HALCON under X Windows (concerning operators like disp_region) on a machine with 6 bitplanes (64 colors).
Attention: This value may only be changed before the first window has been opened on the machine.
Value: 0 - 62
Default: 10
Number of the graphic colors to be reserved by HALCON under X Windows (concerning operators like disp_region) on a machine with 8 bitplanes (256 colors).
Attention: This value may only be changed before the first window has been opened on the machine.
Value: 0 - 64
Default: 20
HALCON reserves the first 'num_graphic_x colors' from this list of color names as graphic colors. As a default HALCON uses this list which is also returned by query_all_colors. However, the list can be changed individually: hereby a tuple of color names will be returned as value. It is recommended that such a tuple always includes the colors 'black' and 'white', and optionally also 'red', 'green' and 'blue'. If 'default' is set as Value, HALCON returns to the initial setting. Note: On gray value machines the first x colors will not be reserved. Instead the first x shades of gray from the list will be reserved.
Attention: This value may only be changed before the first window has been opened on the machine.
Value: Tuples of X Windows color names.
Default: See also query_all_colors.
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_chain, get_region_polygon, get_region_thickness, boundary, paint_region, disp_region, fill_up, contlength, shape_histo_all.
Value: 4 or 8
Default: 8
Determines whether new images shall be set to 0 before using filters. 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 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_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 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 signalled 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 parallelization of HALCON. The number includes the main 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. 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 file and directory names are interpreted that are passed as string parameters to and from HALCON. With the value 'locale' these names are used unaltered, whereas with the value 'utf8' these names are interpreted as being UTF-8 encoded. In the latter case, HALCON tries to translate input parameters from UTF-8 to the locale encoding according to the current system settings, and output parameters from locale to UTF-8 encoding.
Value: 'locale' or 'utf8'
Default: 'locale'
Directories:
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), seperated by semicolons (Windows) or colons (Unix). The path can also be determined using the environment variable HALCONIMAGES.
Value: Name of the filepath.
Default: '$HALCONROOT/images' (Unix) or '%HALCONROOT%/images' (Windows)
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 filepath.
Default: '$HALCONROOT/lut' (Unix) or '%HALCONROOT%/lut' (Windows)
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 filepath.
Default: '$HALCONROOT/help' (Unix) or '%HALCONROOT%/help' (Windows)
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. 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. This procedure should have the following signature: 'void 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 refering 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 systems.
Value: 'true', 'false', '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'
Determines the mode of the measurement of time intervals with count_seconds.
'processor_time' measures the time the running HALCON process occupies the CPU. This kind of measuring time is independend from 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.
'elapsed_time' measures the actual elapsed system time. It includes the waiting time of the current process as well as the CPU time of other processes. Therefore, to get a reliable measurement make sure that no other process causes any CPU load.
'performance_counter' measures the actual system time by using a performance counter, which results in a higher resolution.
'processor_time' is used if the system does not support any performance counter.
'multimedia_timer' uses the Windows multimedia timer.
Default: 'performance_counter'
Determines the mode of measurement used by the operators supporting timeouts.
'elapsed_time' uses the actual system time. This provides a very high resolution on UNIX systems and is therefore the only possible choice on these systems. On Windows systems, however, the resolution of 'elapsed_time' is less than 10 milliseconds.
'multimedia_timer' uses the Windows multimedia timer. This provides a resolution of 1 millisecond. If the resolution on your system is less than 1 millisecond, you can try to increase it. For this purpose, use the Windows calls 'timeBeginPeriod' and 'timeEndPeriod' in exported code (consult the MSDN for further information).
'performance_counter' uses the performance counter on Windows systems and provides a very high resolution. However, it may not work correctly on some systems due to issues with energy management and/or multithreading. You should not use this mode if you are not absolutely sure it works correctly on your system.
Default: 'multimedia_timer' on Windows systems, 'elapsed_time' on UNIX 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: 4194304 (4MByte)
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.
Value: 'idle','exclusive','shared'
Default: 'exclusive'
Flag if unused temporary memory of an operator should be cached ('true') or freed ('false'). An application can be sped up by caching temporary memory, i.e., memory that is only used within an operator. On the other hand, freeing temporary memory reduces the memory consumption (especially of a multithreaded application) but also reduces speed at the same time. The cache is set to 'false' within exclusive run mode whereas 'true' is set within reentrant mode.
Value: 'true' or 'false'
Default: 'true'
Maximum size of memory blocks to be cached by temporary memory management. (No effect, if 'temporary_mem_cache' == 'false'). Usually, it is not be necessary to set this parameter because a reasonable size will be chosen by default (-1).
An appropriate blocksize should typically be able to contain a region and two image matrices. This can lead to allocation errors on systems with limited (physical) memory. In this case, it might be useful to reduce the block size or even turn off temporary memory cache (set 'temporary_mem_cach' auf 'false') even though this will reduce speed.
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.
Value: 'true' or 'false'
Default: 'false'
Flag, if MMX operations were 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 SSE2 operations were used to accelerate selected image processing operators ('true') or not ('false').
Value: 'true' or 'false'
Default: 'true' if CPU supports SSE2, else 'false'
Language used for error messages.
Value: 'english' or 'german'.
Default: 'english'
Name of the system parameter to be changed.
Default value: 'image_dir'
List of values: 'alloctmp_max_blocksize', 'backing_store', 'border_shape_models', 'cancel_draw_result', 'clip_region', 'clock_mode', 'current_runlength_number', 'database', 'default_font', 'do_low_error', 'empty_region_result', 'extern_alloc_funct', 'extern_free_funct', 'filename_encoding', 'flush_file', 'flush_graphic', 'global_mem_cache', 'graphic_colors', 'height', 'help_dir', 'icon_name', 'image_cache_capacity', 'image_dir', 'image_dpi', 'init_new_image', 'int2_bits', 'int_zooming', 'language', 'lut_dir', 'max_connection', 'mmx_enable', 'neighborhood', 'no_object_result', 'num_graphic_2', 'num_graphic_4', 'num_graphic_6', 'num_graphic_8', 'num_graphic_percentage', 'num_gray_4', 'num_gray_6', 'num_gray_8', 'num_gray_percentage', 'ocr_trainf_version', 'parallelize_operators', 'pregenerate_shape_models', 'reentrant', 'sse2_enable', 'store_empty_region', 'temporary_mem_cache', 'thread_num', 'thread_pool', 'timer_mode', 'tsp_cancel_draw_result', 'tsp_clip_region', 'tsp_current_runlength_number', 'tsp_empty_region_result', 'tsp_height', 'tsp_init_new_image', 'tsp_neighborhood', 'tsp_no_object_result', 'tsp_store_empty_region', 'tsp_thread_num', 'tsp_width', 'update_lut', 'width', 'x_package'
New value of the system parameter.
Default value: 'true'
Suggested values: 'true', 'false', 0, 4, 8, 100, 140, 255
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
| Table of Contents / System / Parameters | Operators |
| HALCON Reference Manual 10.0.2 | Copyright © 1996-2011 MVTec Software GmbH |