 |
IDS peak comfortC
v1.5.1
|
|
IDS peak comfortC
v1.5.1
|
IDS peak comfortC provides access to the complete set of features that is required to operate IDS cameras.
The main objective of IDS peak comfortC is to encapsulate the underlying GenICam standard technology and to free the user from the requirement to have a deeper understanding of the GenICam standard and its abstract paradigms.
Technically IDS peak comfortC encapsulates the IDS peak genericSDK as its Backend.
The library requires the use of C99 for the client application.
Qt of at least version 5.7 and C++14 is required for the GUI samples.
Qt must be installed on the system if you want to compile the sample code by yourself.
For Linux Qt must also be in installed to run the GUI samples.
In order to use IDS peak comfortC you need to include the interface header file ids_peak_comfort_c.h and link your application with the ids_peak_comfort_c library.
In order to run an application the shared libraries must be found by the system.
For Windows copy the deployed shared libraries (dll) into the folder with the applications executable.
For Linux add the path to the deployed shared libraries (so) to LD_LIBRARY_PATH.
This section defines several terms that are used throughout the IDS peak comfortC library.
The term library is used to refer to the IDS peak comfortC library and its implementation.
The term backend is used to refer to the backend of the IDS peak comfortC library which is the IDS peak genericSDK.
IDS peak genericSDK is built by IDS peak API and the IDS peak IPL.
All feature-related functions of IDS peak comfortC together are referred to as the convenience interface of the library.
The Generic Feature Access (GFA) functions do not belong to the convenience interface.
The term application is used to refer to the user application, i.e. to the IDS peak comfortC client program.
The access status of a feature or a camera indicates the current availability of the feature or the camera.
A feature or camera can reside permanently or temporarily in a certain access status. For example:
The current access status of a feature or camera can be queried via specific functions.
The enabled status of a feature indicates whether the feature is currently enabled or disabled.
The enabled status can take the boolean values PEAK_TRUE for enabled and PEAK_FALSE for disabled.
The current enabled status of a feature can be queried via specific functions.
A frame is an entity of bulk data which was acquired from a camera.
It combines the memory Buffer to which the bulk data was received and the meta information on the properties of the data.
Typically, a frame represents an acquired image.
But it can also represent other types of bulk data received from a camera. The type of data that a frame represents depends on the camera settings.
A buffer is an entity in the computer memory which can store a certain amount of data.
A buffer is defined by its memory address and the size of the memory in bytes.
In addition a buffer can store a user defined pointer for context purposes.
A buffer underrun is counted when a frame transmission arrives but there is no image buffer available to store it to.
This is the case when all image buffers are locked for the reception of incoming image data. The library automatically locks an image buffer after it was filled with image data. The buffer is then not available to store newly incoming image data until it has been delivered to the application via peak_Acquisition_WaitForFrame and released via peak_Frame_Release. So, the application is responsible for unlocking the buffer via peak_Frame_Release.
In order to avoid buffer underruns in an application
A dropped frame is counted when the frame id of a received frame jumps forward in respect to the last received frame.
This is the case when the camera is not able to transmit or to buffer an acquired image.
This situation typically arises when the cameras' acquisition rate is higher than the rate of frames that it can transmit via the bus.
In order to avoid dropped frames in an application
An incomplete frame is counted when a frame could not be completely transmitted from the camera to the host.
A frame is usually transmitted in a number of transmission units, so-called packets. If at least one of the packets could not be correctly transmitted for a frame, this frame is referred to as incomplete.
This is a typical issue for Ethernet connections as the underlying UDP transport protocol is not reliable, i.e. there is no guarantee of delivery, ordering, or duplicate protection of the transmitted data packets.
Even if the transport layer implements recovery actions for this issue it may not be able to fully prevent packet loss.
In order to minimize incompletes in an application
This section describes some basic principles and programming paradigms of the library.
The application programmer can rely on the library following these principles' throughput the whole interface.
Wherever possible the library guarantees strong exception safety.
Strong exception safety is also known as commit or rollback semantics.
The point of strong exception safety is that a failed operation has no side effects. This means that the system status after a failed function is the same as it was before the function call.
Please note that may not be possible to achieve this goal for every specific situation.
In principle all functions of the library return a status code of type peak_status.
If a function succeeds it will return PEAK_STATUS_SUCCESS. The macro PEAK_SUCCESS can be used to test a returned status code for indication of success.
If a function fails it will return an error code. The macro PEAK_ERROR can be used to test a returned status code for failure indication.
It is strongly recommended checking the return value of every library function call for an error indication.
In addition, there is a third class of status codes which indicate a warning level status. The macro PEAK_WARNING can be used to test a returned status code for indication of a warning.
An example for a warning level status code is PEAK_STATUS_VALUE_ADJUSTED which indicates that the function was not able to apply the exact desired value to a feature and that the value has been adjusted to for example the nearest valid neighbor.
If a function returns an error code, i.e. PEAK_ERROR returns PEAK_TRUE on the status code, the details on the error can be queried via peak_Library_GetLastError. See also Last Error Handling.
The library stores the last error separately for each application thread.
A descriptive message on the last error that occurred in the current thread context can be queried via peak_Library_GetLastError. This message describes the error and its cause in as much detail as possible.
The last error is not cleared after peak_Library_GetLastError has been called.
It is therefore strongly advised to evaluate the last error only in the immediate context of a failed library function call, i.e. a library function indicating an error by a peak_status error code or by PEAK_ACCESS_INVALID.
A code example on how to query the last error is given in the section Two Staged Data Query.
Several library functions provide data of dynamic size in a memory buffer that is to be provided by the application. As the size of the data depends on the required memory buffer size can not be known a priori.
To access such data the application should implement the following procedure:
The following code demonstrates this procedure by the example of peak_Library_GetLastError.
The following code demonstrates this procedure by the example of peak_CameraList_Get.
cameraCount.The following code demonstrates this procedure by the example of peak_PixelFormat_GetList.
cameraCount. In order to spare the size query Stage you may want to pass a buffer that is large enough to store the maximum expected size of data.
For example, you can shortcut the size query for the camera list query if you provide a buffer that is capable of storing the camera descriptors of all cameras that could possibly be connected.
Another example is the last error query. The library will not provide an error message whose length exceeds 1 kB of characters.
With this assumption the example on peak_Library_GetLastError shortens to the following code.
The library provides specific functions for the translation of a certain camera property into the related camera id.
In general all library functions that are related to a certain camera instance require a camera handle (peak_camera_handle) as a parameter to identify the individual camera which is addressed by the function call.
In order to receive the camera handle that allows to use these functions the camera must have been opened before.
However, there are also library functions which can be used on a closed camera.
These functions take a camera id (peak_camera_id) instead of the camera handle.
In order to find the camera id of the camera with a certain property, for example a certain serial number, one would walk the camera descriptors in the camera list and look for the desired camera.
The library provides a number of functions save the application from this procedure.
These functions have in common that they deviate from the generic rule that every library function returns a status code.
This allows a direct simple approach to address a camera with a certain property in the functions that require a camera id as identifier.
The following code demonstrates this by the example of opening a camera with a certain serial number.
An even simpler approach is demonstrated by this example:
Note that for the latter example it is not possible to query the error details for the actual problem.
Instead the last error query will tell that peak_Camera_Open was called with an invalid camera id.
This is because the last error information that was set by peak_Camera_ID_FromSerialNumber is overwritten with the last error information of the call to peak_Camera_Open which is proceeded after the call to peak_Camera_ID_FromSerialNumber.
The majority of the library functions return a peak_status code.
Besides these functions there is an additional group of functions which return a peak_camera_id.
The decision to have these functions report the camera id as a return value rather than as a function parameter was made for the reason of a simpler and a more compact and efficient usage in the application code.
By this an application can directly address a camera with a certain property value in the library functions that require a camera id as a camera identifier.
However, such a function can easily fail. For example if there is no camera with the specified property value.
If so, the function will return PEAK_INVALID_CAMERA_ID as an unspecific error indication.
The details on the error can then be queried via peak_Library_GetLastError which provides the error information as a peak_status code and a descriptive message on the error.
See the example above.
For a description of the term Access Status see Access Status.
The library provides specific functions for the query of the current access status of a certain feature or a camera.
These functions have in common that they deviate from the generic rule that every library function returns a status code.
This allows a direct simple switching on the access status, as the following example demonstrates:
The majority of the library functions return a peak_status code.
Besides these functions there is an additional group of functions which return a peak_access_status code.
The decision to have these functions report the access status as a return value rather than as a function parameter was made for the reason of a simpler and a more compact and efficient usage in the application code.
By this an application can directly switch on the access status of a functional module or a camera.
Moreover, the functions that implement the Access Status Query principle will rarely fail, as long as the library is initialized.
Nonetheless, in theory such a function can fail. For example if the library is not initialized.
If so, the function will return PEAK_ACCESS_INVALID as an unspecific error indication.
The details on the error can then be queried via peak_Library_GetLastError which provides the error information as a peak_status code and a descriptive message on the error.
See the example above.
In practice the access status will mostly be queried in order to determine whether a feature can be written to or read from.
The library offers the macros PEAK_IS_WRITEABLE and PEAK_IS_READABLE to allow phrasing these query in an even more compact way:
But: Be aware that these macros will return PEAK_FALSE not only if the feature is not writeable/readable. They will return PEAK_FALSE also if the access status query failed. For example because the passed handle is invalid.
So, for to be sure that the access status query did not fail on the macro returning PEAK_FALSE, you would have to further investigate the access status on PEAK_FALSE:
The library provides specific functions for the query of a boolean status.
These functions have in common that they deviate from the generic rule that every library function returns a status code.
This allows a direct simple switching on the boolean status, as the following examples in the following sections demonstrate.
The downside of this approach is that it is not possible for these functions to return an error. See the section On the specific return type and on error indication for boolean status queries on this topic.
For a description of the term Enabled Status see Enabled Status.
The library provides specific functions for the query of the current enabled status of a certain feature.
These functions have in common that they deviate from the generic rule that every library function returns a status code.
This allows a direct simple switching on the enabled status, as the following example demonstrates:
The downside of this approach is that it is not possible for these functions to return an error. See the section On the specific return type and on error indication for boolean status queries on this topic.
For a description of the libraries concept on the query for a features valid values see Feature Valid Values Query.
The library provides specific functions for the query of the organization of the valid values for a certain feature.
These functions have in common that they deviate from the generic rule that every library function returns a status code.
This allows a direct simple switching on the indication whether the features valid values are organized as a range or as a list, as the following example demonstrates:
The downside of this approach is that it is not possible for these functions to return an error. See the section On the specific return type and on error indication for boolean status queries on this topic.
The majority of the library functions return a peak_status code.
Besides these functions there is an additional group of functions which return a peak_bool value.
The decision to have these functions report the boolean status as a return value rather than as a function parameter was made for the reason of a simpler and a more compact and efficient usage in the application code.
By this an application can directly switch on the boolean status of a functional module.
Moreover, the functions that implement the Boolean Status Query principle will rarely fail, as long as the library is initialized.
Nonetheless, in theory such a function can fail. For example if the library is not initialized or if it is passed invalid arguments.
If so, the function will return PEAK_FALSE.
As the boolean type does not offer a value beyond true and false it is not possible to indicate failure of the enabled status query.
A failure of the enabled status query is treated just like the feature being disabled.
It is not treated as an error and the library does not store last error information on this.
This section provides explanations on the basic functioning of IDS peak comfortC.
In order to receive acquired images from the camera and provide the data to the application the library must be provided with memory buffers to which the incoming image data can be stored.
For an efficient data transfer these buffers must be sufficient in size and number.
A buffer is sufficient in size if it can store the complete image data that results from the feature settings.
The number of buffers is sufficient if all acquired images can be captured by the library and provided to the application.
This is enabled if the library at any time has a buffer available to store incoming image data. In other words there must always be at least one buffer that is not locked for processing by the application.
The library provides two options for the preparation of the image buffers.
The Automatic Buffer Preparation mode is recommended as long as the application does not need to predetermine the memory addresses of the buffers.
If the application needs to use buffers at well-defined memory addresses it must use the Manual Buffer Preparation mode.
In this mode the library takes care for the preparation of the buffers.
The automatic buffer preparation mode is active by default. The application can switch to the Manual Buffer Preparation mode by using peak_Acquisition_Buffer_Announce to provide self defined buffers.
The library will allocate a sufficient number of sufficiently sized buffers to store the acquired images.
The preparation of the buffers is done in the context of an acquisition start. The size and the number of the buffers that the library allocates depend on the feature settings that apply at the time peak_Acquisition_Start is called.
The following example demonstrates the way to a first image in automatic buffer preparation mode.
The error handling is left out for the reason of example clarity.
In this mode the application is responsible for the preparation of the buffers.
The application must allocate a sufficient number of sufficiently sized buffers to store the acquired images.
Then the application must announce the allocated buffers to the library. The preparation of the buffers must be done before an acquisition is started.
The library checks for the announced buffers to be sufficient in the context of an acquisition start. If the buffers are not sufficient peak_Acquisition_Start will fail.
The minimum number of buffers that is required by the library can be queried via peak_Acquisition_Buffer_GetRequiredCount. The minimum size of the individual buffers depends on the feature settings and can be queried via peak_Acquisition_Buffer_GetRequiredSize.
In manual buffer preparation mode the application is responsible for the allocated buffer memory. I.e. the application must allocate the memory, and free it when the buffers are not used any longer.
The application must make sure that the memory is valid as long as the buffer is announced to the library.
The following example demonstrates the way to a first image in manual buffer preparation mode.
The error handling is left out for the reason of example clarity.
Most of the library and camera features require a setting to be within a certain set of valid values.
The definition of the set of valid values can be of one of two types:
It depends on the specific feature whether its valid values are organized as a range or as a list.
For those features with a range of valid values the library provides a function which is named according to the following pattern:
peak_<FeatureName>_GetRange()
For those features with a list of valid values the library provides a function which is named according to the following pattern:
peak_<FeatureName>_GetList()
Moreover, for individual features it depends on the specific camera model whether the valid values for a feature are organized as a range or as a list.
For these features the library provides both of the above-mentioned functions and an addition function which indicates which one to use. This function follows this pattern:
peak_<FeatureName>_HasRange()
The following code demonstrates how to query the valid values using the pixel clock feature as an example.
The objective of IDS peak comfortC is to encapsulate the underlying GenICam interface so, that the user does not need to have a deep knowledge of the GenICam standard and its concepts.
This is realized by the libraries Convenience Interface where the functions have a clear naming, typing and behaviour.
Nonetheless, the library provides functions which enable the direct access to the systems feature nodes, i.e. to the nodemap of a GenTL module or to the nodemap of the remote device.
This is realized by the libraries generic feature access (GFA) interface where the functions have a more abstract naming, typing and behaviour.
This generic feature access functions can be used to accomplish tasks which are not (yet) available via the libraries convenience interface.
The GFA functions address single feature nodes of the addressed module and apply parameters on a low-level, atomic basis, whereas the convenience functions typically implement a compound functionality.
For example setting the pixel clock to a certain value via the convenience interface is about calling peak_PixelClock_Set, whereas setting the pixel clock via the GFA interface requires to first set a so-called selector node ("DeviceClockSelector") to a certain value and then writing the desired pixel clock value to the node with the name "DeviceClockFrequency".
Actually, the implementation of the convenience functions internally also operates on the atomic nodes to achieve the desired effect on the configuration.
This raises the problem that an unsynchronized concurrent write access via the GFA interface may interfere with the implementation of a convenience interface function.
In the pixel clock example above an unfortunate thread context switch could lead to a GFA access changing the DeviceClockSelector node just before the convenience implementation was able to write the desired pixel clock value to the DeviceClockFrequency node.
In order to prevent the system from such situations and to synchronize the use of the GFA interface with the procedures of the convenience interface the library provides a specific mode. All write accesses via the GFA interface are possible only in this 'GFA write access mode'.
So, in order to issue a write access via the GFA interface the GFA write access mode must be enabled by the application.
The GFA write access mode takes effect on a per-camera basis.
The following rules apply in respect to the GFA write access mode: