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.

Initialization of the SDK

Before accessing any other functions of the SDK, an initialization needs to be done. Please refer to 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.

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.

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 csiGetFeatureParameter 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.

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

Image 1 overview_acquiring_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.

In general, two different ways of 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. Failing to do so will cause an error as soon as all receive buffers have been filled by the incoming data.

To grab images continuously, the processing part needs to keep up with the speed of the camera. Otherwise, images might be lost.

Examples

The SDK software package comes with a set of programming examples for C++. Currently there are four examples included:

Visual Studio Example Projects

The Visual Studio projects for the two examples are also included in the SDK. These projects could the found the same location as stated above. These example projects could also be built with CMake. The following section explains how to build a project with CMake.

Build examples

To build the examples requires CMake version > v3.14 and a build environment. The steps to build the examples are the same for both Windows and Linux:

1) Open the CMake GUI and select the examples root directory as the source folder of your project. ("Where is the source code") 2) Next, select a directory where to generate the project files, should be somewhere outside the source tree. ("Where to build the binaries")

Image 1 cmake build project

3) Press the “Configure” button. After the first configuration it is required to manually set the path to the CSGenICam CMake configuration files:

Image 1 cmake project configuration

4) Press “Configure” again and “Generate” afterwards. The project is now configured and can be opened and built from the directory selected in “Where to build the binaries”. 5) If the generated project is to be opened in Visual Studio, please follow the step mentioned in previousection, to add the DLL search path for the application.