PersonAnalysis 入門：顔認識と身体 ReID
InsightFace 2.1 の導入から Cheetah の選択、参照写真の登録、Python API による画像・ローカル動画内の人物照合までを解説します。
このガイドで作るもの
PersonAnalysis は人物検出、顔認識、身体再識別（ReID）を組み合わせ、現在の画像に写る人物を、名前や ID を付けて登録した参照画像と照合します。
本ガイドでは CPU を使い、特徴抽出、照合、任意の身体参照更新を分けて説明します。動画では同じインスタンスを使い続け、フレーム間で参照情報を保持します。
始める前に
- Python 3.10 以降。仮想環境の利用を推奨します。
- 鮮明な顔が一つだけ写る reference.jpg、scene.jpg、および処理する権限がある短い固定フレームレート動画 clip.mp4。
- 初回のモデルダウンロード用インターネット接続、またはローカルに配置した完全な Cheetah パッケージ。
1. InsightFace 2.1 をインストール
使用する Python 環境で次のコマンドを実行します。基本パッケージには NumPy、OpenCV、CPU 版 ONNX Runtime が含まれ、PersonAnalysis に GUI や PrivateFrame の追加機能は不要です。
NVIDIA CUDA を使う場合は InsightFace の導入後に onnxruntime を onnxruntime-gpu に置き換え、CUDAExecutionProvider を明示的に指定します。手順は実行環境ガイドをご覧ください。PersonAnalysis は CPU と CUDA に対応し、Cheetah は CoreML を使用しません。
python -m pip install --upgrade "insightface==2.1"
python -c "from insightface.app import PersonAnalysis; print(PersonAnalysis.__name__)"2. Cheetah を選び、モデルを配置
まず cheetah_s を選びます。人物検出の入力は 320×320 で、Buffalo S と同じ顔検出・認識モデルを含みます。cheetah_l は 640×640 の人物検出器と Buffalo L の顔モデルを使います。身体 ReID モデルは共通で、顔検出入力は両方とも既定で 640×640 です。
公式 Cheetah パッケージがなければ初回準備時にダウンロードされます。オフラインではモデル公開ページから完全なアーカイブを取得し、~/.insightface/models/cheetah_s/ または cheetah_l/ に展開します。manifest.json、MODEL.LICENSE、四つの ONNX ファイルを同じ階層に置き、フォルダーを余分に入れ子にしないでください。
- 本ガイドでは name="cheetah_s" を明示します。Python コンストラクターの既定値は cheetah_l です。
- 既存パッケージが不正な場合は自動上書きせず、エラーになります。完全なアーカイブで修復してください。
3. 参照登録、特徴抽出、照合
画像用の例を person_image.py として reference.jpg、scene.jpg と同じ場所に保存し、python person_image.py を実行します。参照写真には使用可能な顔が一つだけ必要です。accepted と rejected を確認してください。person_001 は自分で指定する ID です。
get() はデコード済みの OpenCV BGR uint8 画像を受け取り、現在の観測結果を返します。match() は顔の照合を優先し、成立しない場合に身体参照を照合します。どちらも参照ライブラリを変更しません。
この例では auto_update を無効にしています。有効にすると、信頼できる顔照合と明確な顔・身体の対応が得られた場合に update() が身体参照を追加します。身体だけの照合では参照を増やさず、新しい ID も作りません。フレーム全体の照合後にまとめて更新してください。
import cv2
from insightface.app import PersonAnalysis
image = cv2.imread("scene.jpg")
if image is None:
raise FileNotFoundError("scene.jpg")
with PersonAnalysis(name="cheetah_s") as app:
registration = app.register("person_001", "reference.jpg")
if registration.accepted == 0:
raise ValueError(registration.rejected)
observations = app.get(image)
matches = app.match(observations)
for result in matches:
print(result.person_id, result.matched_by, result.similarity)
auto_update = False
if auto_update:
changes = app.update(matches)
print(changes.added, changes.replaced, changes.skipped)4. 動画では同じインスタンスを再利用
次の例を person_video.py として reference.jpg、clip.mp4 と同じ場所に保存し、python person_video.py を実行します。身体参照の任意更新を有効にしているため、不要なら auto_update を False にします。
30 FPS の固定フレームレート動画で analysis_fps=2 を指定すると 15 フレームごとに解析します。全フレームをデコードしますが、モデルに渡すのは抽出したフレームだけです。動画時間に対する上限であり、処理速度や再生速度を保証するものではありません。可変フレームレートでは実際のタイムスタンプを使用します。
この例は順番に読み込みます。Web カメラや RTSP ではデスクトップ機能を使うと、最新の待機フレームを保持し、経過時間に基づいて解析回数を制限できます。
import math
import cv2
from insightface.app import PersonAnalysis
analysis_fps = 2
auto_update = True
capture = cv2.VideoCapture("clip.mp4")
try:
if not capture.isOpened():
raise OSError("clip.mp4")
source_fps = capture.get(cv2.CAP_PROP_FPS)
if not math.isfinite(source_fps) or source_fps <= 0:
raise ValueError("CAP_PROP_FPS")
frame_step = max(1, math.ceil(source_fps / analysis_fps))
with PersonAnalysis(name="cheetah_s") as app:
registration = app.register("person_001", "reference.jpg")
if registration.accepted == 0:
raise ValueError(registration.rejected)
frame_index = -1
while True:
ok, frame = capture.read()
if not ok:
if frame_index < 0:
raise OSError("clip.mp4")
break
frame_index += 1
if frame_index % frame_step:
continue
matches = app.match(app.get(frame))
if auto_update:
app.update(matches)
for result in matches:
print(frame_index / source_fps, result.to_dict())
finally:
capture.release()5. 結果を読み、照合を調整
person_id は登録した ID、未照合なら None です。matched_by は face、body、None のいずれかで、similarity は採用されたコサイン類似度であり正解確率ではありません。result.observation の body_bbox、reid_feature、face は欠損の有無を確認してから使用します。
顔写真だけでは服装は分かりません。本人と分かっている身体の切り抜きを body_images に登録するか、条件を満たす顔照合から身体参照を追加します。身体照合は服装、姿勢、遮蔽、画質の影響を受けます。
既定値は face_similarity_threshold=0.45、reid_similarity_threshold=0.85、max_body_samples=4 です。新しいインスタンスを作る際に PersonConfig で変更し、実際に近い映像で評価します。設定一覧も参照してください。既定値は校正済みの精度保証ではありません。
- 参照情報はインスタンスのメモリ内だけに存在し、終了時に解放されます。自動エクスポート、データベース、再起動後の復元はありません。
- 結果は現在のフレームを表します。SDK は連続した軌跡、匿名 ID、出現時間、イベント履歴を保持しません。
- to_dict() は現在の結果をアプリ側で保存するために使えますが、参照ライブラリの保存形式ではなく、update() に渡せません。
6. デスクトップで試す
多言語対応の Evaluation Studio では、参照写真と解析回数の設定を使い、ローカル動画、Web カメラ、RTSP を解析できます。次の GUI 追加機能を導入して Cheetah S または L を選び、GUI ガイドに従って操作します。
python -m pip install --upgrade "insightface[gui]==2.1"
insightface-gui7. 用途を評価し、モデルの利用条件を確認
鮮明な顔、後ろ姿、似た服装、遮蔽、未登録の人物を含めて試します。誤照合と照合漏れを確認してからしきい値を選び、実際に使う機器と映像で速度を測定します。
SDK コードは MIT ライセンスです。公開 Cheetah 学習済みモデルは非商用の許諾であり、コードの商用利用許可はモデルの商用利用許可を意味しません。
API ガイドとモデルの利用条件をご覧ください。導入やモデルの商用利用はInsightFace にお問い合わせください。機能とモデルの選択は人物解析の概要で確認できます。