diff-cam-engine

Core engine for building motion detection web apps.

Usage

diff-cam-engine.js provides a DiffCamEngine object that accesses the webcam, captures images from it, and evaluates motion.

You'll want to use the adapter.js shim, which is available here: https://github.com/webrtc/adapter. Add it before diff-cam-engine.js.

With that in place, call DiffCamEngine.init() to initialize. This will set things up and ask the user for permission to access the webcam.

DiffCamEngine.init({
	// config options go here
});

Then call start() to begin the actual motion sensing. Do not call start() before init() has finished. It's a good idea to call start() from initSuccessCallback() (more on this later).

Call stop() to turn things off.

Configuration

You can customize how DiffCamEngine behaves by passing an object of name/value pairs into init(). For example:

DiffCamEngine.init({
	video: myVideo,
	captureIntervalTime: 50,
	captureCallback: myCaptureHandler
	// etc.
});

Variables

The following variables can be passed into init():

Name	Default	Description
video	internal <video> (not visible)	The <video> element for showing the live webcam stream
motionCanvas	internal <canvas> (not visible)	The <canvas> element for showing the visual motion heatmap
captureIntervalTime	100	Number of ms between capturing images from the stream
captureWidth	640	Width of captured images from stream
captureHeight	480	Height of capture images from stream
diffWidth	64	Width of (usually downsized) images used for diffing and showing motion
diffHeight	48	Height of (usually downsized) images used for diffing and showing motion
pixelDiffThreshold	32	Minimum difference in a pixel to be considered changed
scoreThreshold	16	Minimum number of changed pixels for an image to be considered as having motion
includeMotionBox	false	Flag to calculate and display (on motionCanvas) the bounding box of motion
includeMotionPixels	false	Flag to include data indicating all the changed pixels

Callbacks

There are also a couple callback functions you can specify. This is the primary way of interacting with DiffCamEngine during execution. Pass these into init() just like the variables above.

Name	Description
initSuccessCallback	Called when init has successfully completed
initErrorCallback	Called when init fails
startCompleteCallback	Called once the webcam has begun streaming
captureCallback	Called after a captured image from the stream has been evaluated

captureCallback is the only one with a parameter. This parameter is an object with multiple properties on it. These properties are:

Property	Description
imageData	The imageData object for the captured image
score	The evaluated score for the captured image
hasMotion	Whether or not the score meets the score threshold for motion
motionBox	An object containg x min/max and y min/max for a box wrapping the region in which motion occurred, only returned if includeMotionBox is true
motionPixels	An object containg each pixel in the image that changed (indicating motion), only returned if includeMotionPixels is true
getURL	Convenience function, returns imageData converted to a URL suitable for setting as the src of an image
checkMotionPixel	Convenience function, takes in an x and y cooridnate, returns a boolean indicating if the pixel at that location has changed

Functions

DiffCamEngine exposes the following public functions:

Function	Description
init	Initializes everything and requests permission to access the webcam
start	Begin streaming from the webcam
stop	Stop streaming from the webcam
getPixelDiffThreshold	Get pixelDiffThreshold during execution
setPixelDiffThreshold	Set pixelDiffThreshold during execution
getScoreThreshold	Get scoreThreshold during execution
setScoreThreshold	Set scoreThreshold during execution

Examples

Check out https://github.com/lonekorean/diff-cam-scratchpad (specifically /diff-cam-example and /turret-security) for examples that use diff-cam-engine. Check out https://github.com/lonekorean/diff-cam-feed for a more complex web app powered by diff-cam-engine.