HumansXドキュメントセンター
公式サイトへ ↗
ドキュメントセンター › RAI-P4

YOLO11 顔検出システム ― API インターフェース仕様

概要

YOLO11 顔検出システムは、REST API とリアルタイム映像ストリームのインターフェースを提供し、ヘルスチェック、システム監視、パラメータ設定、および顔検出結果のリアルタイム映像ストリームに対応しています。すべてのインターフェースは Flask フレームワークをベースにしており、軽量で安定した Web サービスを提供します。

REST API

基本情報

  • Base URL：http://localhost:8003
  • Content-Type：application/json
  • すべての API エンドポイントが CORS（クロスオリジンアクセス）に対応
  • フレームワーク：Flask 2.3 以降

1. ヘルスチェック

GET /api/health

システムの各コンポーネントの稼働状況を確認します。

リクエスト例

GET /api/health

レスポンス例

成功時のレスポンス（200）：

{
  "status": "healthy",
  "face_detector": true,
  "camera_manager": true,
  "config_loaded": true,
  "uptime": 3600.5
}

システム異常時のレスポンス（503）：

{
  "status": "unhealthy",
  "face_detector": false,
  "camera_manager": true,
  "config_loaded": true,
  "uptime": 120.3
}

2. システム統計

GET /api/stats

システム稼働に関する詳細な統計情報を取得します。

リクエスト例

GET /api/stats

レスポンス例

{
  "start_time": 1703001600.0,
  "total_requests": 150,
  "detection_stats": {
    "total_frames": 5420,
    "total_detections": 3245,
    "fps": 28.5,
    "avg_inference_time": 0.018,
    "face_count": 2
  },
  "camera_stats": {
    "fps_actual": 29.2,
    "total_frames": 5420,
    "width": 640,
    "height": 480,
    "is_opened": true
  }
}

3. システム情報

GET /api/info

システム設定とモデル情報を取得します。

リクエスト例

GET /api/info

レスポンス例

{
  "app": {
    "name": "顔検出アプリケーション",
    "version": "1.0.0",
    "environment": "development"
  },
  "model": {
    "name": "YOLO11",
    "path": "models/yolo11n_face_detect_bayese_320x320_nv12.bin",
    "confidence_threshold": 0.6,
    "iou_threshold": 0.45
  },
  "camera": {
    "device_id": 0,
    "width": 640,
    "height": 480,
    "fps": 30,
    "is_opened": true
  },
  "settings": {
    "show_detection_boxes": true,
    "show_center_point": true,
    "show_stats": true,
    "confidence_threshold": 0.6
  }
}

4. 設定の更新

POST /api/settings

検出パラメータと表示設定を動的に更新します。

リクエスト例

POST /api/settings
Content-Type: application/json

{
  "confidence_threshold": 0.7,
  "show_detection_boxes": true,
  "show_center_point": false,
  "show_stats": true
}

リクエストパラメータ：

  • confidence_threshold (float, 任意)：信頼度しきい値（0.0～1.0）
  • show_detection_boxes (boolean, 任意)：検出枠を表示するかどうか
  • show_center_point (boolean, 任意)：中心点を表示するかどうか
  • show_stats (boolean, 任意)：統計情報を表示するかどうか

レスポンス例

成功時のレスポンス（200）：

{
  "status": "success",
  "updated_settings": {
    "confidence_threshold": 0.7,
    "show_detection_boxes": true,
    "show_center_point": false,
    "show_stats": true
  }
}

パラメータエラー時のレスポンス（422）：

{
  "detail": [
    {
      "loc": ["body", "confidence_threshold"],
      "msg": "ensure this value is greater than or equal to 0.0",
      "type": "value_error.number.not_ge",
      "ctx": {"limit_value": 0.0}
    }
  ]
}

5. 設定のリセット

POST /api/settings/reset

すべての設定を既定値に戻します。

リクエスト例

POST /api/settings/reset

レスポンス例

{
  "status": "success",
  "settings": {
    "show_detection_boxes": true,
    "show_center_point": true,
    "show_stats": true,
    "confidence_threshold": 0.6
  }
}

リアルタイム映像ストリーミング

MJPEG 映像ストリーム

GET /video_feed

顔検出結果をリアルタイムで重ねた映像ストリームを取得します。

インターフェース情報

  • レスポンス形式：multipart/x-mixed-replace; boundary=frame
  • エンコード形式：MJPEG（Motion JPEG）
  • フレームレート：設定可能（既定値 15fps）
  • 画質：設定可能（既定値 80）

リクエスト例

GET /video_feed

HTML5 への組み込み：

<img id="videoStream" src="/video_feed" alt="Face Detection Stream">

JavaScript による制御：

// 再生を開始
const videoElement = document.getElementById('videoStream');
videoElement.src = '/video_feed?' + new Date().getTime();

// 再生を停止
videoElement.src = '';

レスポンス形式

マルチパートレスポンスの形式：

--frame
Content-Type: image/jpeg

[JPEG 画像データ]
--frame
Content-Type: image/jpeg

[JPEG 画像データ]
--frame
...

映像ストリームの特長：

  • 顔検出結果をリアルタイムでオーバーレイ表示
  • 検出枠の表示を設定で切り替え可能
  • パフォーマンス統計の表示
  • 画質の自動調整

Web インターフェースサービス

1. メインページ

GET /

Web インターフェースのトップページにアクセスします。

リクエスト例

GET /

戻り値：HTML ページ（templates/index.html）

2. 静的リソース

GET /static/

静的リソースファイルにアクセスします。

リソースのパス

GET /static/css/style.css     # スタイルファイル
GET /static/js/app.js         # JavaScript アプリケーション
GET /static/images/           # 画像リソース

エラー処理

HTTP ステータスコード

ステータスコードの説明

  • 200：リクエスト成功
  • 404：リソースが存在しない
  • 422：リクエストパラメータの検証に失敗
  • 500：サーバー内部エラー
  • 503：サービス利用不可（コンポーネント異常）

エラーレスポンスの形式

標準エラー形式

{
  "detail": "エラーの説明",
  "error_code": "ERROR_CODE",
  "timestamp": "2024-01-01T12:00:00Z"
}

主なエラーコード：

  • CAMERA_NOT_AVAILABLE：カメラが使用できない
  • MODEL_LOAD_FAILED：モデルの読み込みに失敗
  • INVALID_PARAMETER：パラメータ値が無効
  • SYSTEM_ERROR：システム内部エラー

パフォーマンス監視インターフェース

リアルタイムのパフォーマンス指標

FPS の監視

/api/stats インターフェースからリアルタイムの FPS 情報を取得できます。

{
  "detection_stats": {
    "fps": 28.5,              // 検出処理の FPS
    "avg_inference_time": 0.018,  // 平均推論時間（秒）
    "total_frames": 5420,     // 処理した総フレーム数
    "face_count": 2           // 現在検出されている顔の数
  },
  "camera_stats": {
    "fps_actual": 29.2,       // カメラの実際の FPS
    "total_frames": 5420      // カメラの総フレーム数
  }
}

メモリとリソースの監視

システムは主要なリソースの使用状況を自動的に監視します。

  • メモリ使用量：自動ガベージコレクションとメモリリークの検出
  • CPU 使用率：推論および後処理の CPU 使用率
  • 温度監視：ハードウェアの温度（RDK-X5 プラットフォーム）
  • 接続数：現在アクティブな HTTP 接続の数

使用例

Python クライアントの例

ヘルスチェックと設定

import requests
import json

base_url = "http://localhost:8003"

# 1. ヘルスチェック
health_response = requests.get(f"{base_url}/api/health")
print("システム状態:", health_response.json())

# 2. システム情報を取得
info_response = requests.get(f"{base_url}/api/info")
system_info = info_response.json()
print("現在の信頼度しきい値:", system_info['settings']['confidence_threshold'])

# 3. 設定を更新
new_settings = {
    "confidence_threshold": 0.7,
    "show_detection_boxes": True,
    "show_center_point": False
}

settings_response = requests.post(
    f"{base_url}/api/settings",
    json=new_settings
)
print("設定の更新結果:", settings_response.json())

# 4. 統計情報を取得
stats_response = requests.get(f"{base_url}/api/stats")
stats = stats_response.json()
print(f"現在の FPS: {stats['detection_stats']['fps']}")
print(f"検出された顔の数: {stats['detection_stats']['face_count']}")

映像ストリームの処理

import requests
import cv2
import numpy as np

# MJPEG 映像ストリームを読み込む
def read_mjpeg_stream(url):
    """MJPEG 映像ストリームを読み込む"""
    response = requests.get(url, stream=True)

    if response.status_code == 200:
        bytes_data = bytes()
        for chunk in response.iter_content(chunk_size=1024):
            bytes_data += chunk

            # JPEG 画像の境界を検索
            a = bytes_data.find(b'\xff\xd8')  # JPEG の開始
            b = bytes_data.find(b'\xff\xd9')  # JPEG の終了

            if a != -1 and b != -1:
                jpg = bytes_data[a:b+2]
                bytes_data = bytes_data[b+2:]

                # JPEG 画像をデコード
                frame = cv2.imdecode(
                    np.frombuffer(jpg, dtype=np.uint8), 
                    cv2.IMREAD_COLOR
                )

                if frame is not None:
                    yield frame

# 使用例
stream_url = "http://localhost:8003/video_feed"
for frame in read_mjpeg_stream(stream_url):
    # 映像フレームを表示
    cv2.imshow('Face Detection Stream', frame)

    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cv2.destroyAllWindows()

JavaScript フロントエンドの例

Web インターフェースへの組み込み

<!DOCTYPE html>
<html>
<head>
    <title>顔検出システム</title>
</head>
<body>
    <!-- 映像ストリームの表示 -->
    <div id="videoContainer">
        <img id="videoStream" src="/video_feed" alt="Face Detection Stream">
    </div>

    <!-- コントロールパネル -->
    <div id="controlPanel">
        <label>
            信頼度しきい値:
            <input type="range" id="confidenceSlider" 
                   min="0.1" max="1.0" step="0.1" value="0.6">
            <span id="confidenceValue">0.6</span>
        </label>

        <label>
            <input type="checkbox" id="showBoxes" checked> 検出枠を表示
        </label>

        <label>
            <input type="checkbox" id="showCenter" checked> 中心点を表示
        </label>

        <button id="resetSettings">設定をリセット</button>
    </div>

    <!-- 統計情報 -->
    <div id="statsPanel">
        <div>FPS: <span id="fpsValue">--</span></div>
        <div>顔の数: <span id="faceCount">--</span></div>
        <div>推論時間: <span id="inferenceTime">--</span>ms</div>
    </div>

    <script>
        // API インターフェースのラッパー
        class FaceDetectionAPI {
            constructor(baseUrl = '') {
                this.baseUrl = baseUrl;
            }

            async updateSettings(settings) {
                const response = await fetch('/api/settings', {
                    method: 'POST',
                    headers: {
                        'Content-Type': 'application/json',
                    },
                    body: JSON.stringify(settings)
                });
                return await response.json();
            }

            async getStats() {
                const response = await fetch('/api/stats');
                return await response.json();
            }

            async resetSettings() {
                const response = await fetch('/api/settings/reset', {
                    method: 'POST'
                });
                return await response.json();
            }
        }

        // API クライアントを初期化
        const api = new FaceDetectionAPI();

        // コントロールパネルのイベント処理
        const confidenceSlider = document.getElementById('confidenceSlider');
        const confidenceValue = document.getElementById('confidenceValue');
        const showBoxes = document.getElementById('showBoxes');
        const showCenter = document.getElementById('showCenter');
        const resetButton = document.getElementById('resetSettings');

        // 信頼度スライダー
        confidenceSlider.addEventListener('input', async (e) => {
            const value = parseFloat(e.target.value);
            confidenceValue.textContent = value;

            await api.updateSettings({
                confidence_threshold: value
            });
        });

        // 検出枠の表示切り替え
        showBoxes.addEventListener('change', async (e) => {
            await api.updateSettings({
                show_detection_boxes: e.target.checked
            });
        });

        // 中心点の表示切り替え
        showCenter.addEventListener('change', async (e) => {
            await api.updateSettings({
                show_center_point: e.target.checked
            });
        });

        // 設定リセットボタン
        resetButton.addEventListener('click', async () => {
            await api.resetSettings();
            location.reload(); // ページを再読み込みして UI の状態を更新
        });

        // 統計情報を定期的に更新
        setInterval(async () => {
            try {
                const stats = await api.getStats();
                document.getElementById('fpsValue').textContent = 
                    stats.detection_stats.fps.toFixed(1);
                document.getElementById('faceCount').textContent = 
                    stats.detection_stats.face_count;
                document.getElementById('inferenceTime').textContent = 
                    (stats.detection_stats.avg_inference_time * 1000).toFixed(1);
            } catch (error) {
                console.error('統計情報の取得に失敗しました:', error);
            }
        }, 1000);
    </script>
</body>
</html>

cURL コマンドの例

コマンドラインでのテスト

# 1. ヘルスチェック
curl -X GET http://localhost:8003/api/health

# 2. システム情報を取得
curl -X GET http://localhost:8003/api/info

# 3. 統計情報を取得
curl -X GET http://localhost:8003/api/stats

# 4. 信頼度しきい値を更新
curl -X POST http://localhost:8003/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "confidence_threshold": 0.8,
    "show_detection_boxes": true
  }'

# 5. 設定をリセット
curl -X POST http://localhost:8003/api/settings/reset

# 6. 1 フレーム分の画像をダウンロード（MJPEG ストリーム経由）
curl http://localhost:8003/video_feed | head -c 100000 > frame.jpg

パフォーマンスベンチマーク

Horizon RDK-X5 プラットフォーム

ハードウェアアクセラレーション時の性能

  • 推論時間：15～25ms
  • 映像ストリームの FPS：25～30 FPS
  • メモリ使用量：約 200MB
  • CPU 使用率：15～25%
  • 消費電力：3～5W

開発環境（CPU モード）

CPU シミュレーション時の性能

  • シミュレーション推論時間：約 20ms
  • 映像ストリームの FPS：15～20 FPS
  • メモリ使用量：約 150MB
  • CPU 使用率：10～20%

注意：CPU モードは開発・テスト専用であり、実際の推論計算は行いません。

API の制限とクォータ

リクエストの制限

同時接続数の制限

  • 映像ストリーム接続：同時接続は最大 5
  • API リクエスト頻度：最大 100 リクエスト／秒
  • パラメータの更新：設定の更新は最大 30 回／分

データの制限

データサイズの制限

  • リクエストボディのサイズ：最大 1KB
  • 映像ストリームのフレームサイズ：設定された画質パラメータに応じて動的に調整
  • ログファイル：自動ローテーション、最大 100MB
← 前へYOLO11 顔検出システムの実装次へ →YOLO11 顔検出システム -- モデルデプロイメント資料