faced is a light-weight library to identify faces and it's features such as eyes, nose and mouth
JavaScript Shell
Latest commit 148a5eb Oct 18, 2016 @gordalina Add Travis CI
Failed to load latest commit information.
.travis Add Travis CI Oct 19, 2016
examples Fix issue #7: Feature points gone wrong Jul 11, 2016
images Add Lenna & features Mar 6, 2013
lib Set faced as a function Nov 15, 2013
test Add integration test Oct 18, 2016
.gitignore Initial import (0.0.1) Feb 2, 2013
.travis.yml Add Travis CI Oct 19, 2016
LICENSE Initial import (0.0.1) Feb 2, 2013
README.md Add Travis CI Oct 19, 2016
package.json Add Travis CI Oct 19, 2016



Build Status

faced is a light-weight library for face recognition including features such as eyes, nose and mouth. It requires opencv.

Face is outlined in black, the eyes are red & green for left and right respectively, the nose is outlined in white and the mouth in blue.



Make sure you have OpenCV v2.4.x installed on your machine.

For MacOS X you can use Homebrew

$ brew tap homebrew/science
$ brew install opencv

# If you are running macOS 10.12 (Sierra) use the following command
# See: https://github.com/Homebrew/homebrew-science/issues/4303
$ brew install opencv --HEAD


As a dependency to your project

$ npm install --save faced


$ npm install -g faced

Identify your first face

var Faced = require('faced');
var faced = new Faced();

faced.detect('image.jpg', function (faces, image, file) {
  if (!faces) {
    return console.log("No faces found!");

  var face = faces[0];

    "Found a face at %d,%d with dimensions %dx%d",

    "What a pretty face, it %s a mouth, it %s a nose, it % a left eye and it %s a right eye!",
    face.getMouth() ? "has" : "does not have",
    face.getNose() ? "has" : "does not have",
    face.getEyeLeft() ? "has" : "does not have",
    face.getEyeRight() ? "has" : "does not have"

Its that simple! See the program used to generate the above image


Faced.detect(source, function, context)

Loads an image from source which can be a file path or a buffer and executes function upon completion.

The callback function expects a prototype like function (faces, image, file) { }, where the first is an array of Face, the second is a Matrix object from opencv and the third is the path of the image.

In case of error the arguments faces and image will be undefined.

Class Feature

  • Feature.getX() Returns the upper left corner X position of the face
  • Feature.getY() Returns the upper left corner Y position of the face
  • Feature.getX2() Returns the lower right corner X position of the face
  • Feature.getY2() Returns the lower right conrner Y position of the face
  • Feature.getWidth() Returns the width
  • Feature.getHeight() Returns the height
  • Feature.intersect(Feature) Returns the percentage of shared spaced that the current feature has with the given argument Feature. Although this is used internally it might be useful for client usage.

Class Face (extends Feature)

All of the following method1s return an instance of Feture or undefined if it could not detect.

  • Face.getMouth()
  • Face.getNose()
  • Face.getEyeLeft()
  • Face.getEyeRight()

Other significant methods

  • Face.getFeature(name) Returns a feature by name. Possible names are: mouth, nose, eyeLeft and eyeRight.
  • Face.getFeatures() Returns an array of Feature that the instance has detected.
  • Face.getFeatureCount() Returns the number of detected features.


$ node examples/identify.js images/lenna.png

Then open images/lenna.features.png on your favourite image viewer.



faced is licensed under the MIT license


Copyright (c) 2013, Samuel Gordalina samuel.gordalina@gmail.com