Skip to content

Parameter descriptionđź”—

Note that the number of parameters is limited for an extension package operators as listed in the Installation reference.

Again, the definition of dyn_threshold is used as an example. Every description of a single parameter starts with the keyword parameter and contains several slots. A slot begins with a characteristic keyword followed by a colon and is finished by a semicolon. All slots specified for the parameters of an operator are accessible online within the HALCON system using the operator get_param_info.

parameter
  OrigImage:           input_object;
  description.english: Image to be segmented.;
  sem_type:            image;
  type_list:           byte,int2,int4,real;
  multivalue:          optional;

parameter
  ThresholdImage:      input_object;
  description.english: Image containing the local thresholds.;
  sem_type:            image;
  type_list:           byte,int2,int4,real;
  multivalue:          optional;

parameter
  RegionDynThresh:     output_object;
  description.english: Segmented regions.;
  sem_type:            region;
  multivalue:          optional;
parameter
  Offset:              input_control;
  description.english: Offset added to ThresholdImage.;
  sem_type:            number;
  type_list:           integer,real;
  default_type:        real;
  default_value:       5.0;
  values:              1.0, 3.0, 5.0, 7.0, 10.0, 20.0, 30.0;
  multivalue:          false;
  assertion:           -255 < Offset && Offset < 255;
  costs_weight:        0;

parameter
  LightDark:           input_control;
  description.english: Extract light, dark or similar areas?;
  sem_type:            string;
  type_list:           string;
  default_type:        string;
  default_value:       light;
  value_list:          dark,light,equal,not_equal;
  multivalue:          false;
  costs_weight:        0;

The minimum of information needed for every parameter is its name and type, its default type, its semantic type, the number of values allowed (multivalue), and, if the operator should be automatically parallelized, the “costs weight” of input control parameters and the “postprocessing” of output control parameters, see below.

Nameđź”—

parameter
Name: input_object,output_object,input_control,output_control;

This defines the name and the class of a parameter. The parameters must be described in the same order as in their definition within the header of the operator description.

Note

To create PDF hyperlinks referencing parameters (see Text in DEF files and Creating the PDF reference manuals) a parameter name must consist of alphanumerical characters only.

default_typeđź”—

default_type: handle, integer,real,string;

Only for control parameters! This slot specifies, what C type to use in general. It must have exactly one of the four above values.

sem_typeđź”—

sem_type: _class[.spec]_;

This slot determines the semantic type, i.e., it specifies the class of data passed as parameters, when using an object-oriented language. Names of classes within the DEF file are only symbolic. The mapping to the actual class names is provided by the HALCON compiler hcomp.

HDevelop also uses the semantic types, for example, to provide specific inspection routines. A list with the semantic types is given in HALCON semantic types. Some exemplary semantic types (classes) are shown below.

Iconic data (object parameters)
object (any iconic object: images, regions, XLDs)
image (images)
region (regions)
xld (any XLDs)
xld_cont, xld_poly, xld_para, xld_mod_para, xld_ext_para
Elementary data (control parameters)
number (unspecific)
integer, real, string
channel (channel number)
Handles (control parameters)
window (HALCON graphics window)
Arrays (control parameters)
histogram.values (gray value histogram)
distribution.values (distribution)
Geometric data (control parameters)
point.x, point.y (position; (column, row) except for 2D transformations to get mathematically positive rotation)
extent.x, extent.y (dimensioning)
angle.deg, angle.rad (angle given in degrees or radians, respectively)
circle.center.y, circle.center.x, circle.radius (circle)
line.begin.y, line.begin.x, line.end.y, line.end.x (line)
rectangle.origin.y, rectangle.origin.x (rectangle: upper left corner),
rectangle.corner.y, rectangle.corner.x (lower right corner) or
rectangle.extent.x rectangle.extent.y (expansion – as alternative to specifying the 2nd corner)
rectangle2.center.y, rectangle2.center.x (rectangle with arbitrary orientation: center),
rectangle2.angle.rad (orientation – in radians),
rectangle2.hwidth, rectangle2.hheigth (half the size)
ellipse.center.y, ellipse.center.x (ellipse: center),
ellipse.angle.rad (orientation – in radians),
ellipse.radius1, ellipse.radius2 (radii)
arc.center.y, arc.center.x (circle: center),
arc.angle.rad (angle stretched by the circular arc – in radians),
arc.begin.y, arc.begin.x (starting point of circular arc).
hom_mat2d (2D homogeneous transformation matrix)
hom_mat3d (3D homogeneous transformation matrix)
pose (3D pose)
Numerical region descriptions (control parameters)
coordinates.y, coordinates.x (coordinates)
contour.y, contour.x (points of a contour)
chord.y, chord.x1, chord.x2 (runlength code)
polygon.y, polygon.x (polygonal representation)
chain.begin.y, chain.begin.x, chain.code (chain code)
Miscellaneous (control parameters)
filename (name of a file)
filename.read (name of an input file)
filename.write (name of an output file)
attribute.name (name of a generic parameter)
attribute.value (value of a generic parameter)

Note

  • Use the above semantic types for characterizing parameters whenever they are applicable.
  • For control parameters characterizing a composed object like a circle, etc.: Use the specific order of parameters like indicated above.

modifiedđź”—

modified: false,true;

This slot is used to indicate input parameters that may be modified by the operator, for example, handles. If modified is set to 'true', a respective note is automatically created in the corresponding reference manual entry.

multivalueđź”—

multivalue: true,false,optional;

This slot describes the number of values passed in a parameter: 'true' means that an array (tuple) of values must be passed. If 'false' is specified, exactly one value must be passed. 'optional' allows both. If a parameter may also return no values at all, multivalue must be set to 'true' or 'optional'.

All slots mentioned so far must appear in any extended operator description. Moreover, the following optional slots are recommended to provide further information about parameters:

costs_weightđź”—

costs_weight: an unsigned integer value;

This slot must only be used for input control parameters of operators which are suitable for being automatically parallelized (i.e. for operators for that the parallelization subslot method does not contain 'none'; see parallelization). Here, it assigns, whether the time for processing the operator directly depends on the content (value) of the corresponding input control parameter. If costs_weight is set to '0', the duration of the operator processing does not directly depend on the content of the corresponding input control parameter. In this case, the parameter will not be taken into account when HALCON decides, whether an operator should be parallelized for a given allocation of input parameters or not. This also means that this parameter will not be checked during the hardware training (compare the description of optimize_aop). This helps to speed up the training.

If costs_weight contains a value greater than '0', this assigns that there is a direct dependency between the content of the corresponding input control parameter and the computation time of the operator. In this case, HALCON will take into account this parameter during its hardware check (optimize_aop) in order to determine its influence on the operator’s processing time. Note that the slot costs_weight must be filled in for every input control parameter, if the operator should be automatically parallelized, i.e. if the operator’s slot method does not contain 'none' (see parallelization).

postprocessingđź”—

postprocessing: none,tuple_add,tuple_min,tuple_max,tuple_concat, channel_add,channel_min,channel_max,channel_concat, domain_add,domain_min,domain_max,domain_concat;

This slot must only be used for output control parameters of operators which are suitable for being automatically parallelized (i.e. for operators for that the parallelization subslot method does not contain 'none'; see parallelization). Here, postprocessing specifies, which kind of postprocessing is used with the single result values of a parallel processed operator. If, for example, an operator is parallelized by splitting a tuple of iconic input objects and the single result values of the parallel processed operator must be put into one output control object again, the slot postprocessing should contain the keyword 'tuple_concat' which means “concatenate result values”. Or if an operator is parallelized by splitting the single channels of iconic input objects and the overall result value is the minimum of the single result values of the parallel processed operator, postprocessing should contain the keyword 'channel_minimum'. The slot postprocessing can contain several strings in order to define different postprocessing steps for different levels of parallelization (tuple, channel, and domain); of course, there should only be one string per level.

If 'none' is specified (in this case, no other string should be specified), no postprocessing is done on every parallelization level. This means that the overall result value of the corresponding output control parameter is directly determined by the result value of the first parallelized operator instance (e.g., the instance which worked on the first tuple element).
Altogether, HALCON currently supports the following postprocessing steps:

  • none: no postprocessing; adopt first value;
  • tuple_add: overall result value is the sum of the single result values of the tuple parallelization;
  • tuple_min: overall result value is the minimum of the single result values of the tuple parallelization;
  • tuple_max: overall result value is the maximum of the single result values of the tuple parallelization;
  • tuple_concat: overall result value is a tuple which contains all the result values of the tuple parallelization (“concatenation”);
  • channel_add: overall result value is the sum of the single result values of the channel parallelization;
  • channel_min: overall result value is the minimum of the single result values of the channel parallelization;
  • channel_max: overall result value is the maximum of the single result values of the channel parallelization;
  • channel_concat: overall result value is a tuple which contains all the result values of the channel parallelization (“concatenation”);
  • domain_add: overall result value is the sum of the single result values of the parallelization on domain level;
  • domain_min: overall result value is the minimum of the single result values of the parallelization on domain level;
  • domain_max: overall result value is the maximum of the single result values of the parallelization on domain level;
  • domain_concat: overall result value is a tuple which contains all the result values of the parallelization on domain level (“concatenation”);

The example below shows the definition of postprocessing for the operator circularity, which calculates the shape factor for the circularity (similarity to a circle) of input regions. If circularity is tuple parallelized the overall result is a tuple of values, of which the single elements contain the “circularity” of the single input regions. Thus the postprocessing of the corresponding output control parameter is assigned by 'tuple_concat'.

parameter
  Circularity:             output_control;
  description.english:     Roundness of the input region(s).;
  sem_type:                real;
  type_list:               real;
  default_type:            real;
  multivalue:              optional;
  assertion:               0 <= Circularity && Circularity <= 1.0;
  postprocessing:          tuple_concat;

Note that the slot postprocessing must be filled in for every output control parameter, if the operator should be automatically parallelized, i.e. if the operator’s slot method does not contain 'none' (see parallelization).

descriptionđź”—

description.english:LaTeX/Ascii-Text;

This slot contains a short description of the parameter. The extension .english refers to a English description. In addition to that a German description might be given in description.german. For the syntax of LaTeX/Ascii-Text, see Text in DEF files.

type_listđź”—

The slot type_list is only used in connection with object parameters with sem_type = image and for control parameters.

For images (sem_type = image):
type_list: any,byte,int1,int2,int4,real,cyclic,direction,complex;

For images this slot contains an enumeration of all supported pixel types. Note that in many cases there will be more than one supported pixel type. Thus, type_list is a list separated by commas.

For control parameters:
type_list: handle, integer,real,string;

For control parameters, this slot contains a list of all C-types allowed for the parameter.

default_valueđź”—

default_value:Default;

This slot defines the default value used by HDevelop to initialize the parameter in the operator window, for example. Suggesting default values can help the programmer to find suitable values of parameters. Generally, strings are unquoted in the description (not 'theString', but theString); exceptions: empty string ('') and strings with special characters ('the string').

valuesđź”—

values:Suggested values;

This slot contains a collection of possible values. This list does not have to be complete. It just suggests some typical values the user might want to try.

value_listđź”—

value_list:List of values;

This slot contains a complete list of all allowed values. So, if a parameter can hold only a discrete number of specific values, value_list should be specified, otherwise values might be used to provide some typical values.

value_min, value_maxđź”—

value_min:Number;
value_max:Number;

Instead of a list an interval may be used to specify a range of values for a parameter. The interval may be unlimited in one direction. The slot value_min specifies the minimum of the allowed values, value_max the maximum.

Please note that the range is not used to check the passed parameter values. The slots are provided for applications that need the possible range of values to create sliders or other graphical elements to interact with parameters.

To restrict the values of a parameter, use the slot assertion.

step_rec, step_min, value_functionđź”—

step_rec:Number;
step_min:Number;
value_function: lin,log,quad, … ;

If a range of values is possible for a parameter it might be a useful information to specify a suitable step width (step_rec) between distinct values to be tested. Based on this information a user interface might generate a list of suggestions for parameter values. The corresponding minimum reasonable step width can be provided by step_min. The step width can also be modified by specifying a function in the slot value_function.

value_numberđź”—

value_number:boolean expression;

This slot contains a boolean expression that determines how the number of passed or returned values of a parameter is absolutely or relatively connected to the number of values in other parameters or some absolute values. The operators and functions listed in Table 1 may appear within the expression.

Table 1: Operators and functions used for the slots value_number and assertion
Group Symbol Meaning
Unary operators ! logical NOT
- negation
Binary operators && logical AND
|| logical OR
== equal
!= not equal
> greater
>= greater or equal
< less
<= less or equal
+ sum
- difference
* multiplication
/ division (DIV)
% rest of division (MOD)
Functions odd true, if odd
even true, if even
ld binary logarithm
length length
number number of values (only for assertion)
width (image-)width
height (image-)height

Example

  • Param1 == Param2 && Param2 > 0
    This means that the same number of values and at least one value must be passed with parameter 1 and parameter 2.
  • Param2 == 3
    This means that exactly three values must be passed with parameter 2.

For output parameters this can be seen as an assertion. This may also refer to input parameters, e.g.: RegionOut <= RegionIn in connection with the HALCON operator select_shape expresses the fact that the number of output regions does not exceed the number of input regions.

assertionđź”—

assertion:boolean expression;

This slot contains a boolean expression that determines how the passed or returned values of parameters are absolutely or relatively connected to the values of other parameters or some absolute values. The same expressions may appear as described above for value_number, see Table 1.

Example

  • Param1 == Param2 && Param2 > 0
    This means that parameter 1 and 2 must have the same value and this value is greater than 0.
  • 0 <= Param2 && Param2 <= 255
    This means that parameter 2 must have a value between 0 and 255.
  • Param1 <= number(ImageIn)
    This means that the value of parameter 1 must be less or equal the number of input images.
  • Param2 < width(ImageIn) && Param2 >= 0 && odd(Param2)
    This means that the value of parameter 2 must be between 0 and the width of the input image and must be an even number.

multichannelđź”—

multichannel: true,false,optional;

This slot is only used in connections with image objects. It contains an assertion about the necessary or supported number of channels of an image. If set to false, the processing is done only on the first channel (all others are ignored), if set to true, a multichannel image must be passed. optional specifies operators that can work on more than one channel but can also work on only one channel as well.

multiinstanceđź”—

multiinstance: true,false,optional;

This slot is used for semantic tuples. A semantic tuple is a tuple of values that, put together, describes a single instance, for example, a pose (consisting of seven values) or calibration parameters (consisting of several values, depending on the camera type).

The slot multiinstance is only used if multivalues = true. As for one instance multiple values need to be permitted you can use multiinstance in order to specify if multiple semantic tuples may be passed (true) or not (false). optional specifies operators that can work on both one or more semantic tuples.

file_ext, file_ext_descrđź”—

file_ext:list of file extensions;
file_ext_descr.english:list of descriptions;

These slots are used for parameters of the semantic type filename (see sem_type). In file_ext, you can specify a list of possible file extensions. HDevelop, for example, uses this information when opening file selectors.

In file_ext_descr.english (and file_ext_descr.german), you can add descriptions for the extensions. If file_ext contains a list of extensions, you can either pass a single description for all of them or one for each extension. When passing a list of descriptions, you can insert a period to indicate that the previous value should be used. If a description contains a space, you must enclose it in single quotes. Note that HDevelop automatically appends the text Files to the descriptions.

Example

  • file_ext: tif,tiff,gif;
    file_ext_descr.english: Image;

    results in:
    Image Files (*.tif; *.tiff; *.gif)

  • file_ext: tif,tiff,gif;
    file_ext_descr.english: 'TIFF Image',.,'GIF Image';

    results in:
    TIFF Image Files (*.tif)
    TIFF Image Files (*.tiff)
    GIF Image Files (*.gif)