Skip to content

Describing operators (DEF files)đź”—

The following sections give a detailed description of the steps mentioned in About HALCON operators and extension packages. This is done with respect to system-defined HALCON operators as well as to the examples within the directory %HALCONEXAMPLES%\extension_package\halconuser. We start with the generation of an operator description.

Important

DEF files with non-ASCII characters should be UTF-8 encoded.

Short operator descriptionđź”—

Before implementing an operator the author should think about the task of the operator and what kind of user interface is best for calling the operator. This specification is used to automatically generate the interface code for the desired host language with the HALCON compiler hcomp.

To do this, it is necessary to describe at least the following features beside the operator name in a DEF file:

  • the name of the operator as used within the application programming language,
  • the name of the C-procedure (supply procedure) called by HALCON in order to start the processing (this procedure must be implemented later on),
  • all iconic objects and control parameters that are needed by the operator as input (input parameters),
  • all iconic objects and control parameters that are returned by the operator as result (output parameters),
  • the types of these parameters,
  • the number of values per parameter (there is only a distinction between parameters that need or can process exactly one value and those expecting more than one value).

There exist two kinds of parameters within HALCON: Iconic object parameters and parameters containing any other data – so called control parameters. By distinguishing input and output parameters we get four parameter classes: Input iconic object parameters, output iconic object parameters, input control parameters, and output control parameters. Basically, specifying the number of parameters per class would suffice to describe the operator. The internal access (in particular within the supply procedure) on individual parameters works this way by using the parameter’s position within its class. But to refer to single parameters and add further information regarding a parameter, it is useful to give it a name.

The information specified up to now is already sufficient to integrate an operator within the HALCON/Extension Package Interface by using hcomp. It describes the operator properly and may be specified as a “one line short version” of the DEF file according to the following syntax:

extern_operator_name <- InternCProcedure
          [InputObjects:OutputObjects:InputCtrlParams:OuputCtrlParams];

Extended operator description explains the meaning of the single identifiers and the name convention. Please note that in contrast to the header mentioned there, the short version header must be finished by a semicolon (;) and that the default type and the number of values is specified together with the name of a control parameter (InputCtrlParams and OuputCtrlParams). This is done by concatenating a dollar sign and an additional character to the name encoding the type and number of values (see the example in Short version of the definition of the operator user_inside).

Short version of the definition of the operator user_inside

user_inside <- CIPUserSelect[Regions:RegionSelected:Row$i,Column$i:];

Compare %HALCONEXAMPLES%\extension_package\halconuser\def\regionfeatures.def

The following table shows how to code types and number of values into a character. Lower-case characters stand for exactly one value in the specified parameter. This corresponds to assigning multivalue: false in the extended version. Capital letters specify parameters that contain one or more than one value (multivalue: optional).

Type C-type Code: one value Code: unlimited number
Integer long i I
Floating-point Value double f F
String char * s S

The specification described so far is sufficient to integrate the operator into C applications. However, in general the new operators should also be usable by HDevelop or within C++ or .NET applications. To achieve this, an extended version of the operator description must be generated. This is described in Extended operator description.