Embedded Frame Metadata

This feature allows the camera to insert various metadata directly into the frame buffer. The metadata is generated by the camera itself, appended to the buffer and transferred together with the image data inside the same buffer. The metadata includes all the information necessary to reconstruct the frame along with other data-describing information such as precise HW timestamps, exposure time or other related information.

The Frame Metadata feature is enabled by the PARAM_METADATA_ENABLED parameter. This feature is essential for Multiple ROI Acquisition or Centroids. However, for a single ROI acquisition the Metadata can be disabled to instruct the PVCAM to return the raw frame buffer without any additional information.

Once enabled, the pl_exp_setup_seq and pl_exp_setup_cont functions will report slightly larger frame sizes and the caller is required to allocate the frame buffer accordingly.

Please note that after enabling the feature, the frame data will no longer contain raw image data only and cannot be directly displayed without additional processing.

To properly display the metadata-enabled frame, the following sequence of steps should be followed:

1. User retrieves a pointer to the image buffer, preferably via the pl_exp_get_latest_frame function.
2. The pointer is passed to pl_md_frame_decode function that decodes the buffer and fills a frame descriptor helper structure md_frame. This structure should be created in advance via pl_md_create_frame_struct or pl_md_create_frame_struct_cont and released when not needed by pl_md_release_frame_struct.
3. The frame descriptor structure can be used to directly access each ROI data in the frame. In case the frame contains several ROIs, it is up to the user to decide whether to process and display each ROI data separately or use the helper function pl_md_frame_recompose to generate a directly-displayable frame. The target buffer for recomposition can be e.g. filled with zeros for black-filled frame.
4. Optionally, user can extract extended metadata tied to each ROI in metadata for specific camera features (such as particle tracking) via pl_md_read_extended call.

Please, refer to the SDK example applications to obtain more information on how to use this feature.