CameraDevice

class NatML.Devices.CameraDevice : IMediaDevice<CameraImage>

The CameraDevice provides an abstraction for hardware cameras.

Identifying the Device

Camera devices can be identified either by their unique identifier or by their position relative to the screen.

Unique Identifier

/// <summary>
/// Device unique ID.
/// </summary>
string uniqueID { get; }

Refer to the Identifying the Device section of the IMediaDevice interface for more information.

Device Name

/// <summary>
/// Display friendly device name.
/// </summary>
string name { get; }

Refer to the Identifying the Device section of the IMediaDevice interface for more information.

Device Location

/// <summary>
/// Device location.
/// </summary>
DeviceLocation location { get; }

Refer to the Identifying the Device section of the IMediaDevice interface for more information.

Default Device

/// <summary>
/// Device is the default device for its media type.
/// </summary>
bool defaultForMediaType { get; }

Refer to the Identifying the Device section of the IMediaDevice interface for more information.

Camera Position

/// <summary>
/// Is this camera front facing?
/// </summary>
bool frontFacing { get; }

The camera device provides information about its position relative to the screen.

Field of View

/// <summary>
/// Field of view in degrees.
/// </summary>
(float width, float height) fieldOfView { get; }

The camera device is able to report its field of view angles, in degrees.

Checking the Device State

/// <summary>
/// Is the device running?
/// </summary>
bool running { get; }

Refer to the Checking the Device State section of the IMediaDevice interface for more information.

Streaming the Preview

/// <summary>
/// Start running.
/// </summary>
/// <param name="handler">Delegate to receive preview frames.</param>
void StartRunning (Action<CameraImage> handler);

The camera device streams camera images to the provided handler. Each camera image contains a pixelBuffer along with a selection of EXIF metadata.

The camera startup is typically a complex process, so the can be a small delay before frames start getting reported to the handler.

Preview Resolution

/// <summary>
/// Get or set the current preview resolution of the camera.
/// </summary>
(int width, int height) previewResolution { get; set; }

All camera devices allow getting and setting the camera preview resolution. This setting determines the size of camera images reported by the camera.

Resolutions are always specified in landscape format, meaning that the width is always larger than the height.

Camera devices do not support arbitrary preview resolutions. Instead, the device will find the closest supported resolution to what you request. You can check what this is by getting the value of previewResolution immediately after setting it.

Do not set the previewResolution while the device is running. Instead, set it before starting the device.

Preview Frame Rate

/// <summary>
/// Get or set the current framerate of the camera.
/// </summary>
int frameRate { get; set; }

Camera devices support setting the preview frame rate.

NatDevice supports high frame-rate camera streaming, including 120FPS and 240FPS on camera devices that support it.

Do not set the frameRate while the device is running. Instead, set it before starting the device.

Capturing Photos

/// <summary>
/// Capture a photo.
/// </summary>
/// <param name="handler">Delegate to receive high-resolution photo.</param>
void CapturePhoto (Action<CameraImage> handler);

Camera devices can capture high resolution photos, exactly like standard camera apps can.

Photo Resolution

The photo resolution can be queried and updated:

/// <summary>
/// Get or set the photo resolution.
/// </summary>
(int width, int height) photoResolution { get; set; }

Resolutions are always specified in landscape format, meaning that the width is always larger than the height.

Camera devices do not support arbitrary photo resolutions. Instead, the device will find the closest supported resolution to what you request. You can check what this is by getting the value of photoResolution immediately after setting it.

Do not set the photoResolution while the device is running. Instead, set it before starting the device.

Flash Mode

/// <summary>
/// Get or set the photo flash mode.
/// </summary>
FlashMode flashMode { get; set; }

The flash mode can be set, giving some control over lighting when the photo is captured. The flash mode can be set to one of the following values:

/// <summary>
/// Photo flash mode.
/// </summary>
enum FlashMode : int {
    /// <summary>
    /// Never use flash.
    /// </summary>
    Off = 0,
    /// <summary>
    /// Always use flash.
    /// </summary>
    On = 1,
    /// <summary>
    /// Let the sensor detect if it needs flash.
    /// </summary>
    Auto = 2
}

Before setting a flash mode, you must check whether flash settings are in fact supported by the camera device:

/// <summary>
/// Is flash supported for photo capture?
/// </summary>
bool flashSupported { get; }

The default flash mode is FlashMode.Off. This is also the flash mode reported when the device does not support flash.

Stopping the Stream

/// <summary>
/// Stop running.
/// </summary>
void StopRunning ();

Refer to the Stopping the Stream section of the IMediaDevice interface for more information.

Focus Controls

Camera devices provide focus controls, including setting the focus mode and focus point of interest.

Focus Mode

/// <summary>
/// Get or set the focus mode.
/// </summary>
FocusMode focusMode { get; set; }

Camera devices can be set to use one of the following focus modes:

/// <summary>
/// Focus mode.
/// </summary>
enum FocusMode : int {
    /// <summary>
    /// Continuous autofocus.
    /// </summary>
    Continuous  = 0,
    /// <summary>
    /// Locked focus.
    /// </summary>
    Locked      = 1,
}

Finally, the camera device can be queried for whether it supports a given focus mode:

/// <summary>
/// Check if a given focus mode is supported by the camera device.
/// </summary>
/// <param name="mode">Focus mode.</param>
bool FocusModeSupported (FocusMode mode);

Focus Point

/// <summary>
/// Set the focus point of interest.
/// The point is specified in normalized coordinates in range [0.0, 1.0].
/// </summary>
/// <param name="x">Normalized x coordinate.</param>
/// <param name="y">Normalized y coordinate.</param>
void SetFocusPoint (float x, float y);

Camera devices can be set to focus at a specific point in the camera view.

Focus point coordinates are always normalized in range [0.0, 1.0].

Exposure Controls

Camera devices provide exposure controls, including setting the exposure mode, exposure bias, exposure point of interest, and manual exposure controls.

Exposure Mode

/// <summary>
/// Get or set the exposure mode.
/// If the requested exposure mode is not supported, the camera device will ignore.
/// </summary>
ExposureMode exposureMode { get; set; }

Camera devices operate in one of a set of exposure modes:

/// <summary>
/// Exposure mode.
/// </summary>
enum ExposureMode : int {
    /// <summary>
    /// Continuous auto exposure.
    /// </summary>
    Continuous  = 0,
    /// <summary>
    /// Locked auto exposure.
    /// </summary>
    Locked      = 1,
    /// <summary>
    /// Manual exposure.
    /// </summary>
    Manual      = 2
}

Finally, the camera device can be queried for whether it supports a given exposure mode:

/// <summary>
/// Check if a given exposure mode is supported by the camera device.
/// </summary>
/// <param name="mode">Exposure mode.</param>
bool ExposureModeSupported (ExposureMode mode);

Exposure Bias

/// <summary>
/// Get or set the exposure bias.
/// This value must be in the range returned by `exposureBiasRange`.
/// </summary>
float exposureBias { get; set; }

The exposure bias roughly determines how bright or dark the camera preview is. Its nominal value is $0.0EV$, but can be set to any value within the supported range:

/// <summary>
/// Exposure bias range.
/// </summary>
(float min, float max) exposureBiasRange { get; }

If the minimum exposure bias is equal to the maximum bias, which is equal to 0, then the camera does not support setting an exposure bias.

Exposure Point

/// <summary>
/// Set the exposure point of interest.
/// The point is specified in normalized coordinates in range [0.0, 1.0].
/// </summary>
/// <param name="x">Normalized x coordinate.</param>
/// <param name="y">Normalized y coordinate.</param>
public void SetExposurePoint (float x, float y);

Similar to focus, camera devices can be set to exposure for a specific point in the camera view.

Exposure point coordinates are always normalized in range [0.0, 1.0].

Manual Exposure

/// <summary>
/// Set manual exposure.
/// </summary>
/// <param name="duration">Exposure duration in seconds. MUST be in `exposureDurationRange`.</param>
/// <param name="ISO">Sensor sensitivity ISO value. MUST be in `ISORange`.</param>
void SetExposureDuration (float duration, float ISO);

Camera devices can be configured to use manual exposure, allowing for fine-grained controls for photography and computer vision applications. The duration can be set to any value within the supported range:

/// <summary>
/// Exposure duration range in seconds.
/// </summary>
(float min, float max) exposureDurationRange { get; }

Similarly, the ISO can be set to any value within the supported range:

/// <summary>
/// Sensor sensitivity range.
/// </summary>
(float min, float max) ISORange { get; }

White Balance Controls

Camera devices provide control over the white balance mode:

White Balance Mode

/// <summary>
/// Get or set the white balance mode.
/// </summary>
WhiteBalanceMode whiteBalanceMode { get; set; }

Camera devices operate in one of a set of exposure modes:

/// <summary>
/// White balance mode.
/// </summary>
enum WhiteBalanceMode : int {
    /// <summary>
    /// Continuous auto white balance.
    /// </summary>
    Continuous  = 0,
    /// <summary>
    /// Locked auto white balance.
    /// </summary>
    Locked      = 1,
}

The camera can be queried for whether it supports a given white balance mode:

/// <summary>
/// Check if a given white balance mode is supported by the camera device.
/// </summary>
/// <param name="mode">White balance mode.</param>
bool WhiteBalanceModeSupported (WhiteBalanceMode mode);

Video Stabilization

/// <summary>
/// Get or set the video stabilization mode.
/// </summary>
VideoStabilizationMode videoStabilizationMode { get; set; }

Some camera devices support video stabilization. As such, this behaviour can be enabled by setting an appropriate stabilization mode:

/// <summary>
/// Video stabilization mode.
/// </summary>
enum VideoStabilizationMode : int {
    /// <summary>
    /// Disabled video stabilization.
    /// </summary>
    Off     = 0,
    /// <summary>
    /// Standard video stabilization.
    /// </summary>
    Standard = 1
}

Camera devices can be queried for whether they support a given video stabilization mode:

/// <summary>
/// Check if a given video stabilization mode is supported by the camera device.
/// </summary>
/// <param name="mode">Video stabilization mode.</param>
bool VideoStabilizationModeSupported (VideoStabilizationMode mode);

Zoom Ratio

/// <summary>
/// Get or set the zoom ratio.
/// This value must be in the range returned by `zoomRange`.
/// </summary>
float zoomRatio { get; set; }

Some camera devices support setting the zoom ratio. The zoom ratio applies to the camera preview and captured photos alike. The zoom ratio can be set to any value within the camera's zoom range:

/// <summary>
/// Zoom ratio range.
/// </summary>
(float min, float max) zoomRange { get; }

Torch Unit

/// <summary>
/// Get or set the torch mode.
/// </summary>
TorchMode torchMode { get; set; }

Some camera devices have accompanying torch units. This property can be used to activate or deactivate the torch unit. Supported modes include:

/// <summary>
/// Torch mode.
/// </summary>
enum TorchMode : int {
    /// <summary>
    /// Disabled torch.
    /// </summary>
    Off     = 0,
    /// <summary>
    /// Maximum supported torch level.
    /// </summary>
    Maximum = 100
}

The camera can be queried for whether it has an available torch unit:

/// <summary>
/// Is torch supported?
/// </summary>
bool torchSupported { get; }

The torch unit can be enabled even when the device is not running.