8.2   Control Types and Constants

All non-iconic data is represented by so called control data (numbers, strings or handles) in HDevelop. The name is derived from their respective functions within HALCON operators where they control the behavior of image processing, for example, thresholds for a segmentation operator. Control parameters in HDevelop may contain arithmetic or logical operations. A control data item can be of one of the following data types: integer, real, string, boolean, and handle.

integer  

The data type integer is used under the same syntactical rules as in C. Integer numbers can be input in the standard decimal notation, in hexadecimal by prefixing the number with 0x, and in octal by prefixing the number with 0 (zero).

For example:

  4711
  -123
  0xbeef (48879 in decimal notation)
  073421 (30481 in decimal notation)

Data items of type integer are converted to their machine-internal representations, that is the C type long (4 or 8 bytes).

The minimum and maximum possible values of an integer depend on whether the 64- or 32-bit version of HALCON is used. You can use the operator tuple_number to verify that a value fits into the range of the integer data type. For a reference, see table 8.1.

	64-bit	32-bit
Minimum value	− 9223372036854775808	− 2147483648
Maximum value	9223372036854775807	2147483647

Table 8.1: Minimum and maximum values of integer.

real  

The data type real is used under the same syntactical rules as in C.

For example:

  73.815
  0.32214
  .56
  -17.32e-122
  32E19

Data items of type real are converted to their machine-internal representations, that is the C type double (8 bytes).

string  

A string is a sequence of characters that is enclosed in single quotes ('). Special characters, like the line feed, are represented in the C-like notation, as you can see in table 8.2, see the reference of the C language for comparison. You can enter arbitrary characters using the format \xnn where nn is a two-digit hexadecimal number, or using the format \0nnn where nnn is a three-digit octal number. Less digits may be used if the string is unambiguous. For example, a line feed may be specified as \xa unless the string continues with another hexadecimal digit (0-F).

Meaning	Abbreviation	Notation
line feed	NL (LF)	\n
horizontal tabulator	HT	\t
vertical tabulator	VT	\v
backspace	BS	\b
carriage return	CR	\r
form feed	FF	\f
bell	BEL	\a
backslash	\	\\
single quote	'	\'
arbitrary character (hexadecimal)		\xnn
arbitrary character (octal)		\0nnn

Table 8.2: Substitutes for special characters.

For example: The string Sobel's edge-filter has to be specified as 'Sobel\'s edge-filter'. A Windows directory path can be entered as 'C:\\Programs\\MVTec\\Halcon\\images'

boolean  

The constants true and false belong to the data type boolean. The value true is internally represented by the number 1 and the value false by 0. This means, that in the expression Val := true the effective value of Val is set to 1. In general, every integer value other than 0 means true. Note that some HALCON operators take logical values for input, for example, set_system. In this case, the HALCON operators expect string constants like 'true' or 'false' rather than the boolean values true or false.

handle  

Handles are references to complex data structures, for example, a connection to an image acquisition device or a model for shape-based matching.

In addition to these general types, there are special constants and the type tuple, which are specific to HALCON or HDevelop, respectively. HDevelop also supports the variable type vector, see section “Vectors”.

constants  

For the return value (result state) of an operator, constants exist. The constants can be used together with the operator dev_error_var and dev_set_check. These constants represent the normal return value of an operator, so-called messages. For errors, no constants are available but there are plenty of error numbers internally, see the 扩展包程序员手册. In table 8.3, all return messages can be found.

Constant	Meaning	Value
H_MSG_TRUE	No error; for tests: true	2
H_MSG_FALSE	For tests: false	3
H_MSG_VOID	No result could be computed	4
H_MSG_FAIL	Operator did not succeed	5

Table 8.3: Return values for operators.

Additionally, there are constants for the types of control data, see table 8.4. These can be compared to the result of a type operation to react to different types of control data, see section “Type Operations”.

Constant	Meaning	Value
H_TYPE_INT	integer value	1
H_TYPE_REAL	real value	2
H_TYPE_STRING	string value	4
H_TYPE_MIXED	mixed value	8
H_TYPE_HANDLE	handle value	16
H_TYPE_ANY	empty tuple	31

Table 8.4: Type values for control data.

Finally, you can access minimum and maximum values of integers and floating-point numbers via the constants mentioned in table 8.5.

Constant	Meaning
H_FLOAT32_EPSILON	maximal relative approximation error for 32-bit floating-point numbers
H_FLOAT32_MAX	largest possible 32-bit floating-point number
H_FLOAT32_MIN	smallest possible 32-bit floating-point number
H_FLOAT32_MIN_POSITIVE	smallest possible positive floating-point number (32-bit)
H_FLOAT64_EPSILON	maximal relative approximation error for 64-bit floating-point numbers
H_FLOAT64_MAX	largest possible 64-bit floating-point number
H_FLOAT64_MIN	smallest possible 64-bit floating-point number
H_FLOAT64_MIN_POSITIVE	smallest possible positive 64-bit floating-point number
H_FLOAT_INFINITY	∞ (for example: 1.0 / 0.0), shown as inf in variable window
H_FLOAT_NAN	Not a Number (NaN), shown as nan in variable window
H_FLOAT_NEG_INFINITY	− ∞ (for example:  − 1.0 / 0.0), shown as -inf in variable window
H_INT32_MAX	largest possible 32-bit integer
H_INT32_MIN	smallest possible 32-bit integer
H_INT64_MAX	largest possible 64-bit integer (error in 32-bit HALCON)
H_INT64_MIN	smallest possible 64-bit integer (error in 32-bit HALCON)
H_INT_MAX	H_INT64_MAX or H_INT32_MAX, depending on HALCON version
H_INT_MIN	H_INT64_MIN or H_INT32_MIN, depending on HALCON version

Table 8.5: Numeric constants.

For further explanation of the numeric constants, see the HDevelop example program tuple_numeric_limits.hdev. See also the description of the operator tuple_constant.

tuple  

The control types are only used within the generic HDevelop type tuple. A tuple of length 1 is interpreted as an atomic value. A tuple may consist of several data items with different types. The standard representation of a tuple is a listing of its elements included into brackets. This is illustrated in figure 8.1.

Figure 8.1: Syntax of tuple constants.

[] specifies the empty tuple. A tuple with just one element is to be considered as a special case, because it can either be specified in the tuple notation or as an atomic value: [55] defines the same constant as 55. Examples for tuples are:

  []
  4711
  0.815
  'Text'
  [16]
  [100.0,100.0,200.0,200.0]
  ['FileName','Extension']
  [4711,0.815,'Hugo']