About the parameter classes🔗
HALCON distinguishes these classes of operator parameters:
-
Iconic parameters (input image objects and output image objects)
- Images
- There is more to HALCON images than just a matrix of pixels:
In HALCON, this matrix is called a channel, and images may consist of one or more such channels.
For example, gray value images consist of a single channel, color images of three channels.
An image coordinate therefore isn’t necessarily represented by a single gray value, but by a vector of up to n gray values (if the coordinate lies within the image region).
Channels can not only contain the standard 8-bit pixels (pixel typebyte) used to represent gray value images, HALCON allows images to contain various other data, for example, 16-bit integers (typeint2) or 32-bit floating point numbers (typereal) to represent derivatives.
Besides the pixel information, each HALCON image also stores its so-called domain in form of a HALCON region. The domain can be interpreted as a region of interest, that is, HALCON operators (with some exceptions) restrict their processing to this region. - Regions
- A region is a set of coordinates in the image plane.
Such a region does not need to be connected and it may contain holes.
A region can be larger than the actual image format.
Regions are represented by the so-called “runlength coding” in HALCON. - XLD objects
- XLD is a data structure used for describing areas (for example, arbitrarily sized regions or polygons) or any closed or open contour, which includes lines.
In contrast to regions, which represent all areas at pixel precision, XLD objects provide subpixel precision.
There are two basic XLD structures: contours and polygons.
-
Control parameters (input control parameters and output control parameters)
- integer numbers
- floating point numbers
- strings
- handles
More Info
The HALCON operator reference contains a complete list of the generic classes and member functions of HALCON/C++.
In addition, HALCON/C++ contains many operator overloads.
For more information, see Overloading operators.
More Info
The HALCON operator reference contains a complete list of the generic classes and member functions of HALCON/.NET.
In addition, HALCON/.NET contains many operator overloads.
For more information, see Overloading operators.
A strength of HALCON is that most operators automatically work with multiple input values (tuple values). These different approaches are also called “simple mode” versus “tuple mode.”
For example, you can call the operator AreaCenter with a single or with multiple input regions.
The operator automatically returns the area and center coordinates of all passed regions. Analogously, if you call GenRectangle1 with multiple values for the rectangle coordinates, it creates multiple regions.
Calling operators with single or multiple values
You can check whether an operator also works with tuples in the operator reference.
Below, we show the relevant parts of the operators AreaCenter and GenRectangle1.
As shown, the iconic classes like HRegion automatically handle multiple values.
Whether such a parameter accepts or returns multiple values is not visible from the signature, but only in the parameter section:
Here, an appended (-array) (in the example: HRegion(-array)) signals that the parameter can contain a single or multiple values.
Reference entry of AreaCenter
Reference entry of GenRectangle1
static void HOperatorSet.GenRectangle1
(out HObject rectangle, HTuple row1, HTuple column1, HTuple row2, HTuple column2)
public HRegion
(HTuple row1, HTuple column1, HTuple row2, HTuple column2)
public HRegion
(double row1, double column1, double row2, double column2)
void HRegion.GenRectangle1
(HTuple row1, HTuple column1, HTuple row2, HTuple column2)
void HRegion.GenRectangle1
(double row1, double column1, double row2, double column2)
rectangle (output_object) region(-array) → HRegion
row1 (input_control) rectangle.origin.y(-array) → HTuple (double / int / long)
column1 (input_control) rectangle.origin.x(-array) → HTuple (double / int / long)
row2 (input_control) rectangle.corner.y(-array) → HTuple (double / int / long)
column2 (input_control) rectangle.corner.x(-array) → HTuple (double / int / long)
In contrast, control parameters show whether they contain a single or multiple values by their data type.
Example
In the first case, they use basic data types like double.
In the second case, they use the HALCON/.NET class HTuple.
Thus, you can call GenRectangle1 via HRegion in two ways, either by passing doubles or HTuples (here, using the constructor form):
HRegion SingleRegion = new HRegion(10.0, 10.0, 50.0, 50.0);
HRegion MultipleRegions = new HRegion(new HTuple(20.0, 30.0), new HTuple(20.0, 30.0),
new HTuple(60.0, 70.0), new HTuple(60.0, 70.0));
Similarly, AreaCenter can be called in two ways:
Input parameters are passed by value; output parameters are passed by reference (using the & operator).
An exception to this rule are output control parameters of type char*.
Here, the caller has to provide the memory and only a pointer to that memory is passed to the operator.
Most HALCON operators can also be called using tuples of parameters instead of single values (so-called tuple mode).
Example
Take the operator threshold from our example program in Quick start, which segments an image and returns the segmented region:
If you pass a tuple of images, it will return a tuple of regions, one for each input image.
However, in contrast to HDevelop and other programming interfaces, in HALCON/C the tuple mode must be selected explicitly by prefixing the operator with T_ and by using tuples for all control values (see Control parameters).
Whether an operator can be called in tuple mode can be seen in the operator reference.
HALCON/C provides the data structure Htuple for tuples of control parameters (see section Tuple mode for details) and the data structure Hobject for image objects (single objects as well as object tuples; see About iconic objects).
About iconic objects🔗
The base class of the iconic parameter classes in HALCON/C++ is the class HObject, which manages entries in the database, that is, the copying or releasing of objects.
The class HObject can contain all types of iconic objects.
This has the advantage that important methods like DispObj() can be applied to all iconic objects in the same manner.
Three classes are derived from the root class HObject:
HImageclass for handling imagesHRegionclass for handling regionsHXLDclass for handling polygons
These classes are described in more detail below.
Images
HImage provides the following member functions:
HTuple HImage::Width()- Returns the width of the image; see
GetImageSize. HTuple HImage::Height()- Returns the height of the image; see
GetImageSize.
Regions
The class HRegion represents a region in HALCON/C++.
Besides operators that can be called via HRegion (see also About classes and instances), HRegion provides the following member functions:
HTuple HRegion::Area()- Returns the area of the region, that is, the number of pixels; see
AreaCenter. HTuple HRegion::Column()- Returns the center column of the region.
HTuple HRegion::Row()- Returns the center row of the region.
XLD objects
HALCON/C++ provides both a base class HXLD and a set of specialized classes derived from HXLD, for example, HXLDCont for contours or HXLDPoly for polygons.
In contrast to the classes described in the previous sections, the XLD classes provide only member functions corresponding to HALCON operators (see also About classes and instances).
The iconic classes HImage, HRegion, and HXLD can contain single or multiple objects.
To process all elements of a tuple, you first query the number of elements with the operator CountObj:
Subsequently, access elements either with the operator SelectObj or (when using C#) with the operator []:
Important
In iconic tuples, element indices start with 1.
You can create or extend iconic tuples with the operator ConcatObj:
HALCON/C provides the data type Hobject for image objects (both images and regions).
Hobject is a surrogate of the HALCON database containing all image objects.
Input image objects are passed to the HALCON operators by value as usual; output image objects are passed by reference, using the & operator.
Variables of type Hobject can be a single image object as well as tuples of image objects.
Single objects are treated as tuples with length one.
You can also access specific objects in an object tuple.
To do so, it is necessary to extract the specific object key, converted to integer, using the operators obj_to_integer or copy_obj.
The number of objects in a tuple can be queried with count_obj.
To convert the keys (returned from obj_to_integer) back to image objects again, use the operator integer_to_obj.
Note
integer_to_obj duplicates the image objects.
This does not necessarily mean that the corresponding gray value arrays are also duplicated. As long as there is only read-access, a duplication of the references is sufficient.
All extracted objects have to be deleted explicitly from the HALCON database, using clear_obj.
The following example contains an excerpt from a C program to clarify that approach.
Accessing the i-th image object in a tuple of image objects
...
Hobject objects; /* tuple of image objects */
Hobject obj; /* single image object */
Hlong surrogate; /* object key, converted to integer */
Htuple Tsurrogates; /* tuple of object keys */
Htuple Index,Num; /* temporary tuple for parameter passing */
Hlong i; /* loop variable */
Hlong num; /* number of objects */
...
count_obj(objects, &num);
/* variant 1: object key -> control parameter */
create_tuple_i(&Index,1);
create_tuple_i(&Num,num);
T_obj_to_integer(objects,Index,Num,&Tsurrogates);
for (i=0; i<num; i++)
{
surrogate = get_i(Tsurrogates,i);
/* process single object */
}
/* variant 2: copying objects individually */
for (i=1; i<=num; i++)
{
copy_obj(objects,&obj,i,1);
/* process single object */
}
...
Some HALCON operators like difference allow the use of the following specific image objects as input parameters:
NO_OBJECTS- An empty tuple of image objects
EMPTY_REGION- An image object with empty region (area = 0)
FULL_REGION- An image object with maximal region
These objects can be returned by HALCON operators, too.
About control parameters🔗
You can use these different types of control parameters for HALCON operators with HALCON/C++:
- integer numbers (
Hlong) - floating point numbers (
double) - strings (
HString) - handles (
HHandle)
A special form of control parameters are the so-called handles, which provide access to more complex data structures like windows, image acquisition connections, or models for shape-based matching.
Internally, handles are represented by a distinct control data type.
They are “magic” values that must not be changed and can differ from execution to execution and version to version.
Once all instances of the handle are overwritten or cleared, the handle and its content will be destroyed and will become invalid.
For more information about corresponding classes, see Classes encapsulating handles.
About tuples
With HTuple, HALCON/C++ provides a container class for control parameters.
HTuple may contain arrays of control parameters of mixed type.
The class HTuple implements an array of dynamic length.
The default constructor constructs an empty array (Length() == 0).
This array can dynamically be expanded via assignments.
The memory management, that is, reallocation and freeing, is also managed by the class.
The index for accessing the array is in the range between 0 and Length() − 1.
To use instances of an HTuple in different threads concurrently, the method HTuple::Clone() has to be
used (see below).
The following member functions reflect only a small portion of the total.
For more information, see the file HTuple.h in %HALCONROOT%\include\halconcpp.
HTuple &HTuple::Append(const HTuple& tuple)- Append data to existing tuple.
void HTuple::Clear()- Clear all data inside the tuple.
HTuple HTuple::Clone()- Create a detached copy duplication the tuple data.
Hlong HTuple::Length()- Return the number of elements of the tuple.
HTupleType HTuple::Type()- Return the data type of the tuple (pure data types or mixed tuple).
HString HTuple::ToString()- Return a simple string representation of the tuple contents.
Hlong* HTuple::LArr(),double* HTuple::DArr(),char** HTuple::SArr(),
Hcpar* HTuple::PArr(),Hphandle* HTuple::HArr()- Access tuple data.
About string encoding
The class HTuple always stores raw char pointer strings in the interface encoding.
This is important especially when accessing the internal raw pointer via the methods HTuple::SArr() and HTupleElement::C().
Windows only
Under Windows, it is possible to initialize an HTuple or an HTupleElement with a wide character string (wchar_t*, UTF-16).
This wide character string is converted into the current interface encoding (default: UTF-8).
If the interface encoding is not UTF-8, the conversion can involve transcoding errors, that is, the stored string may not contain all characters of the input-wide character string.
The class HTuple does not allow accessing the string in a different encoding or as wide character string.
The class HString can be used when transcoding or access to a wide character raw pointer is needed.
Like HTuple, the class can be initialized with a wchar_t pointer string (Windows only) or with a raw char pointer string with the current interface encoding.
HString allows creating a string with a specific encoding via HString::FromUtf8(const char*) or HString::FromLocal8bit(const char*).
Furthermore, this class allows storing the same string in UTF-8, local-8-bit encoding, and wide character string at the same time.
Thus it is save to use the required raw pointer, as long as the HString instance is not modified or destroyed.
The string remains the owner of the string memory for all representations.
The following methods for accessing raw pointers are provided:
HString::TextA()andHString::Text()-
Return the string as char pointer in the interface encoding.
-
When the char pointer string is needed in a different encoding, the methods
HString::ToUtf8()andHString::ToLocal8bit()can be used. -
The methods
HString::LengthA()andHString::Length()return the length in bytes of the char pointer string returned byHString::TextA()andHString::Text(), respectively. HString::TextW()(Windows only)-
Return the string as wide character pointer.
-
The method
HString::LengthW()returns the length of the string returned byHString::TextW()in words of the datatypewchar_t.
Classes encapsulating handles
The most important handle class is probably HWindow (see HALCON windows).
HALCON/C++ also provides classes for handles to files or functionality like access to image acquisition devices, measuring, or shape-based matching.
See Other handle classes for an overview.
HALCON windows
The class HWindow provides the management of HALCON windows in a very convenient way.
The properties of HALCON windows can be easily changed; images, regions, and polygons can be displayed; etc.
Besides the operators that can be called via HWindow (see also About classes and instances), HWindow provides the following member functions:
void HWindow::Click()- Wait for a mouse click in the window.
void HWindow::CloseWindow()- Close the window.
Other handle classes
HALCON/C++ provides the so-called handle classes like HFramegrabber, HBarCode, or HClassBoxMlp.
These are based on the class HHandle.
Besides the default constructor, the classes typically provide additional constructors based on suitable operators as described in section Constructors.
For example, the class HBarCode provides a constructor based on the operator CreateBarCodeModel.
The operator reference provides short overview pages for these classes, listing the operators that can be called via them.
You can use these different types of control parameters for HALCON operators with HALCON/.NET:
- integer numbers (
int) - floating point numbers (
double) - strings (
string) - handles (
HHandle)
About tuples
For control tuples, HALCON/.NET provides the class HTuple.
Instances of HTuple can contain elements of the types double, int, string, and HHandle.
They can also contain a mixture of element types.
Accessing tuple elements
To process all elements of a tuple, first query its length via the property Length:
You can access tuple elements with the operator []:
Important
If you try to read a non-existing tuple element or if you try to assign an element to a variable with a different type without cast, you get an exception.
Creating tuples
The class HTuple provides many different constructors (see the Object Browser in Visual Studio for a list).
The following line creates an int tuple with a single value:
In contrast, the following line creates a double tuple:
You can also pass multiple values to a constructor.
When mixing double and int values as in the following line, a double tuple is created:
In contrast, when the list of values also contains a string, a mixed type tuple is created, in which the second value is stored as an int:
The type of a tuple or of a tuple element can be queried via its property Type:
You can concatenate tuples simply by passing them in a constructor:
You can also append elements to a tuple by writing into a non-existing element:
Casts, ambiguities, and unexpected results
The class HTuple provides many implicit cast methods so that you can intuitively use the basic data types in most places.
For example, the following line automatically casts the element, which is in fact an instance of the class HTupleElement, into a double:
Similarly, basic types are automatically casted into instances of HTuple.
The drawback of the casts is that the compiler often cannot decide whether you want to use the simple or the tuple version of an operator and issues a corresponding error.
For example, if you used the following line, the values could either be casted from int to double or to HTuple:
You can resolve the ambiguity by appending .0 to the first parameter:
Example
The example Matching contains two other cases of ambiguities, both arising because basic type and HTuple parameters are mixed in the same call.
In the first, the ambiguity is solved by explicitly casting the double parameters into instances of HTuple:
private double row, column;
HTuple angleCheck;
HHomMat2D matrix = new HHomMat2D();
matrix.VectorAngleToRigid(new HTuple(row), new HTuple(column), new HTuple(0.0),
result.GetGenericShapeModelResult(0, "row"),
result.GetGenericShapeModelResult(0, "column"),
angleCheck);
In the second case, the instances of HTuple (which only contain single values) are explicitly casted into double by using the property D, which returns the value of the first element as a double (actually, it is a shortcut for tuple[0].D):
private double rectPhi, rectLength1, rectLength2;
HTuple rect1RowCheck, rect1ColCheck;
rectangle1.GenRectangle2(rect1RowCheck.D, rect1ColCheck.D,
rectPhi + angleCheck.D,
rectLength1, rectLength2);
With similar properties, you can cast tuple elements into the other basic types. Note, however, that you get an exception if you try to cast an element into a “wrong” type.
In contrast to input parameters, output parameters are not automatically casted.
Sometimes, this leads to unexpected results.
In the following code, for example, doubles are used for the output parameters and the return value in a call to AreaCenter with a tuple of regions:
HRegion MultipleRegions = new HRegion(new HTuple(20.0, 30.0), new HTuple(20.0, 30.0),
new HTuple(60.0, 70.0), new HTuple(60.0, 70.0));
double Area, Row, Column;
HTuple Areas, Rows, Columns;
Area = MultipleRegions.AreaCenter(out Row, out Column);
Consequently, only the area and the center of the first region are returned.
The same happens if you assign the return value to an HTuple, but still pass doubles for the output parameters:
In contrast, if you pass an HTuple for the output parameters and assign the return value to a double, the operator returns the center coordinates of all regions, but only the area of the first region:
HALCON operators for processing tuples
HALCON provides many operators for processing tuples. In the operator reference, these operators can be found in the chapter Tuple.
Operator overloads
For the basic arithmetic operations, HALCON/.NET provides operator overloads.
For example, the operator + automatically calls the HALCON operator TupleAdd.
You can use these different types of control parameters for HALCON operators with HALCON/C:
- integer numbers
- floating point numbers
- strings
- handles
About tuples
Using control parameter tuples in C is not as elegant as using image object tuples.
To circumvent the missing generic lists in C, HALCON/C provides two different working modes:
the simple mode and the tuple mode.
If a tuple is necessary for at least one control parameter, the tuple mode has to be used for operator calls.
In tuple mode, all control parameters of an operator must be passed as type Htuple.
Mixing of the two modes is not possible.
The tuple mode also has to be used if the number or type of values that a operator calculates is unknown beforehand.
Use one of these three ways to determine the default type of control parameters for a given operator:
- Operator description in the HALCON reference
- HALCON system operator
get_param_info - Description of the HALCON interface in the file
HProto.h
Sometimes the documentation mentions more than one possible type. If only integers and floating point numbers are allowed for a parameter, values have to be passed as parameters of type double. For all other combinations of types, the tuple mode has to be used.
HALCON operators that are called in tuple mode are distinguished from simple mode calls by a preceding T_.
This means that the following is a call of the HALCON operator select_shape in simple mode:
select_shape
A call of the same operator in tuple mode is:
T_select_shape
Simple mode
In the so-called simple mode, all control parameters of operator calls are variables (or constants) of these data types:
Hlong- integers (HALCON type
LONG_PAR) double- floating point numbers (
DOUBLE_PAR) char*- character arrays (strings,
STRING_PAR)
Hlong and double input control parameters are passed by value as usual.
The corresponding output control parameters are passed by reference, using the & operator.
String parameters are pointers to char in both cases.
Important
The memory for output control parameters (in particular strings) has to be provided by the caller.
We recommend allocating memory for at least 1024 characters for string parameters of unknown length.
Output parameter values that are of no further interest can be set to NULL.
Operators with parameters resembling handles must always be called in the tuple mode as described in the following section.
The simple mode for these operators is only available in legacy handle mode (see set_system).
You can find examples for operator calls in simple mode in “About iconic objects” above and in Quick start.
Tuple mode
Control parameter tuples for HALCON operators need special treatment. The HALCON reference describes a large number of operators that don’t operate on single control values but on tuples of values. Using those operators, it is easy to write very compact and efficient programs, because often it is possible to combine multiple similar operator calls into a single call.
Unfortunately, C provides no generic tuple or list constructor. In contrast, HALCON allows tuples with mixed types as control parameter values (for example, integers mixed with floating point numbers).
Therefore, in addition to the very intuitive simple mode, there is the tuple mode in HALCON/C. Using this mode is a little more elaborate. If at least one of the control parameters of a HALCON operator is passed as a tuple, the tuple mode has to be used for all control parameters. Mixing of both modes is not possible. Furthermore, the tuple mode also has to be used if the number or type of the calculated values are unknown beforehand.
Syntactically, tuple mode is distinguished from simple mode by a T_ preceding the operator name.
For example, calling disp_circle in tuple mode is done by
T_disp_circle(...)
To ease the usage of the tuple mode, HALCON/C provides the abstract data type Htuple for control parameter tuples.
Objects of type Htuple can be constructed using arrays of the following types:
Hlong*- integer arrays (HALCON type
LONG_PAR) double*- floating point arrays (
DOUBLE_PAR) char**- string arrays (strings,
STRING_PAR) Hphandle*- handle arrays (
HANDLE_PAR)
Additionally, the MIXED_PAR array type can hold an array with any of the three native value types in arbitrary combination.
The usage of these four array types is transparent.
Control parameter tuples must only be created, deleted, and manipulated using the appropriate HALCON/C procedures. For more information, see the examples in the workflow below.
The rules for parameter passing are valid in tuple mode, too:
Input control parameters (type Htuple) are passed by value as usual.
Output control parameters are passed by reference, using the & operator.
For output parameters that are of no further interest, you can pass NULL.
Workflow for tuple mode
The most important steps when calling a HALCON operator in tuple mode are:
-
Allocate memory.
Allocate memory for all tuples of input control parameters, using
create_tupleorcreate_tuple_type, respectively (see Example 1). Memory for output control parameter tuples is allocated by HALCON/C; a call ofcreate_tupleis not necessary.Htupleprocedures in HALCON/C (1/5)void create_tuple(tuple,length) or macro CT(tuple,length) Htuple *tuple; Hlong length; /* creates a MIXED_PAR tuple that can hold 'length' entries h */ void create_tuple_type(tuple,length,type) Htuple *tuple; Hlong length; Hlong type; /* creates a tuple of 'type' that can hold 'length' entries. * 'type' can hold either LONG_PAR, DOUBLE_PAR, STRING_PAR, * HANDLE_PAR, or MIXED_PAR. */ void destroy_tuple(tuple) or macro DT(tuple) Htuple tuple; /* deletes a tuple (if the tuple contains string entries, */ /* the memory allocated by the strings is freed, too) */ Hlong length_tuple(tuple) or macro LT(tuple) Htuple tuple; /* returns the length of a tuple (number of entries) */ void copy_tuple(input,output) or macro CPT(input,output) Htuple input; Htuple *output; /* creates a tuple and copies the entries of the input tuple */ void resize_tuple(htuple,new_length) or macro RT(htuple,new_length) Htuple *htuple; Hlong new_length; /* creates a tuple with the new size and copies the previous */ /* entries */With
create_tuple_ietc., you can create a tuple of length 1 and set its value in a single step (see Example 2).Htupleprocedures in HALCON/C (2/5)void create_tuple_i(tuple,value) Htuple *tuple; Hlong val; /* creates a tuple with specified integer value */ void create_tuple_d(tuple,value) Htuple *tuple; double val; /* creates a tuple with specified double value */ void create_tuple_h(tuple,value) Htuple *tuple; Hphandle val; /* creates a tuple with specified handle value */ void create_tuple_s(tuple,value) Htuple *tuple; char *val; /* creates a tuple with specified string value */ void create_tuple_s_from_local8bit(tuple,value) Htuple *tuple; char *val; /* creates a tuple with specified string value converted */ /* from local-8-bit encoding */ void create_tuple_s_from_utf8(tuple,value) Htuple *tuple; char *val; /* creates a tuple with specified string value converted */ /* from UTF-8 encoding */ void create_tuple_s_from_wcs(tuple,value) Htuple *tuple; wchar_t *val; /* creates a tuple with specified string value converted */ /* from wide-character encoding */With
reuse_tuple_ietc., you can reuse an existing tuple, that is, destroy and reallocate it and set a single value (see Example 3).Htupleprocedures in HALCON/C (3/5)void reuse_tuple_i(tuple,val) Htuple *tuple; Hlong val; /* reuses a tuple with specified integer value */ void reuse_tuple_d(tuple,val) Htuple *tuple; double val; /* reuses a tuple with specified double value */ void reuse_tuple_h(tuple,val) Htuple *tuple; Hphandle val; /* reuses a tuple with specified handle value */ void reuse_tuple_s(tuple,val) Htuple *tuple; char *val; /* reuses a tuple with specified string value */ void reuse_tuple_s_from_local8bit(tuple,val) Htuple *tuple; char *val; /* reuses a tuple with specified string value converted */ /* from local-8-bit encoding */ void reuse_tuple_s_from_utf8(tuple,val) Htuple *tuple; char *val; /* reuses a tuple with specified string value converted */ /* from UTF-8 encoding */ void reuse_tuple_s_from_wcs(tuple,val) Htuple *tuple; wchar_t *val; /* reuses a tuple with specified string value converted */ /* from wide-character encoding */ -
Create input parameters.
You set tuple elements using the appropriate procedures
set_*.set_s, which insert a string into a tuple, allocates the needed memory by itself, and then copies the string (see Example 4).Htupleprocedures in HALCON/C (4/5)void set_i(tuple,val,index) or macro SI(tuple,val,index) Htuple tuple; Hlong val; Hlong index; /* inserts an integer with value 'val' into a tuple at */ /* position 'index' ('index' in [0,length_tuple(tuple) - 1]) */ void set_d(tuple,val,index) or macro SD(tuple,val,index) Htuple tuple; double val; Hlong index; /* inserts a double with value 'val' into a tuple at */ /* position 'index' ('index' in [0,length_tuple(tuple) - 1]) */ void set_h(tuple,val,index) or macro SH(tuple,val,index) Htuple tuple; Hphandle val; Hlong index; /* inserts a handle with value 'val' into a tuple at */ /* position 'index' ('index' in [0,length_tuple(tuple) - 1]) */ void set_s(tuple,val,index) or macro SS(tuple,val,index) Htuple tuple; char *val; Hlong index; /* inserts a copy of string 'val' into a tuple at position */ /* 'index' ('index' in [0,length_tuple(tuple) - 1]); */ /* memory necessary for the string is allocated by set_s */ void set_s_from_local8bit(tuple,val,index) or macro SS_LOC(tuple,val,index) Htuple tuple; char *val; Hlong index; /* inserts a copy of string 'val', converted from */ /* local-8-bit encoding, into a tuple at position 'index' */ /* ('index' in [0,length_tuple(tuple) - 1]). */ void set_s_from_utf8(tuple,val,index) or macro SS_U(tuple,val,index) Htuple tuple; char *val; Hlong index; /* inserts a copy of string 'val', converted from UTF-8 */ /* encoding, into a tuple at position 'index' ('index' in */ /* [0,length_tuple(tuple) - 1]). */ void set_s_from_wcs(tuple,val,index) or macro SS_W(tuple,val,index) Htuple tuple; wchar_t *val; Hlong index; /* inserts a copy of string 'val', converted from */ /* wide-character encoding, into a tuple at position */ /* 'index' ('index' in [0,length_tuple(tuple) - 1]). */ -
Call operator.
Then, the HALCON operator is actually called. Precede the operator name by a
T_to denote tuple mode. -
Process output parameters.
Further processing of the output parameter tuples takes place, using the procedures
length_tuple,get_type(see Example 1) andget_*(see Example 5).Htupleprocedures in HALCON/C (5/5)int get_type(tuple,index) or macro GT(tuple,index) Htuple tuple; Hlong index; /* returns type of value at position 'index' in the tuple. */ /* Possible values: LONG_PAR, DOUBLE_PAR or STRING_PAR */ Hlong get_i(tuple,index) or macro GI(tuple,index) Htuple tuple; Hlong index; /* returns the integer at position 'index' in the tuple */ /* (a type error results in a run time error) */ double get_d(tuple,index) or macro GD(tuple,index) Htuple tuple; Hlong index; /* returns the floating point number at position 'index' in */ /* the tuple. (a type error results in a run time error) */ Hphandle get_h(tuple,index) or macro GH(tuple,index) Htuple tuple; Hlong index; /* tuple. (a type error results in a run time error) */ /* returns the handle at position 'index' in the */ char *get_s(tuple,index) or macro GS(tuple,index) Htuple tuple; Hlong index; /* returns the pointer(!) to the string at position 'index' */ /* in the tuple. (a type error results in a run time error) */ /* Attention: indices must be in [0,length_tuple(tuple) - 1] */ Hlong get_s_to_local8bit(buffer,size,tuple,index) or macro GS_LOC(tuple,index) char* buffer; Hlong size; Htuple tuple; Hlong index; /* Copies the (local-8-bit encoded) string at position */ /* 'index' into 'buffer'. 'size' determines the size of the */ /* buffer. The return value determines the size of the */ /* string, that would be written. If the returned length of */ /* the string is greater or equal to the provided */ /* buffer, the buffer was too small. */ /* Attention: indices must be in [0,length_tuple(tuple) - 1] */ Hlong get_s_to_utf8(buffer,size,tuple,index) or macro GS_U(tuple,index) char* buffer; Hlong size; Htuple tuple; Hlong index; /* Copies the (UTF-8) string at position */ /* 'index' into 'buffer'. 'size' determines the size of the */ /* buffer. The return value determines the size of the */ /* string, that would be written. If the returned length of */ /* the string is greater or equal to the provided */ /* buffer, the buffer was too small. */ /* Attention: indices must be in [0,length_tuple(tuple) - 1] */ Hlong *get_s_to_wcs(buffer,size,tuple,index) or macro GS_W(tuple,index) wchar_t* buffer; Hlong size; Htuple tuple; Hlong index; /* Copies the (wide-character) string at position */ /* 'index' into 'buffer'. 'size' determines the size of the */ /* buffer. The return value determines the size of the */ /* string, that would be written. If the returned length of */ /* the string is greater or equal to the provided */ /* buffer, the buffer was too small. */ /* Attention: indices must be in [0,length_tuple(tuple) - 1] */When processing strings (using
get_s), the allocated memory is freed automatically upon deleting the tuple withdestroy_tuple. If the string has to be processed even after the deletion of the tuple, copy the whole string first.
Note that output handles might be freed when deleting the last tuple. If a handle is to be used further, keep it in a tuple. -
Free memory.
The memory allocated by all the tuples (input and output) has to be freed again.
This is done withdestroy_tuple. If you still need the values of the tuple variables, remember to copy them first.
Now, the whole series can start again – using different or the same tuple variables.
Tuple mode example program: Printing the current HALCON system state
This example for the tuple mode aims to obtain information about the current HALCON system state.
The operator get_system('?',Values) (here in HDevelop syntax) returns all system flags with their current values.
Since in our case neither number nor type of the output parameters is known beforehand, we have to use tuple mode for the actual operator call in HALCON/C.
#include "HalconC.h"
main ()
{
Htuple In, SysFlags, Info;
Hlong i, num;
printf("System information:\n");
/* prepare query */
create_tuple(&In, 1);
/* "?" = list of all informations */
set_s(In, "?", 0);
T_get_system(In, &SysFlags);
destroy_tuple(In);
num = length_tuple(SysFlags);
for (i = 0; i < num; i++)
{
create_tuple(&In, 1);
set_s(In, get_s(SysFlags, i), 0);
printf("%s ", get_s(SysFlags, i));
T_get_system(In, &Info);
destroy_tuple(In);
if (length_tuple(Info) > 0)
{
switch (get_type(Info, 0))
{
case INT_PAR:
printf("(Hlong): %" LONG_FORMAT "d\n", get_i(Info, 0));
break;
case DOUBLE_PAR:
printf("(double): %f\n", get_d(Info, 0));
break;
case STRING_PAR:
printf("(string): %s\n", get_s(Info, 0));
break;
case HANDLE_PAR:
printf("(handle): %" LONG_FORMAT "d\n", (Hlong)get_h(Info, 0));
break;
}
}
else
{
printf("(--): no data\n");
}
destroy_tuple(Info);
}
}
example3.c.
Generic calling mechanism
Intended for the use in interpreters or graphical user interfaces, there is also an alternative, generic calling mechanism for HALCON operators in tuple mode.
T_call_halcon_by_id(id, ...)
calls the HALCON operator id in tuple mode, passing input parameters and getting the output parameters.
The ID of an operator can be requested with get_operator_id.
The complete signature is:
/* generic HALCON operator call style:
* - the operator is called by an id that is returned by get_operator_id;
* attention: this id may differ for different HALCON versions
* - the tuple arrays are passed directly to the call -> this method is
* thread-safe
*-----------------------------------------------------------------------*/
int get_operator_id(const char* name);
Herror T_call_halcon_by_id(int id,
const Hobject in_objs[],
Hobject out_objs[],
const Htuple in_ctrls[],
Htuple out_ctrls[]);
About string encoding
Regardless of the encoding of the HALCON library (set_system('filename_encoding', ...)), the HALCON/C interface expects raw char pointer strings that are passed to HALCON operators and to Htuple instances to be UTF-8 encoded.
The encoding of the HALCON/C interface (interface encoding) can be changed to local-8-bit encoding via a call of SetHcInterfaceStringEncodingIsUtf8(false).
Important
The encoding must not be changed when using HDevEngine / HALCON Script Engine.
The current interface encoding can be requested via IsHcInterfaceStringEncodingUtf8().
Switching the interface encoding back and forth is not recommended.
The setting should be adjusted only once at the very beginning of the program (before the first HALCON operator or assignment), because the Htuple structure cannot store in which encoding the contained strings are present.
This means, for all write and read accesses, the same encoding must be set.
Further, the interface encoding is set globally and is therefore not suitable for multithreading programs:
Changing the setting in one thread has an effect on other threads.
Also note that UTF-8 encoded strings may take more memory space than strings in local-8-bit-encoding.
This must be considered when providing the buffer for strings returned by HALCON operators.
As long as the maximum length of the strings returned is not known for sure, prefer operator calls in tuple mode over simple mode.
If the string encoding needs to be converted without changing the interface encoding, the following functions for converting wchar_t* strings and char* strings to or from tuples are provided:
| UTF-8 version | local 8-bit version | wchar_t* version (Windows only) |
|---|---|---|
create_tuple_s_from_utf8 |
create_tuple_s_from_local8bit |
create_tuple_s_from_wcs |
reuse_tuple_s_from_utf8 |
reuse_tuple_s_from_local8bit |
reuse_tuple_s_from_wcs |
init_s_from_utf8 |
init_s_from_local8bit |
init_s_from_wcs |
set_s_from_utf8 |
set_s_from_local8bit |
set_s_from_wcs |
get_s_to_utf8 |
get_s_to_local8bit |
get_s_to_wcs |
When converted to a different encoding, a string may need a buffer of bigger size.
To check whether you have to allocate more memory for your string, you can use the get_s_to_* functions mentioned in Table 1 (see also Example 5).
The functions transcode a string to the respective encoding and write it into the buffer provided by the user.
If the returned size of the string is greater or equal to the provided buffer, the passed buffer size was too small.
About vectors🔗
A HALCON vector is a container that can hold an arbitrary number of elements of the identical data type (that is, tuple, iconic object, or vector) and dimension. The type of a vector – its dimension and the type of its elements – is defined when initializing the vector instance and cannot be changed during its lifetime.
A one-dimensional vector may be a vector of tuples or a vector of iconic objects.
A two-dimensional vector may be a vector of vectors of tuples or a vector of vectors of iconic objects, and so on.
HALCON/C++ provides the class HVector for the use of HALCON vectors in C++ programs.
Two classes are derived from the root class HVector:
HObjectVectorclass- Handles vectors of iconic objects
HTupleVectorclass- Handles vectors of tuples
In the following, some basic information on how to use vectors in HALCON/C++ is given, for example, how to construct vectors and how to access and set vector elements.
For a complete list of the available functionality, see the corresponding header file HVector.h in %HALCONROOT%\include\halconcpp.
HALCON/.NET provides the class HVector for the use of HALCON vectors.
Instances of vectors can be created from the following derived classes:
HObjectVectorclass- Handles vectors of iconic objects
HTupleVectorclass- Handles vectors of tuples
In the following, some basic information on how to use vectors in HALCON/.NET is given when using C#.
HALCON/C provides the data structure Hvector for the use of HALCON vectors in C programs.
Constructing vectors🔗
As mentioned above, you have to distinct between vectors of iconic objects and vectors of tuples. The type of a vector must be defined at its construction as in the following lines:
// Create a one-dimensional vector of iconic objects
HObjectVector vectorObj(1);
// Create a one-dimensional vector of tuples
HTupleVector vectorTup(1);
The type of the vector cannot be changed within a program after its construction. Thus, a tuple cannot be assigned to a vector of iconic objects and vice versa. To create a two-dimensional vector, meaning: a vector of vectors of iconic objects or a vector of vector of tuples, you can use the following line:
// Create a two-dimensional vector of iconic objects
HObjectVector vectorObjMulti(2);
// Create a two-dimensional vector of tuples
HTupleVector vectorTupMulti(2);
You can also create a multi-dimensional vector with more than two dimensions by specifying the desired dimension in brackets. However, the dimension of a vector is part of its type and has to remain constant within the program; it cannot be changed.
// Create a vector of iconic objects
HObjectVector vectorObj;
// Create a vector of tuples
HTupleVector vectorTup;
The vector type cannot be changed after its construction. Thus, a tuple cannot be assigned to a vector of iconic objects and vice versa.
You can also create a multi-dimensional vector, that is, a vector of vectors and so on, by specifying the number of dimensions in brackets.
However, the dimension of a vector has to remain constant within the program and cannot be changed.
The following code line describes how to create a vector of two dimensions, that is, a vector of vectors of tuples:
Hvector vectorObj, vectorTup;
// Create a one-dimensional vector of iconic objects
V_create_object_vector(1,&vectorObj);
// Create a one-dimensional vector of tuples
V_create_tuple_vector(1,&vectorTup);
These calls create empty vectors of one dimension, for example, a vector of tuples. It is also possible to create multi-dimensional vectors, that is, a vector of vectors of tuples or a vector of vectors of iconic objects and so on, by specifying the number of dimensions in the call:
The vector type and its dimension cannot be changed after the creation of the vector.
Accessing and setting vector elements🔗
The vectors created by the previous calls are still empty. Like with the construction of vectors, the call for accessing and setting vector elements differs depending on the vector type.
To access a single element of a vector of iconic objects, use the method O().
To access the elements of a vector of tuples, use T():
// Access a vector element of a one-dimensional HObjectVector
vectorObj[elem_index].O();
// Access a vector element of a one-dimensional HTupleVector
vectorTup[elem_index].T();
The vector element to be accessed is addressed by the specified index in square brackets. If a subelement of a multi-dimensional vector is to be accessed, you have to use the indices of the corresponding subvector and its subelement instead:
// Access a subelement of a two-dimensional HObjectVector
vectorObjMulti[vec_index][elem_index].O();
The left index vec_index defines the index of the subvector, and elem_index defines the desired element of the specified subvector.
When setting a vector element, the expression for accessing a vector element is used as reference to the HObject or HTuple element to be set.
The right side of the assignment specifies the value assigned to the vector element.
// Set a vector element of a one-dimensional HObjectVector
vectorObj[0].O() = HImage("Image");
// Set a vector element of a one-dimensional HTupleVector
HTuple tuple;
tuple[0] = 1.0;
tuple[1] = 2.5;
vectorTup[0].T() = tuple;
In the example code above, the Image is copied and set as the first vector element of vectorObj.
The tuple is also copied and set as first vector element of vectorTup.
Setting a subelement of a multi-dimensional vector can be done with the same call. However, instead of a single index, multiple indices must be specified for the corresponding vector element and its subelement to be set:
Writing to a non-existing vector element is also allowed. In this case, the vector is automatically filled with empty elements if necessary.
To access a single element of a vector of iconic objects, use .O.
To access the elements of a vector of tuples, use .T.
// Access an element of a one-dimensional HObjectVector
vectorObj[0].O;
// Access an element of a one-dimensional HTupleVector
vectorTup[0].T;
The specified index in square brackets defines the element to be accessed. To access a subelement of a multi-dimensional vector, use the indices of the corresponding subvector and its subelement instead.
When setting a vector element, the expression for accessing a vector element is needed as reference to the HObject or HTuple, respectively.
Specify the value to be set on the right side of the assignment.
// Set an element of a one-dimensional HObjectVector
HImage image = new HImage("Image1");
vectorObj[0].O = image;
// Set an element of a HTupleVector
HTuple tuple = new HTuple(1,2);
vectorTup[1].T = tuple;
In the example code, the image is copied and set as the first element of vectorObj.
The tuple is also copied but set as the second vector element of vectorTup.
Setting a subelement of a multi-dimensional vector can be done analogously to setting an element in a one-dimensional vector when using the corresponding indices of the subvector(s) and its subelement.
If a non-existing vector element is set or accessed, the vector is automatically enlarged and filled with empty elements if necessary.
To access an element in a vector of tuples, you can use V_get_vector_tuple.
The following code line queries a tuple contained in vectorTup at position index and returns a copy of the result as a HTuple in tuple:
To access elements in vectors of iconic objects, V_get_vector_obj can be used instead:
The element to be accessed is specified by its index in form of a tuple. It may either contain a single index of an element in one-dimensional vectors or several indices of the corresponding subvector(s) and its subelement(s) in multi-dimensional vectors.
You can also query a whole subvector of a multi-dimensional vector using V_get_vector_elem.
Before accessing the contents of a vector, you can set some vector elements first. Again, a distinction is made between vectors of tuples, vectors of iconic objects, and multi-dimensional vectors. The following lines show how to set vector elements of one-dimensional vectors:
// Set an element of a vector of iconic objects
V_set_vector_obj(image,vectorObj,index);
// Set an element of a vector of tuples
V_set_vector_tuple(vectorTup,index,tuple);
The element to be set is again addressed by the specified index, which is represented as a Htuple.
Beside the index, the vector itself and the respective Hobject or Htuple to be set (for example, image or tuple) must be added to the call.
For multi-dimensional vectors, the specified index tuple must contain the indices of the subvector(s) and its subelement. The following code lines show the whole process from creating a two-dimensional vector, the image to be set, and the index tuple up to specifying the indices and finally setting the element of the vector:
// Initialize and set the image and indices
Hobject img;
Htuple indices;
Hvector vectorObjMulti;
V_create_object_vector(2,&vectorObjMulti);
read_image(&img,"Image");
set_i(indices,0,0);
set_i(indices,1,1);
// Set a subvector of a multi-dimensional vector
V_set_vector_obj(img,vectorObjMulti,indices);
You can also set a subvector of multi-dimensional vectors using V_set_vector_elem.
Further, it is possible to set non-existing vector elements. If necessary, the vector is automatically enlarged and initialized with empty elements.
Destructing vectors🔗
If a vector is not needed anymore for further processing, its contents can be cleared with the following call explicitly:
If an HObjectVector or HTupleVector is not needed anymore for further processing, its contents should be cleared with .Dispose():
Further information🔗
In addition to the previously mentioned information, HObjectVector and HTupleVector provide some more functionality, for example: inserting or removing vector elements, or concatenation of vectors.
For more information, see the corresponding header file HVector.h in %HALCONROOT%\include\halconcpp.
In addition to the previously mentioned information, HObjectVector and HTupleVector provide some more functionality, for example: inserting and removing vector elements or concatenation of vectors.
For more information, you can use the automatic context help in Visual Studio (“IntelliSense”).
In addition to the previously mentioned information, the data structure of Hvector provides some more functionality, for example: inserting or removing vector elements, or concatenation of vectors.
For more information, see the corresponding header file Hvector.h in %HALCONROOT%\include\halconc.