Advanced Camera API

The Advanced Camera API provides low level access to a device's system camera APIs, enabling more precise control of camera parameters. This API can be used to support custom computer vision modules that utilize the Vuforia Image API and lets you improve performance on specific devices and/or in specific environments.

The Advanced Camera API is not a general-purpose API. Any use of this API should be thoroughly tested to understand its impact on the performance of Vuforia Engine.

The Advanced Camera API is currently only implemented on Android.

NOTE: The Advanced Camera API is only available for certain license types. See our Pricing page for details on which licenses offer this feature.

Use the Advanced Camera API in Unity

Attach the following script to an object in your Vuforia scene and then build the project to a device and look at the logs to see the list of the native fields returned. Once you have the field key names, you can use those to access a field as demonstrated in the script below.

using UnityEngine;
using System.Collections;
using Vuforia;

public class TestAdvancedCameraAPI : MonoBehaviour
{
    void Start()
    {
        VuforiaApplication.Instance.OnVuforiaStarted += OnVuforiaStarted;
    }

    void OnVuforiaStarted()
    {
        // Get the fields
        IEnumerable cameraFields = VuforiaBehaviour.Instance.CameraDevice.Android.GetCameraFields();

        // Print fields to device logs
        foreach (CameraDevice.AndroidDevice.CameraField field in cameraFields)
        {
            Debug.Log("Key: " + field.Key + "; Type: " + field.Type);
        }

        // Retrieve a specific field and print to logs
        string focusMode = "";

        VuforiaBehaviour.Instance.CameraDevice.Android.GetField("focus-mode", out focusMode);

        Debug.Log("FocusMode: " + focusMode);
    }
}

Example Output from Device Logs

The following is sample output from the .adb logcat logs when running the Unity script above on a Galaxy S6 device. The fields may vary per device.

NOTE: Some devices may not return any fields.

  Key: 3dnr; Type: TypeString
  Key: Infinity; Type: TypeString
  Key: antibanding; Type: TypeString
  Key: antibanding-values; Type: TypeString
  Key: auto-exposure-lock-supported; Type: TypeString
  Key: auto-whitebalance-lock-supported; Type: TypeString
  Key: best-capture; Type: TypeString
  Key: brightness; Type: TypeString
  Key: brightness-max; Type: TypeString
  Key: brightness-min; Type: TypeString
  Key: burst-capture; Type: TypeString
  Key: constant-growth-rate-zoom-supported; Type: TypeString
  Key: contrast; Type: TypeString
  Key: drc; Type: TypeString
  Key: dual_mode; Type: TypeString
  Key: dualrecording-hint; Type: TypeString
  Key: dynamic-range-control; Type: TypeString
  Key: effect; Type: TypeString
  Key: effect-values; Type: TypeString
  Key: effectrecording-hint; Type: TypeString
  Key: exposure-compensation; Type: TypeString
  Key: exposure-compensation-step; Type: TypeString
  Key: exposure-time; Type: TypeString
  Key: fast-fps-mode; Type: TypeString
  Key: flash-mode; Type: TypeString
  Key: flash-mode-values; Type: TypeString
  Key: fnumber-value-denominator; Type: TypeString
  Key: fnumber-value-numerator; Type: TypeString
  Key: focal-length; Type: TypeString
  Key: focallength-35mm-value; Type: TypeString
  Key: focallength-value-denominator; Type: TypeString
  Key: focallength-value-numerator; Type: TypeString
  Key: focus-areas; Type: TypeString
  Key: focus-distance; Type: TypeString
  Key: focus-distances; Type: TypeString
  Key: focus-mode; Type: TypeString
  Key: focus-mode-values; Type: TypeString
  Key: hdr-mode; Type: TypeString
  Key: horizontal-view-angle; Type: TypeString
  Key: hue; Type: TypeString
  Key: hue-max; Type: TypeString
  Key: hue-min; Type: TypeString
  Key: imageuniqueid-value; Type: TypeString
  Key: intelligent-mode; Type: TypeString
  Key: iso; Type: TypeString
  Key: iso-values; Type: TypeString
  Key: jpeg-quality; Type: TypeString
  Key: jpeg-thumbnail-height; Type: TypeString
  Key: jpeg-thumbnail-quality; Type: TypeString
  Key: jpeg-thumbnail-size-values; Type: TypeString
  Key: jpeg-thumbnail-width; Type: TypeString
  Key: llv_mode; Type: TypeString
  Key: max-exposure-compensation; Type: TypeString
  Key: max-exposure-time; Type: TypeString
  Key: max-num-detected-faces-hw; Type: TypeString
  Key: max-num-detected-faces-sw; Type: TypeString
  Key: max-num-focus-areas; Type: TypeString
  Key: max-num-metering-areas; Type: TypeString
  Key: max-wb-k; Type: TypeString
  Key: max-zoom; Type: TypeString
  Key: maxaperture-value-denominator; Type: TypeString
  Key: maxaperture-value-numerator; Type: TypeString
  Key: metering; Type: TypeString
  Key: metering-areas; Type: TypeString
  Key: metering-values; Type: TypeString
  Key: min-exposure-compensation; Type: TypeString
  Key: min-exposure-time; Type: TypeString
  Key: min-wb-k; Type: TypeString
  Key: odc; Type: TypeString
  Key: ois; Type: TypeString
  Key: ois-supported; Type: TypeString
  Key: phase-af; Type: TypeString
  Key: phase-af-values; Type: TypeString
  Key: picture-format; Type: TypeString
  Key: picture-format-values; Type: TypeString
  Key: picture-size; Type: TypeString
  Key: picture-size-values; Type: TypeString
  Key: preferred-preview-size-for-video; Type: TypeString
  Key: preview-format; Type: TypeString
  Key: preview-format-values; Type: TypeString
  Key: preview-fps-range; Type: TypeString
  Key: preview-fps-range-values; Type: TypeString
  Key: preview-frame-rate; Type: TypeString
  Key: preview-frame-rate-values; Type: TypeString
  Key: preview-size; Type: TypeString
  Key: preview-size-values; Type: TypeString
  Key: quick-shot; Type: TypeString
  Key: rotation; Type: TypeString
  Key: rt-hdr; Type: TypeString
  Key: rt-hdr-values; Type: TypeString
  Key: saturation; Type: TypeString
  Key: saturation-max; Type: TypeString
  Key: saturation-min; Type: TypeString
  Key: scene-mode; Type: TypeString
  Key: scene-mode-values; Type: TypeString
  Key: sharpness; Type: TypeString
  Key: sharpness-max; Type: TypeString
  Key: sharpness-min; Type: TypeString
  Key: smooth-zoom-supported; Type: TypeString
  Key: vertical-view-angle; Type: TypeString
  Key: video-frame-format; Type: TypeString
  Key: video-size; Type: TypeString
  Key: video-size-values; Type: TypeString
  Key: video-snapshot-supported; Type: TypeString
  Key: video-stabilization-supported; Type: TypeString
  Key: vrmode; Type: TypeString
  Key: vrmode-supported; Type: TypeString
  Key: wb-k; Type: TypeString
  Key: wdr; Type: TypeString
  Key: whitebalance; Type: TypeString
  Key: whitebalance-values; Type: TypeString
  Key: zoom; Type: TypeString
  Key: zoom-ratios; Type: TypeString
  Key: zoom-supported; Type: TypeString

 

Use the Advanced Camera API in a native Android application

The CameraController class provides advanced camera properties that can be adjusted after the initialization of the camera. This allows for use cases such as tweaking ISO, exposure compensation, etc. of the Android Camera 2 API.

NOTE: Currently this feature will only work on Android.

The VuCameraConfig class provides access to the device’s built-in camera. Use the different modes and focus modes to adjust the device’s camera configurations. Please refer to Working with the Camera for adjusting focus and video modes.

Setup the camera

  1. Configure your camera according to the Camera API Overview. The camera is initialized with vuEngineStart() and can be stopped with vuEngineStop().
  2. Use the CameraController to acquire the supported video modes of a device’s camera. The VuCameraField can be of data type: String, int64, float, bool, or int64_range. See the reference API library for details on the data types.
// Retrieve the camera controller to access camera specific functionality in Engine 
vuEngineGetCameraController(const VuEngine* engine, VuController** controller);

// Create list for storing the properties of a camera and determine the size
vuCameraFieldListCreate(VuCameraFieldList** list);
vuCameraFieldListGetSize(const VuCameraFieldList* list, int32_t* listSize);

// Get an element in the camera field list
vuCameraFieldListGetElement(const VuCameraFieldList* list, int32_t element, VuCameraField* cameraField);

// Get all supported video modes for the camera
vuCameraControllerAcquireSupportedCameraFields(const VuController* controller, VuCameraFieldList* cameraFieldList);

// Destroy list after usage
vuCameraFieldListDestroy(VuCameraFieldList* list)

Get the VuCameraField

  1. Once you know the VuCameraFieldDataType, you can use the appropriate get call with valid key and type pointers to read the VuCameraField.

The key must match one of the keys returned in the camera field list. value is the output variable of the requested key. The call returns VU_SUCCESS on success, and VU_FALSE on failure.

Read the camera field values

// Returns VU_SUCCESS on success and VU_FALSE on failure
vuCameraControllerGetFieldString(const VuController* controller, const char* key, char* value, int32_t maxLength);
vuCameraControllerGetFieldInt64(const VuController* controller, const char* key, int64_t* value);
vuCameraControllerGetFieldFloat(const VuController* controller, const char* key, float* value);
vuCameraControllerGetFieldBool(const VuController* controller, const char* key, VuBool* value);
vuCameraControllerGetFieldInt64Range(const VuController* controller, const char* key, int64_t* value);

Set the camera field values

// Returns VU_SUCCESS on success and VU_FALSE on failure
vuCameraControllerSetFieldString(VuController* controller, const char* key, const char* value);
vuCameraControllerSetFieldInt64(VuController* controller, const char* key, int64_t value);
vuCameraControllerSetFieldFloat(VuController* controller, const char* key, float value);
vuCameraControllerSetFieldBool(VuController* controller, const char* key, VuBool value);
vuCameraControllerSetFieldInt64Range(VuController* controller, const char* key, int64_t value[2]);