2 product name
About this Document
This document provides specific information on how to operate your microEnable 5 CLHS frame
grabber with the Software Development Kit.
For basic functions that can be used for all frame grabber families please refer to our global SDK
Manual.
The purpose of the CLHS Extension mainly refers to the detection and control of cameras supplied
having a CLHS interface. Therefore Silicon Software provides a specific API, that has to be used in
combination with the standard frame grabber library. The control of the camera is primarily based
on the GenICam interface, which CLHS cameras provide. Furthermore a direct access to camera
registers is available as well.
The following aspects are covered within this document:
Automatic detection of cameras connected to the frame grabber
Manual setup of cameras connected to the frame grabber
Parametrizing and controlling of cameras by using the GenICam interface
1. General Usage
1.1. Classes and Hierachy
The major concept of this library tries to follow the users point of view and represents a
hierarchical structure, which can be understood easily: A frame grabber (board) - represented by a
board handle - supports up to 2 cameras - each represented by an according camera handle. Each
camera administrates a number of camera links, dependent on the topology of the system (type of
connected cameras, link aggregation).
1 board (board handle) : n cameras (camera handle)
1 camera (camera handle) : n links (camera properties)
3 product name
These objects are created by according functions within the library and have to be used for further
access at each level.
Cameras may have more than 2 links. If a camera has more than 2 links and is configured to use
these links there need to be another framegrabber in the PC, configured to take these links.
1.2. API
The library works in combination with the standard Silicon Software SDK (FgLibX) SDK Manual.
The scheme of using could look like this:
1. Create a frame grabber handle (FGLib-SDK) by addressing the framegrabber and the applet 2. Create an board handle (SiSo-Genicam-SDK) 3. Create the camera handle(s), either by automatic detection or by predefining the used
cameras (SiSo-Genicam-SDK) and connect to cameras. 4. Activate GenICam connection 5. Parametrize the camera (image dimensions, camera triggering, etc.) (SiSo-Genicam-SDK) 6. Parametrize the applet according to application needs (FGLib-SDK) 7. Start Acquisition at the applet (FGLib-SDK) 8. Start Acquisition at the camera (SiSo-Genicam-SDK) 9. Grab images (FGLib-SDK) 10. Release resources (SiSo-Genicam-SDK) 11. Release resources (FGLib-SDK)
4 product name
2. Initialization
2.1. Creating a Board Handle
As mentioned above, the library requires an access to the frame grabber. Therefore a board
handle obtained by a previous call of Fg_Init( <AppletName>, <BoardIndex>) is required. For
further details please refer to the SDK documentation. First step for using the SiSo-genicam library
itself is creating a SiSo-Genicam board handle by using the function
Sgc_InitBoard().
This function creates resources for a board object, controlling various cameras. A Fg-Lib board is
needed to gernerate a SiSo-Genicam board handle. This board handle can be used for further
access to cameras.
Note, these two board handles(FG handle and Sgc handle) are not the same.
3. Creating Ccamera Connections
Before a camera can be controlled, a connection to the according camera needs to be established.
The SiSo-Genicam SDK offers different ways to get access to a CLHS camera. The system topology
(how many cameras, how many links at each camera, which link is connected to which frame
grabber port) can be either detected automatically or need to be known if a certain topology is
desired.
There are three ways of getting a camera handle:
a) Automatic detection (camera discovery according to the CLHS specification -> the maximum
possible way of connecting to the connected camera will be used)
b) Predefine the camera connection (either manually or by using stored connection)
c) Load previously saved camera configurations
After one of these steps has been done, camera and link information can be queried.
5 product name
This basic camera handling can be done using the following methods:
Sgc_scanPorts() : Automatic camera detection (discovery)
Sgc_getCamera() : Create or retrieve a camera handle when you know the frame grabber port
Sgc_getCameraPropertyWithType() : Retrieve camera information
Sgc_setCameraPropertyWithType() : Set camera and link configuration
Sgc_LinkConnect () : Establish a camera connection based on camera configuration
Sgc_getCameraCount() : Retrieve the number of present cameras
Sgc_getCameraByIndex() : Retrieve an existing camera handle in the order they were discovered
3.1. Discovery
The camera detection is based on the definition of the CLHS standard and detects the connected
cameras or camera links. Therefore all frame grabber ports are scanned for connected cameras.
The function that performs the discovery is named:
Sgc_scanPorts()
The Camera connection Information can be saved to an configuration file for later reconnects.
If Sgc_scanPorts() is used camera handles are created automatically inside the library and can be
retrieved by Sgc_getCameraCount(), Sgc_getCameraByIndex(),
Sgc_getCameraPropertyWithType(). These Handles allow direct communication with the camera.
After a system topology is detected or defined the camera needs to be connected to be used. This
is done by Sgc_LinkConnect().
Please note that cameras might run in a certain default configuration with a reduced set of active
camera links (please refer to the respective camera documentation). Automatic discovery will set
the camera to the maximum possible connected configuration. If you use a manual configuration
you may need to change the configuration.
Example in pseudo-code:
// Discovery
Sgc_scanPorts();
6 product name
// Display camera information
CameraCount = Sgc_getCameraCount();
for (i = 0 to CameraCount-1){
CameraHandle = Sgc_getCameraByIndex(i);
}
ShowCameraInfo(CameraHandle);
The procedure of discovery assigns the camera links to the image processing according to a fixed
scheme. For more details please refer to section 3.4 "Assigning links for image processing".
3.2. Manual Link Configuration
As an alternative, the SiSo-Genicam SDK offers the possibility to configure the camera connection
manually.
Camera and link properties are applied by the application in order to establish a connection based
on a user defined configuration. This option need to be done if the system needs a special
configuration that would not be detected automatically.
This approach might cause errors, if the link configuration does not match the physical connection.
Functions needed for manual link configuration are:
Sgc_getCamera()
Sgc_setCameraPropertyWithType()
Sgc_LinkConnect()
Example in pseudo-code for a 2 Link camera connection on 1 Framegrabber:
// create a handle for the grabber port A
Sgc_getCamera(BoardHandle, Port, & CameraHandle);
//apply a configuration manually
unsigned int nrOfLinks = 2;
7 product name
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_NROFLINKS_S, &nrOfLinks,
SGC_PROPERTY_TYPE_UINT, 0);
unsigned int masterId = 1;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_MASTERID_S, &masterId,
SGC_PROPERTY_TYPE_UINT, 0);
unsigned int linkSpeed = LINK_SPEED_10000;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_LINKSPEED_S, &linkSpeed,
SGC_PROPERTY_TYPE_UINT, 0);
unsigned int streamPacketSize = 8192;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_STREAMPACKETSIZE_S,
&streamPacketSize, SGC_PROPERTY_TYPE_UINT, 0);
// Setup link 0
unsigned int fgPort = 0;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_FGPORT_S, &fgPort,
SGC_PROPERTY_TYPE_UINT, &linkId);
// Optionally, set the applet port if you know the applet topology
unsigned int vaPort = 0;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_APPLETPORT_S, &vaPort,
SGC_PROPERTY_TYPE_UINT, &linkId);
// Link 1
fgPort = 1;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_FGPORT_S, &fgPort,
SGC_PROPERTY_TYPE_UINT, &linkId);
// This is again optional
vaPort = 1;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_APPLETPORT_S, &vaPort,
SGC_PROPERTY_TYPE_UINT, &linkId);
8 product name
// try to connect based on the configuration
Sgc_LinkConnect();
// Display camera information
CameraCount = Sgc_getCameraCount();
for (i = 0 to CameraCount-1)
CameraHandle = Sgc_getCameraByIndex(i);
ShowCameraInfo(CameraHandle);
In addition the camera links need to be connected to defined applet ports for performing the
image processing. For more details please refer to section "3.4 Assigning links for image
processing"
3.3. Using a Frame Grabber Configuration File
Connections can be created by using predefined configuration files. Such files contain information
on connected cameras, enabled camera links per camera, speed rate of the CLHS link (at the
moment only one speed rate is available) , connected frame grabber link ports and other
additional information. The file format is based on XML to simplify parsing the file by an user
application.
Needed functions:
Sgc_LoadLinkConfiguration()
Sgc_SaveLinkConfiguration()
This functions simplify the manual discovery. After a successful automatic/manual discovery a
configuration file can be created. For the next time you may use the configuration file instead of
configuring the camera manually each time.
Example in pseudo-code:
// Connection based on frame grabber configuration file,
// in case of an error do a rescan and save a new configuration file
9 product name
bool error = Sgc_LoadLinkConfiguration();
if (error)
// Rescan and save new configuration
Sgc_scanPorts();
Sgc_SaveLinkConfiguration();
// Further camera interaction
// Display camera information
CameraCount = Sgc_getCameraCount();
for (i = 0 to CameraCount-1)
CameraHandle = Sgc_getCameraByIndex(i);
ShowCameraInfo(CameraHandle);
3.4. Assigning Links to Image Processing
The CLHS standard covers definitions for link aggregation (LAG). In order to support link
aggregation, it is necessary to define the relationship between the used links of the frame grabber
and the interface to the image processing chain of a certain the applet. In case of automatic
detection (discovery), this is done automatically according to some rules. The application does not
need to take care of this.
The discovery procedure assigns the links to the applet following the order of Links within the
camera. Applet Input 0 is connected with Camera Port 0 Applet Input 1 to Camera Port 1. The
actual ports are determined by the PortId register in the camera. If Ports are swapped the
firmware will automatically swap them to map to the correct ordering.
For a manual configuration, this assignment has to be done by calls to the
Sgc_SetCameraProperty() function by using the properties like CAM_PROP_APPLETPORT_S for
the applet port or CAM_PROP_FGPORT_S for the frame grabber port. It is strongly recommended
to comply with the schema for discovery.
Example: using a camera having a LAG x2 interface:
Precondition:
10 product name
- 2 camera links are connected to the frame grabber
- The master link is connected to the frame grabber port A
- 1st. extension link is connected to frame grabber port B
Applet is processing in LAG mode using 2 links:
Property definition for this topology:
//apply a configuration manually
unsigned int nrOfLinks = 2;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_NROFLINKS_S, &nrOfLinks,
SGC_PROPERTY_TYPE_UINT, 0);
unsigned int masterId = 1;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_MASTERID_S, &masterId,
SGC_PROPERTY_TYPE_UINT, 0);
unsigned int linkSpeed = LINK_SPEED_10000;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_LINKSPEED_S, &linkSpeed,
SGC_PROPERTY_TYPE_UINT, 0);
unsigned int streamPacketSize = 8192;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_STREAMPACKETSIZE_S,
&streamPacketSize, SGC_PROPERTY_TYPE_UINT, 0);
// Setup link 0
unsigned int fgPort = 0;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_FGPORT_S, &fgPort,
SGC_PROPERTY_TYPE_UINT, &linkId);
// Optionally, set the applet port if you know the applet topology
unsigned int vaPort = 0;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_APPLETPORT_S, &vaPort,
SGC_PROPERTY_TYPE_UINT, &linkId);
11 product name
// Link 1
fgPort = 1;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_FGPORT_S, &fgPort,
SGC_PROPERTY_TYPE_UINT, &linkId);
// This is again optional
vaPort = 1;
Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_APPLETPORT_S, &vaPort,
SGC_PROPERTY_TYPE_UINT, &linkId);
3.5. Query Information on the Camera
Retrieving information on the camera, is independently whether the camera connection is done
automatically or manually and can be done by using the following functions:
Sgc_getCameraCount() : retrieve the number of present cameras
Sgc_getCameraByIndex() : retrieve an existing camera handle
Sgc_getCameraPropertyWithType() : retrieve a certain information from a camera handle or link
Example:
// Display camera information
CameraCount = Sgc_getCameraCount();
for (i = 0 to CameraCount-1)
CameraHandle = Sgc_getCameraByIndex(i);
int result = 0;
Sgc_setCameraPropertyWithType(cameraHandle, CAM_PROP_XXX_S, &result);
Sgc_setCameraPropertyWithType(cameraHandle, CAM_PROP_YYY_S, &result);
The available camera properties are defined at the CAM_PROP_XXX constants at the file
SISO_GENICAM.H .
12 product name
4. Camera Access and Control
This chapter describes the concepts of camera control and camera parametrization by using the
SISO_GENICAM library. Be aware, that this control goes hand in hand with the basic
parametrization of the image processing functions of the applets. For details please refer to the
Silicon Software frame grabber SDK manual. In the following we will only focus on the
SISO_GENICAM library.
The camera access is done by reading or writing camera registers, which have to be known and
can be obtained from the camera manufacturer or the camera XML.
The camera parametrization and camera control is possible by using two different concepts:
a) access by using the GenICam interface definition
b) access by reading or writing the camera registers directly (Registers have to be known)
Both ways do not exclude each other and might be used in combination. Using the GenICam
interface is more convenient and should be preferred. The SISO_GENICAM library offers a support
to use the XML description provided by GenICam. It provides methods for reading and writing
control data to the camera in different data types (integers, enumerations, strings, etc.), which are
defined within the GenICam standard.
Function overview:
Sgc_setIntegerValue() : write an integer value for a certain camera feature
Sgc_getIntegerValue() : read an integer value for a certain camera feature
Sgc_setEnumerationValue() : write an enumeration value for a certain camera feature
Sgc_getEnumerationValue() : read an enumeration value for a certain camera feature
Sgc_setStringValue() : write an enumeration value for a certain camera feature
Sgc_getStringValue() : read an enumeration value for a certain camera feature
Sgc_setBooleanValue() : write a boolean value for a certain camera feature
Sgc_getBooleanValue() : read a boolean value for a certain camera feature
Sgc_setFloatValue() : write a floating point value for a certain camera feature
Sgc_getFloatValue() : read a floating point for a certain camera feature
Sgc_executeCommand() : Executes a command defined by camera's GenICam
13 product name
For details please refer to the SISO_GENICAM function reference documentation
Before any access can be performed, a connection to the camera based on a valid camera
GenICam XML has to be established in addition to the underlying CLHS connection (as described
above). It is possible, either
- to use a GenICam XML file stored on the camera, or
- to use a GenICam XML file present on the hard disk.
Relevant functions are:
Sgc_connectCamera() : reads the GenICam information from the camera
Sgc_connectCameraWithExternalXml() : reads the GenICam information from the hard disk
Sgc_getGenICamXML() : allows to get a copy of the currently used GenICam XML
Sgc_setGenICamXML() : allows to set the currently GenICam XML
Alternatively to GenICam communication, direct camera register access is possible.
Function overview:
Sgc_DirectRegisterRead() : read a camera register value from a camera connected to a certain
grabber port
Sgc_DirectRegisterWrite() : write a camera register value to a camera connected to a certain
grabber port
The addresses and allowed values for each register is camera specific and needs to be known.
5. Image Acquisition
To start and stop the camera's image acquisition, the following functions are provided:
Sgc_startAcquisition() : starting the acquisition based on the GenICAm command ""
Sgc_stopAcquisition() : stopping the acquisition based on the GenICAm command ""
14 product name
This functions have to be used in combination with functions of the standard frame grabber SDK.
These functions control the camera without affecting the Framegrabber. The related function for
the framegrabber are:
Fg_StartAcquire(): start image processing and the data transfer.
Fg_StopAcquire(): stop image processing and the data transfer.
The recommended sequence is
1. Start Acquisition (Fg_StartAcquire())
This starts the processing at the applet and data transfer to PC memory
2. Start Acquisition at the camera (Sgc_startAcquisition())
This starts the image acquisition at the camera and the transfer of images from the camera to the
frame grabber.
3. grab images ....
4. Stop Acquisition at the camera (Sgc_stopAcquisition())
This stops the image acquisition at the camera and the transfer of frames from the camera to the
frame grabber.
5. Stop Acquisition (Fg_StopAcquire())
This stops image processing at the frame grabber and data transfer to the PC memory
This sequences ensures, that no image is lost or corrupted (within the limitations of the used
applet). To ensure, that a timeout occurs between step 1) and 2) doesn't occur, enlarge the
timeout accordingly by using the FG_TIMEOUT parameter of the applet. This is especially of
interest, when an external triggering of the camera is used.
6. Releasing Resources
All resources need to be released at the end of the program. Additionally to the Fg_FreeGrabber()
Sgc_freeBoard() needs to be called.
This function releases all resources, which are currently administered from a board handle.
15 product name
7. Error Handling
In general, all functions return their status to the caller by giving a return value (integer value). A
return value of 0 indicates success. If the return value is < 0 , an error occurred. This error code can
be translated to a text message by using:
Sgc_getErrorDescription()
The result is a NULL-terminated string.
8. Event Notification
To allow event notification from frame grabber to an application, it is possible to register a
callback handler for event notifications:
Sgc_registerEventCallback()
Currently no events are defined.
9. Appendix
9.1. Compiler and Linker Settings
In order to use the Silicon-Software genicam library the application needs to be linked the
SISO_GENICAM.LIB in the directory <SISO-INSTALL-DIR>\lib.
Function prototypes, structures and definitions are defined in the header file SISO_GENICAM.h
(directory: <SISO-INSTALL-DIR>\include).
The implementation can be found in the file SISO_GENICAM.DLL (directory : <SISO-INSTALL-
DIR>\bin).
16 product name
9.2. Dependencies
Using this library requires the GenAPI-library (Genicam standard). Generally, this package will be
installed by the Silicon-Software Runtime installation. It might be updated, if necessary. Please
refer to the GenICam web site for further details.
17 product name
Contact Details
GmbH
Steubenstrasse 46
D - 68163 Mannheim, Germany
Phone: +49(0)621.789 507 0
Fax: +49(0)621.789 507 10
Email: [email protected]
Web: www.silicon.software
Inc.
1 Tara Boulevard, Suite 200
Nashua, NH 03062, USA
Phone: +1 603 324 7172
Fax: +1 603 324 7101
Email: [email protected]
Web: www.silicon.software
Document Details
Document Version: 1.0, Document Language: en (US), Last Change: August 2016
Disclaimer
While every precaution has been taken in the preparation of this manual, Silicon Software GmbH
assumes no responsibility for errors or omissions. Silicon Software GmbH reserves the right to
change the specification of the product described within this manual and the manual itself at any
time without notice and without obligation of Silicon Software GmbH to notify any person of such
revisions or changes.
Trademarks
All trademarks and registered trademarks are the property of their respective owners.
Copyright Note
© Copyright 2016 Silicon Software GmbH. All rights reserved. This document may not in whole or
in part, be reproduced, transmitted, transcribed, stored in any electronic medium or machine
readable form, or translated into any language or computer language without the prior written
consent of Silicon Software GmbH.