W3C

Picture Settings

W3C Editor's Draft 26 October 2012

This version:
http://gmandyam.github.com/media-capture
Latest editor's draft:
http://gmandyam.github.com/media-capture
Editor:
Giridhar Mandyam, Qualcomm Innovation Center, Inc

Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This document specific settings for a takePicture() method to be defined as part of the Media Capture specification.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Comments on this document are welcomed.

This document was published by the Media Capture Task Force as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-media-capture@w3.org (subscribe, archives). All feedback is welcome.

Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

Various proposals have been provided to the Task Force regarding methods for taking a picture that can extend getUserMedia(). This proposal focused on picture settings that are compatible with the cameras associated with many handheld devices. It leverages the takePicture() method as described in Settings API Version 4.

The takePicture() method is currently defined on a a PictureDeviceTrack according to the cited proposal as follows:

interface PictureDeviceTrack : VideoStreamTrack {
    void takePicture ();
             attribute EventHandler onpicture;
};

1.1 Attributes

onpicture of type EventHandler
Register/unregister for "picture" events. The handler should expect to get a PictureEvent object as its first parameter.

1.2 Methods

takePicture
Temporarily mutes the owning VideoDeviceTrack's stream, then asynchronously switches the camera into "high resolution picture mode", applies the PictureDeviceTrack settings (a snapshot from the time the takePicture API was called, and records/encodes an image using a user-agent determined format into a Blob object. Finally, queues a task to fire a "picture" event with the resulting Blob instance.
No parameters.
Return type: void

For the purposes of this proposal, the main focus is on the PictureDeviceTrack object and takePicture() method. In addition, the MediaSettingsRange is leveraged.

2. MediaSettingsRange

interface MediaSettingsRange {
    readonly attribute any max;
    readonly attribute any min;
    readonly attribute any initial;
    void request (any value, optional boolean mandatory);
};

2.1 Attributes

initial of type any, readonly
The initial value of this setting
max of type any, readonly
The maximum value of this setting
min of type any, readonly
The minimum value of this setting

2.2 Methods

request
Creates an internal constraint based on the setting name with the provided value, adds that constraint into the pending constraint structure (to the MediaTrackConstraint array by default or replaces an entry in the MediaTrackConstraintSet if the mandatory flag is set) and queues a task (if not already queued) to process the pending constraint structure at the conclusion of this task.
ParameterTypeNullableOptionalDescription
valueany✘✘
mandatoryboolean✘✔
Return type: void

3. MediaSettingsItem

The MediaSettingsItem interface is now defined, which allows for a single setting to be managed.

interface MediaSettingsItem {
    readonly attribute any value;
    readonly attribute any initial;
    void request (any value, optional boolean mandatory);
};

3.1 Attributes

initial of type any, readonly
The initial value of this setting
value of type any, readonly
Value of current setting.

3.2 Methods

request
Creates an internal constraint based on the setting name with the provided value, adds that constraint into the pending constraint structure (to the MediaTrackConstraint array by default or replaces an entry in the MediaTrackConstraintSet if the mandatory flag is set) and queues a task (if not already queued) to process the pending constraint structure at the conclusion of this task.
ParameterTypeNullableOptionalDescription
valueany✘✘
mandatoryboolean✘✔
Return type: void

4. PictureSettings

A new object PictureSettings is defined to control the settings for takePicture(). PictureDeviceTrack implements PictureSettings.

The PictureSettings interface must be supported by the User Agent. However, any settings in this object that are not supported by the User Agent or selected camera may be ignored.

interface PictureSettings {
             attribute MediaSettingsItem  whiteBalanceMode;
             attribute MediaSettingsItem  autoExposureMode;
             attribute MediaSettingsRange exposureCompensation;
             attribute MediaSettingsItem  iso;
             attribute MediaSettingsItem  redEyeReduction;
             attribute MediaSettingsRange brightness;
             attribute MediaSettingsRange constrast;
             attribute MediaSettingsRange saturation;
             attribute MediaSettingsRange sharpness;
};

4.1 Attributes

autoExposureMode of type MediaSettingsItem
This feature control the auto exposure mode setting. Values are of type ExposureModeEnum.
brightness of type MediaSettingsRange
This feature controls the brightness setting of the camera. Values are numeric.
constrast of type MediaSettingsRange
This feature controls the contrast setting of the camera. Values are numeric.
exposureCompensation of type MediaSettingsRange
This feature changes the exposure level for recorded images. Values are numeric.
iso of type MediaSettingsItem
This feature control the camera ISO setting. Values are of type ISOModeEnum.
redEyeReduction of type MediaSettingsItem
This feature turns on or off the camera red eye reduction and is boolean - on is true
saturation of type MediaSettingsRange
This feature controls the saturation setting of the camera. Values are numeric.
sharpness of type MediaSettingsRange
This feature controls the sharpness setting of the camera. Values are numeric.
whiteBalanceMode of type MediaSettingsItem
This feature control the white balance mode setting. Values are of type WhiteBalanceModeEnum.

4.2 WhiteBalanceModeEnum

enum WhiteBalanceModeEnum {
    "auto",
    "incandescent",
    "fluorescent",
    "warm-fluorescent",
    "daylight",
    "cloudy-daylight",
    "twilight",
    "shade"
};
Enumeration description
auto
incandescent
fluorescent
warm-fluorescent
daylight
cloudy-daylight
twilight
shade

4.3 ExposureModeEnum

enum ExposureModeEnum {
    "frame-average",
    "center-weighted",
    "spot-metering"
};
Enumeration description
frame-average
center-weighted
spot-metering

4.4 ISOModeEnum

enum ISOModeEnum {
    "auto",
    "100",
    "200",
    "400",
    "800",
    "1250"
};
Enumeration description
auto
100
200
400
800
1250

5. Example: Taking a picture after turning on Red Eye Reduction

Example 1
navigator.getUserMedia({video: true}, gotMedia, failedToGetMedia);

function gotMedia(mediastream) {
   var videoDevice = mediastream.videoTracks[0];
   // Check if this device supports a picture mode...
   var pictureDevice = videoDevice.pictureDeviceTrack;
   if (pictureDevice) {
     pictureDevice.onpicture = showPicture;
     if (pictureDevice.redEyeReduction) {
        pictureDevice.redEyeReduction.request(true,true);
        }
     else
        console.log('No red eye reduction');
     pictureDevice.takePicture();
     }
   }

function showPicture(e) {
   var img = document.querySelector("img");
   img.src = URL.createObjectURL(e.data);
   }

function failedToGetMedia{
   console.log('Stream failure');
   }