Skip to content

Operators and procedures🔗

About operators🔗

When using one of the HALCON operators, HALCON Script behaves very similar to HDevelop, with this general signature of an operator:

operator (iconic input, out iconic output, control input, out control output)

More Info

For more information about control and iconic data, see Basic types of parameters.

About procedures🔗

Declaring and calling procedures🔗

In HALCON Script, you write the code of a procedure just as you write the “main” program part, as procedures are just a part of the program file. Procedures are distinguished by certain keywords.

Adhere to the following:

  • A procedure must start with one proc statement and end with one endproc statement.
  • A procedure by default has private scope, that is, it is only accessible within the current file. To create a public procedure (that is, make it accessible from other files), declare it as such by adding the public statement before the first proc statement.
  • You can either use a dedicated mainprocedure or put all lines of code that are not part of a procedure (“standalone statements”) at the end of the program. This means: In the HSCRIPT file, all procedures (that is, all proc ... endproc blocks) must come before any standalone statements.
  • There can only be one procedure called main. If this procedure exists (that is, if there is a public proc main (...) endproc block), it serves as the entry point of the program. In this case, the main block does not need to be at the end, but there must not be any further standalone statements.
  • Only a public main procedure can be used for running a program. This means that the main procedure must start with the corresponding access specifier: public proc main.

  • Parameters are defined using the following keywords:

    • Iconic input: object keyword

    • Control input: tuple keyword

    • Iconic output: out object keyword

    • Control output: out tuple keyword

  • Parameters must be separated by , (comma).

General syntax of procedure declaration
proc proc_name (object InputImage, tuple InputParam, out object OutputImage, out tuple OutputParam)
  (...)
endproc

The above syntax creates a procedure with private scope by default. To specify the scope of a procedure, use the private or public keyword:

Syntax of procedure declaration, private scope
private proc proc_name (...) # (1)!
  (...)
endproc
  1. The private keyword is optional.
Syntax of procedure declaration, public scope
public proc proc_name (...)
  (...)
endproc

When declaring a procedure, the order of the parameter types (iconic in, control in, iconic out, control out) is not fixed, as can be seen in the following example.

Example: Procedure declarations with different parameter order

The following two declarations both are valid: 

proc initialize_visualization_1 (tuple Width, 
                                 tuple Height, 
                                 out tuple WindowHandle, 
                                 out tuple WindowHandleText)
  <code of procedure>
endproc

proc initialize_visualization_2 (out tuple WindowHandle, 
                                 out tuple WindowHandleText,
                                 tuple Width,
                                 tuple Height)
  <code of procedure>
endproc
While both procedures expect identical input and output parameters, you have to provide them in the corresponding, correct order when calling the procedures: 
initialize_visualization_1 ('600', '400', WindowHandle, WindowHandleText)

initialize_visualization_2 (WindowHandle, WindowHandleText, '600', '400')

Procedure resolution🔗

When your HSCRIPT file contains one or more correct import statements, all procedures from the imported files become available within your file. That means, you can call the external procedures from anywhere within your own code.

Importing procedures is not transitive. That means, if your own file imports from other_file.hscript, and other_file.hscript then imports from yet_another_file.hscript in turn, you will nonetheless only be able to access the procedures from other_file.hscript – but not from yet_another_file.hscript.

Keep the following in mind:

  • If your own file locally contains a procedure with the corresponding name, this procedure will be called but none of the external ones.
  • If there are only external procedures available, HDevelopEVO will arbitrarily choose one of them. There is no way to controll which one at the moment.
  • HDevelopEVO will report a warning that the regarding call is ambiguous and it will list the file from which the procedure will be called as well as the file containing the procedure that is hidden.

Preview restriction

Currently, there is no solution to select the procedure to call if there is more than one possible candidate.

Procedure and file documentation🔗

Any procedure and file documentation is purely descriptive and provides a structured documentation block for files and procedures in your code. It does not affect the script itself. An invalid procedure or file documentation will generate warnings only, not errors.

Procedure and file documentation can appear in two locations:

File documentation🔗

  • Positioned at the beginning of a source file, is it placed before a procedure block it then describes only this procedure.
  • May appear before or after imports.
  • Must appear before any procedures or executable code.

A file documentation block may contain only:

  • @short — short description

  • @description — detailed description

Any other tags will generate a warning.

Procedure documentation🔗

  • Positioned at the start of a procedure block.
  • Appears after the procedure interface.
  • Appears before the actual code.
  • Describes the specific procedure.

General procedure tags describe the procedure as a whole, can appear in any order and @short may be omitted if it appears first. The parameter block marker @parameters is optional and used only as a visual marker, for example for code folding. It has no functional effect.

Parameter rules
Each parameter can appear only once.
Duplicate entries are ignored or may generate warnings.
All tags for a parameter must be grouped in a sub-block.
The order of parameters is arbitrary, and should generally match the procedure interface.
Parameter definition

Each parameter block begins with

@parameter <ParameterName>

followed by a description and other tags. If the description follows immediately, @description may be omitted.

Example: Procedure and parameter tags

'''
<short description>
@description <long description>
'''

proc p (tuple p1, tuple p2)
'''<short description>
@description <long description>

@parameter p1 <description>
    @sem_type integer

@parameter p2 
    @description <description>
'''
endproc

Syntax and structure🔗

Procedure and file documentation is enclosed by three single quotes '''.

The content consists of a list of properties, referred to as tags.

General rules:
Each tag may appear only once per block.
Additional occurrences are ignored and produce warnings.
A tag consists of a tag name, followed by a value or list of values.
Tag names:
Always start with @ for example, @short or @description.
Some tag names can be omitted in specific cases:
  • @short may be omitted if it is the first entry.
  • @description may be omitted in parameter descriptions.
Tag values:
Free Text
Start the free text immediately after the tag name.
End at the next tag, or the end of the block.
Leading and trailing whitespace is being trimmed.
To include the special character “@” in text, add two backslashes: \\@.
Tuple values
Tuple values represent as single tokens with no whitespace or line breaks.
They must be numeric literals, numeric constants like H_INT_MAX, or string literals.
Individual elements of value lists are separated by , (comma). Optionally, a value list may be enclosed in square brackets [].

Important

false → interpreted as a boolean (numeric value 0)

'false' → interpreted as a string

Table 1: Procedure tag values
Tag Free text Definition
@short yes Short description
@description yes Description
@warning yes
@example yes
@param yes
@keywords yes
Table 2: Parameter tag values
Tag
 Free text Definition
@sem_type yes Specifies the class of data passed as parameter
@default_type yes Specifies, which tuple type to use in general; control parameters only
@type_list yes Accepted pixel type for images, tuple type for control parameters
@multivalue yes Number of values passed in a parameter; true, false, optional
@mixed_type yes Variety of tuple types; true, false, optional
@multichannel yes Number of channels in an image; true, false, optional
@default_value no (one single) default value for autocompletion
@suggested_values no List of suggested values for autocompletion
@value_list no Complete list of allowed values for autocompletion
@min_value no Maximum value of a control parameter
@max_value no Maximum value of a control parameter
@file_ext yes List of file extensions
@file_ext_descr yes List of descriptions