face_recognition による顔のクラスタリングを行う Python プログラム（Dlib，ageitgey/face_recognition，Python を使用）（Windows 上）

1. エグゼクティブサマリー

Dlibは，機械学習，数値計算，画像処理，GUI 等の機能を持つ C++ ライブラリ．Python API もある．

本記事では，face_recognition による顔のクラスタリングを行う Python プログラム（Dlib，ageitgey/face_recognition，Python を使用）について，Windows 上での環境構築から実行・結果確認までの手順を説明する．

このプログラムは，指定フォルダ内のすべての JPEG 画像から顔を検出し，Dlib の顔認識モデルにより 128 次元の顔特徴量ベクトルを計算する．得られた特徴量ベクトルを Dlib の chinese_whispers_clustering によりクラスタリングし，クラスタごとに分類された顔画像を 150×150 ピクセルの画像ファイルとして出力する．

【サイト内の関連ページ】

説明資料: Dlib の機能概要 [PDF], [パワーポイント]
顔情報処理の Python プログラム（Dlib，face_recognition を使用）について: 別ページ »にまとめ
Windows で動く人工知能関係 Pythonアプリケーション，オープンソースソフトウエア: 別ページ »にまとめている．

【関連する外部ページ】

ageitgey/face_recognition のページ: https://github.com/ageitgey/face_recognition

2. 前準備（必要ソフトウェアの入手）

ここでは、最低限の事前準備について説明する。機械学習や深層学習を行う場合は、NVIDIA CUDA、Visual Studio、Cursorなどを追加でインストールすると便利である。これらについては別ページ https://www.kkaneko.jp/cc/dev/aiassist.htmlで詳しく解説しているので、必要に応じて参照してください。

Build Tools for Visual Studio 2026 のインストール（Windows 上） [クリックして展開]

Build Tools for Visual Studio は，Visual Studio の IDE を含まない C/C++ コンパイラ，ライブラリ，ビルドツール等のコマンドライン向け開発ツールセットである。インストール済みの場合、この手順は不要である。

管理者権限のコマンドプロンプトで以下を実行する。管理者権限のコマンドプロンプトを起動するには、Windows キーまたはスタートメニューから「cmd」と入力し、表示された「コマンドプロンプト」を右クリックして「管理者として実行」を選択する。

REM VC++ ランタイム
winget install --scope machine --id Microsoft.VCRedist.2015+.x64 -e --silent --disable-interactivity --force --accept-source-agreements --accept-package-agreements --override "/quiet /norestart"

REM Build Tools + Desktop development with C++（VCTools）+ 追加コンポーネント（一括）
winget install --scope machine --id Microsoft.VisualStudio.BuildTools -e --silent --disable-interactivity --force --accept-source-agreements --accept-package-agreements --override "--quiet --wait --norestart --nocache --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --add Microsoft.VisualStudio.Workload.MSBuildTools --add Microsoft.VisualStudio.Component.VC.CMake.Project --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --add Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset --add Microsoft.VisualStudio.Component.Windows11SDK.26100"

--add で追加されるコンポーネント

上記のコマンドでは，まず Build Tools 本体と Visual C++ 再頒布可能パッケージをインストールし，次に setup.exe を用いて以下のコンポーネントを追加している。

VCTools：C++ デスクトップ開発ワークロード（--includeRecommended により、MSVC コンパイラ、C++ AddressSanitizer、vcpkg、CMake ツール、Windows 11 SDK 等の推奨コンポーネントが含まれる）
VC.Llvm.Clang：Windows 向け C++ Clang コンパイラ
ClangCL：clang-cl ツールセットを含むコンポーネントグループ（MSBuild から Clang を使用するために必要）
VC.CMake.Project：Windows 向け C++ CMake ツール
Windows11SDK.26100：Windows 11 SDK（ビルド 10.0.26100）

インストール完了の確認

winget list Microsoft.VisualStudio.BuildTools

上記以外の追加のコンポーネントが必要になった場合は Visual Studio Installer で個別にインストールできる。

Visual Studio の機能を必要とする場合は、追加インストールできる。

Python 3.12 のインストール（Windows 上） [クリックして展開]

以下のいずれかの方法で Python 3.12 をインストールする。Python がインストール済みの場合、この手順は不要である。

方法1：winget によるインストール

winget install --scope machine --id Python.Python.3.12 -e --silent --disable-interactivity --force --accept-source-agreements --accept-package-agreements --override "/quiet InstallAllUsers=1 PrependPath=1 Include_pip=1 Include_test=0 Include_launcher=1 InstallLauncherAllUsers=1"

--scope machine を指定することで、システム全体（全ユーザー向け）にインストールされる。このオプションの実行には管理者権限が必要である。インストール完了後、コマンドプロンプトを再起動すると PATH が自動的に設定される。

方法2：インストーラーによるインストール

Python 公式サイト（https://www.python.org/downloads/）にアクセスし、「Download Python 3.x.x」ボタンから Windows 用インストーラーをダウンロードする。
ダウンロードしたインストーラーを実行する。
初期画面の下部に表示される「Add python.exe to PATH」に必ずチェックを入れてから「Customize installation」を選択する。このチェックを入れ忘れると、コマンドプロンプトから python コマンドを実行できない。
「Install Python 3.xx for all users」にチェックを入れ、「Install」をクリックする。

インストールの確認

コマンドプロンプトで以下を実行する。

python --version

バージョン番号（例：Python 3.12.x）が表示されればインストール成功である。「'python' は、内部コマンドまたは外部コマンドとして認識されていません。」と表示される場合は、インストールが正常に完了していない。

AIエディタ Windsurf のインストール（Windows 上） [クリックして展開]

Pythonプログラムの編集・実行には、AIエディタの利用を推奨する。ここでは、Windsurfのインストールを説明する。Windsurf がインストール済みの場合、この手順は不要である。

winget install --scope machine --id Codeium.Windsurf -e --silent --disable-interactivity --force --accept-source-agreements --accept-package-agreements --custom "/SP- /SUPPRESSMSGBOXES /NORESTART /CLOSEAPPLICATIONS /DIR=""C:\Program Files\Windsurf"" /MERGETASKS=!runcode,addtopath,associatewithfiles,!desktopicon"
powershell -Command "$env:Path=[System.Environment]::GetEnvironmentVariable('Path','Machine')+';'+[System.Environment]::GetEnvironmentVariable('Path','User'); windsurf --install-extension MS-CEINTL.vscode-language-pack-ja --force; windsurf --install-extension ms-python.python --force; windsurf --install-extension Codeium.windsurfPyright --force"

【関連する外部ページ】

Windsurf の公式ページ: https://windsurf.com/

Git のインストール（Windows 上） [クリックして展開]

REM Git をシステム領域にインストール
winget install --scope machine --id Git.Git -e --silent --disable-interactivity --force --accept-source-agreements --accept-package-agreements --override "/VERYSILENT /NORESTART /NOCANCEL /SP- /CLOSEAPPLICATIONS /RESTARTAPPLICATIONS /COMPONENTS=""icons,ext\reg\shellhere,assoc,assoc_sh"" /o:PathOption=Cmd /o:CRLFOption=CRLFCommitAsIs /o:BashTerminalOption=MinTTY /o:DefaultBranchOption=main /o:EditorOption=VIM /o:SSHOption=OpenSSH /o:UseCredentialManager=Enabled /o:PerformanceTweaksFSCache=Enabled /o:EnableSymlinks=Disabled /o:EnableFSMonitor=Disabled"

7-Zip のインストール（Windows 上） [クリックして展開]

REM 7-Zip をシステム領域にインストール
winget install --scope machine --id 7zip.7zip -e --silent --installer-type msi --disable-interactivity --force --accept-source-agreements --accept-package-agreements --override "/qn /norestart"
REM 7-Zip のパス設定
powershell -NoProfile -Command "$p='C:\Program Files\7-Zip'; $c=[Environment]::GetEnvironmentVariable('Path','Machine'); if((Test-Path $p) -and $c -notlike \"*$p*\"){[Environment]::SetEnvironmentVariable('Path',\"$p;$c\",'Machine')}"

Dlib ライブラリのインストールと学習済みモデルのダウンロード [クリックして展開]

Dlib ライブラリのインストール

python -m pip uninstall -y dlib
cd C:\
rmdir /s /q dlib
git clone https://github.com/davisking/dlib
cd C:\dlib
python setup.py build --no DLIB_GIF_SUPPORT
python setup.py install --no DLIB_GIF_SUPPORT

インストールの確認

バージョン番号が表示されれば OK である．下の図とは異なるバージョンが表示されることがある．

python -c "import dlib; print( dlib.__version__ )"

Dlib のソースコード等のダウンロード

cd C:\
rmdir /s /q dlib
git clone https://github.com/davisking/dlib

学習済みモデルのダウンロード

cd C:\dlib
cd python_examples
curl -O http://dlib.net/files/mmod_human_face_detector.dat.bz2
curl -O http://dlib.net/files/dlib_face_recognition_resnet_model_v1.dat.bz2
curl -O http://dlib.net/files/shape_predictor_5_face_landmarks.dat.bz2
curl -O http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2
"c:\Program Files\7-Zip\7z.exe" x mmod_human_face_detector.dat.bz2
"c:\Program Files\7-Zip\7z.exe" x dlib_face_recognition_resnet_model_v1.dat.bz2
"c:\Program Files\7-Zip\7z.exe" x shape_predictor_5_face_landmarks.dat.bz2
"c:\Program Files\7-Zip\7z.exe" x shape_predictor_68_face_landmarks.dat.bz2
del mmod_human_face_detector.dat.bz2
del dlib_face_recognition_resnet_model_v1.dat.bz2
del shape_predictor_5_face_landmarks.dat.bz2
del shape_predictor_68_face_landmarks.dat.bz2

Dlib の動作確認

次を実行し，エラーメッセージが出ずに顔検出の結果が表示されれば OK とする．

cd C:\dlib
cd python_examples
python cnn_face_detector.py mmod_human_face_detector.dat ..\examples\faces\2007_007763.jpg

3. 実行のための準備とその確認手順（Windows 前提）

3.1 プログラムファイルの準備

第5章のソースコードをテキストエディタ（メモ帳等）に貼り付け，cluster.py として保存する（文字コード：UTF-8）．

保存先ディレクトリは以下のとおりである．

cd /d c:%HOMEPATH%
cd face_recognition
notepad cluster.py

3.2 実行コマンド

Windows のコマンドプロンプトを開き，ファイルの保存先ディレクトリで以下の Python プログラムを実行する．

python cluster.py ..\dlib\python_examples\shape_predictor_5_face_landmarks.dat ..\dlib\python_examples\dlib_face_recognition_resnet_model_v1.dat ..\examples\faces output_folder

コマンドライン引数は順に，顔ランドマーク予測モデル，顔認識モデル，入力画像フォルダ，出力フォルダである．

3.3 動作確認チェックリスト

確認項目	期待される結果
プログラム起動時	各 JPEG ファイルについて「Processing file: ＜ファイルパス＞」と表示される
顔検出処理	各画像について「Number of faces detected: ＜検出数＞」と表示される
クラスタリング結果	「Number of clusters: ＜クラスタ数＞」と表示され，各クラスタの番号が順に出力される
出力フォルダ	指定した出力フォルダ（output_folder）が作成されている
出力画像ファイル	「face_＜クラスタ番号＞_＜クラスタ内での番号＞.jpg」形式の 150×150 ピクセルの顔画像が生成されている
完了メッセージ	「Saved face chips to: ＜出力フォルダパス＞」と表示される

4. 概要・使い方・実行上の注意

本プログラムは，Dlib に付属の python_examples\face_clustering.py（パブリックドメイン）を書き替えたものである．元のプログラムは最大クラスタの顔のみを出力するが，本プログラムはすべてのクラスタの顔画像を出力する．

処理の流れは以下のとおりである．

Dlib の正面顔検出器（get_frontal_face_detector），顔ランドマーク予測器（shape_predictor），顔認識モデル（face_recognition_model_v1）を読み込む．
入力フォルダ内のすべての JPEG 画像（*.jpg）を順に処理する．
各画像で顔の矩形領域を検出し，各顔のランドマーク（特徴点）を取得する．
顔認識モデルにより各顔の 128 次元特徴量ベクトル（face descriptor）を計算する．
全特徴量ベクトルを chinese_whispers_clustering（閾値 0.5）でクラスタリングする．
クラスタごとに dlib.save_face_chip で 150×150 ピクセル（パディング 0.25）の画像ファイルを出力フォルダに保存する．

結果の画像ファイルは出力フォルダ（上記例では output_folder）に格納される．ファイル名は「face_＜クラスタ番号＞_＜クラスタ内での番号＞」となる．

次のような結果が得られる．

ソースコードは第5章に掲載している．

5. ソースコード

次のソースコードは，Dlib に付属の python_examples\face_clustering.py（パブリックドメイン）を書き替えたもの．太字が書き換え部分．顔画像のすべてを出力するように変更．

import sys
import os
import dlib
import glob

predictor_path = sys.argv[1]
face_rec_model_path = sys.argv[2]
faces_folder_path = sys.argv[3]
output_folder_path = sys.argv[4]

detector = dlib.get_frontal_face_detector()
sp = dlib.shape_predictor(predictor_path)
facerec = dlib.face_recognition_model_v1(face_rec_model_path)

descriptors = []
images = []

for f in glob.glob(os.path.join(faces_folder_path, "*.jpg")):
    print("Processing file: {}".format(f))
    img = dlib.load_rgb_image(f)
    dets = detector(img, 1)
    print("Number of faces detected: {}".format(len(dets)))
    for k, d in enumerate(dets):
        shape = sp(img, d)
        descriptors.append(facerec.compute_face_descriptor(img, shape))
        images.append((img, shape))

labels = dlib.chinese_whispers_clustering(descriptors, 0.5)
num_classes = len(set(labels))
print("Number of clusters: {}".format(num_classes))

os.makedirs(output_folder_path, exist_ok=True)

for i in range(num_classes):
    print(i)
    indices = [k for k, label in enumerate(labels) if label == i]
    for k, index in enumerate(indices):
        img, shape = images[index]
        file_path = os.path.join(output_folder_path, "face_{}_{}".format(i, k))
        dlib.save_face_chip(img, shape, file_path, size=150, padding=0.25)

print("Saved face chips to: {}".format(output_folder_path))

6. まとめ

Dlib の顔検出・顔認識モデル

Dlib は正面顔検出器，顔ランドマーク予測器，顔認識モデルを提供しており，本プログラムではこれら3つを組み合わせて顔の検出から特徴量計算までを行う．

128 次元顔特徴量ベクトル

顔認識モデル（face_recognition_model_v1）により各顔の 128 次元特徴量ベクトル（face descriptor）を計算する．このベクトルがクラスタリングの類似度計算の基盤となる．

chinese_whispers_clustering

Dlib の chinese_whispers_clustering を閾値 0.5 で適用し，クラスタ数を事前に指定せず顔の自動分類を行う．同一人物と推定される顔が同じクラスタにまとめられる．

クラスタリング結果の画像出力

dlib.save_face_chip により，クラスタごとの顔画像を 150×150 ピクセル（パディング 0.25）で出力する．ファイル名は「face_＜クラスタ番号＞_＜クラスタ内での番号＞」の形式となる．

Windows 上での環境構築

本プログラムの実行には，Build Tools for Visual Studio 2026，Python 3.7，Git，7-Zip，Dlib のインストールおよび Dlib の学習済みモデルのダウンロードが必要である．