About the example package🔗
The following example illustrates the steps described in HALCON packages.
Assume, one wants to implement a new operator named user_thresh to extract all pixels with a gray value larger than a threshold value specified in an input parameter.
The use of user_thresh within a C program is illustrated in Calling the operator user_thresh in C; a more detailed example is provided in %HALCONEXAMPLES%\extension_package\halconuser\source\testthreshold.c.
main()
{
Hobject Image,Region;
int Thresh;
read_image(&Image,"monkey");
Thresh = 100;
user_thresh(Image,&Region,Thresh);
}
To use user_thresh in this way within C programs1,
- The new operator must be implemented.
- The corresponding HALCON interface code must be generated.
- The corresponding package must be created especially containing the operator and interface libraries.
- The application must be linked.
user_thresh <- CIPUserThreshold[Image:Region:Threshold:]
short.german
Schwellenwert-Operator.;
short.english
Selection of gray values by thresholding.;
module
foundation;
chapter.german
BenutzerErweiterungen;
chapter.english
UserExtensions;
functionality
image;
parameter
Image: input_object;
sem_type: image;
parameter
Region: output_object;
sem_type: region;
parameter
Threshold: input_control;
default_type: integer;
multivalue: false;
sem_type: number;
First of all one has to create a definition file (file extension .def), as illustrated in Defining a new operator user_thresh and An example for an extended DEF file of the operator user_thresh (minimal form), see %HALCONEXAMPLES%extension_packagehalconuserdefthreshold.def.
Defining a new operator user_thresh shows only the absolute minimum of information that a definition file must contain in order to call a new operator within C programs.
When using HDevelop, C++, or C#, an extended version is necessary as described in Extended operator description.
The minimal form of such an extended definition is illustrated in An example for an extended DEF file of the operator user_thresh (minimal form), see %HALCONEXAMPLES%extension_packagehalconuserdefthreshold.def.
The definition file specifies:
- the name of the operator (
user_thresh), - the name of the supply procedure that has to be implemented in C (
CIPUserThreshold), - names and types of the operator’s parameter(s). The names of the parameters are only important for the manuals and within HDevelop.
The minimal form of the extended operator DEF file includes: A short description (short), the HALCON module (module) the operator belongs to, the mapping to a chapter (chapter) of the manual, the mapping to an iconic object (functionality), and for every parameter its semantic type (sem_type).
In addition, the type (default_type) and number (multivalue) must be specified for control parameters.
Our operator user_thresh has got the following parameters:
- one input iconic object parameter (
Image), - one output iconic object parameter (
Region), - one input control parameter (
Threshold) of typeintwith exactly one value and - no output control parameter.
hcomp -u -H -phalconuser threshold.def
hcomp -u -C -phalconuser threshold.def
The operator definition within the DEF file now is used by hcomp to generate the appropriate interface code.
Calls of hcomp for HALCON/C shows the calls of hcomp.
Note, that within this manual halconuser is used as name of the HALCON package to be created.
By calling hcomp with these options2 the files Hhalconuser.c (HALCON interface code), HChalconuser.c (C-specific interface code) and HChalconuser.h (prototype of the new HALCON operator) are created.
In the next step one has to program the new HALCON operator. This is done by implementing the supply and action procedure. This results in the typical structure of HALCON operators as illustrated in Sample source code of supply CIPUserThreshold() and action IPBThreshold() procedure.
/* action procedure */
Herror IPBThreshold(proc_handle,region,image,
width,threshold,region_out)
{
...
}
/* supply procedure - always with this parameter! */
Herror CIPUserThreshold(Hproc_handle proc_handle)
{
HGetCPar(..,&Threshold,..); /* get control */
/* parameter */
HAllSegm(proc_handle,®ion,&image,1,i) /* work on all */
/* input images */
{
HCkP(proc_handle,IPBThreshold(...)); /* call action */
/* procedure */
HNewRegion(proc_handle,region_out); /* store (result) */
/* region */
}
return(H_MSG_TRUE);
}
Compiling the source code generates an object file (in the example cipuserthreshold.o) that should be integrated into the user extension library (halconuser).
Moreover, the generated interface code must be converted to the corresponding language dependent interface library: In case of a C application, this is halconuserc containing HChalconuser.o.
The example CMake file CMakeLists.txt in the directory %HALCONEXAMPLES%\extension_package\halconuser can be used for generating the example package under Linux or Windows and test programs as well.
Now we can use our new operators within C programs. But they are not yet available within HDevelop, because the online help files have not been generated so far. There is also still missing any kind of documentation, such as the HTML manual pages.
The online help files (as they are used e.g., by HDevelop) can also be generated with the help of the HALCON compiler hcomp, see Calling the HALCON compiler hcomp to create the help files.
However, to do so an extended version of the DEF file must be available.
The generated help files must be placed in the subdirectory help of the package.
The help files generated by now are used to access information about the new operators by calling specific HALCON operators like get_operator_info.
This important especially for constructing graphical user interfaces like HDevelop.
For the user a more convenient way to access information online is to browse through HTML documents.
The HTML documentation of HALCON operators can be generated by hcomp as well.
The HTML files have to be placed in the corresponding subdirectory doc\html\reference of the package.
If you now add the package path to HALCONEXTENSIONS and start HDevelop the user extensions, e.g. user_thresh, are automatically available in the specified menu (i.e., chapter).
In our example this menu is called UserExtensions as specified in %HALCONEXAMPLES%\extension_package\halconuser\def\threshold.def.3 You can select and execute the user-defined operators like all the built-in operators of the HALCON system.
The HTML documentation is available via the Help button within the operator window.
Examples of how to use the user defined extensions in HDevelop can be found in the subdirectory examples of %HALCONEXAMPLES%\extension_package\halconuser (*.dev).
Furthermore, the *.dev programs have been exported as C++ and C programs.
The *.cpp and *.c files can be found in the subdirectory source.
You can compile them using the already mentioned CMake file.
These *.cpp and *.c files also serve as an example for the integration of user defined operators into the host languages C++ and C.
Note that before compiling the exported C++ and C code containing operators from the package halconuser, the corresponding user extension libraries have been created.
This can be done via the CMakeLists.txt in %HALCONEXAMPLES%\extension_package\halconuser which will also generate the needed user extension C++ library halconusercpp and C library halconuserc.
Please note that on some systems not all users have write permissions in the directories mentioned above. To experiment with the example package we recommend to create a private copy in your working directory. In such a case you must of course use the actual path to your copy when modifying environment variables.
-
To use it within C++, C#, or Visual Basic basically the same steps are necessary, see Creating a new HALCON package. ↩
-
see The HALCON compiler
hcompfor a complete description. ↩ -
UserExtensionsis integrated into the menuOperatorof HDevelop. ↩