Skip to content

Commit 3285f28

Browse files
justadudewhohacksjustadudewhohacks
committed
update readme
1 parent 1b5e9d2 commit 3285f28

File tree

1 file changed

+107
-10
lines changed

1 file changed

+107
-10
lines changed

‎README.md

Lines changed: 107 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ Table of Contents:
1616
* **[Face Detection Models](#models-face-detection)**
1717
* **[68 Point Face Landmark Detection Models](#models-face-landmark-detection)**
1818
* **[Face Recognition Model](#models-face-recognition)**
19+
* **[Getting Started](#getting-started)**
20+
* **[face-api.js for the Browser](#getting-started-browser)**
21+
* **[face-api.js for Nodejs](#getting-started-nodejs)**
1922
* **[Usage](#usage)**
2023
* **[Loading the Models](#usage-loading-models)**
2124
* **[High Level API](#usage-high-level-api)**
@@ -75,15 +78,42 @@ Check out my face-api.js tutorials:
7578

7679
## Running the Examples
7780

81+
Clone the repository:
82+
7883
``` bash
7984
git clone https://github.com/justadudewhohacks/face-api.js.git
80-
cd face-api.js/examples
85+
```
86+
87+
### Running the Browser Examples
88+
89+
``` bash
90+
cd face-api.js/examples/examples-browser
8191
npm i
8292
npm start
8393
```
8494

8595
Browse to http://localhost:3000/.
8696

97+
### Running the Nodejs Examples
98+
99+
``` bash
100+
cd face-api.js/examples/examples-nodejs
101+
npm i
102+
```
103+
104+
Now run one of the examples using ts-node:
105+
106+
``` bash
107+
ts-node faceDetection.ts
108+
```
109+
110+
Or simply compile and run them with node:
111+
112+
``` bash
113+
tsc faceDetection.ts
114+
node faceDetection.js
115+
```
116+
87117
<a name="models"></a>
88118

89119
# Available Models
@@ -130,6 +160,55 @@ The neural net is equivalent to the **FaceRecognizerNet** used in [face-recognit
130160

131161
The size of the quantized model is roughly 6.2 MB (**face_recognition_model**).
132162

163+
<a name="getting-started"></a>
164+
165+
# Getting Started
166+
167+
<a name="getting-started-browser"></a>
168+
169+
## face-api.js for the Browser
170+
171+
Simply include the latest script from [dist/face-api.js](https://github.com/justadudewhohacks/face-api.js/tree/master/dist).
172+
173+
Or install it via npm:
174+
175+
``` bash
176+
npm i face-api.js
177+
```
178+
179+
<a name="getting-started-nodejs"></a>
180+
181+
## face-api.js for Nodejs
182+
183+
We can use the equivalent API in a nodejs environment by polyfilling some browser specifics, such as HTMLImageElement, HTMLCanvasElement and ImageData. The easiest way to do so is by installing the node-canvas package.
184+
185+
Alternatively you can simply construct your own tensors from image data and pass tensors as inputs to the API.
186+
187+
Furthermore you want to install @tensorflow/tfjs-node (not required, but highly recommended), which speeds things up drastically by compiling and binding to the native Tensorflow C++ library:
188+
189+
``` bash
190+
npm i face-api.js canvas @tensorflow/tfjs-node
191+
```
192+
193+
Now we simply monkey patch the environment to use the polyfills:
194+
195+
``` javascript
196+
// import nodejs bindings to native tensorflow,
197+
// not required, but will speed up things drastically (python required)
198+
import '@tensorflow/tfjs-node';
199+
200+
// implements nodejs wrappers for HTMLCanvasElement, HTMLImageElement, ImageData
201+
import * as canvas from 'canvas';
202+
203+
import * as faceapi from 'face-api.js';
204+
205+
// patch nodejs environment, we need to provide an implementation of
206+
// HTMLCanvasElement and HTMLImageElement, additionally an implementation
207+
// of ImageData is required, in case you want to use the MTCNN
208+
const { Canvas, Image, ImageData } = canvas
209+
faceapi.env.monkeyPatch({ Canvas, Image, ImageData })
210+
```
211+
133212
# Usage
134213

135214
<a name="usage-loading-models"></a>
@@ -150,14 +229,38 @@ await faceapi.loadSsdMobilenetv1Model('/models')
150229
// await faceapi.loadFaceRecognitionModel('/models')
151230
```
152231

153-
Alternatively, you can also create instance of the neural nets:
232+
All global neural network instances are exported via faceapi.nets:
233+
234+
``` javascript
235+
console.log(faceapi.nets)
236+
```
237+
238+
The following is equivalent to `await faceapi.loadSsdMobilenetv1Model('/models')`:
239+
240+
``` javascript
241+
await faceapi.nets.ssdMobilenetv1.loadFromUri('/models')
242+
```
243+
244+
In a nodejs environment you can furthermore load the models directly from disk:
245+
246+
``` javascript
247+
await faceapi.nets.ssdMobilenetv1.loadFromDisk('./models')
248+
```
249+
250+
You can also load the model from a tf.NamedTensorMap:
251+
252+
``` javascript
253+
await faceapi.nets.ssdMobilenetv1.loadFromWeightMap(weightMap)
254+
```
255+
256+
Alternatively, you can also create own instances of the neural nets:
154257

155258
``` javascript
156259
const net = new faceapi.SsdMobilenetv1()
157260
await net.load('/models')
158261
```
159262

160-
Using instances, you can also load the weights as a Float32Array (in case you want to use the uncompressed models):
263+
You can also load the weights as a Float32Array (in case you want to use the uncompressed models):
161264

162265
``` javascript
163266
// using fetch
@@ -205,7 +308,7 @@ By default **detectAllFaces** and **detectSingleFace** utilize the SSD Mobilenet
205308

206309
``` javascript
207310
const detections1 = await faceapi.detectAllFaces(input, new faceapi.SsdMobilenetv1Options())
208-
const detections2 = await faceapi.detectAllFaces(input, new faceapi.inyFaceDetectorOptions())
311+
const detections2 = await faceapi.detectAllFaces(input, new faceapi.TinyFaceDetectorOptions())
209312
const detections3 = await faceapi.detectAllFaces(input, new faceapi.MtcnnOptions())
210313
```
211314

@@ -513,12 +616,6 @@ const landmarks2 = await faceapi.detectFaceLandmarksTiny(faceImage)
513616
const descriptor = await faceapi.computeFaceDescriptor(alignedFaceImage)
514617
```
515618

516-
All global neural network instances are exported via faceapi.nets:
517-
518-
``` javascript
519-
console.log(faceapi.nets)
520-
```
521-
522619
### Extracting a Canvas for an Image Region
523620

524621
``` javascript

0 commit comments

Comments
 (0)