IDS Peak comfortSDK, genericSDK, IPL, and AFL developer manuals are external documents. Please contact us if you need them.
Return code
Basically, you should check the return code of all calls with comfortSDK. In case of an error, an error code is returned. This should be handled carefully in a end application, e.g. by closing open cameras at critical points where the application needs to be terminated and closing the peak library.
comfortC
if(PEAK_ERROR(status)) { /* Error handling ... */ // Close camera (void)peak_Camera_Close(hCam); hCam=NULL; // Exit library (void)peak_Library_Exit(); }
The return code can also provide information about the error occurred. This way, certain error cases can be handled differently.
The most important return codes and their meaning in the context of camera parameterization are listed below. The complete list of return codes is in the comfortSDK Developer Manual.
Return code
Meaning
PEAK_STATUS_SUCCESS
The function call was executed successfully.
PEAK_STATUS_VALUE_ADJUSTED
The entered value could be set, but was automatically adjusted.
PEAK_STATUS_INVALID_PARAMETER
One or more parameters are invalid. The ErrorMessage should be checked to get more information about the error type.
PEAK_STATUS_OUT_OF_RANGE
The value specified is outside of the valid value range of the camera parameter. Check the valid value range _GetRange or _GetList.
PEAK_STATUS_BUFFER_TOO_SMALL
The buffer created is too small for the data read, especially when reading lists or strings.
PEAK_STATUS_ACCESS_DENIED
Access denied. The current system status does not allow to access the function. This can be remedied, for example, by stopping image acquisition.
PEAK_STATUS_NOT_IMPLEMENTED
The function or camera parameter is not implemented.
PEAK_STATUS_INVALID_HANDLE
The specified camera handle is not valid.
PEAK_STATUS_NOT_INITIALIZED
The IDS peak library has not been initialized yet. The peak_Library_Init function must be called.
PEAK_STATUS_WARNING
Non-specific warning. The ErrorMessage should be checked.
PEAK_STATUS_ERROR
Non-specific error. The ErrorMessage should be checked.
Parameter functions
Functions for specific camera parameters (feature) start with peak_<feature>_....
Parametertyp
AccessStatus
Getter
Setter
Value range
double
_GetAccessStatus
_Get
_Set
_GetRange
_GetList
uint32_t / int_64_t
_GetAccessStatus
_Get
_Set
_GetRange
_GetList
bool
_GetAccessStatus
_IsEnabled
_Enable
-
enum
_GetAccessStatus
_Get
_Set
_GetList (optional)
AccessStatus
The AccessStatus of the camera parameter indicates if the parameter is currently readable and/or writable. The AccessStatus is queried with the associated functionpeak_<feature>_GetAccessStatus(hCam).
This AccessStatus can also be used to initialize variables.
PEAK_ACCESS_NOT_SUPPORTED
The parameter is not supported, e.g. because the camera does not support a certain function.
PEAK_ACCESS_NONE
The parameter is not accessible.
PEAK_ACCESS_GFA_LOCK
The camera is currently in GFA mode, thus other parameter functions of the API are not accessible. If the GFA mode is terminated, the AccessStatus changes again.
The macros PEAK_IS_READABLE and PEAK_IS_WRITEABLE simplify the interpretation of the AccessStatus.
Example
peak_access_statusaccessStatus=peak_ExposureTime_GetAccessStatus(hCam); if(PEAK_IS_READABLE(accessStatus)) { // ExposureTime is readable, you can call e.g. the getter function } if(PEAK_IS_WRITEABLE(accessStatus)) { // ExposureTime is writeable, you can call e.g. the setter function }
The AccessStatus of a camera parameter can change when other camera settings are changed. Therefore, it is recommended to query the AccessStatus before writing or reading a node.
For some parameters, additional information must be specified in order to query the AccessStatus, e.g. to query if an option is available or if parameters depend on each other.
Getter functions read the current parameter value and are usually named peak_<feature>_Get. Next to querying the current value, there are also the functions _GetRange and _GetList, which are used to query the valid value range. Depending on the parameter type, different calls are used, see Parameter types and their handling.
Setter functions
Setter functions set a new parameter value and are usually named peak_<feature>_Set. Depending on the parameter type, different calls are used, see Parameter types and their handling.
Parameter types and their handling
Camera parameters have different types. Depending on the type, different functions are available to read, set or query information about the values. The most common types are double, uint32_t, bool, enum, struct and arrays.
Double and integer parameters can provide either a value range or a list to determine valid input values. The related functions are peak_<feature>_GetRange and peak_<feature>_GetList.
Double and integer parameters with a value range
A value range is defined by minimum, maximum and increment. Minimum, maximum and increment are used to ensure valid values when setting camera parameters. The value must be at least as big as the minimum and at most as big as the maximum. Furthermore, the difference between the value and the minimum should be divisible by the increment.
peak_statusstatus=PEAK_STATUS_SUCCESS; doubleexposureTime=0.0; peak_access_statusaccessStatus=peak_ExposureTime_GetAccessStatus(hCam); if(PEAK_IS_READABLE(accessStatus)) { // ExposureTime is readable, call the getter function status=peak_ExposureTime_Get(hCam,&exposureTime); if(PEAK_ERROR(status)){/* Error handling ... */} } if(PEAK_IS_WRITEABLE(accessStatus)) { // ExposureTime is writeable, call the setter function // Be sure that the new value is within the valid range doubledoubleMin=0.0; doubledoubleMax=0.0; doubledoubleInc=0.0; status=peak_ExposureTime_GetRange(hCam,&doubleMin,&doubleMax,&doubleInc); if(PEAK_ERROR(status)){/* Error handling ... */} // double exposureTime exposureTime*=2; // make sure, the new value is still within the valid range if(exposureTime>doubleMax) { exposureTime=doubleMax; } status=peak_ExposureTime_Set(hCam,exposureTime); if(PEAK_ERROR(status)){/* Error handling ... */} } uint32_ttriggerDivider=1; peak_access_statusaccessStatus=peak_Trigger_Divider_GetAccessStatus(hCam); if(PEAK_IS_READABLE(accessStatus)) { // TriggerDivider is readable, call the getter function status=peak_Trigger_Divider_Get(hCam,&triggerDivider); if(PEAK_ERROR(status)){/* Error handling ... */} } if(PEAK_IS_WRITEABLE(accessStatus)) { // TriggerDivider is writeable, call the setter function // Be sure that the new value is within the valid range uint32_tintMin=0; uint32_tintMax=0; uint32_tintInc=0; status=peak_Trigger_Divider_GetRange(hCam,&intMin,&intMax,&intInc); if(PEAK_ERROR(status)){/* Error handling ... */} // increment TriggerDivider triggerDivider+=intInc; // make sure, the new value is still within the valid range if(triggerDivider>intMax) { triggerDivider=intMax; } status=peak_Trigger_Divider_Set(hCam,triggerDivider); if(PEAK_ERROR(status)){/* Error handling ... */} }
peak_statusstatus=PEAK_STATUS_SUCCESS; uint32_tbinningFactorX=1; uint32_tbinningFactorY=1; peak_access_statusaccessStatus=peak_Binning_GetAccessStatus(hCam); if(PEAK_IS_READABLE(accessStatus)) { // Binning is readable, call the getter function // The binning feature has two integer values for x and y direction status=peak_Binning_Get(hCam,&binningFactorX,&binningFactorY); if(PEAK_ERROR(status)){/* Error handling ... */} } if(PEAK_IS_WRITEABLE(accessStatus)) { // Binning is writeable, call the setter function // Be sure that the new value is within the list of valid values uint32_t*intList=NULL; size_tcount=0; // first query the count of elements in the list status=peak_Binning_FactorX_GetList(hCam,NULL,&count); if(PEAK_ERROR(status)){/* Error handling ... */} // allocate the array large enough for all elements intList=(uint32_t*)calloc(count,sizeof(uint32_t)); // fill the list status=peak_Binning_FactorX_GetList(hCam,intList,&count); if(PEAK_ERROR(status)){/* Error handling ... */} // set the x-factor to the largest possible value in the list binningFactorX=intList[count-1]; // free the list, if not needed any longer free(intList); status=peak_Binning_Set(hCam,binningFactorX,binningFactorY); if(PEAK_ERROR(status)){/* Error handling ... */} }
Bool parameters
Setter functions for Boolean parameters are called peak_<feature>_Enable, Getter functions have the current Boolean value directly as return value peak_<feature>_IsEnabled().
peak_statusstatus=PEAK_STATUS_SUCCESS; peak_boolenable=PEAK_FALSE; peak_access_statusaccessStatus=peak_Mirror_LeftRight_GetAccessStatus(hCam); if(PEAK_IS_READABLE(accessStatus)) { // Mirror left/right is readable, call the getter function enable=peak_Mirror_LeftRight_IsEnabled(hCam); if(PEAK_ERROR(status)){/* Error handling ... */} } if(PEAK_IS_WRITEABLE(accessStatus)) { // Mirror left/right, call the setter function // Invert the current mirror state if(enable==PEAK_TRUE) { enable=PEAK_FALSE; } else { enable=PEAK_TRUE; } status=peak_Mirror_LeftRight_Enable(hCam,enable); if(PEAK_ERROR(status)){/* Error handling ... */} }
Enum parameters
Enum parameters allow to select an option from a list of options. Some enum parameters have a function to query the currently possible options, especially if the availability changes due to other camera settings. These include, for example, PixelFormat and Trigger Edge.
peak_statusstatus=PEAK_STATUS_SUCCESS; peak_pixel_formatnewFormat=PEAK_PIXEL_FORMAT_INVALID; peak_access_statusaccessStatus=peak_PixelFormat_GetAccessStatus(hCam); if(PEAK_IS_READABLE(accessStatus)) { // PixelFormat is readable, call the get list function peak_pixel_format*formatList=NULL; size_tcount=0; // first query the count of elements in the list peak_statusstatus=peak_PixelFormat_GetList(hCam,NULL,&count); if(PEAK_ERROR(status)){/* Error handling ... */} // allocate the array large enough for all elements formatList=(peak_pixel_format*)calloc(count,sizeof(peak_pixel_format)); // fill the list status=peak_PixelFormat_GetList(hCam,formatList,&count); if(PEAK_ERROR(status)){/* Error handling ... */} // select the first value in the list as new PixelFormat newFormat=formatList[0]; // free the list, if not needed any longer free(formatList); if(PEAK_IS_WRITEABLE(accessStatus)) { // Set the selected PixelFormat status=peak_IPL_PixelFormat_Set(hCam,newFormat); if(PEAK_ERROR(status)){/* Error handling ... */} } }
If the parameter does not have a _GetList function, usually all values of the enum are allowed.
peak_statusstatus=PEAK_STATUS_SUCCESS; peak_auto_feature_modenewAutoMode=PEAK_AUTO_FEATURE_MODE_OFF; peak_access_statusaccessStatus=peak_AutoBrightness_Exposure_GetAccessStatus(hCam); if(PEAK_IS_WRITEABLE(accessStatus)) { // Auto exposure is writeable, set the new mode status=peak_AutoBrightness_Exposure_SetMode(hCam,newAutoMode); if(PEAK_ERROR(status)){/* Error handling ... */} }
Composite parameters
Some camera parameters are composed of several values. Examples are all ROI parameters, the trigger mode and the ColorCorrectionMatrix. The PixelFormat is also composed of several values, but they are mapped into an enum for better usability. The gain has a special role. Although it is a double, it depends on two enum parameters.
Parameters with ROI
The ROI is a struct and is composed of Offset and Size, which in turn contain a parameter for horizontal (X) and vertical (Y) direction. After defining a ROI, the individual elements can be accessed directly. The _GetRange function is divided into two functions, one for Offset and one for Size.
The trigger mode consists of trigger target and IO channel. There are predefined trigger modes, e.g. for hardware triggers on the trigger input pin or for software trigger The availability of a selected trigger mode is queried via _GetAccessStatus. If a trigger mode has been set, it must be enabled with peak_Trigger_Enable. If the trigger mode is deactivated, the camera switches to freerun.
Trigger mode
// Use predefined trigger modes peak_trigger_modetriggerModeHardware=PEAK_TRIGGER_MODE_HARDWARE_TRIGGER; peak_trigger_modetriggerModeSoftware=PEAK_TRIGGER_MODE_SOFTWARE_TRIGGER; // Create a trigger mode manually peak_trigger_modetriggerModeGPIO1={PEAK_TRIGGER_TARGET_FRAME_START,PEAK_IO_CHANNEL_GPIO_1}; peak_trigger_modetriggerModeLevelControlled={PEAK_TRIGGER_TARGET_LEVEL_CONTROLLED_EXPOSURE,PEAK_IO_CHANNEL_GPIO_1}; // Change an existing trigger mode triggerModeLevelControlled.ioChannel=PEAK_IO_CHANNEL_GPIO_2; peak_statusstatus=PEAK_STATUS_SUCCESS; // Check if the trigger mode is supported peak_trigger_modenewTriggerMode=triggerModeLevelControlled; peak_access_statusaccessStatus=peak_Trigger_Mode_GetAccessStatus(hCam,newTriggerMode); if(PEAK_IS_WRITEABLE(accessStatus)) { // Selected trigger mode is supported and writeable, call the setter function status=peak_Trigger_Mode_Set(hCam,newTriggerMode); if(PEAK_ERROR(status)){/* Error handling ... */} // additional trigger configurations, e.g. edge, divider, delay, ... // Enable trigger configuration status=peak_Trigger_Enable(hCam,PEAK_TRUE); if(PEAK_ERROR(status)){/* Error handling ... */} } elseif(PEAK_IS_READABLE(accessStatus)) { // Trigger mode supported but not writeable, e.g. because acquisition is running... } elseif(accessStatus==PEAK_ACCESS_NOT_SUPPORTED) { // Trigger mode not supported... } else { // Something went wrong when calling the function... }
ColorCorrectionMatrix
The ColorCorrectionMatrix is defined as a 3x3 matrix. Among other things, a predefined identity matrix is available for initialization.
If a user-defined ColorCorrectionMatrix is to be used, the ColorCorrection Mode must be set to _User_1.
PixelFormat information
The PixelFormat is composed of several values, but for ease of use they are mapped into an enum. Therefore, the well-known enum Getter and Setter functions are used. However, it is possible to query the details of each PixelFormat as a struct using the _GetInfo function. See Image color formats (PixelFormat).
Example
peak_pixel_format_infoinfo; peak_statusstatus=peak_PixelFormat_GetInfo(PEAK_PIXEL_FORMAT_RGBA10,&info); if(PEAK_SUCCESS(status)) { // calling the GetInfo function was successful, print info printf("PEAK_PIXEL_FORMAT_RGBA10 Info\n"); printf("Bits per pixel: %lli\n",info.numBitsPerPixel); printf("Significant bits per pixel: %lli\n",info.numSignificantBitsPerPixel); printf("Number of channels: %lli\n",info.numChannels); printf("Bits per channel: %lli\n",info.numBitsPerChannel); printf("Significant bits per channel: %lli\n",info.numSignificantBitsPerChannel); printf("Maximum value per channel: %lli\n",info.maxValuePerChannel); }
Output:
PEAK_PIXEL_FORMAT_RGBA10 Info Bits per pixel: 64 Significant bits per pixel: 40 Number of channels: 4 Bits per channel: 16 Significant bits per channel: 10 Maximum value per channel: 1023
Gain
Gain is also a composite parameter, since the double value always refers to a specific gain channel and gain type.
Possible gain types:
PEAK_GAIN_TYPE_ANALOG
Analog gain of the camera
PEAK_GAIN_TYPE_DIGITAL
Digital gain of the camera
PEAK_GAIN_TYPE_COMBINED
Combined gain, e.g. to enable finer gradations.
Possible gain channels:
PEAK_GAIN_CHANNEL_MASTER
Master Gain, corresponds to the camera parameters "AnalogAll" and "DigitalAll" or All Affects all three color channels equally in color cameras.
PEAK_GAIN_CHANNEL_RED
Red gain for color cameras.
PEAK_GAIN_CHANNEL_GREEN
Green gain for color cameras.
PEAK_GAIN_CHANNEL_BLUE
Blue gain for color cameras.
You can use the peak_Gain_GetChannelList function to query which gain channels are available for a selected gain type. The following example lists all available type-channel combinations of a camera:
Example
peak_statusstatus=PEAK_STATUS_SUCCESS; // Step through the gain types for(size_tj=0;j<3;j++) { peak_gain_typegainType=PEAK_GAIN_TYPE_INVALID; switch(j) { case0: gainType=PEAK_GAIN_TYPE_ANALOG; printf("Analog gains (PEAK_GAIN_TYPE_ANALOG): \n"); break; case1: gainType=PEAK_GAIN_TYPE_DIGITAL; printf("Digital gains (PEAK_GAIN_TYPE_DIGITAL): \n"); break; case2: gainType=PEAK_GAIN_TYPE_COMBINED; printf("Combined gains (PEAK_GAIN_TYPE_COMBINED): \n"); break; default: break; } peak_gain_channel*gainChannelList=NULL; size_tcount=0; // first query the count of elements in the list status=peak_Gain_GetChannelList(hCam,gainType,NULL,&count); if(PEAK_ERROR(status)){/* Error handling ... */} // allocate the array large enough for all elements gainChannelList=(peak_gain_channel*)calloc(count,sizeof(peak_gain_channel)); // fill the list status=peak_Gain_GetChannelList(hCam,gainType,gainChannelList,&count); if(PEAK_ERROR(status)){/* Error handling ... */} // print all gain channels for the current gain type for(size_ti=0;i<count;++i) { switch(gainChannelList[i]) { casePEAK_GAIN_CHANNEL_MASTER: printf("\tPEAK_GAIN_CHANNEL_MASTER\n"); break; casePEAK_GAIN_CHANNEL_RED: printf("\tPEAK_GAIN_CHANNEL_RED\n"); break; casePEAK_GAIN_CHANNEL_GREEN: printf("\tPEAK_GAIN_CHANNEL_GREEN\n"); break; casePEAK_GAIN_CHANNEL_BLUE: printf("\tPEAK_GAIN_CHANNEL_BLUE\n"); break; } } }
For calling functions via their generic FeatureName, functions of the GFA module are available. This makes it possible to access camera parameters similar to the generic APIs, even though there is no explicit comfortSDK function for this yet. To use the GFA functions, see sample "configure_camera_gfa" and the comfortSDK Developer Manual. Contact us if you need this manual.
