CameraControl.takePicture

  • Revision slug: DOM/CameraControl.takePicture
  • Revision title: CameraControl.takePicture
  • Revision id: 350819
  • Created:
  • Creator: Jeremie
  • Is current revision? No
  • Comment

Revision Content

{{ non-standard_header() }}

Summary

Captures a still image from the camera and passes it as a {{domxref("Blob")}} to a success callback handler, which can manipulate the image as you wish (for example, by manipulating its pixel data or storing it).

If the camera supports doing so, you may call this method while the camera is already recording video.

Note: Using this function will stop the preview stream, which must be specifically resumed by calling {{domxref("CameraControl.resumePreview()")}}.

Syntax

CameraControl.takePicture(options, onsuccess[, onerror]);

Parameters

options
An object specifying options for the photo capture operation; see {{anch("Options")}} below.
onsuccess
A callback function to be invoked once the image has been captured. The function receives one parameter: a {{domxref("Blob")}} containing a JPEG formatted image.
onerror {{optional_inline}}
An optional callback function that's invoked if an error occurs; it receives one parameter: an error string.

Options

The options object passed to this method has the following properties:

 
dateTime {{optional_inline()}}
The time at which the image was captured, in seconds since the beginning of January 1, 1970 UTC. This date will be add to the EXIF header as the recording time of the photo.
fileFormat {{optional_inline()}}
A string indicated the file format of the picture. This object must match one of the supported file format described in the {{domxref("CameraCapabilities")}} object's fileFormats property.
pictureSize {{optional_inline()}}
An object with two properties—width and height—indicating the size of image to capture. This object must match one of the supported image sizes described in the {{domxref("CameraCapabilities")}} object's pictureSizes property. You may specify null to use the default size.
position {{optional_inline}}
An optional object that contains metadata that can be added to the captured image; this information describes geolocation data about where and when the photo was taken, as described in {{anch("Position")}}.
rotation {{optional_inline()}}
The number of degrees clockwise to rotate the image upon capture.

Position

The position object, specified as a property of the options object, provides optional additional GPS metadata that can be attached to the captured image.

timestamp {{optional_inline()}}
The time at which the image was captured, in seconds since the beginning of January 1, 1970 UTC.
altitude {{optional_inline()}}
The altitude at which the image was captured, in meters above sea level.
latitude {{optional_inline()}}
The latitude at which the image was captured, in degrees.
longitude {{optional_inline()}}
The longitude at which the image was captured, in degrees.

Example

var storage = navigator.getDeviceStorage('pictures');
var cameraOptions = {
  camera: navigator.mozCameras.getListOfCameras()[0]
};
var pictureOptions = {
  rotation: 90,
  pictureSize: null,
  fileFormat: null
}

function onPictureTaken( blob ) {
  storage.addNamed(blob, 'myImage.jpg');
}

function onAccessCamera( camera ) {
  pictureOptions.pictureSize = camera.capabilities.pictureSizes[0];
  pictureOptions.fileformat  = camera.capabilities.fileFormats[0];

  camera.takePicture(pictureOptions, onPictureTaken);
};

navigator.mozCameras.getCamera(cameraOptions, onAccessCamera)

Specification

Not part of any specification; however, this API should be removed when the WebRTC Capture and Stream API has been implemented.

See also

  • {{domxref("CameraControl")}}
  • {{domxref("CameraControl.resumePreview()")}}
  • {{domxref("Blob")}}
  • The DeviceStorage API

Revision Source

<p>{{ non-standard_header() }}</p>
<h2 id="Summary">Summary</h2>
<p>Captures a still image from the camera and passes it as a {{domxref("Blob")}} to a success callback handler, which can manipulate the image as you wish (for example, by manipulating its pixel data or storing it).</p>
<p>If the camera supports doing so, you may call this method while the camera is already recording video.</p>
<div class="note">
  <p><strong>Note:</strong> Using this function will stop the preview stream, which must be specifically resumed by calling {{domxref("CameraControl.resumePreview()")}}.</p>
</div>
<h2 id="Syntax">Syntax</h2>
<pre>
CameraControl.takePicture(options, onsuccess[, onerror]);</pre>
<h3 id="Parameters">Parameters</h3>
<dl>
  <dt>
    <code>options</code></dt>
  <dd>
    An object specifying options for the photo capture operation; see {{anch("Options")}} below.</dd>
  <dt>
    <code>onsuccess</code></dt>
  <dd>
    A callback function to be invoked once the image has been captured. The function receives one parameter: a {{domxref("Blob")}} containing a JPEG formatted image.</dd>
  <dt>
    <code>onerror</code> {{optional_inline}}</dt>
  <dd>
    An optional callback function that's invoked if an error occurs; it receives one parameter: an error string.</dd>
</dl>
<h3 id="Options">Options</h3>
<p>The <code>options</code> object passed to this method has the following properties:</p>
<dl>
  <dt>
    &nbsp;</dt>
  <dt>
    <code>dateTime</code> {{optional_inline()}}</dt>
  <dd>
    The time at which the image was captured, in seconds since the beginning of January 1, 1970 UTC. This date will be add to the EXIF header as the recording time of the photo.</dd>
  <dt>
    <code>fileFormat</code> {{optional_inline()}}</dt>
  <dd>
    A string indicated the file format of the picture. This object must match one of the supported file format described in the {{domxref("CameraCapabilities")}} object's <code>fileFormats</code> property.</dd>
  <dt>
    <code>pictureSize </code>{{optional_inline()}}</dt>
  <dd>
    An object with two properties—<code>width</code> and <code>height</code>—indicating the size of image to capture. This object must match one of the supported image sizes described in the {{domxref("CameraCapabilities")}} object's <code>pictureSizes</code> property. You may specify <code>null</code> to use the default size.</dd>
  <dt>
    <code>position</code> {{optional_inline}}</dt>
  <dd>
    An optional object that contains metadata that can be added to the captured image; this information describes geolocation data about where and when the photo was taken, as described in {{anch("Position")}}.</dd>
  <dt>
    <code>rotation</code> {{optional_inline()}}</dt>
  <dd>
    The number of degrees clockwise to rotate the image upon capture.</dd>
</dl>
<h3 id="Position">Position</h3>
<p>The <code>position</code> object, specified as a property of the <code>options</code> object, provides optional additional GPS metadata that can be attached to the captured image.</p>
<dl>
  <dt>
    <code>timestamp </code>{{optional_inline()}}</dt>
  <dd>
    The time at which the image was captured, in seconds since the beginning of January 1, 1970 UTC.</dd>
  <dt>
    <code>altitude </code>{{optional_inline()}}</dt>
  <dd>
    The altitude at which the image was captured, in meters above sea level.</dd>
  <dt>
    <code>latitude </code>{{optional_inline()}}</dt>
  <dd>
    The latitude at which the image was captured, in degrees.</dd>
  <dt>
    <code>longitude </code>{{optional_inline()}}</dt>
  <dd>
    The longitude at which the image was captured, in degrees.</dd>
</dl>
<h2 id="Example">Example</h2>
<pre class="brush: js">
var storage = navigator.getDeviceStorage('pictures');
var cameraOptions = {
  camera: navigator.mozCameras.getListOfCameras()[0]
};
var pictureOptions = {
  rotation: 90,
  pictureSize: null,
  fileFormat: null
}

function onPictureTaken( blob ) {
  storage.addNamed(blob, 'myImage.jpg');
}

function onAccessCamera( camera ) {
  pictureOptions.pictureSize = camera.capabilities.pictureSizes[0];
  pictureOptions.fileformat  = camera.capabilities.fileFormats[0];

  camera.takePicture(pictureOptions, onPictureTaken);
};

navigator.mozCameras.getCamera(cameraOptions, onAccessCamera)
</pre>
<h2 id="Specification" name="Specification">Specification</h2>
<p>Not part of any specification; however, this API should be removed when the <a class="external" href="http://dev.w3.org/2011/webrtc/editor/getusermedia.html" rel="external" title="http://dev.w3.org/2011/webrtc/editor/getusermedia.html">WebRTC Capture and Stream API</a> has been implemented.</p>
<h2 id="See_also">See also</h2>
<ul>
  <li>{{domxref("CameraControl")}}</li>
  <li>{{domxref("CameraControl.resumePreview()")}}</li>
  <li>{{domxref("Blob")}}</li>
  <li><a href="https://developer.mozilla.org/en-US/docs/WebAPI/Device_Storage_API" title="https://developer.mozilla.org/en-US/docs/WebAPI/Device_Storage_API">The DeviceStorage API</a></li>
</ul>
Revert to this revision