Please enable JavaScript to view this site.

IDS peak 2.8.0 / uEye+ firmware 3.33

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 are in the comfortSDK Developer Manual. Please Contact us if you need this 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).

Example

peak_access_status accessStatus = PEAK_ACCESS_INVALID;
 
accessStatus = peak_Binning_GetAccessStatus(hCam);
accessStatus = peak_Decimation_GetAccessStatus(hCam);
accessStatus = peak_ExposureTime_GetAccessStatus(hCam);
accessStatus = peak_FrameRate_GetAccessStatus(hCam);
accessStatus = peak_Gamma_GetAccessStatus(hCam);
accessStatus = peak_Mirror_LeftRight_GetAccessStatus(hCam);
accessStatus = peak_Mirror_UpDown_GetAccessStatus(hCam);
accessStatus = peak_ROI_GetAccessStatus(hCam);
...

The AccessStatus can have the following values:

AccessStatus

Meaning

Readable

Writeable

PEAK_ACCESS_READWRITE

The parameter is readable and writable.

(tick)

(tick)

PEAK_ACCESS_READONLY

The parameter is read-only.

(tick)

(error)

PEAK_ACCESS_WRITEONLY

The parameter is write-only.

(error)

(tick)

PEAK_ACCESS_INVALID

Querying the AccessStatus has failed.

This AccessStatus can also be used to initialize variables.

(error)

(error)

PEAK_ACCESS_NOT_SUPPORTED

The parameter is not supported, e.g. because the camera does not support a certain function.

(error)

(error)

PEAK_ACCESS_NONE

The parameter is not accessible.

(error)

(error)

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.

(error)

(error)

The macros PEAK_IS_READABLE and PEAK_IS_WRITEABLE simplify the interpretation of the AccessStatus.

Example

peak_access_status accessStatus = 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.

Example

peak_access_status accessStatus = PEAK_ACCESS_INVALID;
 
accessStatus = peak_IOChannel_GetAccessStatus(hCam, PEAK_IO_CHANNEL_GPIO_1);
accessStatus = peak_IOChannel_Inverter_GetAccessStatus(hCam, PEAK_IO_CHANNEL_GPIO_1);
accessStatus = peak_Flash_Mode_GetAccessStatus(hCam, PEAK_FLASH_MODE_EXPOSURE_ACTIVE);
accessStatus = peak_Gain_GetAccessStatus(hCam, PEAK_GAIN_TYPE_ANALOG, PEAK_GAIN_CHANNEL_MASTER);
accessStatus = peak_Trigger_Mode_GetAccessStatus(hCam, PEAK_TRIGGER_MODE_HARDWARE_TRIGGER);
...

Getter functions

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.

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().

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.

If the parameter does not have a _GetList function, usually all values of the enum are allowed.

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.

ROI

peak_roi roi = { { 0, 0 }, {256, 256} };
roi.offset.x = 16;
roi.offset.y = 8;
roi.size.width = 1024;
roi.size.height = 800;
 
peak_position offsetMin = {0, 0};
peak_position offsetMax = {0, 0};
peak_position offsetInc = {0, 0};
peak_size sizeMin = {0, 0};
peak_size sizeMax = {0, 0};
peak_size sizeInc = {0, 0};
 
peak_status status = PEAK_STATUS_SUCCESS;
 
status = peak_ROI_Offset_GetRange(hCam, &offsetMin, &offsetMax, &offsetInc);
if (PEAK_ERROR(status)) { /* Error handling ... */ }
 
status = peak_ROI_Size_GetRange(hCam, &sizeMin, &sizeMax, &sizeInc);
if (PEAK_ERROR(status)) { /* Error handling ... */ }

Trigger mode

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_mode triggerModeHardware = PEAK_TRIGGER_MODE_HARDWARE_TRIGGER;
peak_trigger_mode triggerModeSoftware = PEAK_TRIGGER_MODE_SOFTWARE_TRIGGER;
   
// Create a trigger mode manually
peak_trigger_mode triggerModeGPIO1 = { PEAK_TRIGGER_TARGET_FRAME_START, PEAK_IO_CHANNEL_GPIO_1 };
peak_trigger_mode triggerModeLevelControlled = { PEAK_TRIGGER_TARGET_LEVEL_CONTROLLED_EXPOSURE, PEAK_IO_CHANNEL_GPIO_1 };
 
// Change an existing trigger mode
triggerModeLevelControlled.ioChannel = PEAK_IO_CHANNEL_GPIO_2;
 
peak_status status = PEAK_STATUS_SUCCESS;
 
// Check if the trigger mode is supported
peak_trigger_mode newTriggerMode = triggerModeLevelControlled;
peak_access_status accessStatus = 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 ... */ }
}
else if (PEAK_IS_READABLE(accessStatus))
{
  // Trigger mode supported but not writeable, e.g. because acquisition is running...
}
else if (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.

Example

peak_matrix identityMatrix = PEAK_IDENTITY_MATRIX;
peak_matrix newMatrix = { 1.0, 0.0, 0.0,
                        0.0, 1.0, 0.0,
                        0.0, 0.0, 1.0 };

For element-by-element access, either the elementArray or the struct elements are available.

Example: element-by-element access

peak_matrix newMatrix = { 1.0, 0.0, 0.0,
                        0.0, 1.0, 0.0,
                        0.0, 0.0, 1.0 };
newMatrix.elementArray[1][1] = 2;
newMatrix.elements.element_22 = 3;

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_info info;  
peak_status status = 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_status status = PEAK_STATUS_SUCCESS;
 
// Step through the gain types
for (size_t j = 0; j < 3; j++)
{
  peak_gain_type gainType = PEAK_GAIN_TYPE_INVALID;
 
  switch (j)
  {
  case 0:
      gainType = PEAK_GAIN_TYPE_ANALOG;
      printf("Analog gains (PEAK_GAIN_TYPE_ANALOG): \n");
      break;
  case 1:
      gainType = PEAK_GAIN_TYPE_DIGITAL;
      printf("Digital gains (PEAK_GAIN_TYPE_DIGITAL): \n");
      break;
  case 2:
      gainType = PEAK_GAIN_TYPE_COMBINED;
      printf("Combined gains (PEAK_GAIN_TYPE_COMBINED): \n");
      break;
  default:
      break;
  }
 
  peak_gain_channel* gainChannelList = NULL;
  size_t count = 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_t i = 0; i < count; ++i)
  {
      switch (gainChannelList[i])
      {
      case PEAK_GAIN_CHANNEL_MASTER:
          printf("\tPEAK_GAIN_CHANNEL_MASTER\n");
          break;
      case PEAK_GAIN_CHANNEL_RED:
          printf("\tPEAK_GAIN_CHANNEL_RED\n");
          break;
      case PEAK_GAIN_CHANNEL_GREEN:
          printf("\tPEAK_GAIN_CHANNEL_GREEN\n");
          break;
      case PEAK_GAIN_CHANNEL_BLUE:
          printf("\tPEAK_GAIN_CHANNEL_BLUE\n");
          break;
      }
  }
}

For detailed examples of how to read or write gain values, see Setting the color gain (white balance).

Generic Feature Access (GFA)

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 comfortSDK Developer Manual.

© 2024 IDS Imaging Development Systems GmbH