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 to 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 the Vuforia SDK. The Advanced Camera API is only available for certain license types. See our Pricing page for details on which licenses offer this feature.

The CameraFields class provides getters and setters on CameraDevice.  These allow modification of the camera's ISO, and exposure compensation using the parameters of the Android Camera 1 API.
 

/*===============================================================================
@file 
    CameraDevice.h
 
@brief
    Header file for CameraDevice class.
===============================================================================*/
 
namespace Vuforia
{
 
/// Implements access to the phone's built-in camera
class VUFORIA_API CameraDevice : private NonCopyable
{

...        
    
    /// Write accessors for camera fields
 
    // Setting to NULL removes the field
    virtual bool setField(const char* key, const char* value) = 0;
    virtual bool setField(const char* key, Vuforia::Int64 value) = 0;
    virtual bool setField(const char* key, float value) = 0; 
    virtual bool setField(const char* key, bool value) = 0; 
    virtual bool setField(const char* key, Vuforia::Int64 intRange[2]) = 0;
    
    /// Get the number of camera fields
    /**
     *  Note this may not be the complete set of camera fields available on this
     *  device and some keys may not be supported on every device
     */
    virtual int getNumFields() const = 0;
 
    /// Get the CameraField and associated key for the given index
    virtual bool getCameraField(int index, CameraField& field) const = 0; 
 
    /// Read accessors for camera fields
    virtual bool getFieldString(const char* key, char* value, size_t maxlength) const = 0; 
    virtual bool getFieldInt64(const char* key, Vuforia::Int64& value) const = 0;
    virtual bool getFieldFloat(const char* key, float& value) const = 0; 
    virtual bool getFieldBool(const char* key, bool& value) const = 0;
    virtual bool getFieldInt64Range(const char* key, Vuforia::Int64* intRange) const = 0;
};
 
} // namespace Vuforia
 
#endif // _VUFORIA_CAMERADEVICE_H_
 
/*===============================================================================
 @file
    CameraField.h
 
 @brief
    Header file for CameraField class.
 ===============================================================================*/
#ifndef _VUFORIA_CAMERAFIELD_H_
#define _VUFORIA_CAMERAFIELD_H_
 
 
namespace Vuforia
{
 
/// Camera fields are advanced properties of the camera
/**
 *  Camera fields represent advanced camera properties and capture parameters such as
 *  exposure compensation, ISO and others. A field may be read only (e.g. maximum
 *  exposure compensation value) or read-write (e.g. exposure compensation value).
 *
 *  Camera fields are accessed as key-value pairs, where the value may be one of
 *  multiple basic types.
 *
 *  Camera fields are highly platform dependent and the keys to identify a given
 *  property and available values to set will vary across operating system,
 *  operating system version, camera API version and the device model itself.
 *  Furthermore the behavior of the camera driver wrt. these fields is highly
 *  fragmented. Thus CameraFields should only be used for specific use case and devices.
 *
 *  All of the Camera field APIs shall be called only after initializing the
 *  CameraDevice.
 *
 *  Camera Fields are currently only implemented for Android.
 *
 *  Finally, setting advanced camera parameters may adversely affect Vuforia
 *  tracking performance as well as cause functional issues.
 */
class CameraField
{
public:
    /// A camera field may be of the following types. On some platforms all
    /// fields are strings.
    enum DataType
    {
        TypeString,     ///< Null terminated array of characters (ASCII)
        TypeInt64,      ///< 64-bit signed integer
        TypeFloat,      ///< Single precision floating point
        TypeBool,       ///< Boolean
        TypeInt64Range, ///< Array of two 64-bit signed integer
        
        /// On some platforms the type may not be known at run-time. Setting
        /// or getting a parameter of unknown type will fail.
        TypeUnknown
    };
    
    /// Default constructor
    CameraField() : mType(TypeUnknown), mKey("") {};
    
    /// The data type of this field
    DataType mType;
    
    /// The key to identify this field.
    /// Note the string is only valid until the next call to getCameraField,
    /// take a copy of the string if you want to hold on to it.
    const char* mKey;
};
    
} // namespace Vuforia
#endif //_VUFORIA_CAMERAFIELD_H_
 

Testing with a Unity Project

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 System.Collections.Generic;
using Vuforia;

public class TestAdvancedCameraAPI : MonoBehaviour
{
    void Start()
    {
        VuforiaARController.Instance.RegisterVuforiaStartedCallback(OnVuforiaStarted);
    }

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

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

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

        CameraDevice.Instance.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