<commit_before>## Project Oxford for Node.js
[![npm version](https://badge.fury.io/js/project-oxford.svg)](http://badge.fury.io/js/project-oxford)

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](http://www.projectoxford.ai/demo/face#detection).

This Node module implements Project Oxford's API for Faces, Vision, Text, Video, and WebLM.

![](https://i.imgur.com/Zrsnhd3.jpg)

## Usage
To install this package, run `npm install --save project-oxford` [and obtain an API key](http://www.projectoxford.ai/doc/general/subscription-key-mgmt). To obtain such a key, [you will also need an (free) Microsoft Azure Account](http://www.azure.com). 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:
```
client.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
<a name="Client"></a>

## Client
**Kind**: global class  

* [Client](#Client)
    * [new Client(key, host)](#new_Client_new)
    * [.emotion](#Client.emotion) : <code>object</code>
        * [~analyzeEmotion(options)](#Client.emotion..analyzeEmotion) ⇒ <code>Promise</code>
    * [.face](#Client.face) : <code>object</code>
        * _static_
            * [.faceList](#Client.face.faceList) : <code>object</code>
                * [.list()](#Client.face.faceList.list) ⇒ <code>Promise</code>
                * [.create(faceListId, options)](#Client.face.faceList.create) ⇒ <code>Promise</code>
                * [.update(faceListId, options)](#Client.face.faceList.update) ⇒ <code>Promise</code>
                * [.delete(faceListId)](#Client.face.faceList.delete) ⇒ <code>Promise</code>
                * [.get(faceListId)](#Client.face.faceList.get) ⇒ <code>Promise</code>
                * [.addFace(faceListId, options)](#Client.face.faceList.addFace) ⇒ <code>Promise</code>
                * [.deleteFace(faceListId, persistedFaceId)](#Client.face.faceList.deleteFace) ⇒ <code>Promise</code>
            * [.personGroup](#Client.face.personGroup) : <code>object</code>
                * [.create(personGroupId, name, userData)](#Client.face.personGroup.create) ⇒ <code>Promise</code>
                * [.delete(personGroupId)](#Client.face.personGroup.delete) ⇒ <code>Promise</code>
                * [.get(personGroupId)](#Client.face.personGroup.get) ⇒ <code>Promise</code>
                * [.trainingStatus(personGroupId)](#Client.face.personGroup.trainingStatus) ⇒ <code>Promise</code>
                * [.trainingStart(personGroupId)](#Client.face.personGroup.trainingStart) ⇒ <code>Promise</code>
                * [.update(personGroupId, name, userData)](#Client.face.personGroup.update) ⇒ <code>Promise</code>
                * [.list()](#Client.face.personGroup.list) ⇒ <code>Promise</code>
            * [.person](#Client.face.person) : <code>object</code>
                * [.addFace(personGroupId, personId, options)](#Client.face.person.addFace) ⇒ <code>Promise</code>
                * [.deleteFace(personGroupId, personId, persistedFaceId)](#Client.face.person.deleteFace) ⇒ <code>Promise</code>
                * [.updateFace(personGroupId, personId, persistedFaceId, userData)](#Client.face.person.updateFace) ⇒ <code>Promise</code>
                * [.getFace(personGroupId, personId, persistedFaceId)](#Client.face.person.getFace) ⇒ <code>Promise</code>
                * [.create(personGroupId, name, userData)](#Client.face.person.create) ⇒ <code>Promise</code>
                * [.delete(personGroupId, personId)](#Client.face.person.delete) ⇒ <code>Promise</code>
                * [.get(personGroupId, personId)](#Client.face.person.get) ⇒ <code>Promise</code>
                * [.update(personGroupId, personId, name, userData)](#Client.face.person.update) ⇒ <code>Promise</code>
                * [.list(personGroupId)](#Client.face.person.list) ⇒ <code>Promise</code>
        * _inner_
            * [~detect(options)](#Client.face..detect) ⇒ <code>Promise</code>
            * [~similar(sourceFace, options)](#Client.face..similar) ⇒ <code>Promise</code>
            * [~grouping(faces)](#Client.face..grouping) ⇒ <code>Promise</code>
            * [~identify(faces, personGroupId, maxNumOfCandidatesReturned, confidenceThreshold)](#Client.face..identify) ⇒ <code>Promise</code>
            * [~verify(faces)](#Client.face..verify) ⇒ <code>Promise</code>
    * [.text](#Client.text) : <code>object</code>
        * [~proof(text, preContextText, postContextText, market)](#Client.text..proof) ⇒ <code>Promise</code>
        * [~spellCheck(text, preContextText, postContextText, market)](#Client.text..spellCheck) ⇒ <code>Promise</code>
    * [.video](#Client.video) : <code>object</code>
        * _static_
            * [.result](#Client.video.result)
                * [.get(operation)](#Client.video.result.get) ⇒ <code>Promise</code>
                * [.getVideo(url, pipe)](#Client.video.result.getVideo) ⇒ <code>Promise</code>
        * _inner_
            * [~trackFace(options)](#Client.video..trackFace) ⇒ <code>Promise</code>
            * [~detectMotion(options)](#Client.video..detectMotion) ⇒ <code>Promise</code>
            * [~stabilize(options)](#Client.video..stabilize) ⇒ <code>Promise</code>
    * [.vision](#Client.vision) : <code>object</code>
        * _static_
            * [.result](#Client.vision.result)
                * [.get(operation)](#Client.vision.result.get) ⇒ <code>Promise</code>
            * [.models](#Client.vision.models) : <code>object</code>
                * [.list()](#Client.vision.models.list) ⇒ <code>Promise</code>
                * [.analyzeImage(model, options)](#Client.vision.models.analyzeImage) ⇒ <code>Promise</code>
        * _inner_
            * [~analyzeImage(options)](#Client.vision..analyzeImage) ⇒ <code>Promise</code>
            * [~thumbnail(options)](#Client.vision..thumbnail) ⇒ <code>Promise</code>
            * [~ocr(options)](#Client.vision..ocr) ⇒ <code>Promise</code>
            * [~recognizeText(options)](#Client.vision..recognizeText) ⇒ <code>Promise</code>
    * [.weblm](#Client.weblm) : <code>object</code>
        * [~listModels()](#Client.weblm..listModels) ⇒ <code>Promise</code>
        * [~breakIntoWords(model, text, options)](#Client.weblm..breakIntoWords) ⇒ <code>Promise</code>
        * [~generateWords(model, words, options)](#Client.weblm..generateWords) ⇒ <code>Promise</code>
        * [~getJointProbabilities(model, phrases, order)](#Client.weblm..getJointProbabilities) ⇒ <code>Promise</code>
        * [~getConditionalProbabilities(model, queries, order)](#Client.weblm..getConditionalProbabilities) ⇒ <code>Promise</code>

<a name="new_Client_new"></a>

### new Client(key, host)
Creates a new Project Oxford Client using a given API key.


| Param | Type | Description |
| --- | --- | --- |
| key | <code>string</code> | Project Oxford API Key |
| host | <code>string</code> | Optional host address |

<a name="Client.emotion"></a>

### Client.emotion : <code>object</code>
**Kind**: static namespace of <code>[Client](#Client)</code>  
<a name="Client.emotion..analyzeEmotion"></a>

#### emotion~analyzeEmotion(options) ⇒ <code>Promise</code>
Analyze the emotions of one or more faces in an image.

**Kind**: inner method of <code>[emotion](#Client.emotion)</code>  
**Returns**: <code>Promise</code> - - Promise resolving with the resulting JSON  

| Param | Type | Description |
| --- | --- | --- |<commit_msg>Update argument description for client constructor<commit_after>## Project Oxford for Node.js
[![npm version](https://badge.fury.io/js/project-oxford.svg)](http://badge.fury.io/js/project-oxford)

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](http://www.projectoxford.ai/demo/face#detection).

This Node module implements Project Oxford's API for Faces, Vision, Text, Video, and WebLM.

![](https://i.imgur.com/Zrsnhd3.jpg)

## Usage
To install this package, run `npm install --save project-oxford` [and obtain an API key](http://www.projectoxford.ai/doc/general/subscription-key-mgmt). To obtain such a key, [you will also need an (free) Microsoft Azure Account](http://www.azure.com). 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:
```
client.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
<a name="Client"></a>

## Client
**Kind**: global class  

* [Client](#Client)
    * [new Client(key, hostOrRegion)](#new_Client_new)
    * [.emotion](#Client.emotion) : <code>object</code>
        * [~analyzeEmotion(options)](#Client.emotion..analyzeEmotion) ⇒ <code>Promise</code>
    * [.face](#Client.face) : <code>object</code>
        * _static_
            * [.faceList](#Client.face.faceList) : <code>object</code>
                * [.list()](#Client.face.faceList.list) ⇒ <code>Promise</code>
                * [.create(faceListId, options)](#Client.face.faceList.create) ⇒ <code>Promise</code>
                * [.update(faceListId, options)](#Client.face.faceList.update) ⇒ <code>Promise</code>
                * [.delete(faceListId)](#Client.face.faceList.delete) ⇒ <code>Promise</code>
                * [.get(faceListId)](#Client.face.faceList.get) ⇒ <code>Promise</code>
                * [.addFace(faceListId, options)](#Client.face.faceList.addFace) ⇒ <code>Promise</code>
                * [.deleteFace(faceListId, persistedFaceId)](#Client.face.faceList.deleteFace) ⇒ <code>Promise</code>
            * [.personGroup](#Client.face.personGroup) : <code>object</code>
                * [.create(personGroupId, name, userData)](#Client.face.personGroup.create) ⇒ <code>Promise</code>
                * [.delete(personGroupId)](#Client.face.personGroup.delete) ⇒ <code>Promise</code>
                * [.get(personGroupId)](#Client.face.personGroup.get) ⇒ <code>Promise</code>
                * [.trainingStatus(personGroupId)](#Client.face.personGroup.trainingStatus) ⇒ <code>Promise</code>
                * [.trainingStart(personGroupId)](#Client.face.personGroup.trainingStart) ⇒ <code>Promise</code>
                * [.update(personGroupId, name, userData)](#Client.face.personGroup.update) ⇒ <code>Promise</code>
                * [.list()](#Client.face.personGroup.list) ⇒ <code>Promise</code>
            * [.person](#Client.face.person) : <code>object</code>
                * [.addFace(personGroupId, personId, options)](#Client.face.person.addFace) ⇒ <code>Promise</code>
                * [.deleteFace(personGroupId, personId, persistedFaceId)](#Client.face.person.deleteFace) ⇒ <code>Promise</code>
                * [.updateFace(personGroupId, personId, persistedFaceId, userData)](#Client.face.person.updateFace) ⇒ <code>Promise</code>
                * [.getFace(personGroupId, personId, persistedFaceId)](#Client.face.person.getFace) ⇒ <code>Promise</code>
                * [.create(personGroupId, name, userData)](#Client.face.person.create) ⇒ <code>Promise</code>
                * [.delete(personGroupId, personId)](#Client.face.person.delete) ⇒ <code>Promise</code>
                * [.get(personGroupId, personId)](#Client.face.person.get) ⇒ <code>Promise</code>
                * [.update(personGroupId, personId, name, userData)](#Client.face.person.update) ⇒ <code>Promise</code>
                * [.list(personGroupId)](#Client.face.person.list) ⇒ <code>Promise</code>
        * _inner_
            * [~detect(options)](#Client.face..detect) ⇒ <code>Promise</code>
            * [~similar(sourceFace, options)](#Client.face..similar) ⇒ <code>Promise</code>
            * [~grouping(faces)](#Client.face..grouping) ⇒ <code>Promise</code>
            * [~identify(faces, personGroupId, maxNumOfCandidatesReturned, confidenceThreshold)](#Client.face..identify) ⇒ <code>Promise</code>
            * [~verify(faces)](#Client.face..verify) ⇒ <code>Promise</code>
    * [.text](#Client.text) : <code>object</code>
        * [~proof(text, preContextText, postContextText, market)](#Client.text..proof) ⇒ <code>Promise</code>
        * [~spellCheck(text, preContextText, postContextText, market)](#Client.text..spellCheck) ⇒ <code>Promise</code>
    * [.video](#Client.video) : <code>object</code>
        * _static_
            * [.result](#Client.video.result)
                * [.get(operation)](#Client.video.result.get) ⇒ <code>Promise</code>
                * [.getVideo(url, pipe)](#Client.video.result.getVideo) ⇒ <code>Promise</code>
        * _inner_
            * [~trackFace(options)](#Client.video..trackFace) ⇒ <code>Promise</code>
            * [~detectMotion(options)](#Client.video..detectMotion) ⇒ <code>Promise</code>
            * [~stabilize(options)](#Client.video..stabilize) ⇒ <code>Promise</code>
    * [.vision](#Client.vision) : <code>object</code>
        * _static_
            * [.result](#Client.vision.result)
                * [.get(operation)](#Client.vision.result.get) ⇒ <code>Promise</code>
            * [.models](#Client.vision.models) : <code>object</code>
                * [.list()](#Client.vision.models.list) ⇒ <code>Promise</code>
                * [.analyzeImage(model, options)](#Client.vision.models.analyzeImage) ⇒ <code>Promise</code>
        * _inner_
            * [~analyzeImage(options)](#Client.vision..analyzeImage) ⇒ <code>Promise</code>
            * [~thumbnail(options)](#Client.vision..thumbnail) ⇒ <code>Promise</code>
            * [~ocr(options)](#Client.vision..ocr) ⇒ <code>Promise</code>
            * [~recognizeText(options)](#Client.vision..recognizeText) ⇒ <code>Promise</code>
    * [.weblm](#Client.weblm) : <code>object</code>
        * [~listModels()](#Client.weblm..listModels) ⇒ <code>Promise</code>
        * [~breakIntoWords(model, text, options)](#Client.weblm..breakIntoWords) ⇒ <code>Promise</code>
        * [~generateWords(model, words, options)](#Client.weblm..generateWords) ⇒ <code>Promise</code>
        * [~getJointProbabilities(model, phrases, order)](#Client.weblm..getJointProbabilities) ⇒ <code>Promise</code>
        * [~getConditionalProbabilities(model, queries, order)](#Client.weblm..getConditionalProbabilities) ⇒ <code>Promise</code>

<a name="new_Client_new"></a>

### new Client(key, hostOrRegion)
Creates a new Project Oxford Client using a given API key.


| Param | Type | Description |
| --- | --- | --- |
| key | <code>string</code> | Project Oxford API Key |
| hostOrRegion | <code>string</code> | Optional host address or region |

<a name="Client.emotion"></a>

### Client.emotion : <code>object</code>
**Kind**: static namespace of <code>[Client](#Client)</code>  
<a name="Client.emotion..analyzeEmotion"></a>

#### emotion~analyzeEmotion(options) ⇒ <code>Promise</code>
Analyze the emotions of one or more faces in an image.

**Kind**: inner method of <code>[emotion](#Client.emotion)</code>  
**Returns**: <code>Promise</code> - - Promise resolving with the resulting JSON  

| Param | Type | Description |
| --- | --- | --- |
{'fraction_non_alphanumeric': 0.17141341819146116, 'fraction_numerical': 0.0042429063908777515, 'mean_word_length': 3.523992322456814, 'pattern_counts': {'":': 0, '<': 279, '<?xml version=': 0, '>': 279, 'https://': 4, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4681166', 'n_tokens_mistral': 6160, 'n_tokens_neox': 5821, 'n_words': 1247}