Software Development Kit · 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

Software Development Kit

Version 1.0

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)

http://www.siliconsoftware.de/download/live_docu/RT5/en/documents/SDK/SDK.html

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,


unsigned int linkSpeed = LINK_SPEED_10000;

Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_LINKSPEED_S, &linkSpeed,


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,


// Link 1

fgPort = 1;



// This is again optional

vaPort = 1;



8 product name

// try to connect based on the configuration

Sgc_LinkConnect();



for (i = 0 to CameraCount-1)



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






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,


unsigned int masterId = 1;

Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_MASTERID_S, &masterId,


unsigned int linkSpeed = LINK_SPEED_10000;

Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_LINKSPEED_S, &linkSpeed,


unsigned int streamPacketSize = 8192;

Sgc_setCameraPropertyWithType(CameraHandle, CAM_PROP_STREAMPACKETSIZE_S,

&streamPacketSize, SGC_PROPERTY_TYPE_UINT, 0);

// Setup link 0

unsigned int fgPort = 0;



// Optionally, set the applet port if you know the applet topology

unsigned int vaPort = 0;



11 product name

// Link 1

fgPort = 1;



// This is again optional

vaPort = 1;



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:





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.

Documents

Software Development Kit · 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