Chromasens GEN I CAM-SDK User manual

Chromasens GEN<i>CAM-SDK | Manual

R03 / 2021-04-15

 
GenICam_SDK.docx 2 
Table of Contents 
 
1General information 3 
1 About Chromasens 3 
1.1 Contact information 3 
1.2 Support 3 
2 Conventions used in this manual 4 
2.1 Styles 4 
2.2 Symbols 5 
2.3 List of abbreviations 5 
2General aspects of the API 7 
3Getting started 8 
1 Initialization of the SDK 8 
2 Connecting to a camera 8 
3 Getting and setting features 9 
4 Acquiring images 10 
5 Examples 11 
5.1 Build examples 11 
4List of SDK-functions 12 
1 Init/Deinit-functions 12 
2 Connecting and closing a device 12 
3 Getting and setting device parameters 15 
4 Functions related to image acquisition 22 
5 File transfer functions 26 
6 Memory transfer functions 27 
7 Helper functions 28 
8 Enumerations 29 
9 Structures 32 
5Installation 36 
1 Windows installation 36 
1.1 Installer Contents 36 
2 Linux installation 36 
2.1 Preparation 36 
2.2 Step by Step Installation Ubuntu 18.04 36 
2.3 Installer Contents 37 

GenICam_SDK.docx 3

1 General information

1.1 About Chromasens

The name of our company, Chromasens, is a combination of 'Chroma' which means color, and

'Sens' which stands for sensor technology.

Chromasens designs, develops, and produces high-quality and user-friendly products:

◼Line scan cameras

◼Camera systems

◼Camera illumination systems

◼Image acquisition systems

◼Image processing solutions

Today, Chromasens GmbH is experiencing steady growth and is continually penetrating new

sales markets around the globe. The company's technologies are used, for example, in products

and for applications such as book and document scanners, sorting systems and inspection

systems for quality assurance monitoring.

Customers from all over the world of a wide range of industrial sectors have placed their trust in

the experience of Chromasens in the field of industrial image processing.

1.1.1Contact information

Chromasens GmbH

Max-Stromeyer-Str. 116

78467 Konstanz

Germany

Phone: +49 (0) 7531 / 876-0

Fax: +49 (0) 7531 / 876-303

Email: info@chromasens.de

HP: www.chromasens.de

1.1.2Support

Chromasens GmbH

Max-Stromeyer-Str. 116

D-78467 Konstanz

Germany

Phone: +49 (0) 7531 / 876-500

Fax: +49 (0) 7531 / 876-303

Email: support@chromasens.de

HP: http://www.chromasens.de/en/support

Visit our website at http://www.chromasens.de which features detailed information on our

company and products.

GenICam_SDK.docx 4

1.2 Conventions used in this manual

1.2.1Styles

Notification

To ease the use of the document and to clearly indicate the type of the used data different colors for the

different elements are used. Three different colors are used when displaying elements in tables:

Enumerations:

For example:

csiEventType

Defines events which can be received from the SDK

Definition

typedef enum csiEventType {

CSI_EVT_NEWIMAGEDATA = 0x00,

CSI_EVT_ERROR = 0x01,

CSI_EVT_MODULE = 0x02,

CSI_EVT_CUSTOM = 0x1000

} csiEventType;

Elements

CSI_EVT_NEWIMAGEDATA: New image data received

CSI_EVT_ERROR: Error occurred in the SDK

CSI_EVT_MODULE: General event notification

CSI_EVT_CUSTOM: A custom event was triggered

Structures:

For example:

Struct-name

csiDiscoveryInfo

Variable type

Element name

Description

uint32_t

numDevices

double

progress

bool

discoveryRunning

Functions:

For example:

csiDiscoverDevices

Searches for the devices currently connected to the system

Syntax

csiErr csiDiscoverDevices( csiDiscoveryInfo* discoveryInfoOut,

uint64_t timeoutMilliseconds,

csiDiscoveryInfoCallbackFunc discCallbackFunc = NULL,

const char* additionalSearchPaths = NULL,

bool overrideSearchPath CSI_DEFAULT_PARAM_FALSE);

Parameters:

In:

timeoutMilliseconds: The amount of time to search on a specific transport layer for a device

discCallBackFunc: pointer to a callback function which gets called when a result was received

AdditionalSearchPaths: as default only the paths given in the system variable “GENICAM_GENTL64_PATH” are being searched for the

used transport layers

overrideSearchPath: If set, only the given path is searched for transport layers to use.

Out:

discoveryInfoOut: The structure will be filled with the available devices

Return value:

Returns csiSuccess or an error defined in the csiErr-Enum.

Comment:

GenICam_SDK.docx 5

1.2.2Symbols

CAUTION

Indicates a potentially hazardous situation or task, which, if not

avoided, may result in minor or moderate injury.

Indicates a potentially hazardous situation or task, which, if not avoided, could

result in damage to the product or the surrounding environment.

Indicates a helpful tip.

More detailed information can be retrieved online.

1.2.3List of abbreviations

Abbreviation

Meaning

Explanation

CCM

Color conversion matrix

The CCM supports the conversion from for

example RGB to sRGB or any user-defined

conversion

Corona II

LED illumination

Chromasens product

DSNU

Dark signal non-

uniformity

Irregularity in the dark image

GenICam

Generic interface for

cameras

Generic programming interface for industrial

cameras administered by the European

Machine Vision Association

www.emva.org

CTI

Common Transport

Interface

A GenTL Producer implementation as

dynamic loadable platform dependent library

GCT

GenICam Control Tool

Graphical user interface using the SDK.

Provides a graphical way to configure devices

using different TLs.

GenICam_SDK.docx 6

GenApi

GenICam Module

GenTL

Generic Transport Layer

GenTL

Consumer

A library or application

using an implementation

of a Transport Layer

Interface

GenTL

Producer

Transport Layer Interface

implementation

LED

Light emitting diode

PRNU

Photo response non-

uniformity

Difference in sensitivity of the individual pixels

ROI

Region of interest

RS485

ANSI standard defining the electrical

characteristics of drivers and receivers for use

in serial communications systems.

SFNC

Standard Feature Naming

Convention

Document of the GenICam standard, which

provides feature names for common camera

features.

VSync

Vertical synchronization

Frame signal for an image (corresponds to

FVAL: frame valid)

GenICam_SDK.docx 7

2 General aspects of the API

The purpose of the Chromasens Gen<I>Cam-SDK is to provide a user friendly and easy way to

handle all Chromasens cameras regardless of the physical interface.

Requirements:

Supported operating systems:

Windows: Windows 10 Version 2

Linux: Ubuntu >= 18.X

Supported compiler:

Visual Studio >= 2015

GCC

GenICam_SDK.docx 8

3 Getting started

This chapter will describe the basic functions/sequences needed to handle the basic

functionality of the camera.

Ready to use-Examples are also shipped with the SDK in order to demonstrate the usage of the

SDK regarding getting/setting features and acquiring images.

3.1 Initialization of the SDK

Before accessing any other functions of the SDK, an initialization needs to be done.

Please refer to 4.1 Init/Deinit-functions for the detailed description of the function csiInit.

After finishing the work with the SDK make sure to call the csiClose function. This makes

sure that all memory is freed again, and all connections/interfaces are properly closed again

3.2 Connecting to a camera

The use of the Chromasens Gen<I>CAM-SDK enables the user to use different transport layers

and interfaces for the available devices.

Depending on the requirements for your application these transport layers can be selected

during the device discovery process.

It is possible to use the standard search paths for the already installed transport layers.

These paths are set in the environmental variable “GENICAM_GENTL64_PATH”or for 32Bit-

applications: “GENICAM_GENTL32_PATH”.

This is the default behavior. To reduce the time needed for the discovery process a specific path

can be given. The search can also be limited to this single path when the

overrideSearchPath is set.

To establish a connection, you will need to call 2 functions:

csiDiscoverDevices and csiOpenDevice. Detailed information regarding the functions

can be found here: 3.2 Connecting to a camera

GenICam_SDK.docx 9

3.3 Getting and setting features

To configure the camera, so called features can be set and read by using the feature names

provided by the device-xml-file.

All features are of a specific type. The following different types exist:

- Boolean

- Integer

- Floating point

- String

- Command

- Register

- Enumeration

For each type, a “Get”- and “Set”-function does exist in the API. For example use

“csiGetFeatureFloat” to get a float parameter.

To retrieve additional information the function “csiGetFeatureParameter” exists. This function

will fill a csiFeatureParameter-structure which provides information about the display name,

minimum and maximum values, etc. This function is especially useful if you do not know the

valid thresholds of a parameter.

Please be careful when treating string features. You must not exceed the maximum length! This

can also be retrieved with the function “csiGetFeatureParameter”. The parameter

“maximumStringLength” of the csiFeatureParameter-structure will indicate the maximum string

length to set in the feature.

If the complete list of the device features needs to be retrieved, it is recommended to use the

function “csiIterateFeatureTree”. An example is shipped with the SDK to demonstrate the

usage of it.

To set the values please use the type-specific set-functions. For example, use

“csiSetFeatureInt” for an integer value.

These functions are described in detail in the chapter “3.3 Getting and setting features”.

 
GenICam_SDK.docx 10 
3.4 Acquiring images 
To get images from the device, it must be opened first by calling the appropriate functions. 
The diagram below provides an overview of the functions which should be called during an 
acquisition process. 
 
Depending on the type of the device it is possible to retrieve multiple data streams in parallel 
from the same device. This capability can be checked by using the 
“csiGetNumberOfDataStreams”-function which is described in the chapter 4.4 Functions related 
to image acquisition. 
 
In general, two different ways in acquiring the images can be used: 
1. Using Events (Events must be registered by the  “csiRegisterEvent”-function prior to the 
usage of the event. 
2. Directly calling the csiGetNextImage-function 
 
Independent of these two ways, the Acquisition from the device must be started first by calling 
csiStartAcquisition. 
If enough images have been processed this needs to be stopped again by calling 
csiStopAcquisition. 
After a received image is processed it must be released back into the receive buffer of the 
acquisition engine by calling csiReleaseImage. 
By failing to do so the user will cause an error as soon as all receive buffers have been filled by 
the incoming data. 
Tograb images continuously the processing part needs to keep up with the speed of the camera. 
Otherwise, images might be lost. 