Project Oxford for Node.js

This package contains a set of intelligent APIs understanding images: It can detect and analyze people's faces, their age, gender, and similarity. It can identify people based on a set of images. It can understand what is displayed in a picture and crop it according to where the important features are. It can tell you whether an image contains adult content, what the main colors are, and which of your images belong in a group. If your image features text, it will tell you the language and return the text as a string. It's basically magic. For more details on the Project Oxford API, please visit projectoxford.ai.

This Node module implements all APIs available in the Face and Vision APIs of Project Oxford.

Usage

To install this package, run npm install --save project-oxford and obtain an API key. To obtain such a key, you will also need an (free) Microsoft Azure Account. Once you got your key, you can instantiate an Oxford client in your code:

var oxford = require('project-oxford'),
    client = new oxford.Client('7fb073s72bh72663y5ddh129m12e598d');

Now that you got your client running, you're ready to do some pretty smart stuff. Have a picture of a person and want a computed guess of their age and gender?

client.face.detect({
    path: 'myFolder/myFace.jpg',
    analyzeAge: true,
    analyzeGender: true
}).then(function (response) {
    console.log('The age is: ' + response.body.attributes.age);
    console.log('The gender is: ' + response.body.attributes.gender);
});

Creating a smart-cropped thumbnail:

client.vision.thumbnail({
    path: './photo.jpg',
    height: 150,
    width: 150,
    smartCropping: true,
    pipe: fs.createWriteStream('./photo2.jpg')
});

Running OCR on an image, returning the text on the image:

visionClient.vision.ocr({
    path: './test/images/ocr.jpg',
    language: 'en'
}).then(function (response) {
    console.log(response.body);
});

For the full documentation, please see the API reference below.

API Reference

• Client
  • new Client(key)
  • .face : object
    • .detect(options) ⇒ Promise
    • .similar(sourceFace, candidateFaces) ⇒ Promise
    • .grouping(faces) ⇒ Promise
    • .identify(faces) ⇒ Promise
    • .verify(faces) ⇒ Promise
  • .vision : object
    • .analyzeImage(options) ⇒ Promise
    • .thumbnail(options) ⇒ Promise
    • .ocr(options) ⇒ Promise

new Client(key)

Creates a new Project Oxford Client using a given API key.

Param	Type	Description
key	string	Project Oxford API Key

Client.face : object

Kind: static namespace of Client

• .face : object
  • ~detect(options) ⇒ Promise
  • ~similar(sourceFace, candidateFaces) ⇒ Promise
  • ~grouping(faces) ⇒ Promise
  • ~identify(faces) ⇒ Promise
  • ~verify(faces) ⇒ Promise

face.detect(options) ⇒ Promise

Call the Face Detected API Detects human faces in an image and returns face locations, face landmarks, and optional attributes including head-pose, gender, and age. Detection is an essential API that provides faceId to other APIs like Identification, Verification, and Find Similar.

Returns: Promise - Promise resolving with the resulting JSON

Param	Type	Description
options	object	Options object
options.url	string	URL to image to be used
options.path	string	Path to image to be used
options.analyzesFaceLandmarks	boolean	Analyze face landmarks?
options.analyzesAge	boolean	Analyze age?
options.analyzesGender	boolean	Analyze gender?
options.analyzesHeadPose	boolean	Analyze headpose?

face.similar(sourceFace, candidateFaces) ⇒ Promise

Detect similar faces using faceIds (as returned from the detect API)

Returns: Promise - Promise resolving with the resulting JSON

Param	Type	Description
sourceFace	string	String of faceId for the source face
candidateFaces	Array.<string>	Array of faceIds to use as candidates

face.grouping(faces) ⇒ Promise

Divides candidate faces into groups based on face similarity using faceIds. The output is one or more disjointed face groups and a MessyGroup. A face group contains the faces that have similar looking, often of the same person. There will be one or more face groups ranked by group size, i.e. number of face. Faces belonging to the same person might be split into several groups in the result. The MessyGroup is a special face group that each face is not similar to any other faces in original candidate faces. The messyGroup will not appear in the result if all faces found their similar counterparts. The candidate face list has a limit of 100 faces.

Returns: Promise - Promise resolving with the resulting JSON

Param	Type	Description
faces	Array.<string>	Array of faceIds to use

face.identify(faces) ⇒ Promise

Identifies persons from a person group by one or more input faces. To recognize which person a face belongs to, Face Identification needs a person group that contains number of persons. Each person contains one or more faces. After a person group prepared, it should be trained to make it ready for identification. Then the identification API compares the input face to those persons' faces in person group and returns the best-matched candidate persons, ranked by confidence.

Returns: Promise - Promise resolving with the resulting JSON

Param	Type	Description
faces	Array.<string>	Array of faceIds to use

face.verify(faces) ⇒ Promise

Analyzes two faces and determine whether they are from the same person. Verification works well for frontal and near-frontal faces. For the scenarios that are sensitive to accuracy please use with own judgment.

Returns: Promise - Promise resolving with the resulting JSON

Param	Type	Description
faces	Array.<string>	Array containing two faceIds to use

Client.vision : object

Kind: static namespace of Client

• .vision : object
  • ~analyzeImage(options) ⇒ Promise
  • ~thumbnail(options) ⇒ Promise
  • ~ocr(options) ⇒ Promise

vision.analyzeImage(options) ⇒ Promise

This operation does a deep analysis on the given image and then extracts a set of rich visual features based on the image content.

Returns: Promise - Promise resolving with the resulting JSON

Param	Type	Description
options	Object	Options object describing features to extract
options.url	string	Url to image to be analyzed
options.path	string	Path to image to be analyzed
options.ImageType	boolean	Detects if image is clipart or a line drawing.
options.Color	boolean	Determines the accent color, dominant color, if image is black&white.
options.Faces	boolean	Detects if faces are present. If present, generate coordinates, gender and age.
options.Adult	boolean	Detects if image is pornographic in nature (nudity or sex act). Sexually suggestive content is also detected.
options.Categories	boolean	Image categorization; taxonomy defined in documentation.

vision.thumbnail(options) ⇒ Promise

Generate a thumbnail image to the user-specified width and height. By default, the service analyzes the image, identifies the region of interest (ROI), and generates smart crop coordinates based on the ROI. Smart cropping is designed to help when you specify an aspect ratio that differs from the input image.

Returns: Promise - Promise resolving with the resulting JSON

Param	Type	Description
options	Object	Options object describing features to extract
options.url	string	Url to image to be thumbnailed
options.path	string	Path to image to be thumbnailed
options.width	number	Width of the thumb in pixels
options.height	number	Height of the thumb in pixels
options.smartCropping	boolean	Should SmartCropping be enabled?
options.pipe	Object	We'll pipe the returned image to this object

vision.ocr(options) ⇒ Promise

Optical Character Recognition (OCR) detects text in an image and extracts the recognized characters into a machine-usable character stream.

Returns: Promise - Promise resolving with the resulting JSON

Param	Type	Description
options	Object	Options object describing features to extract
options.url	string	Url to image to be analyzed
options.path	string	Path to image to be analyzed
options.language	string	BCP-47 language code of the text to be detected in the image. Default value is "unk", then the service will auto detect the language of the text in the image.
options.detectOrientation	string	Detect orientation of text in the image

License

Licensed as MIT - please see LICENSE for details.