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

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

概要

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

REST API

基本情報

  • Base URL：http://localhost:8004
  • Content-Type：application/json
  • フレームワーク：Flask 2.3 以降

1. ヘルスチェック

GET /api/health

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

リクエスト例

GET /api/health

レスポンス例

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

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

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

{
  "status": "unhealthy",
  "object_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,
    "object_count": 3,
    "objects_detected": 3245
  },
  "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_shape_detect_bayese_320x320_nv12_fix_forward.bin",
    "confidence_threshold": 0.7,
    "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.7
  }
}

4. 設定の更新

POST /api/settings

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

リクエスト例

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

{
  "confidence_threshold": 0.8,
  "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.8,
    "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.7
  }
}

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

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="Object 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：システム内部エラー

検出結果の形式

図形検出の結果

検出結果のデータ構造

{
  "success": true,
  "boxes": [
    [100, 150, 200, 250],  # [x1, y1, x2, y2]
    [300, 100, 400, 200]
  ],
  "class_ids": [0, 1],      # 0: orange, 1: green, 2: red
  "confidences": [0.85, 0.92],
  "inference_time": 0.018,
  "object_count": 2,
  "error": null
}

フィールドの説明：

  • boxes：検出枠の座標リスト [x1, y1, x2, y2]
  • class_ids：クラス ID のリスト（0 = オレンジ、1 = 緑、2 = 赤）
  • confidences：信頼度のリスト（0.0～1.0）
  • inference_time：推論時間（秒）
  • object_count：検出された物体の数

計測システムの結果

計測結果のデータ構造

{
  "coordinate_system": {
    "enabled": true,
    "axis_length_percentage": 0.8,
    "axis_color": [255, 255, 255]
  },
  "distance_measurements": [
    {
      "object1": 0,
      "object2": 1, 
      "distance_pixels": 150.5,
      "center1": [150, 200],
      "center2": [350, 150]
    }
  ],
  "dimension_measurements": [
    {
      "object_id": 0,
      "width": 100,
      "height": 100,
      "area": 10000
    }
  ]
}

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

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

FPS の監視

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

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

メモリとリソースの監視

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

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

使用例

Python クライアントの例

ヘルスチェックと設定

import requests
import json

base_url = "http://localhost:8004"

# 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.8,
    "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']['object_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:8004/video_feed"
for frame in read_mjpeg_stream(stream_url):
    # 映像フレームを表示
    cv2.imshow('Object 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="Object Detection Stream">
    </div>

    <!-- コントロールパネル -->
    <div id="controlPanel">
        <label>
            信頼度しきい値:
            <input type="range" id="confidenceSlider" 
                   min="0.1" max="1.0" step="0.1" value="0.7">
            <span id="confidenceValue">0.7</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="objectCount">--</span></div>
        <div>推論時間: <span id="inferenceTime">--</span>ms</div>
    </div>

    <script>
        // API インターフェースのラッパー
        class ObjectDetectionAPI {
            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 ObjectDetectionAPI();

        // コントロールパネルのイベント処理
        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('objectCount').textContent = 
                    stats.detection_stats.object_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:8004/api/health

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

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

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

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

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

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

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

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

  • 推論時間：15～25ms
  • 映像ストリームの FPS：25～30 FPS
  • メモリ使用量：約 200MB
  • CPU 使用率：15～25%
  • 消費電力：3～5W
  • 検出精度：mAP@0.5：90% 以上

開発環境（CPU モード）

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

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

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

API の制限とクォータ

リクエストの制限

同時接続数の制限

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

データの制限

データサイズの制限

  • リクエストボディのサイズ：最大 1KB
  • 映像ストリームのフレームサイズ：設定された画質パラメータに応じて動的に調整
  • ログファイル：自動ローテーション、最大 100MB

検出クラスの説明

対応する図形クラス

クラスの詳細

クラス ID クラス名 色 検出枠の色（BGR） 説明
0 orange オレンジ [0, 165, 255] オレンジ色の図形物体
1 green 緑 [0, 255, 0] 緑色の図形物体
2 red 赤 [0, 0, 255] 赤色の図形物体

特長：

  • 色ごとに異なる検出枠の色を割り当て
  • 同じクラスの複数物体の同時検出に対応
  • 信頼度の評価と正確な位置特定を提供
  • サイズと距離を算出する計測システムを統合
← 前へYOLO11 物体検出システムの実装次へ →YOLO11 物体検出システム -- モデルデプロイメント資料