Developer Info

Before You Start

1. Stay up to date

Before going deep with ezAR, check out the latest progress report to learn what's new and about any known issues. Even better sign up for the ezAR Newsletter at the bottom of the page.

2. New to Cordova Hybrid-Mobile SDK 

ezAR is provided as a plugin for the Apache Cordova SDK and Cordova-compatible  SDKs such as PhoneGap,  Ionic, Sencha and others. If you are new to software development using the Cordova SDK see the resources section at the bottom of this page.

3. Quick overview

ezAR is comprised of 4 Cordova plugins:

  • video overlay - overlays the Cordova WebView on top of a video preview from a device camera
  • face detector - detect human faces present in the camera view of the video overlay plugin
  • flashlight - turn the device light on and off
  • snapshot - capture screenshots of the application user interface

Based on the needs of your app the plugins can be used individual or combined in any combination. See the plugin api descriptions below.


Download and Installing ezAR SDK

1. Download

Download the ezAR Startup Kit (zip) from here

2. Install ezAR Startup Kit Software

  1. Unzip the ezAR using your favorite Zip file utility,  e.g., WinZip or 7-Zip to your local file system. 
  2. ezAR includes 4 Cordova plugins that you can use separately or together in your app. Install the ezAR plugins into your Cordova-compatible project.

cordova plugin add <path-to-ezar-software>/plugins/com.ezartech.ezar.<plugin>

The plugin names are:

com.ezartech.ezar.videooverlay 
com.ezartech.ezar.facedetector
com.ezartech.ezar.flashlight

com.ezartech.ezar.snapshot

   example - from Cordova commandline enter
     cordova plugin add plugins/com.ezartech.ezar.videooverlay
     cordova plugin add plugins/com.ezartech.ezar.snapshot
     cordova plugin add plugins/com.ezartech.ezar.flashlight
     cordova plugin add plugins/com.ezartech.ezar.facedetector

ezAR Use-Cases & Snippets

This snippet initializes ezAR video-overlay, starts the camera on the back of the device and lastly sets the HTML <body> background color transparent. The HTML UI renders on top of a video feed. Setting its background transparent makes the video visible. 

ezar.initializeVideoOverlay(
  function() {
    ezar.getBackCamera().start();
    document.body.style.backgroundColor = 'transparent';
  },
  function(error) {
    alert("ezar initialization failed");
  });

Step-1: Initialize ezAR video-overlay (line 1)

Before using the full ezAR JavaScript API it must first be initialized using the global, ezar  initialize() method. This asynchronous methods sets up the native mobile services, including a camera view that is created and positioned below the Cordova WebView.  Live video captured by one of a mobile device camera is rendered onto the camera view.  Upon completion you can access all other ezar methods.

ezar.initializeVideoOverlay(successCB,errorCB)
parameters successCB - function called on successful initialization errorCB - function called on initialization failure

Step-2: Select a Camera (line 3)

Next select the camera by its FRONT or BACK position on the device. Most devices are equipped with at least 1 camera usually located on  the back of the device.  An additional camera mounted on the front (the selfie camera) of the device is also common on the newer high end mobile devices.

var backCamera = ezar.getBackCamera();
var frontCamera = ezar.getFrontCamera();

Step-3: Start the Camera (line 3)

Use the ezAR camera's asynchronous start() method to initiate video capture and rendering from the corresponding device camera.  The camera is rendered onto  the camera view below the Cordova WebView control. 

camera.start(successCB,errorCB)
  parameters
    successCB - function called on success 
    errorCB - function called on failure with error data

NOTE: In addition to starting the camera you must also configure the web UI to be transparent otherwise the video will not be visible. You can set the entire display or a region of the web UI transparent. The example below programmatically sets the HTML document <body> to be transparent. 

Step-4: Adjust Camera Zoom Level (line 4)

Most device cameras support zooming (aka scaling) the camera. The camera api includes the following methods for adjusting the camera zoom level:

camera.hasZoom()
  returns true if camera supports zoom level adjustment
  

camera.getZoom()
  returns scaling factor as a float on range [1.0, maxZoom]
 

camera.setZoom(aFloat)
  parameters
    aFloat - set scaling factor, on range [1.0, maxZoom]


camera.getMaxZoom()
  returns maximum level of the zoom range

Step-5: Control the Device Light

Install the com.ezartech.ezar.flashlight plugin to detect and control the device light. Call ezar.initializeLight() before attempting to turn the device light on. See the full Flashlight api documentation below.

ezar.initializeLight(
  function() {
    if (ezar.hasLight() {
      ezar.setLightOn();
    }
  },
  function(error) {
    alert("ezar light initialization failed");
  }); 

Step-6: Snapshot

Install the com.ezartech.ezar.snapshot plugin to enable capturing screenshots of the app user interface. In this example save a PNG snapshot to the device photo gallery.

ezar.snapshot(
  function(base64EncodedImage) {
    //do something with snapshot image here
  },
  function(error) {
    alert("ezar snapshot failed");
  },
  {"saveToPhotoGallery": true,
   "encoding": ezar.ImageEncoding.PNG}
  ); 

Step-7: Stop the Camera

Finally use the stop() method  to discontinue video rendering. This operation executes asynchronous.

camera.stop(successCB,errorCB)
  parameters
    successCB - function called on success 
    errorCB - function called on failure with error data

Step-7: Resume the Camera

When a camera is stopped it can be resumed using the start() method. Alternatively if the device is equipped with front and back cameras you can switch between them. You do not have to stop the current camera before starting another camera. ezAR automatically handles  the internal state of the cameras. 

updated 20160915
 
 
ic_file_download_grey600_48dp.png
 
 
ic_camera_alt_grey600_48dp.png
 
 


Resources

Apache Cordova Developer Guide

Cordova "Getting Started" Tutorial

Ionic Framework - popular free UI framework based on Angular.js

Ionic Tutorials and Videos