Counting 1,690 Big Data & Machine Learning Frameworks, Toolsets, and Examples...
Suggestion? Feedback? Tweet @stkim1

Last Commit
Aug. 18, 2017
May. 30, 2017


Build Status NPM Version Downloads Join the chat at node TypeScript

Easy face recognition, verification, and clustering in JavaScript/Node.js.

Google Facenet

FaceNet is a deep convolutional network designed by Google, trained to solve face verification, recognition and clustering problem with efficiently at scale.

  1. directly learns a mapping from face images to a compact Euclidean space where distances directly correspond to a measure of face similarity.
  2. optimize the embedding face recognition performance using only 128-bytes per face.
  3. achieves accuracy of 99.63% on Labeled Faces in the Wild (LFW) dataset, and 95.12% on YouTube Faces DB.


The follow examples will give you some intuitions for using the code.

  1. visualize example will calculate the similarity between faces and draw them on the photo.
  2. demo exmaple will show you how to do align for face alignment and embedding to get face feature vector.

1. Visualize for Intuition

FaceNet Visualization

  1. Face is in the green rectangle.
  2. Similarity(distance) between faces showed as a number in the middle of the line.
  3. To identify if two faces belong to the same person, we could use an experiential threshold of distance: 0.75.
$ git clone [email protected]:zixia/facenet.git
$ cd facenet
$ npm install
$ npm run example:visualize

01:15:43 INFO CLI Visualized image saved to:  facenet-visulized.jpg

2. Demo for API Usage

TL;DR: Talk is cheap, show me the code!

import { Facenet, FaceImage } from 'facenet'

const facenet = new Facenet()

// Load image from file
const imageFile = `${__dirname}/../tests/fixtures/two-faces.jpg`
const image = new FaceImage(imageFile)

// Do Face Alignment, return faces
const faceList = await facenet.align(image)

for (const face of faceList) {
  // Calculate Face Embedding, return feature vector
  const embedding = await facenet.embedding(face)
  assert(face.embedding === embedding)

  console.log('bounding box:',  face.boundingBox)
  console.log('landmarks:',     face.facialLandmark)
  console.log('embedding:',     face.embedding)

Full source code can be found at here:

Try it by run:

$ git clone [email protected]:zixia/facenet.git
$ cd facenet
$ npm install
$ npm run example:demo

image file: /home/zixia/git/facenet/examples/../tests/fixtures/two-faces.jpg
face file: 1-1.jpg
bounding box: {
  p1: { x: 360, y: 95 }, 
  p2: { x: 589, y: 324 } 
landmarks: { 
  leftEye:  { x: 441, y: 181 },
  rightEye: { x: 515, y: 208 },
  nose:     { x: 459, y: 239 },
  leftMouthCorner:  { x: 417, y: 262 },
  rightMouthCorner: { x: 482, y: 285 } 
embedding: array([ 0.02453, 0.03973, 0.05397, ..., 0.10603, 0.15305,-0.07288])

face file: 1-2.jpg
bounding box: { 
  p1: { x: 142, y: 87 }, 
  p2: { x: 395, y: 340 } 
landmarks: { 
  leftEye:  { x: 230, y: 186 },
  rightEye: { x: 316, y: 197 },
  nose:     { x: 269, y: 257 },
  leftMouthCorner:  { x: 223, y: 273 },
  rightMouthCorner: { x: 303, y: 281 } 
embedding: array([ 0.03241, -0.0737,  0.0475, ..., 0.07235, 0.12581,-0.00817])

Install & Requirement

$ npm install facenet



  • Linux
  • Mac
  • Windows


  1. Node.js >= 7 (8 is recommend)
  2. Tensorflow >= 1.2
  3. Python >=3.5 (3.6 is recommend)


Neural Network Model Task Ram
MTCNN Facenet#align() 100MB
Facenet Facenet#embedding() 2GB

If you are dealing with very large images(like 3000x3000 pixels), there will need additional 1GB of memory.

So I believe that Facenet will need at least 2GB memory, and >=4GB is recommended.



import { Facenet } from 'facenet'

const facenet = new Facenet()

1. Facenet#align(image: FaceImage): Promise<Face[]>

Do face alignment for the image, return a list of faces.

2. Facenet#embedding(face: Face): Promise<FaceEmbedding>

Get the embedding for a face.


Get the 128 dim embedding vector for this face.(After alignment)

import { Face } from 'facenet'

console.log('bounding box:',  face.boundingBox)
console.log('landmarks:',     face.facialLandmark)
console.log('embedding:',     face.embedding)'/tmp/face.jpg')


import { FaceImage } from 'facenet'

const image = new FaceImage('tests/fixtures/two-faces.jpg')
image.resize(160, 160)'/tmp/image.jpg')

Environment Variables


FaceNet neural network model files, set to other version of model as you like.

Default is set to models/ directory inside project directory. The pre-trained models is come from 20170512-110547, 0.992, MS-Celeb-1M, Inception ResNet v1, which will be download & save automatically by postinstall script.

$ pwd

$ ls models/


Docker Pulls Docker Stars Docker Layers


Issue Stats Issue Stats Coverage Status Greenkeeper badge

$ git clone [email protected]:zixia/facenet.git
$ cd facenet
$ npm install
$ npm test

Command Line Interface


Draw a rectangle with five landmarks on all faces in the input_image, save it to output_image.

$ ./node_modules/.bin/ts-node bin/align.ts input_image output_image


Output the 128 dim embedding vector of the face image.

$ ./node_modules/.bin/ts-node bin/embedding.ts face_image


Machine Learning


1. Typing

1. NumJS


  1. LFW - Labeled Faces in the Wild


  • NPM Module: facenet
  • Docker Image: zixia/facenet
  • Examples
    • API Usage Demo
    • Triple Distance Visulization Demo
    • Performance Test(Align/Embedding/Batch)
    • Validation Test(LFW Accuracy)
  • Neural Network Models
  • Python async & await
  • Divide Different Neural Network to seprate class files(e.g. Facenet/Mtcnn/ChineseWhisper)
  • TensorFlow Sereving
  • OpenAPI Specification(Swagger)


This repository is heavily inspired by the following implementations:


  1. Face alignment using MTCNN: Joint Face Detection and Alignment using Multi-task Cascaded Convolutional Networks
  2. Face embedding using FaceNet: FaceNet: A Unified Embedding for Face Recognition and Clustering
  3. TensorFlow implementation of the face recognizer: Face recognition using Tensorflow


FaceNet Badge

Powered by FaceNet

[![Powered by FaceNet](](


Huan LI <[email protected]> (

I'm an active angel investor, serial entrepreneur with strong technical background and rich social network experience.

profile for zixia at Stack Overflow, Q&A for professional and enthusiast programmers

Copyright & License