Skip to content

AlbertoTrindade/project-oxford

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

74 Commits
dist
dist
 
 
src
src
 
 
test
test
 
 
.gitignore
.gitignore
 
 
.jscsrc
.jscsrc
 
 
.jshintrc
.jshintrc
 
 
.travis.yml
.travis.yml
 
 
Gruntfile.js
Gruntfile.js
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
jsconfig.json
jsconfig.json
 
 
package.json
package.json
 
 

Repository files navigation

Project Oxford for Node.js

npm version Build Status

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 Project Oxford's API for Faces, Vision, Text, Video, and WebLM.

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',
    analyzesAge: true,
    analyzesGender: true
}).then(function (response) {
    console.log('The age is: ' + response[0].attributes.age);
    console.log('The gender is: ' + response[0].attributes.gender);
});

Have a picture of a person and want a computed guess about their emotions?

client.emotion.analyzeEmotion({
    path: './myFace.jpg',
}).then(function (response) {
    console.log(response);
});

Or, you can add the rectangle of the face yourself, in the form "left,top,width,height". Delimited multiple face rectangles with a “;”.

client.emotion.analyzeEmotion({
    path: './myFace.jpg',
    faceRectangles: '10, 10, 100, 100'
}).then(function (response) {
    console.log(response);
});

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

Kind: global class

new Client(key)

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

Param Type Description
key string Project Oxford API Key

Client.emotion : object

Kind: static namespace of Client

emotion~analyzeEmotion(options) ⇒ Promise

Analyze the emotions of one or more faces in an image.

Kind: inner method of emotion
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
options Object Options object
options.url string URL to the image file
options.path string URL to a local image file
options.faceRectangles Array.<Object> Array of face rectangles. Face rectangles are returned in the face.detect and vision.analyzeImage methods.

Client.face : object

Kind: static namespace of Client

face.faceList : object

Kind: static namespace of face

faceList.list() ⇒ Promise

Lists the faceListIds, and associated names and/or userData.

Kind: static method of faceList
Returns: Promise - - Promise resolving with the resulting JSON

faceList.create(faceListId, options) ⇒ Promise

Creates a new face list with a user-specified ID. A face list is a list of faces associated to be associated with a given person.

Kind: static method of faceList
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
faceListId string Numbers, en-us letters in lower case, '-', '_'. Max length: 64
options object Optional parameters
options.name string Name of the face List
options.userData string User-provided data associated with the face list.

faceList.update(faceListId, options) ⇒ Promise

Creates a new person group with a user-specified ID. A person group is one of the most important parameters for the Identification API. The Identification searches person faces in a specified person group.

Kind: static method of faceList
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
faceListId string Numbers, en-us letters in lower case, '-', '_'. Max length: 64
options object Optional parameters
options.name string Name of the face List
options.userData string User-provided data associated with the face list.

faceList.delete(faceListId) ⇒ Promise

Deletes an existing person group.

Kind: static method of faceList
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
faceListId string ID of face list to delete

faceList.get(faceListId) ⇒ Promise

Gets an existing face list.

Kind: static method of faceList
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
faceListId string ID of face list to retrieve

faceList.addFace(faceListId, options) ⇒ Promise

Gets an existing face list.

Kind: static method of faceList
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
faceListId string ID of face list to retrieve
options object Options object
options.url string URL to image to be used
options.path string Path to image to be used
options.stream stream Stream for image to be used
options.name string Optional name for the face
options.userData string Optional user-data for the face

faceList.deleteFace(faceListId, persistedFaceId) ⇒ Promise

Delete a face from the face list. The face ID will be an ID returned in the addFace method, not from the detect method.

Kind: static method of faceList
Returns: Promise - - Promise; successful response is empty

Param Type Description
faceListId string ID of face list to retrieve
persistedFaceId string ID of face in the face list

face.personGroup : object

Kind: static namespace of face

personGroup.create(personGroupId, name, userData) ⇒ Promise

Creates a new person group with a user-specified ID. A person group is one of the most important parameters for the Identification API. The Identification searches person faces in a specified person group.

Kind: static method of personGroup
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string Numbers, en-us letters in lower case, '-', '_'. Max length: 64
name string Person group display name. The maximum length is 128.
userData string User-provided data attached to the group. The size limit is 16KB.

personGroup.delete(personGroupId) ⇒ Promise

Deletes an existing person group.

Kind: static method of personGroup
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string Name of person group to delete

personGroup.get(personGroupId) ⇒ Promise

Gets an existing person group.

Kind: static method of personGroup
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string Name of person group to get

personGroup.trainingStatus(personGroupId) ⇒ Promise

Retrieves the training status of a person group. Training is triggered by the Train PersonGroup API. The training will process for a while on the server side. This API can query whether the training is completed or ongoing.

Kind: static method of personGroup
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string Name of person group to get

personGroup.trainingStart(personGroupId) ⇒ Promise

Starts a person group training. Training is a necessary preparation process of a person group before identification. Each person group needs to be trained in order to call Identification. The training will process for a while on the server side even after this API has responded.

Kind: static method of personGroup
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string Name of person group to get

personGroup.update(personGroupId, name, userData) ⇒ Promise

Updates an existing person group's display name and userData.

Kind: static method of personGroup
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string Numbers, en-us letters in lower case, '-', '_'. Max length: 64
name string Person group display name. The maximum length is 128.
userData string User-provided data attached to the group. The size limit is 16KB.

personGroup.list() ⇒ Promise

Lists all person groups in the current subscription.

Kind: static method of personGroup
Returns: Promise - - Promise resolving with the resulting JSON

face.person : object

Kind: static namespace of face

person.addFace(personGroupId, personId, options) ⇒ Promise

Adds a face to a person for identification. The maximum face count for each person is 248.

Kind: static method of person
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string The target person's person group.
personId string The target person that the face is added to.
options object The source specification.
options.url string URL to image to be used.
options.path string Path to image to be used.
options.stream stream Stream for image to be used.
options.userData string Optional. Attach user data to person's face. The maximum length is 1024.
options.targetFace object Optional. The rectangle of the face in the image.

person.deleteFace(personGroupId, personId, persistedFaceId) ⇒ Promise

Deletes a face from a person.

Kind: static method of person
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string The target person's person group.
personId string The target person that the face is removed from.
persistedFaceId string The ID of the face to be deleted.

person.updateFace(personGroupId, personId, persistedFaceId, userData) ⇒ Promise

Updates a face for a person.

Kind: static method of person
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string The target person's person group.
personId string The target person that the face is updated on.
persistedFaceId string The ID of the face to be updated.
userData string Optional. Attach user data to person's face. The maximum length is 1024.

person.getFace(personGroupId, personId, persistedFaceId) ⇒ Promise

Get a face for a person.

Kind: static method of person
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string The target person's person group.
personId string The target person that the face is to get from.
persistedFaceId string The ID of the face to get.

person.create(personGroupId, name, userData) ⇒ Promise

Creates a new person in a specified person group for identification. The number of persons has a subscription limit. Free subscription amount is 1000 persons.

Kind: static method of person
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string The target person's person group.
name string Target person's display name. The maximum length is 128.
userData string Optional fields for user-provided data attached to a person. Size limit is 16KB.

person.delete(personGroupId, personId) ⇒ Promise

Deletes an existing person from a person group.

Kind: static method of person
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string The target person's person group.
personId string The target person to delete.

person.get(personGroupId, personId) ⇒ Promise

Gets an existing person from a person group.

Kind: static method of person
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string The target person's person group.
personId string The target person to get.

person.update(personGroupId, name, userData) ⇒ Promise

Updates a person's information.

Kind: static method of person
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string The target person's person group.
name string Target person's display name. The maximum length is 128.
userData string Optional fields for user-provided data attached to a person. Size limit is 16KB.

person.list(personGroupId) ⇒ Promise

Lists all persons in a person group, with the person information.

Kind: static method of person
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
personGroupId string The target person's person group.

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.

Kind: inner method of face
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.stream stream Stream for image to be used
options.returnFaceId boolean Include face ID in response?
options.analyzesFaceLandmarks boolean Analyze face landmarks?
options.analyzesAge boolean Analyze age?
options.analyzesGender boolean Analyze gender?
options.analyzesHeadPose boolean Analyze headpose?
options.analyzesSmile boolean Analyze smile?
options.analyzesFacialHair boolean Analyze facial hair?

face~similar(sourceFace, options) ⇒ Promise

Detect similar faces using faceIds (as returned from the detect API), or faceListId (as returned from the facelist API).

Kind: inner method of face
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
sourceFace string String of faceId for the source face
options object Options object
options.candidateFaces Array.<string> Array of faceIds to use as candidates
options.candidateFaceListId string Id of face list, created via FaceList.create
options.maxCandidates Number Optional max number for top candidates (default is 20, max is 20)

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.

Kind: inner method of face
Returns: Promise - - Promise resolving with the resulting JSON

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

face~identify(faces, personGroupId, maxNumOfCandidatesReturned) ⇒ 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.

Kind: inner method of face
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
faces Array.<string> Array of faceIds to use
personGroupId string Id of person group from which faces will be identified
maxNumOfCandidatesReturned Number Optional max number of candidates per face (default=1, max=5)

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.

Kind: inner method of face
Returns: Promise - - Promise resolving with the resulting JSON

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

Client.text : object

Kind: static namespace of Client

text~proof(text, preContextText, postContextText) ⇒ Promise

Proofs a word or phrase. Offers Microsoft Office Word-like spelling corrections. Longer phrases can be checked, and the result will include casing corrections while avoiding aggressive corrections.

Kind: inner method of text
Returns: Promise - - A promise in which the resulting JSON is returned.

Param Type Description
text string Word or phrase to spell check.
preContextText string Optional context of one or more words preceding the target word/phrase.
postContextText string Optional context of one or more words following the target word/phrase.

text~spellCheck(text, preContextText, postContextText) ⇒ Promise

Spell checks a word or phrase. Spell checks offers search-engine-like corrections. Short phrases (up to 9 tokens) will be checked, and the result will be optimized for search queries, both in terms of performance and relevance.

Kind: inner method of text
Returns: Promise - - A promise in which the resulting JSON is returned.

Param Type Description
text string Word or phrase to spell check.
preContextText string Optional context of one or more words preceding the target word/phrase.
postContextText string Optional context of one or more words following the target word/phrase.

Client.video : object

Kind: static namespace of Client

video.result

Kind: static property of video

result.get(operation) ⇒ Promise

Checks the result of a given operation. When an operation is deemed completed, the status of the returned object should be 'Succeeded' (or, possibly, 'Failed'.) For operations which return a JSON payload, the stringified-JSON is returned in the processingResult field. For operations which return a video, the location of the video is provided in the resourceLocation field. You can use the getVideo method to help you retrieve that, as this would automatically attach the API key to request.

Kind: static method of result
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
operation Object Object holding the result URL

result.getVideo(url, pipe) ⇒ Promise

Downloads the resulting video, for processors that returning videos instead of metadata. Currently this applies to the stabilize operation.

Kind: static method of result
Returns: Promise - - Promise resolving with the resulting video

Param Type Description
url string URL of the resource
pipe Object Destination for video, typically a fs object

video~trackFace(options) ⇒ Promise

Start a face-tracking processor Faces in a video will be tracked.

Kind: inner method of video
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
options object Options object
options.url string URL to video to be processed
options.path string Path to video to be processed
options.stream stream Stream for video to be processed

video~detectMotion(options) ⇒ Promise

Start a motion-tracking processor Motion in a video will be tracked.

Kind: inner method of video
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
options object Options object
options.url string URL to video to be processed
options.path string Path to video to be processed
options.stream stream Stream for video to be processed

video~stabilize(options) ⇒ Promise

Start a stablization processor A stabilized version of you video will be generated.

Kind: inner method of video
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
options object Options object
options.url string URL to video to be processed
options.path string Path to video to be processed
options.stream stream Stream for video to be processed

Client.vision : object

Kind: static namespace of Client

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.

Kind: inner method of vision
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.
options.Tags boolean Tags the image with a detailed list of words related to the image content.
options.Description boolean Describes the image content with a complete English sentence.

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.

Kind: inner method of vision
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.

Kind: inner method of vision
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

Client.weblm : object

Kind: static namespace of Client

weblm~listModels() ⇒ Promise

List available language models for the service currently.

Kind: inner method of weblm
Returns: Promise - - Promise resolving with the resulting JSON

weblm~breakIntoWords(model, text, options) ⇒ Promise

Breaks text in to consituent words

Kind: inner method of weblm
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
model string Name of model. Currently one of title/anchor/query/body
text string Text to break. E.g. onetwothree
options Object Options object
options.order Number Optional N-gram order. Default is 5
options.maxCandidates Number Optional maximum candidate count. Default is 5

weblm~generateWords(model, words, options) ⇒ Promise

Generates a list of candidate of words that would follow the a given sequence of one or more words

Kind: inner method of weblm
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
model string Name of model. Currently one of title/anchor/query/body
words string Text to break. E.g. 'hello world wide'
options Object Options object
options.order Number Optional N-gram order. Default is 5
options.maxCandidates Number Optional maximum candidate count. Default is 5

weblm~getJointProbabilities(model, phrases, order) ⇒ Promise

Generates a list of candidate of words that would follow the a given sequence of one or more words

Kind: inner method of weblm
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
model string Name of model. Currently one of title/anchor/query/body
phrases Array.<string> One or more phrases for which to look up the probalities of the word sequences
order Number Optional N-gram order. Default is 5

weblm~getConditionalProbabilities(model, queries, order) ⇒ Promise

Generates a list of candidate of words that would follow the a given sequence of one or more words

Kind: inner method of weblm
Returns: Promise - - Promise resolving with the resulting JSON

Param Type Description
model string Name of model. Currently one of title/anchor/query/body
queries Array One of more objects consisting of 'words'/'word' pairs, where the conditional probability of 'word' in the context of 'words' is computed.
order Number Optional N-gram order. Default is 5

License

Licensed as MIT - please see LICENSE for details.

About

🔭 Project Oxford for Node

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

3 watching

Forks

0 forks
Report repository

Releases

9 tags

Packages

No packages published

Languages

  • JavaScript 100.0%