Setting of HALCON system parameters.
The operator set_system allows to change different system parameters with relation to the runlength.
Available system parameters:
'neighborhood'
This parameter is used with all procedures which examine
neighborhood relations: connection,
get_region_contour, get_region_chain,
get_region_polygon, get_region_thickness,
boundary,
paint_region, disp_region,
fill_up, contlength.
Value: 4 or 8
default: 8
'default_font'
Whenever a window is opened, a font will be set for the
text output, whereby the 'default_font' will be used.
If the preset font cannot be found, another fontname can
be set before opening the window.
Value: Filename of the fonts
default: fixed
'update_lut'
Determines whether the HALCON color lookup tables
are adapted according to their environment or not.
Value: 'true' or 'false'
default: 'false'
'image_dir'
Image files (e.g.\ 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 (searchpaths) can be indicated,
seperated by semicolons (Windows) or colons
(Unix). The path can also be determined using the
environment variable HALCONIMAGES.
Value: pathname
default: '$HALCONROOT/images' bzw. '%HALCONROOT%/images'
'lut_dir'
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). If HALCONROOT is set,
HALCON will search the color tables in the
subdirectory „lut“.
Value: pathname
default: '$HALCONROOT/lut' bzw. '%HALCONROOT%/lut'
'help_dir'
The online textfiles {german, english}.hlp, .sta,
.key, .num and .idx will be looked for in the
currently used directory or in 'help_dir'. This
system parameter is necessary for instance using the
operators get_operator_info and
get_param_info. This parameter 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-Homedirectory):
e.g.: '/usr/local/halcon'
Value: pathname
default: '$HALCONROOT/help' bzw. '%HALCONROOT%/help'
'init_new_image'
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
not filtered image areas are unimportant.
Value: 'true' or 'false'
default: 'true'
'no_object_result'
Determines how operations processing iconic objects shall
react if the object tuplet is empty (= no objects).
Available values for Value:
'true': the error will be ignored
'false': the procedure returns FALSE
'fail': the procedure returns FAIL
'void': the procedure returns VOID
'exception': an exception is raised
default: 'true'
'empty_region_result'
Controls the reaction of procedures concerning input
objects with empty regions which actually are not
useful for such objects (e.g.\ certain region features,
segmentation, etc.).
Available values for Value:
'true': the error will be ignored if possible
'false': the procedure returns FALSE
'fail': the procedure returns FAIL
'void': the procedure returns VOID
'exception': an exception is raised
default: 'true'
'store_empty_region'
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'
'pregenerate_shape_models'
This parameter determines whether the shape models
created with create_shape_model or
create_scaled_shape_model are pregenerated
completely or not, if this is not explicitly
specified in create_shape_model or
create_scaled_shape_model. 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'
'border_shape_models'
This parameter determines whether the shape models
to be found with find_shape_model,
find_shape_models, find_scaled_shape_model,
or find_scaled_shape_models may lie partially
outside the image (i.e., whether they may cross the image
border).
Value: 'true' or 'false'
default: 'false'
'image_dpi'
This parameter determines the DPI resolution that is
stored in image files written with write_image
in formats that support the storing of the DPI resolution.
default: 300
'backing_store'
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.
It may be recommendable in some cases to deactivate
the security mechanism, if e.g. performance / memory
is what matters.
Value: true or false
default: true
'flush_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 with 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 performance. Unix window manager flash the
display buffer automatically and make this parameter
effectless on respective operating systems, therefore.
Value: 'true' or 'false'
default: 'true'
'flush_file'
This parameter determines whether the output into a file
(also to the terminal) shall be buffered or not.
If the output is to be buffered, in general the data will be
displayed on the terminal only after entering the operator
fnew_line.
Value: 'true' or 'false'
default: 'true'
'ocr_trainf_version'
This parameter determines the version of the file
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 compabtible to older
HALCON releases.
Depending on the file version, the OCR training files
can be read by the following HALCON releases:
File Version | HALCON Release
-----------------+-----------------
1 | All
2 | 7.0.2 and higher
3 | 7.1 and higher
Value: 1, 2, 3
default: 3
'filename_encoding'
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, while 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'
'x_package'
The output of image data via the network may cause errors
owing to the heavy load on the computer or on the network.
In order to avoid this, the data is
transmitted in small packages. If the computer is used
locally, these units can be enlarged at will. This can
lead to a notably improved output performance.
Value: package size (in bytes)
default: 20480
'int2_bits'
Number of significant bits of int2 images.
This number is used when scaling the gray values.
If the values is -1 the gray values will be
automatically scaled (default).
Value: -1 or 9..16
default: -1
'num_gray_4'
Number of the colors to be reserved under X Windows to allow
the output of graylevels (disp_channel) on a machine
with 4 bitplanes (16 colors).
Please note! This value may only be changed before the first
window has been opened on the machine.
Value: 2 - 12
default: 8
'num_gray_6'
Number of the colors to be reserved under X Windows to allow
the output of graylevels (disp_channel) on a machine
with 6 bitplanes (64 colors).
Please note! This value may only be changed before the first
window has been opened on the machine.
Value: 2 - 62
default: 50
'num_gray_8'
Number of the colors to be reserved under X Windows to allow
the output of graylevels (disp_channel) on a machine
with 8 bitplanes (256 colors).
Please note! This value may only be changed before the first
window has been opened on the machine.
Value: 2 - 254
default: 140
'num_gray_percentage'
Under X Windows HALCON reserves a part of the
available colors for the representation of gray
values (disp_channel). This shall interfere
with other X applications as little as
possible. However, if HALCON does not succeed in
reserving a minimum percentage of
'num_gray_percentage' of the necessary colors on the
X server, a certain amount of the lookup table will
be claimed for the HALCON graylevels regardless of
the consequences. This may result in undesired
shifts of color when switching between HALCON
windows and windows of other applications, or
(outside HALCON) if a window-dump is generated.
The number of the real graylevels to be reserved
depends on the number of available bitplanes on the
outputmachine (see also 'num_gray_*'). Naturally no
colors will be reserved on monochrome machines - the
graylevels will instead be dithered when
displayed. If graylevel-displays are used, only
different shades of gray will be applied ('black',
'white', 'gray', etc.). 'num_gray_percentage' is
only used on machines with 8 bit pseudo-color
displays. For machines with displays with 16 bits
or more (true color machines), no colors are reserved
for the display of gray levels in this case.
Attention: This value may only be changed before the
first window has been opened on the machine. Before
opening the first window on a machine with x
bitplanes, num_gray_x indicates the number of colors
which have to be reserved for the display of
graylevels, afterwards, however, it will indicate
the number of colors which actually have been
reserved.
Value: 0 - 100
default: 30
'num_graphic_percentage'
Similar to 'num_gray_percentage', 'num_graphic_percentage'
determines how many graphics colors (for use with
set_color) should be reserved in the LUT on an 8 bit
pseudo-color display under X windows.
default: 60
'int_zooming'
Determines if the zooming of images is done with
integer arithmetic or with floating point
arithmetic.
default: 'true'
'icon_name'
Name of iconified graphics windows under X-Window. By default
the number of the graphics window is displayed.
default: 'default'
'num_graphic_2'
Number of the graphic colors to be reserved by
HALCON under X Windows (concerning the operators
disp_region etc.) 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.
Values: 0 - 2
default: 2
'num_graphic_4'
Number of the graphic colors to be reserved by
HALCON under X Windows (concerning the operators
disp_region etc.) 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.
Values: 0 - 14
default: 5
'num_graphic_6'
Number of the graphic colors to be reserved by
HALCON under X Windows (concerning the operators
disp_region etc.) 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.
Values: 0 - 62
default: 10
'num_graphic_8'
Number of the graphic colors to be reserved by
HALCON under X Windows (concerning the operators
disp_region etc.) 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.
Values: 0 - 64
default: 20
'graphic_colors'
HALCON reserves the first num_graphic_x colors
from this list of color names as graphic colors. As
a default HALCON uses the same list which is also
returned by using query_all_colors.
However, the list can be changed individually:
hereby a tuplet of color names will be returned as
value. It is recommendable that such a tuplet 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 graylevel machines not
the first x colors will be reserved, but the first x
shades of gray from the list. Attention: This value
may only be changed before the first window has been
opened on the machine.
Value: Tuplets of X Windows color names
default: see also query_all_colors
'current_runlength_number'
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
procedures raise the number on their own if
necessary. The value can be enlarged as well as
reduced.
Value: maximum number of chords
default: 50000
'clip_region'
Determines whether the regions of iconic objects of the
HALCON database will be clipped to the currently
used image size or not. This is the case for example
in procedures like gen_circle,
gen_rectangle1 or dilation1.
See also: reset_obj_db
Value: 'true' or 'false'
default: 'true'
'do_low_error'
Determines whether HALCON should print low
level error or not.
Value: 'true' or 'false'
default: 'false'
'reentrant'
Determines whether HALCON must be reentrant for being
used within a parallel programming environment
(e.g. a multithreaded application). This parameter is only
of importance for Parallel HALCON, which can process
several operators concurrently. Thus, the parameter
is ignored by the sequentially working HALCON-Version.
If it is set to 'true', Parallel 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, Parallel HALCON then is no longer
thread-safe, which causes another side-effect: Parallel
HALCON will then no longer use the internal
parallelization of operators, because this needs
reentrancy. Setting 'reentrant' to 'true' resets Parallel
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: Parallel HALCON: 'true', otherwise: 'false'
'parallelize_operators'
Determines whether Parallel 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, Parallel HALCON will remain reentrant
(and thread-safe), unless the parameter 'reentrant' is
changed via set_system accordingly. Changing
'parallelize_operators' can be helpful, for example, if
HALCON operators are called by a multithreaded application
that also does the scheduling and load-balancing of
operators and data by itself. 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. 'split_tuple' enables the tuple parallelization
method, 'split_channel' the parallelization on image
channels, and 'split_domain' the parallelization on the
image domain. A preceding '~' disables the respective 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']
is equivalent to 'true'.
The parameter 'parallelize_operators' is only
supported by Parallel HALCON and thus ignored by the
sequentially working HALCON-Version.
Value:'true','false','split_tuple','split_channel',
'split_domain','~split_tuple',
'~split_channel','~split_domain'
default: Parallel HALCON: 'true', else: 'false'
'thread_num'
Sets the number of threads used by the automatic
parallelization of Parallel 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.
Standard HALCON ignores this parameter value.
Value: 1 <= Value <= processor_num
default: Parallel HALCON: processor_num, else: 1
'thread_pool'
Denotes whether Parallel 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 atomatic
parallelization permanently, deactivating the pool can save
resources of the operating system.
Standard HALCON ignores this parameter value.
Value: 'true', 'false'
default: Parallel HALCON: 'true', else: 'false'
'clock_mode'
Determines the mode of the measurement of time intervals
with count_seconds. For Value='processor_time', the time the
cpu is occupied by the running HALCON process is measured.
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 more inaccurate for
smaller time intervals, therefore.
For Value='elapsed_time', the actual elapsed system time
is measured. 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.
Value='performance_counter' measures the actual system
time by using a performance counter, which results in a
higher resolution. If the system does not support any
performance counter, Value='processor_time' is used.
Value: 'processor_time', 'elapsed_time', 'performance_counter'
default: 'performance_counter'
'max_connection'
Determines the maximum number of regions returned by
connection. For Value=0,
all regions are returned.
'extern_alloc_funct'
Pointer to external function for memory allocation
of result images.
default: 0
'extern_free_funct'
Pointer to external function for memory deallocation
of result images.
default: 0
'image_cache_capacity'
Upper limit in bytes of the internal image memory cache. To
speed up allocation of new images HALCON does not free
image memory but caches it to reuse it. Caching of freed
images is done as long as the upper limit is not reached.
This functionality can be switched off by setting '
image_cache_capacity' to 0.
This parameter is only available in Standard HALCON and
ignored in Parallel HALCON.
default: Standard HALCON: 4194304 (4MByte), else: 0
'global_mem_cache'
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, Parallel 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.
Standard HALCON treats the value 'exclusive' like
the value 'shared'.
Values: 'idle','exclusive','shared'
default: Standard HALCON: 'shared', else: 'idle'
'temporary_mem_cache'
Flag if unused temporary memory of an operator should be
cached ('true', default) or freed ('false').
A single-threaded application can be speeded up by
caching global memory, whereas freeing reduces the memory
consumption of a multithreaded application at the expense
of speed.
Value: 'true' or 'false'
default: 'true'
'alloctmp_max_blocksize'
Maximum size of memory blocks to be allocated
within temporary memory management.
(No effect, if 'alloctmp_max_blocksize' == -1 or
'temporary_mem_cache' == 'false')
Value: -1 or >= 0
default: -1
'mmx_enable'
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)
default: 'true' if cpu supports MMX, else 'false'
'language'
Language used for error messages.
Value: 'english' or 'german'.
default: ' english'
|
SystemParameter (input_control) |
string(-array) -> string |
| Name of the system parameter to be changed. | |
| Default value: 'image_dir' | |
| List of values: 'alloctmp_max_blocksize', 'backing_store', 'border_shape_models', 'clip_region', 'clock_mode', 'current_runlength_number', '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', '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', 'store_empty_region', 'temporary_mem_cache', 'thread_num', 'thread_pool', 'update_lut', 'x_package' | |
|
Value (input_control) |
string(-array) -> string / integer / real |
| 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.
set_system is local and processed completely exclusively without parallelization.
reset_obj_db, get_system, set_check
get_system, set_check, count_seconds
Foundation