Cordova Plugin Camera Preview

Cordova plugin that allows camera interaction from Javascript and HTML

Releases are being kept up to date when appropriate. However, this plugin is under constant development. As such it is recommended to use master to always have the latest fixes & features.

PR's are greatly appreciated. Maintainer(s) wanted.

Features

• Start a camera preview from HTML code.
• Maintain HTML interactivity.
• Drag the preview box.
• Set camera color effect.
• Send the preview box to back of the HTML content.
• Set a custom position for the camera preview box.
• Set a custom size for the preview box.
• Set a custom alpha for the preview box.
• Set the focus mode, zoom, color effects, exposure mode, white balance mode and exposure compensation
• Tap to focus

Installation

Use any one of the installation methods listed below depending on which framework you use.

To install the master version with latest fixes and features

cordova plugin add https://github.com/cordova-plugin-camera-preview/cordova-plugin-camera-preview.git

ionic cordova plugin add https://github.com/cordova-plugin-camera-preview/cordova-plugin-camera-preview.git

meteor add cordova:cordova-plugin-camera-preview@https://github.com/cordova-plugin-camera-preview/cordova-plugin-camera-preview.git#[latest_commit_id]

<plugin spec="https://github.com/cordova-plugin-camera-preview/cordova-plugin-camera-preview.git" source="git" />

or if you want to use the last released version on npm

cordova plugin add cordova-plugin-camera-preview

ionic cordova plugin add cordova-plugin-camera-preview

meteor add cordova:cordova-plugin-camera-preview@X.X.X

<gap:plugin name="cordova-plugin-camera-preview" />

iOS Quirks

If you are developing for iOS 10+ you must also add the following to your config.xml

1<config-file platform="ios" target="*-Info.plist" parent="NSCameraUsageDescription" overwrite="true">
2  <string>Allow the app to use your camera</string>
3</config-file>
4
5<!-- or for Phonegap -->
6
7<gap:config-file platform="ios" target="*-Info.plist" parent="NSCameraUsageDescription" overwrite="true">
8  <string>Allow the app to use your camera</string>
9</gap:config-file>

Android Quirks (older devices)

When using the plugin for older devices, the camera preview will take the focus inside the app once initialized. In order to prevent the app from closing when a user presses the back button, the event for the camera view is disabled. If you still want the user to navigate, you can add a listener for the back event for the preview (see onBackButton)

Methods

startCamera(options, [successCallback, errorCallback])

Starts the camera preview instance.

Options: All options stated are optional and will default to values here

• x - Defaults to 0
• y - Defaults to 0
• width - Defaults to window.screen.width
• height - Defaults to window.screen.height
• camera - See CAMERA_DIRECTION - Defaults to front camera
• toBack - Defaults to false - Set to true if you want your html in front of your preview
• tapPhoto - Defaults to true - Does not work if toBack is set to false in which case you use the takePicture method
• tapFocus - Defaults to false - Allows the user to tap to focus, when the view is in the foreground
• previewDrag - Defaults to false - Does not work if toBack is set to false
• disableExifHeaderStripping - Defaults to false - Android Only - Disable automatic rotation of the image, and let the browser deal with it (keep reading on how to achieve it)
• storeToFile - Defaults to false - Android Only - Capture images to a file and return back the file path instead of returning base64 encoded data.

1let options = {
2  x: 0,
3  y: 0,
4  width: window.screen.width,
5  height: window.screen.height,
6  camera: CameraPreview.CAMERA_DIRECTION.BACK,
7  toBack: false,
8  tapPhoto: true,
9  tapFocus: false,
10  previewDrag: false
11};
12
13CameraPreview.startCamera(options);

When setting the toBack to true, remember to add the style below on your app's HTML or body element:

1html, body, .ion-app, .ion-content {
2  background-color: transparent;
3}

When both tapFocus and tapPhoto are true, the camera will focus, and take a picture as soon as the camera is done focusing.

stopCamera([successCallback, errorCallback])

Stops the camera preview instance.

1CameraPreview.stopCamera();

switchCamera([successCallback, errorCallback])

Switch between the rear camera and front camera, if available.

1CameraPreview.switchCamera();

show([successCallback, errorCallback])

Show the camera preview box.

1CameraPreview.show();

hide([successCallback, errorCallback])

Hide the camera preview box.

1CameraPreview.hide();

takePicture(options, successCallback, [errorCallback])

Take the picture. If width and height are not specified or are 0 it will use the defaults. If width and height are specified, it will choose a supported photo size that is closest to width and height specified and has closest aspect ratio to the preview. The argument quality defaults to 85 and specifies the quality/compression value: 0=max compression, 100=max quality.

1CameraPreview.takePicture({width:640, height:640, quality: 85}, function(base64PictureData){
2  /*
3    base64PictureData is base64 encoded jpeg image. Use this data to store to a file or upload.
4    Its up to the you to figure out the best way to save it to disk or whatever for your application.
5  */
6
7  // One simple example is if you are going to use it inside an HTML img src attribute then you would do the following:
8  imageSrcData = 'data:image/jpeg;base64,' +base64PictureData;
9  $('img#my-img').attr('src', imageSrcData);
10});
11
12// OR if you want to use the default options.
13
14CameraPreview.takePicture(function(base64PictureData){
15  /* code here */
16});

getSupportedFocusModes(cb, [errorCallback])

Get focus modes supported by the camera device currently started. Returns an array containing supported focus modes. See FOCUS_MODE for possible values that can be returned.

1CameraPreview.getSupportedFocusModes(function(focusModes){
2  focusModes.forEach(function(focusMode) {
3    console.log(focusMode + ', ');
4  });
5});

setFocusMode(focusMode, [successCallback, errorCallback])

Set the focus mode for the camera device currently started.

• focusMode - FOCUS_MODE

1CameraPreview.setFocusMode(CameraPreview.FOCUS_MODE.CONTINUOUS_PICTURE);

getFocusMode(cb, [errorCallback])

Get the focus mode for the camera device currently started. Returns a string representing the current focus mode.See FOCUS_MODE for possible values that can be returned.

1CameraPreview.getFocusMode(function(currentFocusMode){
2  console.log(currentFocusMode);
3});

getSupportedFlashModes(cb, [errorCallback])

Get the flash modes supported by the camera device currently started. Returns an array containing supported flash modes. See FLASH_MODE for possible values that can be returned

1CameraPreview.getSupportedFlashModes(function(flashModes){
2  flashModes.forEach(function(flashMode) {
3    console.log(flashMode + ', ');
4  });
5});

setFlashMode(flashMode, [successCallback, errorCallback])

Set the flash mode. See FLASH_MODE for details about the possible values for flashMode.

1CameraPreview.setFlashMode(CameraPreview.FLASH_MODE.ON);

getFlashMode(cb, [errorCallback])

Get the flash mode for the camera device currently started. Returns a string representing the current flash mode.See FLASH_MODE for possible values that can be returned

1CameraPreview.getFlashMode(function(currentFlashMode){
2  console.log(currentFlashMode);
3});

getHorizontalFOV(cb, [errorCallback])

Get the Horizontal FOV for the camera device currently started. Returns a string of a float that is the FOV of the camera in Degrees.

1CameraPreview.getHorizontalFOV(function(getHorizontalFOV){
2  console.log(getHorizontalFOV);
3});

getSupportedColorEffects(cb, [errorCallback])

Currently this feature is for Android only. A PR for iOS support would be happily accepted

Get color modes supported by the camera device currently started. Returns an array containing supported color effects (strings). See COLOR_EFFECT for possible values that can be returned.

1CameraPreview.getSupportedColorEffects(function(colorEffects){
2  colorEffects.forEach(function(color) {
3    console.log(color + ', ');
4  });
5});

setColorEffect(colorEffect, [successCallback, errorCallback])

Set the color effect. See COLOR_EFFECT for details about the possible values for colorEffect.

1CameraPreview.setColorEffect(CameraPreview.COLOR_EFFECT.NEGATIVE);

setZoom(zoomMultiplier, [successCallback, errorCallback])

Set the zoom level for the camera device currently started. zoomMultipler option accepts an integer. Zoom level is initially at 1

1CameraPreview.setZoom(2);

getZoom(cb, [errorCallback])

Get the current zoom level for the camera device currently started. Returns an integer representing the current zoom level.

1CameraPreview.getZoom(function(currentZoom){
2  console.log(currentZoom);
3});

getMaxZoom(cb, [errorCallback])

Get the maximum zoom level for the camera device currently started. Returns an integer representing the manimum zoom level.

1CameraPreview.getMaxZoom(function(maxZoom){
2  console.log(maxZoom);
3});

getSupportedWhiteBalanceModes(cb, [errorCallback])

Returns an array with supported white balance modes for the camera device currently started. See WHITE_BALANCE_MODE for details about the possible values returned.

1CameraPreview.getSupportedWhiteBalanceModes(function(whiteBalanceModes){
2  console.log(whiteBalanceModes);
3});

getWhiteBalanceMode(cb, [errorCallback])

Get the curent white balance mode of the camera device currently started. See WHITE_BALANCE_MODE for details about the possible values returned.

1CameraPreview.getWhiteBalanceMode(function(whiteBalanceMode){
2  console.log(whiteBalanceMode);
3});

setWhiteBalanceMode(whiteBalanceMode, [successCallback, errorCallback])

Set the white balance mode for the camera device currently started. See WHITE_BALANCE_MODE for details about the possible values for whiteBalanceMode.

1CameraPreview.setWhiteBalanceMode(CameraPreview.WHITE_BALANCE_MODE.CLOUDY_DAYLIGHT);

getExposureModes(cb, [errorCallback])

Returns an array with supported exposure modes for the camera device currently started. See EXPOSURE_MODE for details about the possible values returned.

1CameraPreview.getExposureModes(function(exposureModes){
2  console.log(exposureModes);
3});

getExposureMode(cb, [errorCallback])

Get the curent exposure mode of the camera device currently started. See EXPOSURE_MODE for details about the possible values returned.

1CameraPreview.getExposureMode(function(exposureMode){
2  console.log(exposureMode);
3});

setExposureMode(exposureMode, [successCallback, errorCallback])

Set the exposure mode for the camera device currently started. See EXPOSURE_MODE for details about the possible values for exposureMode.

1CameraPreview.setExposureMode(CameraPreview.EXPOSURE_MODE.CONTINUOUS);

getExposureCompensationRange(cb, [errorCallback])

Get the minimum and maximum exposure compensation for the camera device currently started. Returns an object containing min and max integers.

1CameraPreview.getExposureCompensationRange(function(expoxureRange){
2  console.log("min: " + exposureRange.min);
3  console.log("max: " + exposureRange.max);
4});

getExposureCompensation(cb, [errorCallback])

Get the current exposure compensation for the camera device currently started. Returns an integer representing the current exposure compensation.

1CameraPreview.getExposureCompensation(function(expoxureCompensation){
2  console.log(exposureCompensation);
3});

setExposureCompensation(exposureCompensation, [successCallback, errorCallback])

Set the exposure compensation for the camera device currently started. exposureCompensation accepts an integer. if exposureCompensation is lesser than the minimum exposure compensation, it is set to the minimum. if exposureCompensation is greater than the maximum exposure compensation, it is set to the maximum. (see getExposureCompensationRange() to get the minumum an maximum exposure compensation).

1CameraPreview.setExposureCompensation(-2);
2CameraPreview.setExposureCompensation(3);

setPreviewSize([dimensions, successCallback, errorCallback])

Change the size of the preview window.

1CameraPreview.setPreviewSize({width: window.screen.width, height: window.screen.height});

getSupportedPictureSizes(cb, [errorCallback])

1CameraPreview.getSupportedPictureSizes(function(dimensions){
2  // note that the portrait version, width and height swapped, of these dimensions are also supported
3  dimensions.forEach(function(dimension) {
4    console.log(dimension.width + 'x' + dimension.height);
5  });
6});

getCameraCharacteristics(cb, [errorCallback])

Get the characteristics of all available cameras. Returns a JSON object representing the characteristics of all available cameras.

1CameraPreview.getCameraCharacteristics(function(characteristics){
2  console.log(characteristics);
3});

Example Characteristics:

{
  "CAMERA_CHARACTERISTICS": [
    {
      "INFO_SUPPORTED_HARDWARE_LEVEL": 1,
      "LENS_FACING": 1,
      "SENSOR_INFO_PHYSICAL_SIZE_WIDTH": 5.644999980926514,
      "SENSOR_INFO_PHYSICAL_SIZE_HEIGHT": 4.434999942779541,
      "SENSOR_INFO_PIXEL_ARRAY_SIZE_WIDTH": 4032,
      "SENSOR_INFO_PIXEL_ARRAY_SIZE_HEIGHT": 3024,
      "LENS_INFO_AVAILABLE_FOCAL_LENGTHS": [
        {
          "FOCAL_LENGTH": 4.199999809265137
        }
      ]
    },

    {
      "INFO_SUPPORTED_HARDWARE_LEVEL": 0,
      "LENS_FACING": 0,
      "SENSOR_INFO_PHYSICAL_SIZE_WIDTH": 3.494999885559082,
      "SENSOR_INFO_PHYSICAL_SIZE_HEIGHT": 2.625999927520752,
      "SENSOR_INFO_PIXEL_ARRAY_SIZE_WIDTH": 2608,
      "SENSOR_INFO_PIXEL_ARRAY_SIZE_HEIGHT": 1960,
      "LENS_INFO_AVAILABLE_FOCAL_LENGTHS": [
        {
          "FOCAL_LENGTH": 2.0999999046325684
        }
      ]
    }
  ]
}

tapToFocus(xPoint, yPoint, [successCallback, errorCallback])

Set specific focus point. Note, this assumes the camera is full-screen.

1let xPoint = event.x;
2let yPoint = event.y
3CameraPreview.tapToFocus(xPoint, yPoint);

onBackButton(successCallback, [errorCallback])

Callback event for the back button tap

1CameraPreview.onBackButton(function() {
2  console.log('Back button pushed');
3});

getBlob(url, [successCallback, errorCallback])

When working with local files you may want to display those on certain containers like canvas, given that file:// is not always a valid url type, you need to first convert it explicitly to a blob, before you push it further into the display side. The function getBlob will do the proper conversion for you, and if succedeed will pass the content on it's callback function as first argument.

1
2function displayImage(content) {
3  var ctx = $("canvas").getContext('2d');
4
5  img.onload = function(){
6    ctx.drawImage(img, 0, 0)
7  }
8
9  img.src = URL.createObjectURL(blob);
10}
11
12function takePicture() {
13  CameraPreview.takePicture({width: app.dimension.width, height: app.dimension.height}, function(data){
14    if (cordova.platformId === 'android') {
15      CameraPreview.getBlob('file://' + data, function(image) {
16        displayImage(image);
17      });
18    } else {
19      displayImage('data:image/jpeg;base64,' + data);
20    }
21  });
22}

storeToFile

When capturing large images you rather want those to be stored into a file instead of having those base64 enconded, as enconding at least on Android is very expensive. With the feature storeToFile enabled the plugin will capture the image into a temporary file inside the application temporary cache (the same place where Cordova will extract your assets). NOTE: this method will overwrite any previous captured image for sake of simplicity, so if you want to capture multiple images and keep those, you will need assistance from some other plugin to rename the file or store somewhere else, this is made by design to keep the plugin simple. This method is better used with disableExifHeaderStripping to get the best possible performance.

Example:

1<script src="https://raw.githubusercontent.com/blueimp/JavaScript-Load-Image/master/js/load-image.all.min.js"></script>
2
3<p><div id="originalPicture" style="width: 100%"></div></p>

1let options = {
2  x: 0,
3  y: 0,
4  width: window.screen.width,
5  height: window.screen.height,
6  camera: CameraPreview.CAMERA_DIRECTION.BACK,
7  toBack: false,
8  tapPhoto: true,
9  tapFocus: false,
10  previewDrag: false,
11  disableExifHeaderStripping: true,
12  storeToFile: true
13};
14....
15
16function gotRotatedCanvas(canvasimg) {
17  var displayCanvas = $('canvas#display-canvas');
18  loadImage.scale(canvasimg, function(img){
19    displayCanvas.drawImage(img)
20  }, {
21    maxWidth: displayCanvas.width,
22    maxHeight: displayCanvas.height
23  });
24}
25
26CameraPreview.getSupportedPictureSizes(function(dimensions){
27  dimensions.sort(function(a, b){
28    return (b.width * b.height - a.width * a.height);
29  });
30  var dimension = dimensions[0];
31  CameraPreview.takePicture({width:dimension.width, height:dimension.height, quality: 85}, function(path){
32    var image = 'file://' + path;
33    let holder = document.getElementById('originalPicture');
34    let width = holder.offsetWidth;
35    loadImage(
36      image,
37      function(canvas) {
38        holder.innerHTML = "";
39        if (app.camera === 'front') {
40          // front camera requires we flip horizontally
41          canvas.style.transform = 'scale(1, -1)';
42        }
43        holder.appendChild(canvas);
44      },
45      {
46        maxWidth: width,
47        orientation: true,
48        canvas: true
49      }
50    );
51  });
52});

disableExifHeaderStripping

If you want to capture large images you will notice in Android that performace is very bad, in those cases you can set this flag, and add some extra Javascript/HTML to get a proper display of your captured images without risking your application speed.

Example:

1<script src="https://raw.githubusercontent.com/blueimp/JavaScript-Load-Image/master/js/load-image.all.min.js"></script>
2
3<p><div id="originalPicture" style="width: 100%"></div></p>

1let options = {
2  x: 0,
3  y: 0,
4  width: window.screen.width,
5  height: window.screen.height,
6  camera: CameraPreview.CAMERA_DIRECTION.BACK,
7  toBack: false,
8  tapPhoto: true,
9  tapFocus: false,
10  previewDrag: false,
11  disableExifHeaderStripping: true
12};
13....
14
15function gotRotatedCanvas(canvasimg) {
16  var displayCanvas = $('canvas#display-canvas');
17  loadImage.scale(canvasimg, function(img){
18    displayCanvas.drawImage(img)
19  }, {
20    maxWidth: displayCanvas.width,
21    maxHeight: displayCanvas.height
22  });
23}
24
25CameraPreview.getSupportedPictureSizes(function(dimensions){
26  dimensions.sort(function(a, b){
27    return (b.width * b.height - a.width * a.height);
28  });
29  var dimension = dimensions[0];
30  CameraPreview.takePicture({width:dimension.width, height:dimension.height, quality: 85}, function(base64PictureData){
31    /*
32      base64PictureData is base64 encoded jpeg image. Use this data to store to a file or upload.
33      Its up to the you to figure out the best way to save it to disk or whatever for your application.
34    */
35
36    var image = 'data:image/jpeg;base64,' + imgData;
37    let holder = document.getElementById('originalPicture');
38    let width = holder.offsetWidth;
39    loadImage(
40      image,
41      function(canvas) {
42        holder.innerHTML = "";
43        if (app.camera === 'front') {
44          // front camera requires we flip horizontally
45          canvas.style.transform = 'scale(1, -1)';
46        }
47        holder.appendChild(canvas);
48      },
49      {
50        maxWidth: width,
51        orientation: true,
52        canvas: true
53      }
54    );
55  });

Settings

FOCUS_MODE

Focus mode settings:

Name	Type	Default	Note
FIXED	string	fixed
AUTO	string	auto
CONTINUOUS	string	continuous	IOS Only
CONTINUOUS_PICTURE	string	continuous-picture	Android Only
CONTINUOUS_VIDEO	string	continuous-video	Android Only
EDOF	string	edof	Android Only
INFINITY	string	infinity	Android Only
MACRO	string	macro	Android Only

FLASH_MODE

Flash mode settings:

Name	Type	Default	Note
OFF	string	off
ON	string	on
AUTO	string	auto
RED_EYE	string	red-eye	Android Only
TORCH	string	torch

CAMERA_DIRECTION

Camera direction settings:

Name	Type	Default
BACK	string	back
FRONT	string	front

COLOR_EFFECT

Color effect settings:

Name	Type	Default	Note
AQUA	string	aqua	Android Only
BLACKBOARD	string	blackboard	Android Only
MONO	string	mono
NEGATIVE	string	negative
NONE	string	none
POSTERIZE	string	posterize
SEPIA	string	sepia
SOLARIZE	string	solarize	Android Only
WHITEBOARD	string	whiteboard	Android Only

EXPOSURE_MODE

Exposure mode settings:

Name	Type	Default	Note
AUTO	string	auto	IOS Only
CONTINUOUS	string	continuous
CUSTOM	string	custom
LOCK	string	lock	IOS Only

Note: Use AUTO to allow the device automatically adjusts the exposure once and then changes the exposure mode to LOCK.

WHITE_BALANCE_MODE

White balance mode settings:

Name	Type	Default	Note
LOCK	string	lock
AUTO	string	auto
CONTINUOUS	string	continuous	IOS Only
INCANDESCENT	string	incandescent
CLOUDY_DAYLIGHT	string	cloudy-daylight
DAYLIGHT	string	daylight
FLUORESCENT	string	fluorescent
SHADE	string	shade
TWILIGHT	string	twilight
WARM_FLUORESCENT	string	warm-fluorescent

IOS Quirks

It is not possible to use your computers webcam during testing in the simulator, you must device test.

Sample App

cordova-plugin-camera-preview-sample-app for a complete working Cordova example for Android and iOS platforms.

Screenshots

Credits

Maintained by Weston Ganger - @westonganger

Created by Marcel Barbosa Pinto @mbppower