/HAAR.js

Feature Detection based on Haar Cascades in JavaScript (Viola-Jones Algorithm)

Primary LanguageJavaScript

HAAR.js

Feature Detection Library for javascript (uses HTML5 canvas on browser and Canvas package on Node.js)

Based on Viola-Jones Feature Detection Algorithm using Haar Cascades

This is a port of OpenCV C++ Haar Detection (actually a port of JViolaJones which is a port of OpenCV for Java) to javascript and HTML5 canvas.

Light-weight (~10kB) minified.

Haar.js Face Detection Haar.js Many Faces Detection Haar.js Mouth Detection Haar.js Eyes Detection

###Contents

###Live Examples

###How To use You can use the existing openCV cascades to build your detectors.

To do this just transform the opencv xml file to javascript using the haartojs (php or java) tool (in cascades folder)

example: ( to use opencv's haarcascades_frontalface_alt.xml run following command)

haartojs haarcascades_frontalface_alt

this creates a javascript file:
haarcascades_frontalface_alt.js which you can include in your html file or node file

the variable to use in javascript is similarly
haarcascades_frontalface_alt

####Detector Methods

constructor()

new detector(haardata, Parallel);

Explanation of parameters

  • haardata : The actual haardata (as generated by haartojs tool), this is specific per feature, openCV haar data can be used.
  • Parallel : Optional, this is the Parallel object, as returned by the parallel.js script (included). It enables HAAR.js to run parallel computations both in browser and nodejs (much faster)

cascade()

detector.cascade(haardata);

Allow to use same detector (with its cached image data), to detect different feature on same image, by using another cascade. This way any image pre-processing is done only once

Explanation of parameters

  • haardata : The actual haardata (as generated by haartojs tool), this is specific per feature, openCV haar data can be used.

image()

detector.image(ImageOrVideoOrCanvas, scale, CanvasClass);

Explanation of parameters

  • ImageOrVideoOrCanvas : an actual Image or Video element or Canvas Object (in this case they are equivalent).
  • scale : The percent of scaling from the original image, so detection proceeds faster on a smaller image (default 0.5 ). NOTE scaling might alter the detection results sometimes, if having problems opt towards 1 (slower)
  • CanvasClass : This is optional and used only when running in nodejs (passing the node-canvas object).

interval()

detector.interval(detectionInterval);

Explanation of parameters

  • detectionInterval : interval to run the detection asynchronously (if not parallel) in microseconds (default 30).

selection()

detector.selection('auto'|object|feature|x [,y, width, height]);

Allow to set a custom region in the image to confine the detection process only in that region (eg detect nose while face already detected)

Explanation of parameters

  • 1st parameter : This can be the string 'auto' which sets the whole image as the selection, or an object ie: {x:10, y:'auto', width:100, height:'auto'} (every param set as 'auto' will take the default image value) or a detection rectangle/feature, or a x coordinate (along with rest coordinates).
  • y : (Optional) the selection start y coordinate, can be an actual value or 'auto' (y=0)
  • width : (Optional) the selection width, can be an actual value or 'auto' (width=image.width)
  • height : (Optional) the selection height, can be an actual value or 'auto' (height=image.height)

The actual selection rectangle/feature is available as this.Selection or detector.Selection

cannyThreshold()

detector.cannyThreshold({low: lowThreshold, high: highThreshold});

Set the thresholds when Canny Pruning is used, for extra fine-tuning. Canny Pruning detects the number/density of edges in a given region. A region with too few or too many edges is unlikely to be a feature. Default values work fine in most cases, however depending on image size and the specific feature, some fine tuning could be needed

Explanation of parameters

  • low : (Optional) The low threshold (default 20 ).
  • high : (Optional) The high threshold (default 100 ).

detect()

detector.detect(baseScale, scale_inc, increment, min_neighbors, doCannyPruning);

Explanation of parameters (JViolaJones Parameters)

  • baseScale : The initial ratio between the window size and the Haar classifier size (default 1 ).
  • scale_inc : The scale increment of the window size, at each step (default 1.25 ).
  • increment : The shift of the window at each sub-step, in terms of percentage of the window size (default 0.1 ).
  • min_neighbors : The minimum numbers of similar rectangles needed for the region to be considered as a feature (avoid noise) (default 1 )
  • doCannyPruning : enable Canny Pruning to pre-detect regions unlikely to contain features, in order to speed up the execution (optional default true ).

HAAR.js works in the browser and inside Node.js (supports parallel computations both in browser and node)

####Runing inside the brower Loading wth script tags You can run the example face.html or mouth.html inside your browser

####Running inside Node For running, the package have a dependency on canvas You can find an example inside examples/nodes.js Valid Output

node examples/node.js 
processing the picture
[{"x":102.5,"y":105.5,"width":160.66666666666666,"height":160.66666666666666}]

To work properly, canvas need some system depencencies. You can find instruction on https://github.com/LearnBoost/node-canvas/wiki For example for Ubuntu :

sudo apt-get install libcairo2-dev libjpeg8-dev libpango1.0-dev libgif-dev

####Loading with RequireJS As a third option, you can load the library with requireJS, both on the browser on with node. There is an example of loading with RequireJS inside node in examples/require.js. The configuration would be the same inside a browser

####Supporting parallel computation The parallel.js library is included in this repository, see the face.html example for how to use. In most cases using parallel computation (if supported) can be much faster (eg eye.html example)

###Where to find Haar Cascades xml files to use for feature detection

###Usage Ideas

###TODO

  • optimize detector for real-time usage on browsers (eg. -> https://github.com/liuliu/ccv) [DONE use parallel.js]
  • add selection option, detection is confined to that selection (eg detect nose while face already detected) [DONE]
  • check if some operations can use fixed-point arithmetic, or other micro-optimizations [DONE where applicable]
  • keep up with the changes in openCV cascades xml format (will try)
  • add some real performance tests (anyone interested??)

###ChangeLog

0.4.2

  • add cascade method to detect different feature(using other haar cascade) with same cached image data

0.4.1

  • cache image data to use with different selection (not re-compute if image is same but selection different)
  • inline the haar-tree and haar-leaf evaluators inside the haar-stage evaluator for speed

0.4

  • add selection option to confine detection to a specific image region
  • add fine-tuning for canny pruning thresholds
  • refactor/optimize merge method (filter features/rectangles that are inside other features), detection features may be slightly different now
  • reduce unnecessary loops/computations from java port (now it is more javascript-esque or in some cases even asm-esque)
  • implement fixed-point arithmetic where applicable (gray-scaling, canny computation, references included)
  • optimize array indexing (remove unnecessary multiplications use only additions/subtractions)
  • features are now custom classes with own methods (much easier to handle while backwards-compatible)
  • partial code refactoring / minor fixes
  • add more examples (eg many faces detection, tilted faces detection)
  • update Readme

0.3.1

  • fix ordering issue when using parallel computations (rectangles merged in random order)
  • fix dimensions computation when scale <> 1 (floating point numbers can give errors)
  • minor refactoring, optimizations

0.3

  • support optional parallel computation/detection (browser and nodejs) using parallel.js library (included)
  • refactoring of code

0.2.1

  • use TypedArrays if available for faster array operations
  • minor index/number optimizations

0.2

  • add haartojs tool in php (in cascades folder)
  • haartojs produces a javascript file using closures (fixes previous issue with the java tool)

0.1.1

  • customization to work with Node.js and require.js by maxired (using js closures)

0.1

  • initial commit by Nikos M. (works on browser)

URL Nikos Web Development
URL Haar.js blog post
URL WorkingClassCode