![]() |
PVCAM
3.9.x
Programmable Virtual Camera Access Method library
|
This code sample demonstrates how to configure the camera for Centroids acquisition. Centroids are small regions of interest that are selected by the camera based on results from in-camera image analysis. The approach for decoding the regions from the image buffer is exactly the same as with acquisitions where regions are selected by the user (see Multiple Regions example). However, as the Centroids counts and locations may change with every frame, special precautions may be required on the application side to handle this dynamic behavior.
For general information about Centroids acquisition please refer to Centroids chapter.
The code snippet below initializes PVCAM and opens the first available camera. Please, refer to the actual code sample in the SDK installation directory for more details about the common helper functions used in this documentation.
This code example uses the recommended callbacks acquisition (see Polling versus Callbacks). A part of the code omitted here defines a static callback function and registers the function with PVCAM. This approach is used in other code samples as well. The relevant code part is described in Frame Callback Handler section.
As the Centroids feature is not supported by all camera models, a check for the feature availability is recommended.
If the feature is available, we can now access the PARAM_CENTROIDS_COUNT to retrieve and configure the maximum number of regions the camera can generate. Another parameter, the PARAM_CENTROIDS_RADIUS, can be used to configure the desired size of the regions.
The centroids feature requires frame metadata feature to be enabled, therefore, before starting the Centroids acquisition, the PARAM_METADATA_ENABLED needs to be set to TRUE
.
Prepare the acquisition. The pl_exp_setup_seq function returns the size of the frame buffer required for the acquisition. For Centroids acquisition, the input region defines the bounding rectangle where the camera will search for events. The resulting ROIs will all originate from within this boundary region. For general information about how to set up a sequence acquisition please refer to Acquisition Configuration. Please note that newer cameras also support PARAM_CENTROIDS_BG_COUNT and PARAM_CENTROIDS_THRESHOLD parameters. Depending on the light level and number of frames requested, these parameters may need to be adjusted as well. If these parameters are not adjusted, the camera may not be able to locate any events in the image and may send empty frames with no centroids.
Allocate a buffer of the size reported by the pl_exp_setup_seq function.
Prepare the frame descriptor that will be used to extract the centroids from the image buffer. Since we know how many centroids were requested, we can pre-allocate a single descriptor and reuse it for each frame.
Start the acquisition:
Acquire the desired number of frames in a loop:
Here we need to wait for a frame readout notification signaled by the eofEvent
in the CameraContext which is raised in the callback handler we registered. If the frame does not arrive within 5 seconds, or if the user aborts the acquisition with ctrl+c shortcut, the main while
loop is interrupted and the acquisition is aborted.
Once the frame is acquired, use the pl_md_frame_decode to decode the frame and fill in the frame descriptor with pointers to frame metadata and ROI image data. After the frame is decoded, the descriptor can be used to display information about the ROI coordinates. The descriptor can also be used to create a black-filled displayable image (using the pl_md_frame_recompose) or the descriptor can be processed manually by the application to only display the selected ROIs. Please, see the Multiple Regions and pl_md_frame_recompose for more details.
Here the pl_exp_abort is not strictly required as correctly acquired sequence does not need to be aborted. However, it is kept here for situations where the acquisition is interrupted by the user or when it unexpectedly times out. Please, refer to the Closing Camera and Uninitializing PVCAM section for more details.