Skip to content

HALCON compiler hcompπŸ”—

The HALCON compiler hcomp is the most important tool for creating a new HALCON package. It automatically generates the interface code for the desired host language, the help files, and the documentation files. hcomp processes DEF files that contain descriptions of all operators as a basic resource, see Describing operators (DEF files). The HALCON compiler uses the same mechanism for generating the original system operators and user-defined operators.

The syntax of the hcomp command is as follows:

hcomp <options> <files>

Example:

hcomp -u -H -ppackage MyUserOps.def

The parameter -u signals that an interface for user-defined operators should be generated. This parameter can be omitted as it is the default1. The option -H generates the main package interface code (Hpackage.c). One or more definition files that are separated by blanks must be specified as files argument. The extension .def may be omitted:

hcomp -C -ppackage MyUserOps1 MyUserOps2 MyUserOps3

You either call hcomp in the directory of the DEF files (typically the package subdirectory def) or specify the path to the DEF files.

To use the package in a programming language, you must also generate the appropriate interface code. In the example above, the corresponding C files (HCpackage.c and HCpackage.h) are created with the option -C. Their names depend on the host language and the specified package, not on the names of the input DEF files.

Selecting the host languageπŸ”—

One call of hcomp can always create only one interface, i.e, the options described as follows can only be switched on under mutual exclusion. Use

hcomp -H [-ppackage] <DEF files>

to create the main interface code (Hpackage.c), which is necessary independent whether you want to use the package in HDevelop or in a programming language.

Additionally, the commands in the following table create the needed files for the corresponding programming languages.

Language Command Created Files
C hcomp -C [-ppackage] <DEF files> HCpackage.c
HCpackage.h
C++ hcomp -P [-ppackage] <DEF files> HCPPpackage.cpp
HCPPpackage.h
C# hcomp -N [-ppackage] <DEF files> HDOTNETpackage.cs

The generated source files are the basis for the interface libraries, see Generating HALCON packages.

Creating the help filesπŸ”—

Help files are necessary for the online access to the operator knowledge base via HALCON operators like get_operator_info. For example, HDevelop uses their information to build up the menu tree β€˜Operator’ (chapter and section structuring) and β€˜Suggestions’ (alternatives, cross references, predecessor, successor, and keywords). The help files are generated for the language selected with the (optional) -l option. The default language is English.

hcomp -M -l<language> <DEF files>

creates files with the stem operators_, followed by the language (default: en_US), and the following extensions:

Extension Description
.ref The operator description (text, value lists, …).
.idx Index for every operator specifying the start address of its entry within the *.ref file.
.key List of keywords (index entries) with the associated operators.
.num Specification of the number of parameters per parameter class for every operator.
.sta Specification of the parameter names and the chapter names for every operator.

In addition to the option -M

-c<TAGS-FILE>

can be set in order to insert the source file and the line number of the supply procedure of the operator into the *.ref file. To do this, a TAGS-File (usually TAGS) must have been generated by the etags command before.

Creating HTML reference filesπŸ”—

hcomp can generate HTML reference files. Thus, its easy to provide an online documentation of new operators that can be accessed with an HTML browser. Use

hcomp -R [-p<package>] -l<lang> -a<author-info> -f<copyright-footer> <DEF files>

to create HTML files. Note that the created HTML files contain the information for all programming language interfaces.

With the (optional) parameters -a and -f you can customize the created manual: The author information passed with the parameter -a appears on the main HTML page; the string passed with the parameter -f appears at the bottom of every generated HTML page.

The following files are generated:

  • index.html
    Home page containing the chapter structure and links to the different (sub-)chapters (toc_<chapter>_<subchapter>.html)
  • index_by_name.html
    Alphabetical list of all operators with links to the corresponding operator description pages (files <operator>.html)
  • index_classes.html
    List of all classes (for .NET) with links to the corresponding description pages (files <class>.html)
  • toc_<chapter>_<subchapter>.html
    For every (sub-)chapter: A list of all operators within the chapter with links to the corresponding operator description pages (files <operator>.html)
  • <operator>.html
    A description page for each operator
  • <class>.html
    A description page for each class (for .NET)

Creating the PDF reference manualsπŸ”—

hcomp can also generate LaTeX files containing the complete reference manuals adapted to the different supported programming languages, i.e. the description of the operators is provided in a specific syntax. Use

hcomp -Rlatex:<plang> [-p<package>] -l<lang> -a<author-info> -f<copyright-footer> <DEF files>

to create LaTeX files. <plang> can be set to c, cpp, com, dotnet, and hdevelop (HDevelop syntax). hdevelop is default and may therefore be omitted. The package name specified with [-p] is used for the title page of the manual.

The information passed with the parameter -a appears in the PDF version of the manual (see below) in the field β€œAuthor” of the dialog describing the document. With the parameter -f you can pass a string, which then appears on the back side of the title page. A typical use of this parameter is to print a copyright notice.

The generated LaTeX files use the package halcon_reference_en_US.sty (or similar for other languages). This package resides in the directory $HALCONROOT/doc/macros (Linux notation). You must include this directory in the environment variable TEXINPUTS. If the variable is empty, set it to:

:$HALCONROOT/doc/macros

Otherwise, LaTeX will be unable to find it (typical error message: File 'halcon_reference_en_US.sty' not found).

The LaTeX file(s) can be transformed into PDF files by using pdflatex and makeindex. Note that pdflatex must be called several times to get the references right; to get a correct table of context and index the sequence of calls is pdflatex > pdflatex > makeindex > pdflatex > pdflatex.

The generated PDF contains interactive bookmarks and hyperlinks similar to the HTML version (and the author information passed with the parameter -a). Note that this functionality requires that your LaTeX distribution includes the package hyperref; if this package exists but is too old, a warning will be issued, as this can result in errors during the LaTeX process or in suboptimal PDFs.

For a printer-friendly variant of the PDF file, you can disable the interactive features by modifying the file index.tex before starting pdflatex: Replace the line (possibly with different language key)

\usepackage[pdflinks]{halcon_reference_en_US}

by

\usepackage{halcon_reference_en_US}

If you want to create both documents with and without PDF links, use different directories or remember to delete all auxiliary LaTeX files before starting to pdflatex the modified index.tex, because the two versions are not compatible.

Further optionsπŸ”—

Option Description
hcomp -i filename <DEF files> Consider only the operators listed in filename.
hcomp -x filename <DEF files> Do not consider the operators listed in filename.

  1. hcomp is also used by MVTec to generate the interface code for the normal HALCON system. β†©