pdlib/README.md

# PDlib - A PHP extension for Dlib

## Requirements
- Dlib 19.13+
- PHP 7.0+
- C++11

## Dependencies

### Dlib

Install Dlib as shared library

```bash
git clone https://github.com/davisking/dlib.git
cd dlib/dlib
mkdir build
cd build
cmake -DBUILD_SHARED_LIBS=ON ..
make
sudo make install
```

## Installation

```bash
git clone https://github.com/goodspb/pdlib.git
cd pdlib
phpize
./configure --enable-debug
make
sudo make install
```

### Configure PHP installation

```bash
vim youpath/php.ini
```

Append the content below into `php.ini`

```
[pdlib]
extension="pdlib.so"
```

## Tests

For tests, you will need to have bz2 extension installed. On Ubuntu, it boils to:
```bash
sudo apt-get install php-bz2
```

After you successfully compiled everything, just run:
```bash
make test
```

## Usage

### General Usage

Good starting point can be `tests/integration_face_recognition.phpt`. Check that first.

Basically, if you just quickly want to get from your image to 128D descriptor of faces in image,
here is really minimal example how:

```php
<?php
$img_path = "image.jpg";
$fd = new CnnFaceDetection("detection_cnn_model.dat");
$detected_faces = $fd->detect($img_path);
foreach($detected_faces as $detected_face) {
  $fld = new FaceLandmarkDetection("landmark_model.dat");
  $landmarks = $fld->detect($img_path, $detected_face);
  $fr = new FaceRecognition("recognition_model.dat");
  $descriptor = $fr->computeDescriptor($img_path, $landmarks);
  // Optionally use descriptor later in `dlib_chinese_whispers` function
}
```

Location from where to get these models can be found on DLib website, as well as in `tests/integration_face_recognition.phpt` test.

### Specific use cases

#### face detection

If you want to use HOG based approach:

```php
<?php

// face detection
$faceCount = dlib_face_detection("~/a.jpg");
// how mary face in the picture.
var_dump($faceCount);
```

If you want to use CNN approach (and CNN model):

```php
<?php
$fd = new CnnFaceDetection("detection_cnn_model.dat");
$detected_faces = $fd->detect("image.jpg");
// $detected_face is indexed array, where values are assoc arrays with "top", "bottom", "left" and "right" values
```

CNN model can get you slightly better results, but is much, much more demanding (CPU and memory, GPU is also preferred).

#### face landmark detection

```php
<?php

// face landmark detection
$landmarks = dlib_face_landmark_detection("~/a.jpg");
var_dump($landmarks);
```

Additionally, you can also use class-based approach:
```php
$rect = array("left"=>value, "top"=>value, "right"=>value, "bottom"=>value);
// You can download a trained facial shape predictor from:
// http://dlib.net/files/shape_predictor_5_face_landmarks.dat.bz2
$fld = new FaceLandmarkDetection("path/to/shape/predictor/model");
$parts = $fld->detect("path/to/image.jpg", $rect);
// $parts is integer array where keys are associative values with "x" and "y" for keys
```

Note that, if you use class-based approach, you need to feed bounding box rectangle with values obtained from `dlib_face_detection`. If you use `dlib_face_landmark_detection`, everything is already done for you (and you are using HOG face detection model).

#### face recognition (aka getting face descriptor)

```php
<?php

$fr = new FaceRecognition($model_path);
$landmarks = array(
    "rect" => $rect_of_faces_obtained_with_CnnFaceDetection,
    "parts" => $parts_obtained_with_FaceLandmarkDetection);
$descriptor = $fr->computeDescriptor($img_path, $landmarks);
// $descriptor is 128D array
```

#### chinese whispers

Provides raw access to dlib's `chinese_whispers` function.
Client need to build and provide edges. Edges are provided
as numeric array. Each element of this array should also be
numeric array with 2 elements of long type.

Returned value is also numeric array, containing obtained labels.

```php
<?php
// This example will cluster nodes 0 and 1, but would leave 2 out.
// $labels will look like [0,0,1].
$edges = [[0,0], [0,1], [1,1], [2,2]];
$labels = dlib_chinese_whispers($edges);
```

## Features
- [x] 1.Face Detection
- [x] 2.Face Landmark Detection
- [x] 3.Deep Face Recognition
- [x] 4.Deep Learning Face Detection
- [x] 5. Raw chinese_whispers