TRISPECTOR1000 STREAMER

2018-10-04
CONTENT

 Introduction to TriSpector1000 Streamer

 TriSpector1000 Streamer
▸ Interface overview
▸ Needed software components
 Introduction to GenICam GenTL standard
 How to setup Halcon 13 with TriSpector1000 Streamer
 How to use the Demo example program

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 2

TRISPECTOR1000 STREAMER
INTRODUCTION

 The TriSpector1000 Streamer provides data

that can be received according to the
GenICam GenTL 1.5 standard

 Data stream
▸ The TriSpector GenTL producer can send out 8-
bit reflectance and 16-bit range data, as well
as additional information needed to convert
range data into millimeters
▸ The TriSpector GenTL producer is included, it is
simply a dll file (renamed to cti=common
transport interface) that contains a C interface  The TriSpector1000 Streamer continuously
to expose the camera API sends images via the GenTL interface to a
host PC with
 Camera control and events ▸ Any GenICam application software that
receives the images (example provided)
▸ Currently only start and stop of the image
▸ You can write your own receiver using GenAPI
acquisition are implemented
or use existing software such as HALCON by
▸ The camera configuration part of the standard MVTec
is not yet implemented
October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 3
TRISPECTOR1000 STREAMER
INTERFACE OVERVIEW

Data stream

Camera control and events

Only starting and

stopping of the
image acquisition is
implemented

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 4

TRISPECTOR1000 STREAMER
NEEDED SOFTWARE COMPONENTS

 TriSpector GenTL Producer

▸ The TriSpector GenTL Producer is a (32/64-bit) .CTI file
that is used for streaming reflectance and range data
from a TriSpector1000 device to a Windows PC
(Windows 7, Windows 10) via a GenTL interface
 SOPAS ET
▸ Before connecting to the TriSpector GenTL Producer, the
image settings of the TriSpector1000 device must be
configured using SOPAS Engineering Tool
▸ The Task, Results, and Interfaces workflow steps in the
SOPAS ET user interface can be ignored if the image
analysis should be performed on the PC receiving the
data from the GenTL producer
▸ When the device has been configured, the SOPAS ET
user interface should be closed to avoid disturbing the
GenTL Producer
 TriSpector FW
▸ TriSpector1000 runs standard firmware version 2.3 and
no firmware upgrade is needed

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 5

GENICAM GENTL STANDARD
INTRODUCTION

 The goal of the GenICam GenTL standard is to

provide a generic way to enumerate devices
known to a system, communicate with one or
more devices and, if possible, stream data from
the device to the host independent from the
underlying transport technology

 The core of the GenICam GenTL standard is the

definition of a generic Transport Layer Interface
(TLI)
▸ The TLI software interface between the transport
technology and a third party software is defined by The C interface is described in the header
a C interface with a defined behavior and a set of file gentl.h which is needed to develop
standardized feature names and their meaning your application software
described in the SFNC standard document. This
interface is implemented in the .cti file that belongs
to this example.

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 6

GENICAM GENTL STANDARD
INTRODUCTION

 To access the standardized features of the TLI

the GenICam GenApi module is used The GenApi module is included in the
HALCON application, and part of the
▸ The GenICam GenApi module is an API for
TrispectorStreamer example program
accessing and controlling device features

 GenTL is a software TLI to communicate with

devices and stream data from them
▸ The GenTL interface does not cover any device-
TriSpector1000
specific functionality of the remote device except
Streamer is a
the one to establish communication
”remote device”
▸ The GenTL interface allows a third party software
(a GenTL Consumer) to use different technologies
to control cameras and to acquire data in a The TrispectorStreamer
transport layer agnostic way example program and
Halcon are ”Consumers”

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 7

GENICAM GENTL STANDARD
INTRODUCTION

 The GenTL interface provides a port to allow access to the

remote device features via the GenApi module GenTL interface

 A GenTL Producer is a software module implementing the

GenTL Interface to enable an application or a software
library (i.e. a Consumer) to access and configure hardware GenTL
in a generic way and to stream image data from a device Consumer
 Your .cti file for the TriSpector GenTL
Producer
GenAPI
 A GenTL Consumer is any software (for example an module
application or a software library) which can use one or
multiple GenTL Producers via the defined GenTL interface

 The combination of GenApi and GenTL provides a

complete software architecture to access devices

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 8

TRISPECTOR1000 STREAMER
INTEGRATION WITH HALCON 13
TRISPECTOR1000 STREAMER INTEGRATION WITH HALCON 13
INTRODUCTION
 Use case
▸ Image acquisition is configured via SOPAS ET
▸ The TriSpector1000 Streamer continuously sends images via the provided GenTL Producer to a PC
running HALCON to perform image analysis – no image analysis is performed on the device

 HALCON
 HALCON 13 or newer versions are recommended for use with the TriSpector1000 Streamer

 Streamed images and data

▸ Images sent via the GenTL producer consist of height data, reflectance data and metadata (scale and
offset)
▸ The metadata is used for measurement conversion

 Supported camera firmware versions

▸ The V2.4.0 GenTL Producer is compatible with TriSpector1000 version V2.3.0 or later

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 10

TRISPECTOR1000 STREAMER INTEGRATION WITH HALCON 13
INSTALLATION

1. Two .CTI files are provided by SICK. Choose one depending on your
HALCON installation (32-bit or 64-bit)
i. SICKTrispectorTL32.cti
ii. SICKTrispectorTL64.cti
iii. Please note that the .CTI-file is windows specific

2. Create a new environment variable

a) Go to your Control Panel
b) Select System and Security
c) Select System
d) Select Change settings and your System Properties window will open
e) Select Advanced and click on Environment Variables

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 11

TRISPECTOR1000 STREAMER INTEGRATION WITH HALCON 13
INSTALLATION
 Make sure you create a new User variable and not a new
System variable

 Name your environmental variable based on which

HALCON installation you are using
▸ 32-bit: GENICAM_GENTL32_PATH
▸ 64-bit: GENICAM_GENTL64_PATH

 Create a folder in an appropriate location and place the

.CTI-file in the newly created folder
▸ Set the Variable value as the path to your folder containing the
.CTI-file

 Start HDevelop

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 12

TRISPECTOR1000 STREAMER INTEGRATION WITH HALCON 13
OUTPUT

 The TriSpector1000 Streamer will output an 8-bit reflectance and 16-bit range image, as well as
metadata for converting the range data into millimeters. Following metadata is available

 How to convert a 16-bit range value into millimeters

▸ Zmm = OffsetZ + ScaleZ * Z16 (showed in the example program)

 How to calculate the X/Y value in millimeters for a certain pixel in the reflectance/range image
▸ Xmm = OffsetX + ScaleX * column
▸ Ymm = OffsetY + ScaleY * row

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential

 TRISPECTOR1000 STREAMER INTEGRATION WITH HALCON 13
RUN EXAMPLE PROGRAM

 Load the example program

Trispector-Halcon-example.hdev
 Make sure you are connected to
your device
 Press the run button or F5 to run
the program

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential

 TRISPECTOR1000 STREAMER INTEGRATION WITH HALCON 13
GETTING IMAGES

 You should now be getting four images displayed for you. One will contain temporary data and three that are
named as follows: ImageReflectance, ImageRangeMm and ImageRangeContrast
 ImageReflectance contains the 8-bit Reflectance image. ImageRangeMm contains the Range data with
the correct z mm value for each pixel. ImageRangeContrast is the same range image but the contrast is
enhanced (using more grayscale values) to better see the object but you don’t have the mm values here

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential

 TRISPECTOR1000 STREAMER INTEGRATION WITH HALCON 13
VIEWING Z MM VALUES

 Use the zoom window to view the mm values in the ImageRangeMm image

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential

TRISPECTOR1000 STREAMER INTEGRATION WITH HALCON 13
WALKTHROUGH OF THE CODE

 First line opens the connection to your device using “GenICamTL” interface

 After you have connected to your device, you have to enable both Reflectance and Range image to be
sent from your device

 This part of the code reads the scale and offset parameters

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 17

 TRISPECTOR1000 STREAMER INTEGRATION WITH HALCON 13
WALKTHROUGH OF THE CODE

 Enhance the contrast in the range image with equ_histo_image

 Scale the image according to Zmm = OffsetZ + ScaleZ * Z16. You first need to convert the image type to
real otherwise the values get truncated

 In this example a for loop is used to acquire images. If you are interested in continuous image acquisition
you can use a While loop instead. The purpose of this example is just to get you started!

.
.
.

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential

TRISPECTOR1000 STREAMER
INTEGRATION EXAMPLE PROGRAM
TRISPECTOR1000 STREAMER INTEGRATION EXAMPLE PROGRAM
BEFORE YOU START

 About the example program

▸ You will be provided with an example solution builty with C++ in Visual Studio 2015
▸ The example program captures range and reflectance images from a TriSpector1000 Streamer and show them
using openCV. It also shows how to set and get parameters from the Trispector1000 streamer.
▸ The example program is divided into two parts – complete sourcecode and a stand alone application. We will
start with walking you through the stand alone application, but if you are interested in creating your own
application please see slide 26-27. All files needed for either option can be located in following .zip-files
― TriSpectorStreamerApplication.zip
― TriSpectorStreamerSourceCode.zip

 Independently on how you choose to run the example program, you will need to have following software
▸ Visual C++ Redistributable Package
― To run code examples which uses GenICam binaries, you need to have the Visual C++ 2013 runtime environment, i.e., vc120
― If you don't have vc120 installed you can run the executable in the VCRedist2013 directory to install the English version.
Other languages can be downloaded here
▸ SOPAS Engineering Tool

 Make sure you have an x64 operations system since this application is only compatible with that
October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 20
TRISPECTOR1000 STREAMER INTEGRATION EXAMPLE PROGRAM
RUN STAND ALONE APPLICATION (1/4)

 Prerequisites
▸ TriSpectorStreamerApplication.zip
▸ For this specific application you will also need Visual C++ 2015 runtime environment
― If you don’t have either of the runtime environments installed, you can find them inside the .zip-file.
Simply run the executables inside the marked folders to install a

 Solution
1. Unzip the folder TrispectorStreamerApplication to your PC
a) Please make sure you can find TriSpectorS_Config.xml and CaptureImages.exe, since you will need
these files later on to setup and run the application
2. Configure your TriSpector1000 Streamer using SOPAS ET and save your configuration for
image acquisition a

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 21

TRISPECTOR1000 STREAMER INTEGRATION EXAMPLE PROGRAM
RUN STAND ALONE APPLICATION (2/4)
3. Start with configuring your TriSpector1000 Streamer using SOPAS ET and
save your configuration for image acquisition
4. If you want to try sending commands to the TriSpector1000 Streamer you 4
2
need to setup the command channel. This is done on the Ethernet section
of the Interfaces Tab inside SOPAS ET
a) Let the camera act as server
b) Remember the port you choose
c) Note the serial number of your device. This information will be useful for the a
configuration file, and can be found SOPAS ET

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 22

 TRISPECTOR1000 STREAMER INTEGRATION EXAMPLE PROGRAM
RUN STAND ALONE APPLICATION (3/4)
This application gives you the possibility to set profile trigger mode and image trigger mode on your device from the command channel. That
will override the trigger settings you have setup in SOPAS ET. It is possible to set all image acquisition parameters from the command channel
but this application will only show you how to change the trigger parameters. This application will also ask the camera for exposure time when
it starts and then set the exposure time to same value as it get as response. You will see this in the console window when running the program.
In the source code you could easily extend the application to do more configuration from command channel
5
5) Open TriSpectorS_Config.xml and do following changes
a. Change the DEVICE_SN to match the serial number of your device (see
previous slide) a
b. If you want to send commands to the TriSpector change CAM_PARA to
“on” and continue with the configuration. If you don’t want to send
commands you are done with the configuration and can continue to b
next slide
c
c. Change the CAM_IP to match the IP address of your device
d. Change the CAM_PORT to match the port of the command d
channel (see previous slide)
e
e. Change the Profile_Trigger value to match the profile trigger
mode you want, FreeRunning or Encoder f
f. Change the Image_Trigger value to match the image trigger
mode you want, Input, None, Object or Command

Note: If you have set CAM_PARA to off it does not matter what values you have below (CAM_IP, CAM_PORT etc) since the command channel will not be
used. GenTL uses broadcast to find devices and does not need the info about IP address. Thus you will still be able to capture images

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 23

TRISPECTOR1000 STREAMER INTEGRATION EXAMPLE PROGRAM
RUN STAND ALONE APPLICATION (4/4)
6. Run the CaptureImage.exe
― This file should be found in your unzipped folder
― It’s recommended to run it from a console window because if a error occurs you
will see this in the console window, otherwise it will close down whenever a error
occurs without notifying
7. You are now ready to start acquiring images from the TriSpector1000 6
Streamer!

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 24

TRISPECTOR1000 STREAMER INTEGRATION EXAMPLE PROGRAM
BUILD SOURCECODE (1/2)

 Prerequisites
▸ TrispectorStreamerSourceCode.zip
▸ Visual Studio 2015
― The source code is written in Visual Studio 2015 so you need this to build the application
― With the Microsoft Foundation Classes for C++ (install if you don’t have this already)

 Solution
1. Unzip the folder TriSpectorStreamerSourceCode to your PC
2. Open TrispectorS_API_developer /Configuration/TrispectorS_Config.xml
― You will need to do some changes in the .XML-file, please see slide 24
3. Setup your camera according to previous instructions, please see slide 23

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential

TRISPECTOR1000 STREAMER INTEGRATION EXAMPLE PROGRAM
BUILD SOURCE CODE (2/2)
4. Open TrispectorSDemo.sln and start building  project/TrispectorSDemo/TrispectorSDemo.sln
― Only build in x64 release mode, since everything else is untested or faulty
5. You are now ready to start acquiring images from the Trispector1000 Streamer! Use the debugger to step
through the program to understand what is happening!

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 26

EXTRA INFORMATION ABOUT SOURCECODE
VISUAL STUDIO EXAMPLE PROVIDED

 The showcased example program is built with C++ in Visual Studio 2015
 The folder named “TrispectorSDemo” consists of two projects, TrispectorSAPI and
CaptureImages
 TrispectorSAPI contains all the specific code to integrate with the TriSpector1000 streamer. This project
builds a .dll that could be used in any other windows implementation
 CaptureImages is a small example that uses the TrispectorSAPI project to capture images from a
TriSpector1000 Streamer and shows them using openCV

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 27

EXTRA INFORMATION ABOUT SOURCECODE
CONTENT IN TRISPECTORSTREAMERSOURCECODE.ZIP
 Folder src – Consists of two folders. The TrispectorS folder contains code specifically built for enabling
communication with the TriSpector1000 Streamer. The ThirdParty folder contains utility code for logging and xml
reading used in the example project
 Folder TrispectorS_API_developer – Here is everything you need to setup your own project in VS if you do not want to
use the provided project. Contains two bat script for setting and deleting the environment variable
SICK_TRISPECTORS_API and following folders
▸ Bin - All dll:s needed to run the example project, you might not need all of them if you build your own project, pick what is needed
▸ Configuration – Here is the configuration file for the TriSpector1000 Streamer. In the XML-file you could setup some basic parameters such as IP of the
camera to connect to, port of camera to connect to, what profile triggering to use and what image triggering to use
▸ Cti – Contains two cti files applied, 32 and 64 bit, use depending on OS. This is the TriSpector GenTL Producer
▸ Demo – Here is the sourcecode demo_threads.cpp that is used in the example to capture images and show using openCV. There is another demo
showing how to connect to two cameras, demo_two_cams.cpp
▸ Doc – Contains documentation, mostly auto-generated from the code
▸ Include – Here are all the .h and .lib files needed to run the example
▸ Lib – Here is the generated TrispectorSAPI.lib that you might want to use direct if building your own project
▸ Vs_props and vs_props_debug – Contains a number of VS 2015 properties that basically include paths, library paths and needed libraries to build a
project. Convenient to import if setting up your own project

 Folder project – Includes the example solution you can run that is described on earlier slides

October 2018 GBC08 BU81 3D Vision | TriSpector Streamer | Confidential 28

MANY THANKS FOR YOUR ATTENTION.