VC Lib Q Getting Started Manual

Revision: 2.0.3
Date: 2020-08-20
Copyright: 1996-2020 Vision Components GmbH Ettlingen, Germany
Author: VC Support,
Foreword and Disclaimer

This documentation has been prepared with most possible care. However Vision Components GmbH does not take any liability for possible errors. In the interest of progress, Vision Components GmbH reserves the right to perform technical changes without further notice.

Please notify if you become aware of any errors in this manual or if a certain topic requires more detailed documentation.

This manual is intended for information of Vision Component’s customers only. Any publication of this document or parts thereof requires written permission by Vision Components GmbH.

Image symbols used in this document
Symbol Meaning
Note Sign The Light bulb highlights hints and ideas that may be helpful for a development.
Warning Sign This warning sign alerts of possible pitfalls to avoid. Please pay careful attention to sections marked with this sign.
Example Sign This is a sign for an example.


Linux, Debian, the Tux logo, Vivado, Xilinx and Zynq, ARM, Cortex, Windows XP, Total Commander, Tera Term, Motorola, HALCON, FreeRTOS, Vision Components are registered Trademarks. All trademarks are the property of their respective owners.

Table of Contents

1   General Information

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/ (internet connection necessary):


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

2   Installation of the necessary components

2.1   Downloading the necessary components

Download the VC Lib Q library package here:

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 (, 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 Sign

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:

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@

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

3   Programming with VC Lib Q

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.

Description of the example programs
Project name Description Type
vclibqProject Template project. Contains the necessary settings for compiling with VC Lib Q but no source code. -
vclibqECC200FromFile ECC 200 code reading, from image files. HDevelop script export
vclibqShapeMatching1stExample Pattern matching, easy example. HDevelop script export
vclibqShapeMatching1stExampleMouseInput Pattern matching with mouse input for the pattern teaching part. HDevelop script export
vclibqShapeMatchingTeach Pattern matching: pattern teaching with mouse input and saving the pattern as a file. HDevelop procedure export
vclibqShapeMatchingSearchModelsvcimgCapt Pattern matching: pattern (read from file created by vclibqShapeMatchingTeach) finding with image capture and image transfer for visualisation. C code
vclibqECC200vcimgCapt ECC200 code reading with image capture and image transfer for visualisation. C code
vclibqECC200vcimgCaptROI ECC200 code reading with image capture and image transfer for visualisation, with possibility to set a search ROI. C code
vclibqQRvcimgCapt QR code reading with image capture and image transfer for visualisation. C code
vclibqBCvcimgCapt Barcode reading with image capture and image transfer for visualisation. C code


Note Sign

Project import into Eclipse is described in the VCLinux Getting Started Manual, chapter 5.6.2: VCLinux Getting Started Documentation


Note Sign

Under C:\vc\vclibq\examples\hAcqVC-Z you can find examples of HDevelop scripts using the image acquisition interface for VC Z. More information can be found in the corresponding chapter By using the HDevEngine.

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


Warning Sign If you installed the VCLinux SDK in another folder than C:\vc the include and library paths have to be modified accordingly!

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 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
  • vclibqShapeMatching1stExampleMouseInput (with script first_example_shape_matching_mouse.hdev)


Note Sign

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

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 file, otherwise the program will not start correctly. It is advised to use this template:

4   Available VC Lib Q packages

Several packages of the VC Lib Q are available for order.

VC Lib Q packages
Order Number Product / Service description
VK002880 VC Lib Q (Full HALCON functionality)
VK002017 VC Lib Q Code Reading pack
VK002877 VC Lib Q OCR Pack
VK002878 VC Lib Q Code + OCR pack
VK002879 VC Lib Q Pattern Matching pack