DOC Skip to main content
Documentation
>
Orbbec Gemini 330 Series Documentation
>
Frame Metadata
Orbbec Gemini 330 Series Documentation

Frame Metadata

Update on 2025-07-25 03:56:55

Frame metadata is a set of parameters (or attributes) that provide a snapshot of the sensor configuration and/or system state present during the frame’s generation. The attributes are recalculated and updated on a per-frame basis. Orbbec SDK supports querying a set of predefined attributes as part of the frame data available to the end-user.

1. API

Orbbec SDK introduces two functions into its public API to query metadata:

C:

/**
 * @brief check if the frame contains the specified metadata
 *
 * @param[in] frame frame object
 * @param[in] type metadata type, refer to @ref ob_frame_metadata_type
 * @param[out] error Log error messages
 */
bool ob_frame_has_metadata(ob_frame *frame, ob_frame_metadata_type type, ob_error **error);

/**
 * @brief Get the metadata value of the frame
 *
 * @param[in] frame frame object
 * @param[in] type  metadata type, refer to @ref ob_frame_metadata_type
 * @param[out] error Log error messages
 * @return int64_t return the metadata value of the frame
 */
int64_t ob_frame_get_metadata_value(ob_frame *frame, ob_frame_metadata_type type, ob_error **error);

C++:

// Member functions of class ob::Frame

/**
* @brief Check if the frame object has metadata of a given type.
*
* @param type The metadata type. refer to @ref OBFrameMetadataType
* @return bool The result.
*/
bool hasMetadata(OBFrameMetadataType type);

/**
* @brief Get the metadata value
*
* @param type The metadata type. refer to @ref OBFrameMetadataType
* @return int64_t The metadata value.
*/
int64_t getMetadataValue(OBFrameMetadataType type);

2. Example

The envisaged mode of querying metadata attribute is check-then-query

const char *metaDataTypes[] = { "TIMESTAMP", "SENSOR_TIMESTAMP","FRAME_NUMBER",
                                "AUTO_EXPOSURE", "EXPOSURE", "GAIN",
                                "AUTO_WHITE_BALANCE", "WHITE_BALANCE", "BRIGHTNESS",
                                "CONTRAST", "SATURATION", "SHARPNESS",
                                "BACKLIGHT_COMPENSATION", "HUE", "GAMMA",
                                "POWER_LINE_FREQUENCY", "LOW_LIGHT_COMPENSATION", "MANUAL_WHITE_BALANCE",
                                "ACTUAL_FRAME_RATE", "FRAME_RATE",  "AE_ROI_LEFT",
                                "AE_ROI_TOP",  "AE_ROI_RIGHT", "AE_ROI_BOTTOM",
                                "EXPOSURE_PRIORITY", "HDR_SEQUENCE_NAME", "HDR_SEQUENCE_SIZE",
                                "HDR_SEQUENCE_INDEX", "LASER_POWER", "LASER_POWER_MODE",
                                "EMITTER_MODE", "GPIO_INPUT_DATA" };
ob::Pipeline pipe;
pipe.start(nullptr);

auto frameSet = pipe.waitForFrames(100);
auto colorFrame = frameSet->ColorFrame();
for(int metaDataType = 0; metaDataType < OB_FRAME_METADATA_TYPE_COUNT; metaDataType++) {
     // Check if it is supported metaDataType for current frame
    if(colorFrame->hasMetadata((OBFrameMetadataType)metaDataType)) {
       // Get the value of the metadata
       auto value = colorFrame->getMetadataValue((OBFrameMetadataType)metaDataType)
       std::cout << metaDataTypes[metaDataType] << ": " << value << std::endl;
    }
    else {
        std::cout << metaDataTypes[metaDataType] << ": " << "unsupported" << std::endl;
    }
}

3. Display Frame Metadata in OrbbecViewer

image.png

4. OS Support

Windows OS – Metadata extraction is supported by Microsoft starting with Windows 10. Check the Windows installation guide for details.

Other OS – We use libuvc/libusb as the default backend, which does not require any operation to enable metadata support.

5. Devices Support

Currently, only the Orbbec Gemini 300 series supports those APIs.

ON THIS PAGE

Add

  • Name：

  • Link Address：

Cancel

Add

  • Name：

  • Link Address：

Cancel
Questions or
Feedback?

Feedback

  • Your feedback matters! Share your thoughts on this page, report errors, or let us know how we can improve to better support your needs. If applicable, please include the specific sentence or section to help us identify and address the issue.

@2025 0rbbec Inc. All Rights Reserved.

Stay Updated

Be the first to learn about our new products and updates.

Back to top