Reading and writing control parametersđź”—
This section describes routines for reading and writing in-/output control parameters, see Routines for reading control input parameters by reference, Routines for reading control input parameters by copy, Routines for reading control input parameters by copy to a preallocated array, and Routines for writing control output parameters.
Interchanging control data with the host language is done via arrays of the data type INT4_8 for LONG_PAR, double for DOUBLE_PAR, Hphandle for HANDLE_PAR, char* for STRING_PAR, or Hcpar for MIXED_PAR array types (see Control parameters).
Control parameters can be passed through the HALCON interface in two different ways: by reference or by value.
The former is more efficient but does not allow to modify the values.
It is supported by the routines HGetPElemL, HGetPElemD, HGetPElemS, and HGetPPar for reading, depending on the expected type of the input array.
HGetPElem provides a general, type independent read access.
In case of writing output control parameters, HPutPPar and HPutPElem are provided.
In contrast, the routines HGetElemL, HGetElemD, HGetElemS, HGetCElemH1, HGetCElemH, HGetCElemHN, and HGetCPar return a copy of the input array, whereas HPutElem, HPutElemH, and HPutCPar copy an array to an output control parameter.
Names
Conversion Flags
CONV_NONE /* no conversion; do only consider original element types */
CONV_CAST /* <INT4_8>=(INT4_8)<double>; <double>=(double)<INT4_8> */
CONV_IDNT /* convert double to INT4_8, if double has no fraction */
CONV_RND /* <INT4_8>=(INT4_8)(<double>+0.5) */
Synopsis
#include "Halcon.h"
HGetPElemL( Hproc_handle proc_handle,
int par,
int convert,
INT4_8 const*restrict *elem,
INT4_8 *num)
HGetPElemD( Hproc_handle proc_handle,
int par,
int convert,
double const*restrict *elem,
INT4_8 *num)
HGetPElemS( Hproc_handle proc_handle,
int par,
int convert,
char const* const*restrict *elem,
INT4_8 *num)
HGetPPar( Hproc_handle proc_handle,
int par,
Hcpar const* restrict *val,
INT4_8 *num)
HGetPElem( Hproc_handle proc_handle,
int par,
void const*restrict *elem,
INT4_8 *num,
int *type)
HGetPElemL, HGetPElemD, HGetPElemSđź”—
HGetPElemL, HGetPElemD, and HGetPElemS (see Routines for reading control input parameters by reference) return a reference in elem to the value array of the input control parameter at the position par (1… n).
According to the expected type of the array, HGetPElemL is used to get LONG_PAR arrays, HGetPElemD for DOUBLE_PAR, and HGetPElemS for STRING_PAR arrays.
The behavior of the routines in case of passing array types different to the expected can be specified by the convert parameter.
The following values are supported:
CONV_NONE- Supports no conversion and accepts only the requested element type.
Otherwise, the error
'wrong type of input parameter x' (H_ERR_WIPTx)will be returned. CONV_CAST- Provides conversion of
LONG_PARandDOUBLE_PARvalues to the requested type by a cast. In case of conversion, the array is copied to an ad hoc allocated memory buffer. This buffer is freed automatically when the operator returns.LONG_PARandDOUBLE_PARvalue types can not be casted to typeSTRING_PARand vice versa. In this case, error'wrong type of input parameter x' (H_ERR_WIPTx)will be returned. CONV_IDNT- Converts
DOUBLE_PARvalues of aDOUBLE_PARorMIXED_PARarray to typeLONG_PARwhen passed toHGetPElemL. This conversion is performed only if alldoublevalues of the input array have no fraction, i.e., the cast is reversible. When passed toHGetPElemD, values of typeLONG_PARare casted to typeDOUBLE_PAR. Any other conversion is not supported and in this case the error'wrong type of input parameter x' (H_ERR_WIPTx)is returned. In case of conversion, the array is copied to an ad hoc allocated memory buffer. This buffer is freed automatically when the operator returns. CONV_RND- Provides conversion by rounding when
DOUBLE_PARvalues have to be converted toLONG_PARtype (HGetPElemD).LONG_PARvalues are casted toDOUBLE_PARif passed toHGetPElemD. Otherwise, the error'wrong type of input parameter x' (H_ERR_WIPTx)will be returned. In case of conversion, the array is copied to an ad hoc allocated memory buffer. This buffer is freed automatically when the operator returns.
Any conversion of input array types will be paid for by performance and memory consumption.
Refer to HGetPElem (see HGetPElem) if efficient support of different array types is important.
The current number of parameter values is returned in num.
HGetPElemL, HGetPElemD, and HGetPElemS automatically check the result state of the underlying procedure similarly to the macro HCkP (see HCkP).
Thus, you must not use HCkP on HGetPElemL, HGetPElemD, or HGetPElemS yourself.
Read the control parameter values of the operator call demo([5,6.8],’Text’,[1.7,4,’ctrl’]) using HGetPElemL, HGetPElemS, and HGetPPar shows the usage of HGetPElemL andHGetPElemS together with HGetPPar (compare HGetPPar).
HGetPParđź”—
HGetPPar (see Routines for reading control input parameters by reference) returns the reference to a MIXED_PAR array of Hcpar structures, which contain the parameter values of the input control parameter at the position par (1… n).
Contrary to HGetCPar (see HGetCPar), HGetPPar is much more efficient in terms of memory overhead, because it just returns pointers to the values instead of copying them.
On the other hand, the parameter values may only be read and must not be modified.
Note that for every parameter value, its type (LONG_PAR, DOUBLE_PAR, STRING_PAR) is also stored within the Hcpar structure.
Therefore, the same control parameter may contain values of different control data types.
In case the input array is of different type to MIXED_PAR, the array is copied and converted to an ad hoc allocated memory buffer of Hcpar structures.
This buffer is freed automatically when the operator returns.
The current number of parameter values is returned in num.
Note that HGetPPar automatically checks the result state of the underlying procedure similarly to the macro HCkP (see HCkP).
Thus, you must not use HCkP on HGetPPar yourself.
Read the control parameter values of the operator call demo([5,6.8],’Text’,[1.7,4,’ctrl’]) using HGetPElemL, HGetPElemS, and HGetPPar shows the usage of HGetPPar together with HGetPElemL and HGetPElemS (compare HGetPElemL, HGetPElemD, HGetPElemS).
INT4_8 const *ctrl1; /* LONG_PAR array */
char const*const *ctrl2; /* STRING_PAR array */
Hcpar const *ctrl3; /* MIXED_PAR array of Hcpar structures */
INT4_8 num; /* length of an input array */
/* Read all values of parameter number 1. Say, we expect a */
/* LONG_PAR array but also tolerate double values. */
HGetPElemL(proc_handle,1,CONV_CAST,&ctrl1,&num);
/* now ctrl1[0] == 5; ctrl1[1] == 6; */
/* Read a string in parameter number 2. Say, we expect a */
/* STRING_PAR array. */
HGetPElemS(proc_handle,2,CONV_NONE,&ctrl2,&num);
/* now ctrl2[0] == "Text" */
/* Read a tuple of float values in parameter number 3. */
/* At this parameter we handle any value type */
HGetPPar(proc_handle,3,&ctrl_val3,&num);
/* now ctrl3[0].type == DOUBLE_PAR, ctrl3[0].par.d == 1.7 */
/* ctrl3[1].type == LONG_PAR, ctrl3[1].par.l == 4 */
/* ctrl3[2].type == STRING_PAR, ctrl3[2].par.s == "ctrl" */
...
HGetPElemđź”—
A general access on input control parameter without any implicit conversion is provided by the routine HGetPElem (see Routines for reading control input parameters by reference).
HGetPElem returns in elem a reference to the input array of arbitrary type of the input control parameter with the index par (1… n).
The length of the array is returned in num.
type holds the array type of the returned array and can take the values LONG_PAR, DOUBLE_PAR, STRING_PAR, and MIXED_PAR, coding arrays of type INT4_8, double, char*, and Hcpar, respectively.
Read the control parameter values of the first control parameter of an operator using HGetPElem shows the usage of HGetPElem.
const void *restrict ctrl1;
INT4_8 n1;
int t1;
/* Read all values of parameter number 1 */
HGetPElem(proc_handle, 1, &e1, &n1, &t1);
switch( t1)
{
case LONG_PAR:
{
INT4_8 const *l = (INT4_8 const *)e1;
...
break;
}
case DOUBLE_PAR:
{
double const *d = (double const *)e1;
...
break;
}
case STRING_PAR:
{
char const *const *s = (char const *const *)e1;
...
break;
}
case MIXED_PAR:
{
Hcpar const *cpar = (Hcpar const *)e1;
...
break;
}
default:
return H_ERR_WIPT1;
}
...
HGetCElemH1, HGetCElemH, HGetCElemHNđź”—
HGetCElemH1 retrieves a single handle from an input parameter.
HGetCElemH retrieves all handles from an input parameter.
HGetCElemHN retrieves a given number N of handles from an input parameter.
If the parameter does not contain the exact number of handles requested, the macro returns from the caller with an error.
On success the returned array contains pointers to the data stored in the handles.
It is freed automatically when the operator finishes.
Names
Synopsis
#include "Halcon.h"
HGetCElemH1( Hproc_handle proc_handle,
int par,
H_HANDLE_TYPE const *htype,
Hphandle elem)
HGetCElemH( Hproc_handle proc_handle,
int par,
H_HANDLE_TYPE const *htype,
Hphandle elem,
INT4_8 *num)
HGetCElemHN( Hproc_handle proc_handle,
int par,
H_HANDLE_TYPE const *htype,
INT4_8 num,
Hphandle elem)
HGetElemL, HGetElemD, HGetElemSđź”—
Names
Conversion Flags
CONV_NONE /* no conversion; do only consider original element types */
CONV_CAST /* <INT4_8>=(INT4_8)<double>; <double>=(double)<INT4_8> */
CONV_IDNT /* convert double to INT4_8, if double has no fraction */
CONV_RND /* <INT4_8>=(INT4_8)(<double>+0.5) */
Synopsis
#include "Halcon.h"
HGetElemL( Hproc_handle proc_handle,
int par,
int convert,
int memtype,
INT4_8 *restrict *elem,
INT4_8 *num)
HGetElemD( Hproc_handle proc_handle,
int par,
int convert,
int memtype,
double *restrict *elem,
INT4_8 *num)
HGetElemS( Hproc_handle proc_handle,
int par,
int convert,
int memtype,
char *restrict*restrict *elem,
INT4_8 *num)
HGetElemL, HGetElemD, and HGetElemS (see Routines for reading control input parameters by copy) return a copy of the input control parameter array with the index par (1… n).
According to the expected type of the array, HGetElemL is used to get LONG_PAR arrays, HGetElemD for DOUBLE_PAR, and HGetElemS for STRING_PAR arrays.
In contrast to HGetPElemL, HGetPElemD, and HGetPElemS, the input arrays will be allocated and the values copied in any case.
Therefore, the resulting array can be modified with the drawback of memory overhead and loss of performance.
The kind of memory allocation (compare Managing memory in extension packages) can be specified by the parameter memtype.
It supports the values HMEMglobal, HMEMlocal, and HMEMtemp, specifying the allocation function HAlloc, HAllocLocal, or HAllocTmp that is used internally.
The specified function is used by the routines to allocate the array, respectively.
But note that this array must be freed explicitly with the according function HFree, HFreeLocal or HFreeTmp after usage.
The behavior of the routines in case of passing array types different to the expected can be specified by the convert parameter according to the description in HGetPElemL, HGetPElemD, HGetPElemS.
Note that HGetPPar automatically checks the result state of the underlying procedure similarly to the macro HCkP (see HCkP).
Thus, you must not use HCkP on HGetPPar yourself.
HCopyElemL, HCopyElemDđź”—
Names
Conversion Flags
CONV_NONE /* no conversion; do only consider original element types */
CONV_CAST /* <INT4_8>=(INT4_8)<double>; <double>=(double)<INT4_8> */
CONV_IDNT /* convert double to INT4_8, if double has no fraction */
CONV_RND /* <INT4_8>=(INT4_8)(<double>+0.5) */
Synopsis
#include "Halcon.h"
HCopyElemL( Hproc_handle proc_handle,
int par,
int convert,
INT4_8 *restrict elem,
INT4_8 *num);
HCopyElemD( Hproc_handle proc_handle,
int par,
int convert,
double *restrict elem,
INT4_8 *num);
HGetCPar( Hproc_handle proc_handle,
int par,
int type,
Hcpar *val,
INT4_8 min,
INT4_8 max,
INT4_8 *num)
HCopyElemL and HCopyElemD (see Routines for reading control input parameters by copy to a preallocated array) read the parameter values of the input control parameter with the index par (1… n) and write them to the array elem that must have been allocated before with a suitable size (see HGetCParNum for information on getting the actual array length).
According to the routine’s suffix, HCopyElemL expects LONG_PAR, HCopyElemD DOUBLE_PAR arrays.
The behavior of the routines in case of passing array types different to the expected can be specified by the convert parameter according to the description in HGetPElemL, HGetPElemD, HGetPElemS.
The number of elements that have been allocated for elem must be passed to num.
In return, num will hold the number of actually copied array indices.
Note that HCopyElemL and HCopyElemD automatically check the result state of the underlying procedure similarly to the macro HCkP (see HCkP).
Thus, you must not use HCkP on HCopyElemL and HCopyElemD yourself.
INT4_8 l[10]; /* maximum array length of 10 */
INT4_8 num = 10;
/* read a short/int/long value in parameter 1 */
HCopyElemL(proc_handle,1,CONV_RND,l,&num);
/* now l == [2,4], num = 2 */
...
HGetCParđź”—
HGetCPar (see Routines for reading control input parameters by copy to a preallocated array) reads the parameter values of the input control parameter with the index par (1… n) and writes them to the array val of Hcpar structures that must have been allocated before with a suitable size.
Note that HGetCPar automatically checks the result state of the underlying procedure similarly to the macro HCkP (see HCkP).
Thus, you must not use HCkP on HGetCPar yourself.
Hcpar par1,par2;
Hcpar par3[10];
/* allocate memory for strings */
HAllocStringMem(proc_handle,1000);
/* read a short/int/long value in parameter 1 */
HGetCPar(proc_handle,1,LONG_PAR,&par1,1,1,&num);
/* now par1.par.l == 5 */
/* read a string in parameter 2 */
HGetCPar(proc_handle,2,STRING_PAR,&par2,1,1,&num);
/* now par2.par.s == "Text" */
/* read a tuple of float values in parameter 3 */
/* (max. 10 values) */
HGetCPar(proc_handle,3,DOUBLE_PAR,par3,1,10,&num);
for (i=0; i<num; i++) {
/* par3[i].par.d == 0.5,1.7,4.4 */
...
For every input value, its type (LONG_PAR, DOUBLE_PAR, STRING_PAR) is also stored within the Hcpar structure.
Thus, it is possible to pass different control data types within one control parameter of a HALCON operator.
The current number of values is returned in num.
HGetCPar allows to restrict the parameter access in two respects:
- The expected type can be specified by
type. This also includes type combinations such asLONG_PAR | DOUBLE_PAR. - The expected number of values can be specified by the interval (
min,max), whereasmaxshould not exceed the number of allocatedHcparelements within the arrayval.
If the specified number or types of values are violated, HGetCPar exits the supply procedure with an appropriate error message. Read the control parameter values of the operator call demo(5,’Text’,[0.5,1.7,4.4]) using HGetCPar shows an application of HGetCPar.
Note that in case of string parameters, memory has to be allocated for val[i].par.s.
The easiest way to do this is to use HAllocStringMem specifying the expected number of characters for all input strings, see HAllocStringMem.
HGetSParđź”—
HGetSPar is a simplified version of HGetCPar.
In contrast to the latter, a fixed number of parameter values is read, see Read the control parameter values of the operator call demo(5,’Text’,[0.5,1.7,4.4]) using HGetSPar.
Therefore, the routine does not return the actual number of values.1
Note that HGetSPar automatically checks the result state of the underlying procedure similarly to the macro HCkP (see HCkP).
Thus, you must not use HCkP on HGetSPar yourself.
Hcpar par1,par2;
Hcpar par3[3];
/* allocate memory for strings */
HAllocStringMem(proc_handle,1000);
/* read a short/int/long value in parameter 1 */
HGetSPar(proc_handle,1,LONG_PAR,&par1,1);
/* now par1.par.l == 5 */
/* read a string in parameter 2 */
HGetSPar(proc_handle,2,STRING_PAR,&par2,1);
/* now par2.par.s == "Text" */
/* read a tuple of 3 float values in parameter 3 */
HGetSPar(proc_handle,3,DOUBLE_PAR,par3,3);
for (i=0; i<num; i++) {
/* par3[i].par.d == 0.5,1.7,4.4 */
...
HGetCParNumđź”—
HGetCParNum returns the length of input control arrays of the input control parameter with the index par (1… n).
This makes it possible to allocate exactly as much memory for parameter values as needed for reading them, for example, via HCopyElemL, HCopyElemD, or HGetCPar.
As an alternative, you can use the reference passing routines as HGetPElem or HGetPPar, or routines as HGetElemL that allocate memory implicitly. Use HGetCParNum to get the number of control values before reading the control parameter values of the operator call demo(5,’Text’,[0.5,1.7,4.4]) shows an application of HGetCParNum.
Note that HGetCParNum automatically checks the result state of the underlying procedure similarly to the macro HCkP (see HCkP).
Thus, you must not use HCkP on HGetCParNum yourself.
Hcpar par1,par2;
Hcpar *par3;
INT4_8 num;
/* allocate memory for strings */
HAllocStringMem(proc_handle,1000);
/* read a short/int/long value in parameter 1 */
HGetSPar(proc_handle,1,LONG_PAR,&par1,1);
/* now par1.par.l == 5 */
/* read a string in parameter 2 */
HGetSPar(proc_handle,2,STRING_PAR,&par2,1);
/* now par2.par.s == "Text" */
/* read a tuple of float values in parameter 3; */
/* first, get the number of values */
HGetCParNum(proc_handle,3,&num);
/* now num == 3 */
/* second, allocate memory for the values and read them */
HCkP(HAllocTmp(proc_handle,(void**)&par3,(size_t)(num*sizeof(Hcpar))));
HGetSPar(proc_handle,3,DOUBLE_PAR,par3,num);
for (i=0; i<num; i++) {
/* par3[i].par.d == 0.5,1.7,4.4 */
...
HAllocStringMemđź”—
In case of string parameters, additional memory for the parameter values has to be allocated, because the Hcpar structure only contains a pointer to char.
The easiest way to do this is to use HAllocStringMem specifying the expected number of characters for all input strings (parameter size) at the begin of a supply procedure, see Read the control parameter values of the operator call demo(5,’Text’,[0.5,1.7,4.4]) using HGetCPar and Read the control parameter values of the operator call demo(5,’Text’,[0.5,1.7,4.4]) using HGetSPar.
It is not necessary to free this memory explicitly — this is done automatically at the end of the supply procedure.
Note that HAllocStringMem automatically checks the result state of the underlying procedure using HCkP (see HCkP).
Thus, you must not use HCkP on HAllocStringMem yourself.
HPutPElemđź”—
Names
Synopsis
#include "Halcon.h"
/* --- writing output parameters by reference */
HPutPElem( Hproc_handle proc_handle,
int par,
void *val,
INT4_8 num,
int type)
HPutPPar( Hproc_handle proc_handle,
int par,
Hcpar *val,
INT4_8 num)
/* --- writing output parameters by copy */
HPutElem( Hproc_handle proc_handle,
int parnr,
void const *val,
INT4_8 num,
int type)
HPutElemH( Hproc_handle proc_handle,
int par,
void const *elem,
INT4_8 num,
H_HANDLE_TYPE *HHandleInfo)
HPutCPar( Hproc_handle proc_handle,
int par,
Hcpar const *val,
INT4_8 num)
HPutPElem (see Routines for writing control output parameters) writes a native array to the output control parameter with the index par.
val holds the reference to the array of the according type, coded in type (LONG_PAR for arrays of type INT4_8, DOUBLE_PAR, for double, and STRING_PAR for char* arrays).
The length of the array is passed in num.
Instead of copying the array like HPutElem does, HPutPElem directly stores the pointer to the output control parameter and, thus, causes less overhead.
Therefore, this array has to be allocated “permanently”, i.e. it must be allocated by using HAlloc (see Global data).
Furthermore, the array must not be freed after passing it to HPutPElem. Write the control parameter values [1.2,4.4] using HPutPElem shows how to write output control data with HPutPElem.
Note that HPutPElem automatically checks the result state of the underlying procedure similarly to the macro HCkP (see HCkP).
Thus, you must not use HCkP on HPutPElem yourself.
double *d;
HCkP(HAlloc(proc_handle,sizeof(*d)*2,&d));
d[0] = 1.2;
d[1] = 4.4;
HPutPElem(proc_handle,1,d,2,DOUBLE_PAR);
HPutPParđź”—
HPutPPar (see Routines for writing control output parameters) is an alternative to HPutCPar and writes control data to the output control parameter with the index par.
However, instead of copying the num values like HPutCPar does, HPutPPar directly stores the pointer to the array of Hcpar structures (val).
Thus, it causes less overhead.
As HPutPPar directly uses the passed Hcpar array without copying, this array has to be allocated “permanently”, i.e. it must be allocated by using HAlloc (see Global data).
Furthermore, the array must not be freed after passing it to HPutPPar. Write the control parameter values [6,4.4] using HPutPPar shows how to write output control data with HPutPPar.
Note that HPutPPar automatically checks the result state of the underlying procedure similarly to the macro HCkP (see HCkP).
Thus, you must not use HCkP on HPutPPar yourself.
As already mentioned, every data element may use a different type, because the types of the parameter values (LONG_PAR, DOUBLE_PAR, STRING_PAR) are stored with each Hcpar structure.
Hcpar *par;
HCkP(HAlloc(proc_handle,(size_t)(sizeof(Hcpar)*2),(void**)&par));
par[0].par.l = 6;
par[0].type = LONG_PAR;
par[1].par.d = 4.4;
par[1].type = DOUBLE_PAR;
HPutPPar(proc_handle,1,par,2);
HPutElemđź”—
HPutElem (see Routines for writing control output parameters) writes a native array to the output control parameter with the index par of a HALCON operator.
The type of the array passed in val is coded by type, with LONG_PAR for arrays of type INT4_8, DOUBLE_PAR, for double, STRING_PAR for char* arrays.
In contrast to HPutPElem, the values are copied by this routine.
HPutElemHđź”—
HPutElemH (see Routines for writing control output parameters) writes num handle references to the output control parameter with the index par of a HALCON operator.
elem points to an array that holds num elements.
HHandleInfo contains information about the type of the corresponding handles.
Most notably,HHandleInfo contains pointers to the functions that operate on the handles (clear, serialize, deserialize and signal).
Note that the output control variable gains ownership of all pointers that are in elem. When aborting an operator with an error, those values must not be cleared inside the operator’s code, but will be cleared automatically when cleaning the output control variable.
HPutCParđź”—
HPutCPar (see Routines for writing control output parameters) writes control data to the output control parameter with the index par of a HALCON operator.
The num values in the Hcpar structure val are copied by this routine.
Because the types of the parameter values (LONG_PAR, DOUBLE_PAR, STRING_PAR) are stored with each Hcpar structure, you can use a different type for every data element, see Write the control parameter values [6,4.4] using HPutCPar.
Note that HPutCPar automatically checks the result state of the underlying procedure similarly to the macro HCkP (see HCkP).
Thus, you must not use HCkP on HPutCPar yourself.
Hcpar par[2];
par[0].par.l = 6;
par[0].type = LONG_PAR;
par[1].par.d = 4.4;
par[1].type = DOUBLE_PAR;
HPutCPar(proc_handle,1,par,2);
-
This number is fixed. If more or less values are passed to the HALCON operator,
HGetSParexits the supply procedure with an error. ↩