optimize_aopT_optimize_aopOptimizeAopOptimizeAop (Operator)


optimize_aopT_optimize_aopOptimizeAopOptimizeAop — Check hardware regarding its potential for automatic operator parallelization.


optimize_aop( : : OperatorName, IconicType, FileName, GenParamName, GenParamValue : )

Herror T_optimize_aop(const Htuple OperatorName, const Htuple IconicType, const Htuple FileName, const Htuple GenParamName, const Htuple GenParamValue)

void OptimizeAop(const HTuple& OperatorName, const HTuple& IconicType, const HTuple& FileName, const HTuple& GenParamName, const HTuple& GenParamValue)

static void HSystem::OptimizeAop(const HTuple& OperatorName, const HTuple& IconicType, const HTuple& FileName, const HTuple& GenParamName, const HTuple& GenParamValue)

static void HSystem::OptimizeAop(const HString& OperatorName, const HString& IconicType, const HString& FileName, const HTuple& GenParamName, const HTuple& GenParamValue)

static void HSystem::OptimizeAop(const char* OperatorName, const char* IconicType, const char* FileName, const HTuple& GenParamName, const HTuple& GenParamValue)

static void HSystem::OptimizeAop(const wchar_t* OperatorName, const wchar_t* IconicType, const wchar_t* FileName, const HTuple& GenParamName, const HTuple& GenParamValue)   (Windows only)

static void HOperatorSet.OptimizeAop(HTuple operatorName, HTuple iconicType, HTuple fileName, HTuple genParamName, HTuple genParamValue)

static void HSystem.OptimizeAop(HTuple operatorName, HTuple iconicType, HTuple fileName, HTuple genParamName, HTuple genParamValue)

static void HSystem.OptimizeAop(string operatorName, string iconicType, string fileName, HTuple genParamName, HTuple genParamValue)


HALCON supports automatic operator parallelization (AOP) for various operators. optimize_aopoptimize_aopOptimizeAopOptimizeAopOptimizeAop is necessary for an efficient automatic parallelization, what HALCON uses to speed up the execution of operators. As the parallelization of operators is done automatically, there is no need for the user to explicitly prepare or change programs for their parallelization. Thus, all HALCON-based programs can be used without adaptations on multiprocessor hardware and users benefit from the potential of parallel hardware. By default, HALCON uses the maximum available number of threads for AOP, up to the number of processors. But, depending on the datasize and the parameter set passed to an operator, parallelizing on the maximum thread number might be too excessive and inefficient. optimize_aopoptimize_aopOptimizeAopOptimizeAopOptimizeAop optimizes the AOP in terms of thread number and checks a given hardware with respect to a parallel processing of HALCON operators. In doing so, it examines every operator, which can be possibly be sped up by an automatic parallelization on tuple, channel, or domain level (the partial level is not considered). Each examined operator is executed several times - both sequentially and parallel - with a changing set of input parameter values/images. The latter helps to evaluate dependencies between an operator's input parameter characteristics (e.g. the size of an input image) and the efficiency of its parallel processing. This may take up to a couple of hours depending on the settings of the operator's parameters. It is essential for a correct optimization not to run any other computation-intensive application simultaneously on the machine, as this would strongly influence the time measurements of the hardware check and thus would lead to wrong results.

Overall, optimize_aopoptimize_aopOptimizeAopOptimizeAopOptimizeAop performs several test loops and collects a lot of hardware-specific information which enables HALCON to optimize the automatic parallelization for a given hardware. The hardware information can be stored in a binary file given by FileNameFileNameFileNameFileNamefileName so that it can be used again in future HALCON sessions or even transfered to other machines, identical in hardware. When passing an empty string ''"""""""" as file name, optimize_aopoptimize_aopOptimizeAopOptimizeAopOptimizeAop stores the optimization data to the specific HALCON system file '.aop_info' in the HALCON installation directory (see environment variable $HALCONROOT) (Linux/macOS) or within the common application data folder (Windows). This specific file is automatically read when initializing HALCON during the first operator call. Note that the user must have appropriate privileges for read and write access. optimize_aopoptimize_aopOptimizeAopOptimizeAopOptimizeAop will check the file access before starting the AOP optimization and return an appropriate error when failing. The written file can be read by using the operator read_aop_knowledgeread_aop_knowledgeReadAopKnowledgeReadAopKnowledgeReadAopKnowledge again.

Thus, it is sufficient, to start optimize_aopoptimize_aopOptimizeAopOptimizeAopOptimizeAop once on each multiprocessor machine that is used for parallel processing. Of course, it should be started again, if the hardware of the machine changes, for example, by installing a new CPU, new memory, or if the operating system of the machine changes. It is necessary to start optimize_aopoptimize_aopOptimizeAopOptimizeAopOptimizeAop once for each new processing environment as the time response of operators may differ. A new processing environment is given, if different operating systems, such as Windows and Linux, or different HALCON architectures, different HALCON variants are used, i.e., HALCON versus HALCON XL, or when updating to a new HALCON version or revision. Together with the machine's host name, these dependencies form the knowledge attributes and are stored to the file together with the AOP optimization data. The attributes identify the machine-specific AOP knowledge set and enable the storage of different knowledge sets to the same file.

optimize_aopoptimize_aopOptimizeAopOptimizeAopOptimizeAop offers a set of parameters to restrict the extensiveness and specify the behavior of the optimization process. A subset of HALCON operators can be passed to OperatorNameOperatorNameOperatorNameOperatorNameoperatorName. This will restrict the optimization process to the operators passed by their name. When passing an empty string ''"""""""", all operators will be tested. A subset of iconic types that should be checked can be set by parameter IconicTypeIconicTypeIconicTypeIconicTypeiconicType. Again, passing an empty string ''"""""""" will test all supported iconic types. Further settings to modify the optimization process can be parameterized by a pair of values passed to GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue. Every entry in GenParamNameGenParamNameGenParamNameGenParamNamegenParamName must have a corresponding entry in GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue, meaning the tuples passed to the parameters must have the same length. GenParamNameGenParamNameGenParamNameGenParamNamegenParamName supports the values in following list, specifying for each possible value for GenParamNameGenParamNameGenParamNameGenParamNamegenParamName all possible applicable values for GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue:


does nothing specific but ignores the parameter GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue.

'system_mode'"system_mode""system_mode""system_mode""system_mode", 'file_mode'"file_mode""file_mode""file_mode""file_mode"

set the way how the information of the system or file, respectively, gets updated.


for GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue deletes all the existing information before the new knowledge loaded from file is added.


overwrites existing knowledge and adds new one (default).


keeps all existing operator information and just adds the knowledge not already contained.


performs the optimization process but refuses any update of the system or file, respectively.


also tests for appropriate operator parameters if the corresponding value of GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue is set to 'true'"true""true""true""true". These operator parameters are supposed to show significant influence on the operator's processing time like string parameters picking up a certain operator mode or method or, e.g., parameters setting a filter size. 'false'"false""false""false""false" dismisses the parameter check in favour of a faster knowledge identification (default).


sets the underlying simulation of the behavior of parallelizing operators on the current hardware. Different models can be selected by GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue differing in hardware adaptability and computation time:


determines if it is profitable to run on the maximum thread number or not. This is default on dual processor systems.


specifies a linear scale model to determine the best thread number for a given data size and parameter set. This is default on multiprocessor systems.


is the most complex but also most adaptable model. Note that the optimization process can take a couple of hours depending on the used hardware topology.


sets a maximum execution time for a tested operator. If the execution of an operator exeeds the timeout, the test on this operator is aborted. No information about this operator will be stored in this case. The timeout value is set by GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue in seconds. Specifying 'infinite'"infinite""infinite""infinite""infinite" prevents any abortion of an operator's optimization process (default).


restricts the optimization process on a certain parallelization method. The corresponding value of GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue can contain one of the following values, therefore:


performs the check on all image processing operators supporting data parallelization on domain level.


performs the check on all image processing operators supporting data parallelization on channel level.


performs the check on all operators supporting data parallelization on tuple level.


During its test loops optimize_aopoptimize_aopOptimizeAopOptimizeAopOptimizeAop has to start every examined operator several times. Thus, the processing time of optimize_aopoptimize_aopOptimizeAopOptimizeAopOptimizeAop can be rather long depending on the operator's parameter settings. It is essential for a correct optimization not run any other computation-intensive application simultaneously on the machine, as this would strongly influence the time measurements of the hardware check and thus would lead to wrong results. Note that according to the file location optimize_aopoptimize_aopOptimizeAopOptimizeAopOptimizeAop must be called by users with the appropriate privileges for storing the parallelization information. See the operator's description above for more details about these subjects.

Execution Information


OperatorNameOperatorNameOperatorNameOperatorNameoperatorName (input_control)  string(-array) HTupleHTupleHtuple (string) (string) (HString) (char*)

Operators to check

Default value: '' "" "" "" ""

IconicTypeIconicTypeIconicTypeIconicTypeiconicType (input_control)  string(-array) HTupleHTupleHtuple (string) (string) (HString) (char*)

Iconic object types to check

Default value: '' "" "" "" ""

Suggested values: ''"""""""", 'byte'"byte""byte""byte""byte", 'int1'"int1""int1""int1""int1", 'int2'"int2""int2""int2""int2", 'uint2'"uint2""uint2""uint2""uint2", 'int4'"int4""int4""int4""int4", 'int8'"int8""int8""int8""int8", 'direction'"direction""direction""direction""direction", 'cyclic'"cyclic""cyclic""cyclic""cyclic", 'vector_field'"vector_field""vector_field""vector_field""vector_field", 'complex'"complex""complex""complex""complex", 'region'"region""region""region""region", 'xld'"xld""xld""xld""xld", 'xld_cont'"xld_cont""xld_cont""xld_cont""xld_cont", 'xld_poly'"xld_poly""xld_poly""xld_poly""xld_poly"

FileNameFileNameFileNameFileNamefileName (input_control)  filename.write HTupleHTupleHtuple (string / integer) (string / int / long) (HString / Hlong) (char* / Hlong)

Knowledge file name

Default value: '' "" "" "" ""

GenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control)  string-array HTupleHTupleHtuple (string) (string) (HString) (char*)

Parameter name

Default value: 'none' "none" "none" "none" "none"

Suggested values: 'parameters'"parameters""parameters""parameters""parameters", 'model'"model""model""model""model", 'timeout'"timeout""timeout""timeout""timeout", 'file_mode'"file_mode""file_mode""file_mode""file_mode", 'system_mode'"system_mode""system_mode""system_mode""system_mode", 'split_level'"split_level""split_level""split_level""split_level"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control)  string-array HTupleHTupleHtuple (string / real / integer) (string / double / int / long) (HString / double / Hlong) (char* / double / Hlong)

Parameter value

Number of elements: GenParamName == GenParamValue

Default value: 'none' "none" "none" "none" "none"

Suggested values: 'true'"true""true""true""true", 'renew'"renew""renew""renew""renew", 'truncate'"truncate""truncate""truncate""truncate", 'threshold'"threshold""threshold""threshold""threshold", 'linear'"linear""linear""linear""linear", 'mlp'"mlp""mlp""mlp""mlp", -1.0


optimize_aopoptimize_aopOptimizeAopOptimizeAopOptimizeAop returns 2 (H_MSG_TRUE) if all parameters are correct and the file could be read. If necessary, an exception is raised.