機械学習のライブラリ dlib

機械学習のC++ Pythonのライブラリの１つ[dlib](http://dlib.net/)に気づいた。
Pythonには[Scikit-learn](http://scikit-learn.org/stable/)という強力なライブラリがあるが、
選択肢の１つとして考えておこう。

### **機械学習のライブラリ dlibのアルゴリズムの選択ガイド**
機械学習のライブラリ dlibのアルゴリズムの選択ガイドが
図にしてありました。

![Machine Learning Guide](http://dlib.net/ml_guide.svg)



こちらはscikit-learnのガイド
![Choosing the right estimator]
(http://scikit-learn.org/stable/_static/ml_map.png)



### **dlibの記事**
- SlideShare [20160417dlibによる顔器官検出](http://www.slideshare.net/takmin/20160417dlib)

- YouTube [dlib vs OpenCV face detection]
(https://www.youtube.com/watch?v=LsK0hzcEyHI)

- YouTube [Facial Landmark Detection](https://www.youtube.com/watch?v=j49RbZf_SgY)

**C++**
- [OpenCVとdlibを連携した顔検出プログラム](http://kivantium.hateblo.jp/entry/2015/04/05/223841)　顔検出C++
- Qiita [Dlibの高性能な顔器官検出をMacでさくっと試す](http://qiita.com/naoyu822/items/7cce2f2dbad24931cc87)　顔器官検出C++　　
- Qiita [dlib の顔認識を試す](http://qiita.com/ryohey/items/0d563a1fd1c2a583bf3e)　　顔器官検出C++
- Qiita [Xcode で dlib を使用して顔認識を行う](http://qiita.com/ryohey/items/aeb6bfdbc135ce020f02)　顔器官検出C++
- [dlibガイド「Python、C++」](https://qiita.com/miyamotok0105/items/17c222334c4122ac1221)
- [C++の機械学習ライブラリ『Dlib』](http://blog.negativemind.com/2016/06/28/dlib-cpp-machine-learning-library/)　　顔器官検出C++　
> バージョン19.0で新しく入ったDeep Learning APIについて公式ブログで説明されている



- [Raspberry Pi3でdlibを利用してみた](http://geisterhacker.com/index.php/2017/05/21/raspberry-pi3-dlib/)

**Python**
- [【Ubuntu】【Python】dlibとOpenCVの顔検出比べ](http://qiita.com/Kazuhito/items/837d03b6551373be332c)　顔検出Python

- [カメラから取得した映像にdlibを用いた顔認識をする。](http://yamaguchi-1024.hatenablog.com/entry/2015/11/13/164814)　　顔検出Python

- [Python + dlibで顔検出](http://qiita.com/shngt/items/64ff4130f377ddca5973) 顔検出Python
- [OpenCVとdlibとOpenFaceでの顔検出と知見まとめ](http://vaaaaaanquish.hatenablog.com/entry/2016/06/28/004811) 顔検出Python

- [dlibを用いたselective search](http://kivantium.hateblo.jp/entry/2015/07/25/184346) Python
[【Ubuntu】【Python】dlibを用いた物体追跡](http://qiita.com/Kazuhito/items/1778cc5727d237fb50e1)

- [dlibの顔ランドマーク認識の結果をリアルタイムにmatplotlibで表示する](https://qiita.com/yu4u/items/04849491524180d03c7b)

**C#**
- [FaceRig無しでも中の人(二次元)になりたい！【Unity × OpenCV × Dlib × Live2D】](http://qiita.com/utibenkei/items/15925db826721f6bb00c)  C#

- [UnityでDlibFaceLandmarkDetectorを利用した顔器官検出アプリ事始め](https://qiita.com/utibenkei/items/2f392d6fa00960f39e45)
- [HoloLensで猫の顔を認識する Dlib FaceLandmark Detector #アセットアドカレ](https://qiita.com/yuujii/items/ba0a9d3ef7dd1d820599)
- [https://enoxsoftware.com/dlibfacelandmarkdetector/]
    - 人の顔器官点検出、猫の顔器官点検出があるようだ。

SlideShare [20160417dlibによる顔器官検出](https://www.slideshare.net/takmin/20160417dlib) 


顔器官検出は、目・鼻・口などの位置を得ることで、表情や、まばたき、口の動きなどを知ることに使われます。人物の顔認証を行う際には必須の機能として知られています。オープンソースのライブラリでここまで充実している時代になったのです。

 Linux では以下のサイトの手順でインストールできます。
https://github.com/davisking/dlib

しかし、Windowsでも使いたい人がいるかと思うので、以下の手順を記します。

### **インストールから顔器官検出するまで(Pythonの場合)**
#### PIP によるインストール
https://pypi.org/project/dlib/

[dlib 19.24.0  リリース日: 2022年5月8日](https://pypi.org/project/dlib/) 

```
pip install dlib
```

環境：
Windows7


手順：
1. dlibのpython　バインディングをインストールする。
コマンドプロンプト \>pip install dlib
というやり方でWindowsでもインストールできました。

Python のプロンプト\>\>\> import dlib
でエラーを生じないようなったら、インストールは成功です。

2.　標準のサンプルプログラムなどをgithubから[DownloadZip]でダウンロード
https://github.com/davisking/dlib
　ダウンロードしたzipファイルを展開

3．追加のデータのダウンロード
face_landmark_detection.pyを動作させる場合には
http://sourceforge.net/projects/dclib/files/dlib/v18.10/shape_predictor_68_face_landmarks.dat.bz2
をダウンロードして（圧縮済みのデータファイルしても61.1MBあります。）
[7-zip](https://sevenzip.osdn.jp)などで展開します。
展開後のファイルをpython_exampleのディレクトリに移動します。

4．python_exampleのスクリプトの実行
コマンドプロンプト\> cd python_example
コマンドプロンプト\> python face_detector.py 顔のある画像ファイル名

コマンドプロンプト\> python face_landmark_detection.py shape_predictor_68_face_landmarks.dat ..\examples\faces

shape_predictor_68_face_landmarks.dat
のファイルサイズはとても大きいのでコマンド実行の直後しばらく待つことになります。

5.　他の画像で性能を見てみたい場合、
　..\examples\faces
　にjpgファイルを置くのが一番簡単なテスト方法です。


face_landmark_detection.py
https://github.com/mit-nlp/MITIE/blob/master/dlib/python_examples/face_landmark_detection.py
を見ると、各画像で見つかった顔ごとにする処理(高性能な顔器官検出の結果の表示)が
プログラムのわかりやすさをそこなっていないのがわかります。


### その他のpython_examplesの例題を触れてみよう。
https://github.com/davisking/dlib/tree/master/python_examples

まず、次のようにコマンドをうちこむと、大概の場合、正しい使い方を表示してくれる。

```
$ python face_alignment.py 
Call this program like this:
   ./face_alignment.py shape_predictor_5_face_landmarks.dat ../examples/faces/bald_guys.jpg
You can download a trained facial shape predictor from:
    http://dlib.net/files/shape_predictor_5_face_landmarks.dat.bz2

$
```
データファイルを入手しなさいとあるので、wgetで入手する。その後解凍する。

```
$ wget http://dlib.net/files/shape_predictor_5_face_landmarks.dat.bz2
--2017-11-08 00:19:30--  http://dlib.net/files/shape_predictor_5_face_landmarks.dat.bz2
Resolving dlib.net (dlib.net)... 107.180.26.78
Connecting to dlib.net (dlib.net)|107.180.26.78|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 5706710 (5.4M)
Saving to: ‘shape_predictor_5_face_landmarks.dat.bz2’

shape_predictor_5_f 100%[===================>]   5.44M   164KB/s    in 38s     

2017-11-08 00:20:09 (145 KB/s) - ‘shape_predictor_5_face_landmarks.dat.bz2’ saved [5706710/5706710]
$ 
```   

その後、例題の引数でpythonスクリプトを動作させるとよい。
```
./face_alignment.py shape_predictor_5_face_landmarks.dat ../examples/faces/bald_guys.jpg
```

その後、入力画像を差し替えるとよい。

このようにすることで、python_exampleを気軽に試してみることができます。
https://github.com/davisking/dlib/blob/master/python_examples/face_alignment.py


以下は、そのようなスクリプトのコマンドラインでの使い方の表示の部分です。

```
$ ./cnn_face_detector.py 
Call this program like this:
   ./cnn_face_detector.py mmod_human_face_detector.dat ../examples/faces/*.jpg
You can get the mmod_human_face_detector.dat file from:
    http://dlib.net/files/mmod_human_face_detector.dat.bz2
$ ./face_alignment.py 
Call this program like this:
   ./face_alignment.py shape_predictor_5_face_landmarks.dat ../examples/faces/bald_guys.jpg
You can download a trained facial shape predictor from:
    http://dlib.net/files/shape_predictor_5_face_landmarks.dat.bz2

$ ./face_clustering.py 
Call this program like this:
   ./face_clustering.py shape_predictor_5_face_landmarks.dat dlib_face_recognition_resnet_model_v1.dat ../examples/faces output_folder
You can download a trained facial shape predictor and recognition model from:
    http://dlib.net/files/shape_predictor_5_face_landmarks.dat.bz2
    http://dlib.net/files/dlib_face_recognition_resnet_model_v1.dat.bz2

$ ./face_landmark_detection.py 
Give the path to the trained shape predictor model as the first argument and then the directory containing the facial images.
For example, if you are in the python_examples folder then execute this program by running:
    ./face_landmark_detection.py shape_predictor_68_face_landmarks.dat ../examples/faces
You can download a trained facial shape predictor from:
    http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2

```

face_alignment.py　は
顔を検出して
顔器官点をだして
画像の位置正規化して、windowに表示する。リターンキーを出すと次の顔画像を表示する。

```
$ ./face_alignment.py shape_predictor_5_face_landmarks.dat ../examples/faces/bald_guys.jpg
```


face_clustering.py は
入力画像フォルダにある画像の中で顔を検出してそれぞれ特徴量をだして、
その特徴量に基づいてクラスタリングして
一番大きなクラスタに入った画像を出力フォルダに保存する。

```
$ ./face_clustering.py shape_predictor_5_face_landmarks.dat dlib_face_recognition_resnet_model_v1.dat ../examples/faces output_folder
Processing file: ../examples/faces/bald_guys.jpg
Number of faces detected: 24
Processing file: ../examples/faces/2009_004587.jpg
Number of faces detected: 2
Processing file: ../examples/faces/2008_002506.jpg
Number of faces detected: 3
Processing file: ../examples/faces/2008_002079.jpg
Number of faces detected: 6
Processing file: ../examples/faces/2008_004176.jpg
Number of faces detected: 7
Processing file: ../examples/faces/dogs.jpg
Number of faces detected: 0
Processing file: ../examples/faces/2008_007676.jpg
Number of faces detected: 7
Processing file: ../examples/faces/2008_002470.jpg
Number of faces detected: 6
Processing file: ../examples/faces/2008_001009.jpg
Number of faces detected: 2
Processing file: ../examples/faces/2007_007763.jpg
Number of faces detected: 7
Processing file: ../examples/faces/2008_001322.jpg
Number of faces detected: 3
Number of clusters: 45
Biggest cluster id number: 0
Number of faces in biggest cluster: 6
Indices of images in the biggest cluster: [0, 1, 5, 11, 21, 22]
Saving faces in largest cluster to output folder...
$
```

###**dlibのpython　API**
dlib documentation
http://dlib.net/python/index.html
http://dlib.net/
dlibのドキュメンテーションはどんどん整備されてきているようだ。



顔検出器の使い方は次の２つがあります。

### 顔検出器の使い方の例１

```
detector = dlib.get_frontal_face_detector()
dets = detector(img, 1)
```

### 顔検出器の使い方の例２

```
detector = dlib.get_frontal_face_detector()
# RGB変換 (opencv形式からskimage形式に変換)
img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
# frontal_face_detectorクラスは矩形, スコア, サブ検出器の結果を返す
dets, scores, idx = detector.run(img_rgb, 0)
for det in dets:
    cv2.rectangle(img, (det.left(), det.top()), (det.right(), det.bottom()), (0, 0, 255))
```



このdetsは
cv::Rect()とも、cv2の場合の(x,y,w,h)
と違うことに注意することです。

```
dlib.rectangle(left, top, right, bottom))
```

のようにして、このデータ型に変換するようです。

#### dlibでの顔検出の最小の検出サイズについて
以下の記述によれば,detector.run(img_rgb, numUpSampling)
のnumUpSampling=0での最小の検出サイズは80x80 pixelのようです。
http://dlib.net/face_detection_ex.cpp.html

40x40 pixelで検出したいときは　numUpSampling を １に
20x20 pixelで検出したいときは　numUpSampling を 2に
する必要があるようです。
numUpSampling を１ふやすたびに、画像の面積が４倍になり、処理時間も４倍になります。


### dlib自体のface_recognition.pyについて
https://github.com/davisking/dlib/blob/master/python_examples/face_recognition.py
では顔照合のための特徴量を計算をしているようですが、
顔照合自体の計算がみあたりません。

それが理由で、顔照合を行うライブラリが以下のサイトで別途開発されています。
スクリプトファイル名が同じだったりするので、注意してください。
https://github.com/ageitgey/face_recognition


### **ドキュメンテーションブラウザからAPIを知る方法**
dlibのPython実装について、日本語での解説ブログがなくても、ひるむ必要はありません。
スタートメニュー[Python(x,y)][Documentation][Python documentation server]を起動します。
[open browser]
を実行すると、
ブラウザ上で
(Pythonのインストール先)\site-packages
の中からdlibを見つけていけば、Pythonインタフェースに用意されている機能をすべて見ることができます。


Python(x,y) ではなく、Linuxを使っている場合には
$ /usr/lib/python2.7/pydoc.py -p ポート番号 &

としてサーバーを起動し、
それをブラウザで開くことができます。




###**オブジェクト検出器を作るには**
dlibにはオブジェクトの検出器を作るためのツールが用意されています(注)。
http://dlib.net/train_object_detector.py.html
にある記述をご覧ください。
  ./train_object_detector.py ../examples/faces

../examples/faces のディレクトリにはtraining.xml という名前のファイルが
次のようなファイル形式で置かれておることを想定しています。
このxmlファイルをブラウザで表示させると、画像のどの位置に顔枠が表示されます。
https://github.com/davisking/dlib/blob/master/examples/faces/training.xml

画像も../examples/facesのディレクトリに置かれています。

```
dlib.train_simple_object_detector(training_xml_path, "detector.svm", options)
```
のようにして、detector.svm　ファイルとして学習結果のファイルができあがります。

```
detector = dlib.simple_object_detector("detector.svm")
dets = detector(img)
```
のようにして、検出された長方形のリストを得ることができます。

その一連の学習作業については、次の記事が解説してくれている。

- [dlibのSimple_Object_detectorを用いたPythonでの物体検出器の学習](http://vaaaaaanquish.hatenablog.com/?page=1473601318)

> dlibの物体検出は内部でサンプリングもしてくれるので、正データとなる画像と矩形だけ集めれば良いし、精度も良いので結構良い。
パラメータも少なく物体検出できる方だと思う。
メモリとCPUはバカ食いするけど愛嬌がある。

さらには、実際に自分の画像データでオブジェクト検出器を作ってみたいだろう。
その手順が次の記事に舁いてあります。
- [HOG特徴とSVMによる物体検出](http://ishi.main.jp/ros/ros_obj_detection.html)
- [dlibで機械学習して物体検出する](https://qiita.com/atotto/items/ef34c046c2222adf1679)

---

なお、学習済みのモデルファイルは以下の場所にあります。

[dlib-models]
(https://github.com/davisking/dlib-models#dlib-models)

mmod_front_and_rear_end_vehicle_detector.dat.bz2
mmod_rear_end_vehicle_detector.dat.bz2
mmod_dog_hipsterizer.dat.bz2


### **HOGとSVMによる物体検出とその学習についての記事**

- https://github.com/vaaaaanquish/dlib_detection_python_script
- この中の次のスクリプトを使って訓練できる。
- https://github.com/vaaaaanquish/dlib_detection_python_script/blob/master/dlib_train_detector.py

## 顔器官点の学習

Dlib自体の顔器官学習がどのようにされているのかはスクリプト自体のコメントに書かれています。
http://dlib.net/face_landmark_detection.py.html

```
#   The face detector we use is made using the classic Histogram of Oriented
#   Gradients (HOG) feature combined with a linear classifier, an image pyramid,
#   and sliding window detection scheme.  The pose estimator was created by
#   using dlib's implementation of the paper:
#      One Millisecond Face Alignment with an Ensemble of Regression Trees by
#      Vahid Kazemi and Josephine Sullivan, CVPR 2014
#   and was trained on the iBUG 300-W face landmark dataset (see
#   https://ibug.doc.ic.ac.uk/resources/facial-point-annotations/):  
#      C. Sagonas, E. Antonakos, G, Tzimiropoulos, S. Zafeiriou, M. Pantic. 
#      300 faces In-the-wild challenge: Database and results. 
#      Image and Vision Computing (IMAVIS), Special Issue on Facial Landmark Localisation "In-The-Wild". 2016.
#   You can get the trained model file from:
#   http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2.
#   Note that the license for the iBUG 300-W dataset excludes commercial use.
#   So you should contact Imperial College London to find out if it's OK for
#   you to use this model file in a commercial product.
```

- [One Millisecond Face Alignment with an Ensemble of Regression Trees]
(https://pdfs.semanticscholar.org/d78b/6a5b0dcaa81b1faea5fb0000045a62513567.pdf)


- Github [How to train shape_predictor to obtain shape_predictor_68_face_landmarks.dat](https://github.com/davisking/dlib/issues/359)
    - > I used the training data here: http://dlib.net/files/data/ibug_300W_large_face_landmark_dataset.tar.gz. It's just 300-W, but with mirrored images added in.

- [DCNNによる顔パーツ検出は、マンガキャラクターに対しても有効であることが確かめられた。](http://tadaoyamaoka.hatenablog.com/entry/2017/02/04/154050)
    - https://github.com/TadaoYamaoka/gochiusa

- 猫の顔検出・器官点検出はある。
    - [Dlib FaceLandmark Detector　人や動物の顔の形を瞬時に検出するDlib（顔器官検出）とOpenCVを組み合わせれば･･･](http://assetsale.hateblo.jp/entry/Dlib_FaceLandmark_Detector_1)
      

## **dlibの顔検出への課題**

- 横顔が検出されない
    - 横顔検出器はどこにある？　誰か作っていないものか？

## **dlibにもDNN**
- [A Clean C++11 Deep Learning API](http://blog.dlib.net/2016/06/a-clean-c11-deep-learning-api.html)
- qiita [dlib CNNベースの物体検出](https://qiita.com/mkisono/items/a97662dc4518b8f59989)
    - [dnn_mmod_ex.cpp](https://qiita.com/mkisono/items/a97662dc4518b8f59989#dnn_mmod_face_detection_excpp)
    - [dnn_mmod_face_detection_ex.cpp](https://qiita.com/mkisono/items/a97662dc4518b8f59989#dnn_mmod_face_detection_excpp)

- [Dlib19.2のDNN顔検出をウェブカメラで試す(in Windows)](https://qiita.com/SousukeShimoyama/items/a6b853a1575623f603cf)

- [DLIBでCNNを使ってみた in Windows](http://elda27.hatenablog.com/entry/2016/09/27/011522)


### **dlibベースの機能で他のライブラリと置き換え可能なもの**
以下のスクリプトからの抜粋です。
https://github.com/davisking/dlib/blob/master/python_examples/face_recognition.py

次のインスタンス winとそのメソッドは, cv2.imshow(), cv2.rectangle()などで置き換え可能です。
dlibは、OpenCVを使わなくて済む部分は使わなくて済まそうという部分あります。


```
    win = dlib.image_window()
    img = io.imread(f)
    win.clear_overlay()
    win.set_image(img)
    dets = detector(img, 1)
    for k, d in enumerate(dets):
        shape = sp(img, d)
        win.clear_overlay()
        win.add_overlay(d)
    win.add_overlay(shape)
    dlib.hit_enter_to_continue()
```

### **dlib自体にも追跡用のライブラリがある**
- http://dlib.net/python/index.html#dlib.correlation_tracker

- [【Ubuntu】【Python】dlibを用いた物体追跡](https://qiita.com/Kazuhito/items/1778cc5727d237fb50e1)

- https://github.com/gdiepen/face-recognition/blob/master/track%20multiple%20faces/demo%20-%20track%20multiple%20faces.py
- Youtube [person tracking with dlib correlation tracker](https://www.youtube.com/watch?v=sUv0HjpVgd8)



### **dlibベースの顔照合が公開されている**
~~[face_recognition 1.0.0](https://pypi.python.org/pypi/face_recognition)~~

~~[face_recognition 1.2.3 ](https://pypi.org/project/face_recognition/)~~
[face_recognition 1.3.0 ](https://pypi.org/project/face_recognition/)

紹介記事[dlib　ベースの顔照合プログラム face_recognition ](https://qiita.com/nonbiri15/items/f95b5fb01ae38980c9ce)


### dlibのPythonバインディングの実装のしかた
以下のソースをみれば明らかなようにboost::pythonが用いられている。
https://github.com/davisking/dlib/blob/master/tools/python/src/object_detection.cpp

```
#include <boost/python/args.hpp>
using namespace boost::python;
```


### 顔関係でdlibを無視できない理由
- OpenCVには顔のlandmarkを求めるライブラリがあるが、まだ十分には普及していない。
    - https://docs.opencv.org/3.4/dc/d63/classcv_1_1face_1_1FacemarkLBF.html
    - Tutorials for face module [Face landmark detection in an image ](https://docs.opencv.org/3.4.2/d2/d42/tutorial_face_landmark_detection_in_an_image.html)
    - [Facemark : Facial Landmark Detection using OpenCV](https://www.learnopencv.com/facemark-facial-landmark-detection-using-opencv/)
- 各種のライブラリがdlibの顔のlandmark の導出結果を利用している。
- 以下のページをみるとどのようなプロジェクト・論文で利用されているのかが書かれている。
    - https://sourceforge.net/p/dclib/wiki/Known_users/
- またスポンサーもついて開発がされている。
- https://github.com/davisking/dlib#dlib-sponsors

---


dlibのblog サイト がある。
ここでは、実装されている機能について、解説が書かれている。

 http://blog.dlib.net/


### **付記：**

ここに書いていたOpenCV自体の顔照合のメモは独立した項目に変更しました。

[「OpenCV 3.3.0 Face Recognition with OpenCV」への補足記事 ](https://qiita.com/nonbiri15/items/66c643575cbe7224ffcc)

[顔向き推定について調査中](https://qiita.com/nonbiri15/items/f6910a993457a1862632)
[顔照合のオープンソースの実装について調査中](https://qiita.com/nonbiri15/items/a552dc3f6d3d692c0b11)

[Dlib README.md の和訳](https://qiita.com/nonbiri15/items/21023109a8597dc25b55)

[ Ubuntu で Dlib 19.15 のビルドとインストール ](https://www.kunihikokaneko.com/dblab/linuxsoft/ubuntu_dlib_buildout.html)

### 追記　2020.02
この追記を書いている時点では、顔検出・顔照合についての実用的な選択肢が増えました。
この記事を最初に書いた時点では、OpenCV自体の顔照合関連の機能が、オープンソースのトップレベルと言い切るには不足している部分がありました。顔のランドマークを出し、顔照合を行う部分のOpenCV 自体のライブラリが深層学習の成果を反映しきったものではなかったためです。
しかし、2020年の時点では、OpenVinoの顔ライブラリが充実していること、OpenCVの枠組みでOpenVinoのModelOptimizerで変換済みの各種Model ZOOのモデルを利用できるようになっています。
そのことから、ある時期では、dlib一択に近い状況から、OpenVinoが無視できない状況になりつつあります。
今後どのようになっていくのか、動向をその都度みていってください。
東洋系の人の顔照合能力が、どの程度高まっていくのかは、それぞれのモデルの中で東洋系の人の顔を学習にどれくらい使っているのかに依存します。
オープン・ソースの実装の性能を高めておくことは、商用ライブラリの開発会社が、過度に社会的な影響を持つことに対する対抗策となりえます。