VC Lib Q Getting Started Manual

1.1   Goal of this document

This document explains how to set up VC Lib Q for VC Z in a Windows Eclipse environment and how to program VC Z cameras using VC Lib Q powered by Halcon.

1.2   Prerequisites

The following components are necessary:

• a working installation of the Vision Components SDK for VC Z. The installation documentation can be found here: VCLinux Getting Started Documentation
• a HALCON 13.0.2 development version with license on the development PC (see the standard HALCON Installation Guide) is mandatory.
• for C/C++ programming in Eclipse no licence is needed.
• VCLIB version 6.0.0 or higher as well as FLIB version 5.0.11 or higher and libvclinux 3.4.1 or higher are needed. You can check this with the command vcver or dpkg -l | grep vc:

Installed VC packages

If these libraries are not installed on your camera, please upload your camera using the script /root/up.sh (internet connection necessary):

cd
bash up.sh

If you are not sure about your library versions or cannot update your camera over the internet please send the output of the shell command vcver to support@vision-components.com.

2.1   Downloading the necessary components

Download the VC Lib Q library package here: VC_Lib_Q_13.0.4.zip

Unzip the file in a temporary folder. The following files are included:

• camera/libvclibq_13.0.4-1_armhf.deb : this is the debian package for installing the libraries on the VC Z camera
• pc/VC_Lib_Q_13.0.4_setup.exe : VC Lib Q installer for Windows

2.2   Installing VC Lib Q on a VC Z camera

Upload the VC Lib Q Debian package libvclibq_13.0.4-1_armhf.deb to /tmp on your camera using an SFTP client (for example WinSCP). Then connect to the camera via SSH (for example with TeraTerm) and install it with:

cd /tmp
dpkg -i libvclibq_13.0.4-1_armhf.deb

Upload the Debian package

Install the Debian package

The following will be installed:

• the VC Lib Q library and header files, compiled for the VC Z, including the Halcon image acquisition interface for VC Z. They are installed to /usr/lib
• the HALCON benchmark program hbench and the hrun program (allowing to execute HDevelop scripts on the VC Z camera). They are copied to /usr/bin
• /opt/halcon/examples: HDevelop example scripts for the image acquisition interface for VC Z
• /opt/halcon/examples/images: HALCON example images. Only the images needed for the programming examples in this tutorial are installed by the Debian package. If you need more example images, please copy them from your PC Halcon development installation. They are normally found at Documents\MVTec\HALCON-13.0\examples\images
• license: directory for the HALCON license file

The following environment variables are also set at startup on the VC Z camera:

• HALCONROOT=/opt/halcon
• HALCONARCH=armv7a-linux

2.3   Installing VC Lib Q on the development PC

Execute the setup file VC_Lib_Q_13.0.4_setup.exe in the same directory you installed your VC SDK (see the VCLinux Getting Started Documentation), for example C:\vc.

Install the package on Windows

The following will be installed on the development PC:

• the VC Lib Q library files for cross compiling, compiled for the VC Z. They are installed to C:\vc\vclinux\lib
• example Eclipse projects using VC Lib Q. They are installed to C:\vc\vclibq\examples\eclipse
• the image acquisition interface for VC Z (hAcqVC-Z.so, also installed in C:\vc\vclinux\lib), with example HDevelop scripts (C:\vc\vclibq\examples\hAcqVC-Z)
• documentation about the image acquisition interface for VC Z under C:\vc\vclibq\doc

2.4   Licensing

For VC Lib Q you need a runtime license for Vision Components VC Z cameras. For order numbers see chapter Available VC Lib Q packages. Rename the separately obtained license file to license.dat and place it in the subdirectory license of the HALCON folder on the VC Z camera (/opt/halcon/license).

MVTec's Halcon elements are subject to MVTec's EULA to be found at the standard documentation directory of the VC Lib Q Debian package on the camera under the name 'eula.txt'.

Note

To order a runtime license the CID number of the camera is needed (instead of the serial number). This number can be obtained by executing the following command on the camera:

cat  /sys/block/mmcblk0/device/cid

Example of CID number

2.5   Installing Cygwin/X for display

Halcon display functions on VC Z need an installation of X11, which is used as a virtual display. On Windows a solution is to install Cygwin/X.

First install xauth on the VC Z with (internet connection needed):

apt-get install xauth

Instructions for the installation on Windows are available here: http://x.cygwin.com/docs/ug/setup.html

After installing you can start the XWin server from the Windows menu. It then appears in the Task bar:

From there you can right-click the icon and start an xterm terminal:

Connect with:

ssh -Y root@192.168.3.15

From the camera shell you can then start your programs which are using X11 forwarding.

3.1   Example programs

After installing, some example Eclipse project are found under C:\vc\vclibq\examples\eclipse. These projects can be imported directly in Eclipse.

3.2   Setting up the development environment (Eclipse on Windows)

The provided example Eclipse projects already contain the right compiler settings for creating executables with VC Lib Q. These are the settings which have to be done additionnally to the standard settings seen in the Getting Started document:

Compiler settings

Linker settings

3.3   Creating and compiling programs with VC Lib Q

There are several possibilities to create applications with VC Lib Q. The possibilities are the same as with HALCON. Please also read the HALCON documentation about programming.

3.3.1   By exporting a whole program from HDevelop

The first possibility is to export a whole HDevelop script. For a better overview you can add your HDevelop script to your Eclipse project, just by copying this script per drag&drop into your Eclipse project. This is already done in the project vclibqECC200FromFile, which we will take here as an example.

Double-click on your script (in our example datacode.dev) to open it in HDevelop:

You can now modify the script as desired. When finished go to Menu File -> Export... In the dialog browse to your project folder (C:\vc_eclipse\YOUR_ECLIPSE_WORKSPACE\vclibqECC200FromFile\datacode.c). Choose to export the whole program, click on Export and confirm to overwrite.

Go back to Eclipse. Right-click on your project and choose "Refresh". The exported C-code appears, or is refreshed if already existing.

You can now compile the project. Please note the the references to X11 have to be commented first:

Comment the X11 include

Comment the call to XInitThreads

You can also try compiling and executing the following example projects:

• vclibqShapeMatching1stExample (with script first_example_shape_matching.dev)
• vclibqShapeMatching1stExampleMouseInput (with script first_example_shape_matching_mouse.hdev)

Note

X11 is necessary for displaying results when using the Halcon window functions (see chapter Installing Cygwin/X for display).

3.3.2   By exporting a HDevelop procedure and integrating it in one's own C/C++ program

To export a procedure, proceed the same way as before, but choose "Current Procedure" instead of "Program". To demonstrate this we take the example project vclibqShapeMatchingTeach. Double-click on the script vc_shape_matching_teach.hdvp (the script shape_matching_teach.hdev is present to be able to call and test the procedure within HDevelop):

Modify the procedure as needed and export it when finished:

You can now compile the project.

3.3.3   By programming directly in C/C++ in Eclipse

The following example projects show example of programming VC Lib Q directly in C:

• vclibqShapeMatchingSearchModelsvcimgCapt (uses the pattern saved in the program vclibqShapeMatchingTeach in the previous chapter)
• vclibqECC200vcimgCapt
• vclibqECC200vcimgCaptROI
• vclibqQRvcimgCapt
• vclibqBCvcimgCapt

For programmers used to HALCON/C or HALCON/C++ this will be familiar. The important point is the conversion from a VC image variable to a Halcon image variable after image capture. This is done using the function gen_image1_extern().

Image capture with vc_capt(), image conversion with gen_image1_extern() and use of a Halcon function using the newly created image variable

3.3.4   By using the HDevEngine

It is also possible to use the Halcon HDevEngine on the VC Z platform. For this download your HDevelop script directly on the camera and run the script with the provided tool hrun (located in /usr/bin, it can be called as a command directly from the shell). For more information please read the documentation of the image acquisition interface for VC Z.

Direct execution of HDevelop scripts including image acquisition

Note

• Tutorial: Tutorial image acquisition interface for VC Z
• Reference: Reference image acquisition interface for VC Z

3.4   Starting a VC Lib Q program automatically

It is possible to start a VC Lib Q program automatically at camera startup, like any other program. This is described in the Appendix D of our Getting Started manual:

VCLinux Getting Started Documentation

However in the case of a VC Lib Q program it necessary to set the Halcon environment variables directly in the user_init.sh file, otherwise the program will not start correctly. It is advised to use this user_init.sh template: user_init_vc_lib_q.zip