Skip to content

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

short.english
  Segment an image using a local threshold.;

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

warning.english
  This operator is obsolete.;

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🔗

module
  foundation;

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.

chapter.english
  Segmentation;

The structuring can be refined by specifying a section: chapter[,section], for example:

chapter.english
  Filter,Edges;

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🔗

functionality
  image;

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

any, window, image, region, object, xld_cont, xld_poly, xld_para, xld_mod_para, xld_ext_para

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.

keywords.english
  threshold, gray-value threshold, dynamic threshold, local threshold;

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.

see_also
  mean_image,smooth_image,gauss_filter,connection,rank_region,dilation1;

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 parallelization assigns 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_exclusively is 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 parallelization assigns 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_mutual is filled in with an operator, it is assumed that the operator needs no mutual exclusion (“optimistic” assumption).

process_locally: true, false;

This subslot of parallelization assigns, 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_locally is set to true, 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 method and domain_split, if process_locally is set to true. This avoids problems with local operators and multithreading and makes sense because local operators normally are responsible for graphical interaction and thus are not suitable for parallelization.

If no subslot process_locally is 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 parallelization can 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 method is set to anything other but none, the parameter slot costs_weight must be filled in for every input control parameter and the parameter slot postprocessing must be filled in for every output control parameter of the operator (see costs_weight)!

If the slot method is set to split_domain, the slot region_postprocessing (see below) must also be set correctly and may not be omitted!

If the slot process_locally is set to true, method should be set to none, because the operator won’t be parallelized then (see description of process_locally above).

Note that the slot method may contain any combination of the strings split_tuple, split_channel, and split_domain, because an operator may be parallelized by using any combination of those three methods. However, if none is specified with the slot method, no other string should be specified with it in order to keep the description consistent.

If no slot method is 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 parallelization must (only) be set for operators that are suitable for being parallelized by splitting the domain of input objects (i.e. slot method contains split_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_inp can only be used for operators, for which the subslot domain_split (see below) is set to 0. This method is suitable, for example, for the operator threshold which 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_inp can only be used for operators, for which the subslot domain_split (see below) is set to 0. For domain_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 assign domain_concat_mult_inp for 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 operator add_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 defining domain_concat_mult_inp for add_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.

complexity.english
  Let $F$ be the area of the input region.  Then the runtime
  complexity is $O(F)$.;

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.

class halconuser <- user

short.english
  Sample extension package.;

iid
  {bf6a1001-0b95-11d4-b295-00e0293dc2ac};

clsid
  {bf6a1002-0b95-11d4-b295-00e0293dc2ac};

library halconuser <- user_library

libid
  {bf6a1000-0b95-11d4-b295-00e0293dc2ac};

  1. Within the HALCON/C++ and HALCON/.NET class hierarchy, corresponding methods use slightly different conventions: extern_operator_name is transformed into ExternOperatorName. ↩

  2. User-defined extensions are not inserted in the class hierarchy but considered as global methods. ↩