Extended operator description🔗
An operator description within a DEF file must start with a header.
The following entries are variable in their order.
All of these slots begin with a determined keyword and are finished by a semicolon (;).
Semicolons within the text not defining the end of a slot must be quoted with a backslash (\;).
Some slots are language dependent:
For example, short.english contains a short description of the operator in English, short.german the same description in German.
The currently supported languages are English and German.
To allow international use of operators, we strongly recommend always providing all .english slots.
All slots specified within the operator description are accessible online within the HALCON system using the operator get_operator_info.
Describing the single parameters completes the operator description.
Parameter description explains how to do this.
Header🔗
The operator description starts with the header
extern_operator_name <- InternCProcedure
[InputObjects:OutputObjects:InputCtrlParams:OuputCtrlParams]
In contrast to the short version described in Short operator description, the header doesn’t contain any information about the types of the control parameters (e.g. $f) and does not end with a semicolon (;).
The following example is a short version of the operator description for the dynamic threshold operator dyn_threshold.
For better legibility, there should be a comment at the beginning of every operator description, like
/*********************** dyn_threshold *************************/
dyn_threshold <- CIPDynThreshold
[OrigImage,ThresholdImage:RegionDynThresh:Offset,LightDark:]
Comments within DEF files are indicated according to the C syntax (/* ... */).
There are a couple of conventions/restrictions concerning the names of parameters: All word parts should begin with a capital letter (for example, RegionDynThresh).
They are directly concatenated without any separating character.
Especially, they must not contain any underscore (_).
The external operator name exclusively consists of lower-case characters with word parts separated by underscores.
This operator name is used within C programs, low-level calls of the operator in C++, or within HDevelop.1
The four parameter classes (input-/output iconic object/control) are separated by colons (:). One class is described by a list of all parameter names within the class separated by commas. If there is no member of a class for an operator, the list remains empty. The example described above defines the following mapping between parameters and parameter classes:
| Parameter class | Keyword (see Name) | Parameter in the example |
|---|---|---|
| Input iconic objects | input_object |
OrigImage, ThresholdImage |
| Output iconic objects | output_object |
RegionDynThresh |
| Input control parameters | input_control |
Offset, LightDark |
| Output control parameters | output_control |
∅ |
It is helpful to follow certain conventions when choosing names for parameters. They should be meaningful and consequently should be given in English. It is convention to denote parameters that specify a position within an image matrix by Row(s) (not line!) and Column(s) or Col(s). Parameters defining a dimension are called Width and Height.
short🔗
The keyword short starts the short description of the operator, in our example
As all slots specified by the keyword .english, this slot contains purely textual information.
Text can be written in different languages and can contain LaTeX-commands according to special syntactic rules that are defined in Text in DEF files.
warning🔗
With the slot warning, you can show a warning text in bold at the beginning of an operator description, for example
As all slots specified by the keyword .english, this slot contains purely textual information.
Text can be written in different languages and can contain LaTeX-commands according to special syntactic rules that are defined in Text in DEF files.
abstract🔗
A more detailed description of the operator is given within the slot abstract.
The description of the example is here shown as a shortened version:
abstract.english
\OpRef{dyn_threshold} selects from the input image those regions in which the
pixel fulfill a threshold condition. Let $g_{o} = g_{\ParRef{OrigImage}}$,
and $g_{m} = g_{\ParRef{ThresholdImage}}$. Then the condition for
\ParRef{LightDark} = \ValRef{'light'} is:
@a
g_o >= g_m + Offset
@l\[
g_{o} \ge g_{m} + \ParRef{Offset}
\]
@e
For \ParRef{LightDark} = \ValRef{'dark'} the condition is:
@a
g_o <= g_m - Offset
@l\[
g_{o} \le g_{m} - \ParRef{Offset}
\]
@e
Finally, for \ParRef{LightDark} = \ValRef{'equal'} it is:
@a
g_m - Offset <= g_o <= g_m + Offset
@l\[
g_{m} - \ParRef{Offset} \le g_{o} \le g_{m} + \ParRef{Offset}
\]
@e
This means that all points in \ParRef{OrigImage} for which the gray value is
larger or equal to the gray value in \ParRef{ThresholdImage} plus an offset
are aggregated into the resulting region.;
Again, refer to Text in DEF files for the special syntax of text.
module🔗
This slot denotes the module inside HALCON the operator should belong to.
For user extensions the module `foundation’ is recommended.
chapter🔗
To achieve a useful structuring of HALCON operators, they are all arranged in a hierarchy of chapters and sections.
The assignment defined in the slot chapter is reflected in the reference manuals and in the menu Operator of HDevelop.
The structuring can be refined by specifying a section: chapter[,section], for example:
Note that it is not allowed to insert operators and sections into the same chapter at the same level of hierarchy. So if you decide to use sections within a chapter, all operators within this chapter must be assigned to one of these sections.
The chapters and sections created using the slot chapter may be supplemented by an optional chapter description as described in Chapter description.
functionality🔗
This slot denotes the class of which the operator should become a method within an object-oriented programming language like C++ or C#.2
Generally this corresponds to the semantic type of the first parameter, for example, an image object (image).
The specified name is only a symbolic one.
The actual class name depends on the programming language and is provided by the HALCON compiler hcomp.
Possible values for functionality in the current version are
keywords🔗
Furthermore, one can assign a list of keywords to an operator. They are used by HDevelop to support the search for the proper operators for a given problem, for example.
predecessor, successor, alternatives🔗
The following slots also support interactive development of image processing application with HALCON.
They are used to define potential, convenient or necessary predecessor (predecessor) and successor operators (successor) or to define alternatives (alternatives).
All operators within these lists are referenced by their name.
predecessor
mean_image,smooth_image,gauss_filter;
successor
connection,select_shape,reduce_domain,select_gray,rank_region,
dilation1,opening;
alternatives
highpass,threshold,background_seg;
see_also🔗
The slot see_also contains a list of operators that are used for similar tasks or help to understand how an operator works.
attention🔗
The slot attention contains hints for using the operator or specific limitations.
attention.english
If \ParRef{Offset} is chosen from @a -1 .. 1 @l$-1\dots1$@e
usually a very noisy region is generated, requiring large storage.
If \ParRef{Offset} is chosen too large ($>$ 60, say) it may happen
that no points fulfill the threshold condition (i.e.\ an empty
region is returned). If \ParRef{Offset} is chosen too small ($<$
-60, say) it may happen that all points fulfill the threshold
condition (i.e.\ a full region is returned).;
result_state🔗
The slot result_state defines the result value of an operator and the corresponding exception handling.
The syntactical rules for the text are again the same as described in Text in DEF files.
result_state.english
\OpRef{dyn_threshold} returns 2 (H\_MSG\_TRUE) if all parameters are
correct. The behavior with respect to the input images and output
regions can be determined by setting the values of the flags
\ValRef{'no_object_result'}, \ValRef{'empty_region_result'}, and
\ValRef{'store_empty_region'} with \OpRef{set_system}.
If necessary, an exception is raised.;
parallelization🔗
The slot parallelization results in the manual entry Execution Information.
It contains information about the timeout and parallelization characteristics of the operator.
On the one hand, this regards the possibility of using the operator in a parallel, for example, multithreaded application and on the other hand this regards the automatic parallelization which HALCON uses to speed up the operator’s processing when working with multi-processor or multi-core hardware.
The slot parallelization consists of several sub-slots, each starting with a characteristic keyword followed by a colon and finishing with a semicolon.
The example below shows the slot for the operator dyn_threshold, which is not “local”, needs neither complete nor mutual exclusion, and is parallelized on tuple and domain level.
The single subslots and their meaning will be described in the following sections.
parallelization
process_exclusively: false;
process_locally: false;
process_mutual: false;
method: split_tuple, split_domain;
region_postprocessing: domain_concat_si_inp;
process_exclusively: true, false, none;-
This subslot of
parallelizationassigns whether an operator is processed completely exclusively (true) by the main HALCON process/thread or not. An exclusive processing means that no other operator will be processed by HALCON while the exclusive operator is running. If an exclusive operator is started and other operators are still running, the processing of the exclusive operator is delayed until all other (currently running) operators have completed.An exclusively processed operator is always processed without any parallelization by the main HALCON thread/process. Note that even if HALCON is reentrant for most of the operators, there are still some operators that have to be processed exclusively due to reasons of their implementation.
If no subslot
process_exclusivelyis filled in with an operator, it is assumed that the operator needs no completely exclusive processing (“optimistic” assumption).If the subslot contains
none, the operator is processed by HALCON independently of other operators (even exclusive ones). This value is only used internally by MVTec. process_mutual: true, false;-
This subslot of
parallelizationassigns whether HALCON processes an operator under mutual exclusion (true) against itself or not. Here, a mutual exclusion means that the same operator may not run twice or more at the same time (but other HALCON operators can).An mutually processed operator is always processed without any parallelization by the main HALCON thread/process.
If no subslot
process_mutualis filled in with an operator, it is assumed that the operator needs no mutual exclusion (“optimistic” assumption). process_locally: true, false;-
This subslot of
parallelizationassigns, whether an operator must be processed locally (true) by a program thread, or whether it may called by any (“external”) thread without problems.If
process_locallyis set totrue, this signals the programmer that the corresponding operator must be used carefully within multithreaded applications. The simplest way to avoid any problems with such operators is to process them all under mutual exclusion within the main thread of the program.As a side effect, HALCON processes an operator without parallelization regardless the settings of the subslots
methodanddomain_split, ifprocess_locallyis set totrue. This avoids problems withlocaloperators and multithreading and makes sense becauselocaloperators normally are responsible for graphical interaction and thus are not suitable for parallelization.If no subslot
process_locallyis filled in with an operator, it is assumed that the operator must be processed “locally” (“pessimistic” assumption). However, this subslot should be filled in in any case, because it contains a very useful information for programmers of multithreaded applications. method: none, split_tuple, split_channel, split_domain, split_partial, split_partial_domain;-
This subslot of
parallelizationcan contain one or more of the strings above and specifies, which type of (automatic) parallelization the operator is suitable for:none: HALCON does not automatically parallelize the operator.split_tuple: HALCON parallelizes the operator by splitting every input image tuple into several subsets of the tuple; the tuple subsets are then processed in parallel.split_channel: HALCON parallelizes by splitting every multichannel (input) image into several subsets of the channels; the subsets are then processed in parallel.split_domain: HALCON parallelizes by splitting the domain of every input image into several parts; the parts are then processed in parallel.split_partial, split_partial_domain: These methods are only used by MVTec to indicate the internal parallelization of HALCON operators.
If
methodis set to anything other butnone, the parameter slotcosts_weightmust be filled in for every input control parameter and the parameter slotpostprocessingmust be filled in for every output control parameter of the operator (seecosts_weight)!If the slot
methodis set tosplit_domain, the slotregion_postprocessing(see below) must also be set correctly and may not be omitted!If the slot
process_locallyis set totrue,methodshould be set tonone, because the operator won’t be parallelized then (see description ofprocess_locallyabove).Note that the slot
methodmay contain any combination of the stringssplit_tuple,split_channel, andsplit_domain, because an operator may be parallelized by using any combination of those three methods. However, ifnoneis specified with the slotmethod, no other string should be specified with it in order to keep the description consistent.If no slot
methodis filled in with an operator, it is assumed that the operator is not suitable for being automatically parallelized (“pessimistic” assumption). region_postprocessing: none, domain_concat_si_inp, domain_concat_mult_inp;- This subslot of
parallelizationmust (only) be set for operators that are suitable for being parallelized by splitting the domain of input objects (i.e. slotmethodcontainssplit_domain). For such operators, HALCON supports a simple postprocessing of output region components: After splitting the domain of input objects and processing the operator in parallel (within the subparts of the original domain), HALCON creates the overall output iconic objects based on the output objects of the parallel processing. At this, it supports three methods for determining the domain/region components of overall output objects. -
Those three methods correspond to the three possible values of
region_postprocessing:none: No postprocessing of region/domain components.
Here, HALCON directly adopts the region components of input objects and re-uses them unchanged as the region components of the corresponding overall output objects. This method is especially suitable for operators which output solely image objects and where the domain is left unchanged, such as filter operators (e.g.mean_image).domain_concat_si_inp: Postprocess region components by concatenation for operators which have only a single input iconic parameter.
Here, HALCON creates the region components of overall output objects by concatenating the region components of the corresponding output objects of the parallel processing. At this, the latter regions must not overlap! Therefore,domain_concat_si_inpcan only be used for operators, for which the subslotdomain_split(see below) is set to0. This method is suitable, for example, for the operatorthresholdwhich outputs a region containing all pixels of a certain gray value range. Here, HALCON splits the input domain into disjunctive parts, processes the threshold operator in parallel, and finally concatenates the single result regions to one overall result region.domain_concat_mult_inp: Postprocess region components by concatenation for operators which have multiple input iconic parameter and which need a specific handling of the input objects.
This method is quite similar to that above, i.e., HALCON also creates the region components of overall output objects by concatenating the region components of the corresponding output objects of the parallel processing.
Again, the latter regions must not overlap! Therefore,domain_concat_mult_inpcan only be used for operators, for which the subslotdomain_split(see below) is set to0. Fordomain_concat_mult_inp, HALCON uses a specific handling of input objects. Normally, HALCON splits the domains of all objects of all input iconic parameters in the same manner (e.g., by splitting into the first and the second half of the chords, independent from the row index of the chords).
This does not mean any problem as long as all input image domains are the same – especially, if domains of corresponding objects of different input parameters are the same. Because then also the split domains will match each other. This is not the case if we have to expect that domains of objects of different input iconic parameters may differ. Here, it may happen that split domain parts of the first parameter and that of the second parameter do not overlap because of the simple splitting mechanism which does not take into account the row index of chords. If so, and if an operator uses, for example, an intersection of the input domains of different input parameters for defining the valid domain of the processed operation, it would get an empty region – in contrast to the sequential processing of the same operator. Therefore, we must assigndomain_concat_mult_inpfor such operators. This will force HALCON to only split the domains of the objects of the first input iconic parameter. The domains of input objects of all other input iconic parameters are left unchanged so that they fit to the domains of the first input iconic parameter regardless of their position in the image.
This method is suitable, for example, for the operatoradd_image, which adds two images and sets the domain of the result image to the intersection of the domains of the two input images. By definingdomain_concat_mult_inpforadd_image, HALCON only splits the domain of the first image to add, then calculates the intersection of the split domain parts with the unchanged domain of the second image in parallel, performs the addition of gray values in parallel, and finally merges the resulting region components (domains) by concatenation into the region component of the overall output image which also contains the added gray values.
abort_mode: break, cancel, both;- This subslot of parallelization must only be used to determine the supported timeout mode.
In case no timeout is supported, this slot must be omitted.
For an explanation of the different modes, see
set_operator_timeout.
Although we recommend specifying the whole slot parallelization, it is also possible to completely leave it out in an operator’s description.
In this case, it is assumed that the operator is reentrant, i.e. it is not processed under (complete or mutual) exclusion, and that it must be processed “locally”.
The latter also means that no parallelization is used when processing the operator.
This assumption corresponds exactly to those which are used in the case of missing single subslots (see descriptions above).
complexity🔗
The slot complexity describes the complexity of the operation in terms of number of points along a contour, the area of an image region etc.
example🔗
It is possible to describe an example under the keyword example in order to illustrate the usage of an operator.
An extension of the keyword specifies the programming language of the example.
example.trias
/* Looking for regions with the diameter D: */
mean_image(Imaged,Mean,D*2,D*2)
dyn_threshold(Image,Mean,Seg,5,'light')
connection(Seg,Objects);
The extension .trias indicates a HDevelop example.
Moreover, the extensions .c, .cpp, and .c# can be used.
The text of the example is processed unmodified, so it must not contain any LaTeX-special characters.
The only exception is the semicolon that needs a prefixed backslash, because it would signal the end of the example text otherwise.
This must be considered especially for C, C++, and C# examples.
references🔗
The slot references (not specified in the dyn_threshold example) is used to insert references to literature into the documentation, for example:
references
R.M. Haralick, K.G. Shapiro: ``Computer and Robot Vision''\;
Vol. 1, Addison-Wesley Publishing Company, 1992.;
class information🔗
At the end of the DEF file, i.e., after the parameter section described in Parameter description, information about the classes generated for HALCON/.NET must be added, in particular the COM class and library IDs in the subslots iid, clsid, and libid.
The example below shows the corresponding information in threshold.def.