コンテンツにスキップ

YOLOv8 顔検出 (YOLOv8 Face Detection)

Hugging Face モデルを使用するためのセットアップ手順

このノードを完全に機能させるには、Hugging Face アカウントの開設、アクセストークンの発行、および必要なモデルのインストールが必要です。詳細は Hugging Face 連携ガイド を参照してください。

概要 (What is it?)

YOLOv8 Face Detection は、🤗 Hugging Face の YOLOv8（You Only Look Once version 8）物体検出モデルを使用して画像内の人物の顔を検出するコンピュータビジョンノードです。画像を解析し、検出された各顔のバウンディングボックス座標と信頼度スコアを返します。

本実装では、顔検出タスクに特化して学習された arnabdhar/YOLOv8-Face-Detection モデルを採用しており、リアルタイム処理に適した高速かつ高精度な結果を提供します。

使用する場面 (When would I use it?)

以下のような場面でこのノードを使用します：

  • 顔認識パイプラインの前処理として顔領域を検出したい場合
  • 写真から顔部分を自動的に切り抜き（クロップ）抽出したい場合
  • 画像内に写っている人物の人数をカウントしたい場合
  • 顔の有無に基づいて画像を自動分類・フィルタリングしたい場合
  • 顔にフォーカスした構図やビジュアルエフェクトを作成したい場合
  • プライバシー保護のために顔を自動マスキング・ぼかし処理したい場合
  • 写真の自動整理・管理システムを構築したい場合
  • 顔認証ベースのアクセス制御を実装したい場合

使い方 (How to use it)

基本セットアップ

  1. ノードの追加:

    • ワークフローに "YOLOv8 Face Detection" ノードを追加します
    • 初回実行時にモデルが自動的にダウンロードされます（Hugging Face へのアクセス権限が必要）

  2. 入力の接続:

    • input_image パラメータに ImageArtifact または ImageUrlArtifact を接続します
    • ファイルローダー、画像生成ノード、その他の画像処理ノードからの出力を指定できます

  3. パラメータの設定:

    • 検出結果をフィルタリングするために confidence_threshold（0.0〜1.0）を設定します
    • 必要に応じて dilation（0〜100%）を設定し、検出されたバウンディングボックスを外側に拡張します

  4. 検出の実行:

    • ノードを実行して画像内の顔を検出します
    • detected_faces 出力に顔検出結果のリストが格納されます

パラメータ一覧 (Parameters)

入力パラメータ (Input Parameters)

  • input_image（必須）

    • 型: ImageArtifact または ImageUrlArtifact
    • 顔検出を行う対象の画像

  • confidence_threshold

    • 型: float (0.0〜1.0)
    • デフォルト: 0.5
    • 検出結果に含めるための最小信頼度スコア
    • 値を大きくすると誤検出が減り、確実な顔のみが抽出されます
    • 値を小さくすると検出数が増加しますが、誤検出（偽陽性）が含まれる可能性があります

  • dilation

    • 型: float (0.0〜100.0)
    • デフォルト: 0.0
    • 中心点を維持したままバウンディングボックスを拡大する比率（パーセンテージ）
    • 検出された顔の周囲（髪型や背景など）も含めて切り出したい場合に有用です
    • 例: 10.0 を設定すると、上下左右に 10% ずつボックスが拡張されます

出力パラメータ (Output Parameters)

  • detected_faces

    • 型: list
    • 検出された顔の辞書リスト。各要素には以下が含まれます：
      • x: バウンディングボックスの左上 X 座標
      • y: バウンディングボックスの左上 Y 座標
      • width: バウンディングボックスの幅
      • height: バウンディングボックスの高さ
      • confidence: 検出信頼度スコア（0.0〜1.0）

  • logs

    • 型: string
    • 以下の情報を含む検出プロセスの詳細ログ：
      • モデルのロード状態
      • 検出パラメータ
      • 検出された顔の総数

出力フォーマット (Output Format)

検出された各顔は以下のような辞書形式で表現されます：

{
  "x": 150,
  "y": 200,
  "width": 300,
  "height": 350,
  "confidence": 0.95
}

バウンディングボックスの座標値は、画像の左上隅を原点 (0,0) とするピクセル単位の絶対座標です。

ワークフローの例 (Example Workflows)

基本的な顔検出

  1. 画像読み込みノードから画像をロード
  2. YOLOv8 Face Detection の input_image に接続
  3. confidence_threshold を 0.5 に設定
  4. detected_faces 出力からすべての顔の位置と信頼度を取得

顔切り抜きパイプライン

  1. YOLOv8 Face Detection で顔を検出
  2. 顔の周囲の背景を含めるため dilation を 10.0 に設定
  3. detected_faces を "Crop Image" ノードに接続
  4. 個々の顔画像を抽出して後続の処理へ渡す

高信頼度の顔のみを抽出

  1. confidence_threshold を 0.8 以上に設定
  2. 不確実な検出を排除し、厳密な顔画像のみを取得

高度な機能 (Advanced Features)

  • モデルの自動キャッシュ: ダウンロードされたモデルはローカルにキャッシュされ、次回以降高速にロードされます
  • 境界クランプ: 拡張されたバウンディングボックスが画像領域外にはみ出さないよう自動調整されます
  • 中心維持ダイレーション: ボックスの拡大時も元の検出領域の中心点が維持されます
  • バッチ処理対応: ループ構造と組み合わせることで複数画像の一括処理が可能

パフォーマンスに関する考慮事項 (Performance Considerations)

  • 初回実行時: 初回のみモデル（約 6MB）のダウンロードが行われます
  • 次回以降: キャッシュされたモデルから即座にロードされます
  • 画像解像度: 高解像度画像は処理時間が長くなりますが、遠くの小さな顔も検出しやすくなります
  • 検出速度: YOLOv8 はリアルタイム処理向けに最適化されており、通常はミリ秒単位で処理が完了します
  • メモリ使用量: ロード時の RAM 消費量は約 50MB 程度です

よくある問題 (Common Issues)

  • API キーの未設定: Hugging Face API トークンが HF_TOKEN として設定されているか確認してください（手順は ガイド を参照）
  • モデルが見つからない: "model not available" 警告が表示された場合は、リンクをクリックして Model Manager からモデルをダウンロードしてください
  • 顔が検出されない: 顔が写っているはずなのに検出されない場合は、confidence_threshold を下げてみてください
  • 誤検出が多い: confidence_threshold を引き上げて信頼度の低い検出を排除してください
  • 切り抜き領域が狭すぎる: dilation パラメータを大きくして余白を追加してください

技術仕様 (Technical Details)

  • モデル: Hugging Face YOLOv8 Face Detection (arnabdhar/YOLOv8-Face-Detection)
  • アーキテクチャ: 顔検出に特化した YOLOv8 物体検出フレームワーク
  • 依存関係: ultralytics>=8.0.0, supervision>=0.20.0
  • 出力形式: 標準バウンディングボックス形式（x, y, width, height）および信頼度スコア
  • 処理方式: 高速性と精度を両立したシングルパス検出