To get started, the basic structure of an ibaVision program has been described in chapter Working principle. We will also provide an example program here where the most important ibaVision features will be included.

The example program is available on GitHub: https://github.com/iba-ag/ibaVision-Example-Scripts The listed code in this manual may not match the example from GitHub in all details.

The example program will read images from an ibaCapture Server, evaluate the average brightness value and rotate the image by a given angle. The value for the rotation angle can be passed dynamically from an ibaPDA server.

On the outputs, there will be a few numeric and text values as well as the rotated image. This stream of images can then be encoded for storage in an ibaCapture Server.

Listing

HDevelop main() procedure

This procedure is the entry point for program execution in HDevelop. It will however not be executed by ibaVision by default.

For this example, the main() procedure is structured in a way that allows it to be executed from both HDevelop and ibaVision.

These requirements are considered here to allow operation in both HDevelop and ibaVision:

  • In ibaVision, the specification of three procedures (init, main and cleanup) is required. These are called from the HALCON main() procedure in lines 10, 18 and 22.

  • Image acquisition from ibaCapture will be handled in ibaVision. For operation in HDevelop, a framegrabber instance is managed outside the three ibaVision procedures.

  • The main procedure that is specified in ibaVision must not contain an infinite loop. While ibaVision is working, ibaVision will call the main procedure repeatedly to retrieve result values after every execution. This behavior is simulated with the while-loop (line 13) for execution in HDevelop.

  • In the ibaVision_init() procedure a buffer window is created to allow flexible drawing operations for output images. The drawback of this approach is execution time. For time-critical applications where output images are required, other possibilities of dynamically creating images with HALCON operators should be considered.

To avoid runtime errors in HDevelop, on line 7 the input variable that ibaVision would receive from ibaPDA is initialized with a static value. In ibaVision, these can be set as static values but could also be read from ibaPDA inputs.

To actually execute this example in HDevelop, you need access to an ibaCapture Server in the network.

It is necessary to modify the parameters of open_framegrabber in line 3:

  • ‘192.168.0.2\\user\\pass’ needs to be adapted to the actual network address of an ibaCapture Server. If user management is enabled, specify the credentials instead of “user” and “pass”. Otherwise only the server address needs to be specified.

  • ‘Camera Name’ needs to be changed to a camera name that is actually available on the ibaCapture Server where HDevelop connects.

  • The parameter ‘rgb’ is typically used for color cameras. If monochrome images should be acquired, set this to ‘gray’.

Other possibilities of accessing ibaCapture video data are described in the chapter Accessing video data from ibaCapture in HDevelop.

ibaVision_init() procedure

The init procedure is intended to be run once before the actual image processing starts. All resources that need to be available during image processing can be initialized here.

Our example has the following sections:

Global variable definitions

(lines 1 to 3)

Global variables are defined here. Global variables can be used across multiple procedures in a HALCON program. See the HALCON Programmer’s Manual for more information on global variables.

Initialize global variables

(lines 6 to 8)

The global variables are initialized for program execution. Note that it would also be possible to read the initialization values from inputs of the init procedure instead of hard-coding values here.

Set system

(lines 10 and 11)

The operator set_system for width and height is used to maintain properly scaled image output. The values for width and height should be set to the width and height of the output image.

Open log file

(lines 14 to 16)

This creates a log file where messages from the HALCON program can be written to. Be aware that ibaVision needs to be installed with the ibaHALCONLogger option enabled to use logging.

Create rectangular region

(line 21)

A region is generated for use in the main procedure.

Initialize buffer for writing images

(line 24)

This operator creates a buffered window. This will be used for drawing the output images in the main procedure.

Try-catch-block

(Lines 19, 25 to 32)

The try-catch mechanism is a widely used programming technique for error handling. In case a so-called exception happens during the execution of the code in the try-block, its message will be logged in the catch-block, using the previously defined log file. More information on exception handling can be found in the HALCON Programmer’s Manual.

Keep in mind that some programming tools like e.g., barcode models for barcode readers, only need to be initialized once and can be used indefinitely. Such initialization commands should always happen in the init procedure of ibaVision programs.

If the image processing does not require any initialization commands, the procedure can also be left empty except from the “return()” operator.

ibaVision_main() procedure

This procedure will be called repeatedly by ibaVision. Before it is called, all input values (Image, Rectangle, BufferHandle, degrees) are updated with the current values from the respective data sources.

After the execution, the values from all output values (OutputImage, brightness, textOutput) will be forwarded to the defined output channels.

Our example has the following sections:

Global variable definitions

(lines 1 – 3)

To use defined global variables in this procedure, they need to be defined at the beginning.

Count number if procedure executions

(lines 7 – 11)

This is optional for the actual image processing but a very helpful tool for monitoring the execution of this program.

Prepare input image

(lines 14 – 20)

All input images will be resized to 640 x 640 pixels. This size was set globally in the init procedure. In case a color image (RGB) was used as input, it will be converted into a grayscale image.

Determine brightness

(line 23)

The used HALCON operator determines the average brightness of all pixels in a given region. The region in this case is defined by the object “Rectangle”, which also has a size of 640 x 640 pixels.

The output value “Mean” will then be passed to the calling procedure through the output parameters.

Rotate image

(line 26)

After determining the brightness, the image is rotated by the given number of degrees. While the value of the variable “degrees” is constant when executed in HDevelop, a dynamic value can be assigned in ibaVision, for example coming from an ibaPDA input module. That way, the rotation angle could be different for every new image.

Build textOutput

(line 29)

Maincounter, brightness and number of channels are combined into one string.

Write image to buffer

(lines 32, 33)

To prepare the output image, the rotated image is now written to the buffer window.

Write text to buffer

(line 36)

For demonstration purposes, the content of the variable “textOutput” is written to the buffer window.

Get image from buffer

(line 39)

The current state of the buffer window with the recently painted image and string is written to the image object “OutputImage”. This will then be passed as an output parameter from the ibaVision_main procedure.

At the end there is a catch-block where messages from occurred exceptions will be logged.

Please keep in mind that this is just an example to show the possibilities of manipulating data and images in HALCON and communicate the results with other tools in the iba-system.

Other image processing tasks may require programs with significantly higher complexity.

ibaVision_cleanup() procedure

The cleanup procedure should be used to close all open resources. Typically, open resources will have been opened in the init procedure.

In this example, the buffer window needs to be closed.

To indicate that the execution of the cleanup procedure was successful, a final message will be written to the log.

Like in the other procedures the try-catch-block is used to catch and log exceptions.