chromasens GEN I CAM-SDK, Manual

Page 1: ...Chromasens GEN i CAM SDK Manual R03 2021 04 15 ...

Page 2: ...9 3 4 Acquiring images 10 3 5 Examples 11 3 5 1 Build examples 11 4 List of SDK functions 12 4 1 Init Deinit functions 12 4 2 Connecting and closing a device 12 4 3 Getting and setting device parameters 15 4 4 Functions related to image acquisition 22 4 5 File transfer functions 26 4 6 Memory transfer functions 27 4 7 Helper functions 28 4 8 Enumerations 29 4 9 Structures 32 5 Installation 36 5 1 ...

Page 3: ...or 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...

Page 4: ... 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 Paramete...

Page 5: ... 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...

Page 6: ...NU 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 s...

Page 7: ... 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 ...

Page 8: ...ed 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...

Page 9: ...y 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...

Page 10: ...mages 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 receive...

Page 11: ... csgenicam examples feature_iteration 3 5 1Build 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 s...

Page 12: ...vailable transport layers Syntax csiErr csiDiscoverDevices csiDiscoveryInfo discoveryInfoOut uint64_t timeoutMilliseconds csiDiscoveryInfoCallbackFunc discCallbackFunc NULL const char additionalSearchPaths NULL bool overrideSearchPath false Parameters In timeoutMilliseconds The time until when a response from a device needs to be received when doing a discovery discCallbackFunc Pointer to a callba...

Page 13: ...um Comment The SDK uses the environment variable GENICAM_GENTL64_PATH to search for available transport layers This function allows to request the number of transport layers available through that environment variable csiGetTLProducerInfoByIndex Returns additional information about a transport layer Syntax CSI_DLL_EXPORT csiErr csiGetTLProducerInfoByIndex csiTLProducerInfos tlProducerInfos int32_t...

Page 14: ...e acquired CSI_DEV_MODE_CONTROL Camera parameters can be read and written Read access by another process to the device is still possible Out deviceHandleOut Handle to the device This handle needs to be used to any successive call Return value Returns csiSuccess or an error defined in the csiErr Enum Comment Depending on the used transport layer it might be necessary to use a longer timeout Please ...

Page 15: ... an error defined in the csiErr Enum Comment csiSetFeatureBool Set a boolean feature on the device Syntax csiErr csiSetFeatureBool csiHandle device const char parameterName bool value csiModuleLevel module CSI_DEVICE_MODULE Parameters In device Handle provided by the csiOpenDevice function parameterName name Not the display name of the feature to set value Boolean value to set the feature to true ...

Page 16: ...nDevice function parameterName name Not the display name of the feature to get module Module for which the parameter should be get Please use the enum csiModuleLevel to select Determines if the parameter should be retrieved from the device transport layer interface stream or buffer module Out valueOut Pointer to a double value where the current value of the feature will be written to Return value ...

Page 17: ...iHandle device const char parameterName const char value csiModuleLevel module CSI_DEVICE_MODULE Parameters In device Handle provided by the csiOpenDevice function parameterName name Not the display name of the feature to set value pointer to a character array which contains the string to set module Module for which the parameter should be set Please use the enum csiModuleLevel to select Determine...

Page 18: ...rrent value of the feature will be written to length Current length of the retrieved data Return value Returns csiSuccess or an error defined in the csiErr Enum Comment To avoid unexpected behavior it is recommended to retrieve the maximum buffer length before getting it from the device This can be achieved by using the function csiGetFeatureParameter This function will provide all necessary infor...

Page 19: ...e Module for which the feature tree should be iterated Please use the enum csiModuleLevel to select Determines if the feature tree on the device transport layer interface stream or buffer module should be used Out featureNameOut name of the retrieved feature type type of the retrieved feature Return value Returns csiSuccess or an error defined in the csiErr Enum Comment If starting from the very b...

Page 20: ... use the enum csiModuleLevel to select Determines if the parameter should be retrieved from the device transport layer interface stream or buffer module Out featureParamOut Name of the enumeration of the requested index Return value Returns csiSuccess or an error defined in the csiErr Enum Comment The enumeration string will be given in the csiFeatureParameter structure valueStr csiGetFeatureEnumE...

Page 21: ... const char featureName void userObj csiUnRegisterInvalidateCB Unregister an invalidation callback function from a specific feature Syntax csiErr csiUnRegisterInvalidateCB csiHandle device const char featureName csiModuleLevel module CSI_DEVICE_MODULE Parameters In device Handle provided by the csiOpenDevice function featureName Name of the feature to unregister the callback from module Module for...

Page 22: ...ned by csiGetNumberOfDataStreams Out dataStreamInfoOut Information about the selected data stream given by the dsIndex parameter or NULL if the data stream is not found See documentation on csiDataStreamInfo for more information Return value Returns csiSuccess or an error defined in the csiErr Enum Comment csiCreateDataStream Create a data stream to receive images Syntax csiErr csiCreateDataStream...

Page 23: ...was registered Use this handle to wait for events using the csiWaitForEvent or csiGetNextImage functions Return value Returns csiSuccess or an error defined in the csiErr Enum Comment csiWaitForEvent Wait for a desired event to happen Syntax csiErr csiWaitForEvent csiHandle evt uint64_t timeoutMilliseconds csiEventData evtDataOut Parameters In evt the handle of the event to wait for timeoutMillise...

Page 24: ...ll be canceled csiStartAcquisition Start the acquisition on the device and created data streams Syntax csiErr csiStartAcquisition csiHandle device csiAcquisitionMode mode Parameters In device Handle provided by the csiOpenDevice function mode Acquisition mode as defined in csiAcquisitionMode Out None Return value Returns csiSuccess or an error defined in the csiErr Enum Comment This function will ...

Page 25: ...ssing buffer from the device Syntax csiErr csiReleaseImage csiHandle dataStream csiNewBufferEventData bufferInfo Parameters In dataStream the handle to the data stream this buffer belongs to This handle is also part of the csiNewBufferEventData structure bufferInfo Pointer to the buffer event data that was previously received from csiWaitForEvent or csiGetNextImage Out None Return value Returns cs...

Page 26: ...by the csiOpenDevice function filename Full path of the fule to be uploaded filetype Type of the update file as returned from csiGetUpdateFileType timeOutMilliSeconds Timeout for the update procedure in milliseconds Note An update process might take several minutes depending on the type of file please choose a timeout of at least a few minutes here linstener Optional callback function that will be...

Page 27: ...ame time the number of bytes to read from the address Out Return value Returns csiSuccess or an error defined in the csiErr Enum Comment csiWriteMemory Write memory to a register address on the device Syntax csiErr csiWriteMemory csiHandle device uint64_t address const char buffer size_t sizeBytes Parameters In device Handle provided by the csiOpenDevice function address Address of the register on...

Page 28: ... an error defined in the csiErr Enum Comment csiGetErrorDescription Returns a human readable description of an error code Syntax csiErr csiGetErrorDescription csiErr error char bufferOut size_t bufferSize Parameters In error error code to retrieve the text for bufferSize size of the provided text buffer Out bufferOut char buffer where the error text will be written to Return value Returns csiSucce...

Page 29: ...control mode read write other application might still be able to open it in read mode csiDeviceAccessStatus Defines the current access status of a device as returned from device discovery Definition typedef enum csiDeviceAccessStatus CSI_DEV_ACCESS_STATUS_UNKNOWN 0x00 CSI_DEV_ACCESS_STATUS_READWRITE 0x01 CSI_DEV_ACCESS_STATUS_READONLY 0x02 CSI_DEV_ACCESS_STATUS_NOACCESS 0x03 CSI_DEV_ACCESS_STATUS_...

Page 30: ...typedef enum csiModuleLevel CSI_UNKNOWN_MODULE CSI_TRANSPORTLAYER_MODULE CSI_INTERFACE_MODULE CSI_DEVICE_MODULE CSI_LOCAL_DEVICE_MODULE CSI_STREAM_MODULE CSI_BUFFER_MODULE csiModuleLevel Elements CSI_UNKNOWN_MODULE Unknown module level CSI_TRANSPORTLAYER_MODULE Transport layer module System module CSI_INTERFACE_MODULE Interface module CSI_DEVICE_MODULE Device module CSI_LOCAL_DEVICE_MODULE Local d...

Page 31: ...n is not available csiTimeout A timeout occurred csiAborted A pending operation was aborted csiFileOperationFailure There was an error during file operation see log for more information csiFileOperationFatalError There was a fatal error during file operation see log for more information csiNoAccess Access denied e g when trying to write a read only feature csiWrongBufferSize A given buffer was too...

Page 32: ...ion int64_t valueInt Value of the feature in case of integer feature type int64_t incrementInt Possible increment for the feature value in case of integer feature type int64_t minimumInt Minimum for the feature value in case of integer feature type int64_t maximumInt Maximum for the feature value in case of integer feature type double valueFlt Value of the feature in case of floating point feature...

Page 33: ... Progress information text Struct name csiTLProducerInfos Variable type Element name Description char transportLayerName Name of a transport layer char transportLayerDisplayName Display name of a transport layer for GUI representation char transportLayerType Type of the transport layer as string char transportLayerPath Full path to the transport layer library file cti file char transportLayerID Un...

Page 34: ...his is always CSI_EVT_NEWIMAGEDATA for this type of event csiHandle sender Sender of the event a stream handle csiModuleLevel senderType Type of the sender this is always CSI_STREAM_MODULE for this type of event char tl_rawEventData Raw data pointer to the event data as it was sent by the producer This is just the raw data of the event which contains information about the type of event itself and ...

Page 35: ...quisition uint64_t framesAcquired Total number of frames acquired in current acquisition uint64_t networkPacketsOK For GigE Vision The number of network packets received without errors uint64_t networkPacketsError For GigE Vision The number of network packets sent with an error ...

Page 36: ...e CSGenICam cmake GCT The camera configuration and acquisition application with graphical interface Locations installation root bin gct exe SDK Examples Example source code C that shows the basic usage of the SDK Locations C Users Public Documents Chromasens GCT2 examples Documentation Documentation of the SDK Location installation root doc GenTL Producers Optional GenTL producers for Windows syst...

Page 37: ...es to the system environment 5 2 3Installer Contents The software package is grouped into the following components SDK The programming interface and library for customer applications Locations usr lib libcsi so usr include csi csi h usr share CSGenICam cmake GCT The camera configuration and acquisition application with graphical interface Locations usr bin gct SDK Examples Example source code C th...

Page 38: ...GenICam_SDK docx 38 Chromasens GmbH Max Stromeyer Straße 116 Phone 49 7531 876 0 www chromasens de 78467 Konstanz Fax 49 7531 876 303 info chromasens de Germany March 2021 Copyright by Chromasens GmbH ...