mscs-face-api
Version:
Microsoft Cognitive Services Face API
2,397 lines • 30.4 kB
HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Class: MSCSFaceApi</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Class: MSCSFaceApi</h1>
<section>
<header>
<h2>
<span class="ancestors"><a href="module-mscs-face-api.html">mscs-face-api</a>.</span>MSCSFaceApi</h2>
</header>
<article>
<div class="container-overview">
<h4 class="name" id="MSCSFaceApi"><span class="type-signature"></span>new MSCSFaceApi<span class="signature">(key, server)</span><span class="type-signature"></span></h4>
<div class="description">
Creates an instance os MSCSFaceApi
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>key</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">Subscription key which provides access to this API. Found in your Cognitive Services accounts.</td>
</tr>
<tr>
<td class="name"><code>server</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">Server short name to use this API. Options: WUS (westus), EUS2 (eastus2), WCUS (westcentralus), WE (westeurope) and SA (southeastasia).</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line13">line 13</a>
</li></ul></dd>
</dl>
</div>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id="addPersonFace"><span class="type-signature"></span>addPersonFace<span class="signature">(personGroupId, personId, userData, image)</span><span class="type-signature"> → {Promise}</span></h4>
<div class="description">
Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face and this persistedFaceId will not expire.
Note persistedFaceId is different from faceId which represents the detected face by Face - Detect.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>personGroupId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">Specifying the person group containing the target person.</td>
</tr>
<tr>
<td class="name"><code>personId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">Target person that the face is added to.</td>
</tr>
<tr>
<td class="name"><code>userData</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">User-specified data about the target face to add for any purpose. The maximum length is 1KB. (optional)</td>
</tr>
<tr>
<td class="name"><code>image</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">Face image URL. Valid image size is from 1KB to 4MB. Only one face is allowed per image.</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line195">line 195</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
A successful call returns the new persistedFaceId. A unsuccessful call returns the error.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
<h4 class="name" id="createPerson"><span class="type-signature"></span>createPerson<span class="signature">(personGroupId, name, userData)</span><span class="type-signature"> → {Promise}</span></h4>
<div class="description">
Create a new person in a specified person group. A newly created person have no registered face, you can call Person - Add a Person Face API to add faces to the person.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>personGroupId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">Specifying the target person group to create the person.</td>
</tr>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">Display name of the target person. The maximum length is 128.</td>
</tr>
<tr>
<td class="name"><code>userData</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">Optional fields for user-provided data attached to a person. Size limit is 16KB. (optional)</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line222">line 222</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
A successful call returns a new personId created. A unsuccessful call returns the error.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
<h4 class="name" id="createPersonGroup"><span class="type-signature"></span>createPersonGroup<span class="signature">(personGroupId, name, userData)</span><span class="type-signature"> → {Promise}</span></h4>
<div class="description">
Create a new person group with specified personGroupId, name and user-provided userData.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>personGroupId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">User-provided personGroupId as a String. The valid characters include numbers, English letters in lower case, '-' and '_'. The maximum length of the personGroupId is 64.</td>
</tr>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">Person group display name. The maximum length is 128.</td>
</tr>
<tr>
<td class="name"><code>userData</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">User-provided data attached to the person group. The size limit is 16KB. (optional)</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line39">line 39</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
A successful call returns an empty response body. A unsuccessful call returns the error.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
<h4 class="name" id="deletePersonGroup"><span class="type-signature"></span>deletePersonGroup<span class="signature">(personGroupId)</span><span class="type-signature"> → {Promise}</span></h4>
<div class="description">
Delete an existing person group.
Persisted face images of all people in the person group will also be deleted.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>personGroupId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">The personGroupId of the person group to be deleted.</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line65">line 65</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
A successful call returns an empty response body. A unsuccessful call returns the error.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
<h4 class="name" id="detectFace"><span class="type-signature"></span>detectFace<span class="signature">(image)</span><span class="type-signature"> → {Promise}</span></h4>
<div class="description">
Detect human faces in an image and returns face locations and faceIds of the detected faces.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>image</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">URL of input image.</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line270">line 270</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
A successful call returns an array of face entries ranked by face rectangle size in descending order and faceIds. An empty response indicates no faces detected. A unsuccessful call returns the error.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
<h4 class="name" id="getPersonGroup"><span class="type-signature"></span>getPersonGroup<span class="signature">(personGroupId)</span><span class="type-signature"> → {Promise}</span></h4>
<div class="description">
Retrieve the information of a person group, including its name and userData.
This API returns person group information only, use Person - List Persons in a Person Group instead to retrieve person information under the person group.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>personGroupId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">personGroupId of the target person group.</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line86">line 86</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
A successful call returns the person group's information. A unsuccessful call returns the error.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
<h4 class="name" id="getPersonGroupTrainingStatus"><span class="type-signature"></span>getPersonGroupTrainingStatus<span class="signature">(personGroupId)</span><span class="type-signature"> → {Promise}</span></h4>
<div class="description">
Retrieve the training status of a person group (completed or ongoing).
Training can be triggered by the Person Group - Train Person Group API. The training will process for a while on the server side.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>personGroupId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">personGroupId of target person group.</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line107">line 107</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
A successful call returns the person group's training status. A unsuccessful call returns the error.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
<h4 class="name" id="identifyFace"><span class="type-signature"></span>identifyFace<span class="signature">(personGroupId, faceIds, confidenceThreshold)</span><span class="type-signature"> → {Promise}</span></h4>
<div class="description">
Identify unknown faces from a person group.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>personGroupId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">personGroupId of the target person group, created by Person Group - Create a Person Group.</td>
</tr>
<tr>
<td class="name"><code>faceIds</code></td>
<td class="type">
<span class="param-type">Array</span>
</td>
<td class="description last">Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between.</td>
</tr>
<tr>
<td class="name"><code>confidenceThreshold</code></td>
<td class="type">
<span class="param-type">Number</span>
</td>
<td class="description last">Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). (optional)</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line293">line 293</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
A successful call returns the identified candidate person(s) for each query face. An empty response indicates no faces detected. A unsuccessful call returns the error.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
<h4 class="name" id="listPersonGroups"><span class="type-signature"></span>listPersonGroups<span class="signature">(start, top)</span><span class="type-signature"> → {Promise}</span></h4>
<div class="description">
List person groups and their information.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>start</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">List person groups from the least personGroupId greater than the "start". It contains no more than 64 characters. Default is empty. (optional)</td>
</tr>
<tr>
<td class="name"><code>top</code></td>
<td class="type">
<span class="param-type">int</span>
</td>
<td class="description last">The number of person groups to list, ranging in [1, 1000]. Default is 1000. (optional)</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line128">line 128</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
A successful call returns an array of person groups and their information (personGroupId, name and userData). A unsuccessful call returns the error.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
<h4 class="name" id="listPersonsInPersonGroup"><span class="type-signature"></span>listPersonsInPersonGroup<span class="signature">(personGroupId, start, top)</span><span class="type-signature"> → {Promise}</span></h4>
<div class="description">
List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person).
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>personGroupId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">personGroupId of the target person group.</td>
</tr>
<tr>
<td class="name"><code>start</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">List persons from the least personId greater than the "start". It contains no more than 64 characters. Default is empty. (optional)</td>
</tr>
<tr>
<td class="name"><code>top</code></td>
<td class="type">
<span class="param-type">int</span>
</td>
<td class="description last">The number of persons to list, ranging in [1, 1000]. Default is 1000. (optional)</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line248">line 248</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
A successful call returns an array of person information that belong to the person group. A unsuccessful call returns the error.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
<h4 class="name" id="trainPersonGroup"><span class="type-signature"></span>trainPersonGroup<span class="signature">(personGroupId)</span><span class="type-signature"> → {Promise}</span></h4>
<div class="description">
Queue a person group training task, the training task may not be started immediately.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>personGroupId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">Target person group to be trained.</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line149">line 149</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
A successful call returns an empty JSON body. A unsuccessful call returns the error.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
<h4 class="name" id="updatePersonGroup"><span class="type-signature"></span>updatePersonGroup<span class="signature">(personGroupId, name, userData)</span><span class="type-signature"> → {Promise}</span></h4>
<div class="description">
Update an existing person group's display name and userData. The properties which does not appear in request body will not be updated.
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>personGroupId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">personGroupId of the person group to be updated.</td>
</tr>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">Person group display name. The maximum length is 128.</td>
</tr>
<tr>
<td class="name"><code>userData</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last">User-provided data attached to the person group. The size limit is 16KB.</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="mscs-face-api.js.html">mscs-face-api.js</a>, <a href="mscs-face-api.js.html#line169">line 169</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
A successful call returns an empty JSON body. A unsuccessful call returns the error.
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Modules</h3><ul><li><a href="module-mscs-face-api.html">mscs-face-api</a></li></ul><h3>Classes</h3><ul><li><a href="module-mscs-face-api.MSCSFaceApi.html">MSCSFaceApi</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.3</a> on Tue Jun 06 2017 19:43:41 GMT+0100 (Hora de Verão de GMT)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>