YOLO11物体検出システム -- 設定説明

概要

YOLO11幾何形状検出システムは、YAML 設定ファイルと環境変数による階層型の設定管理システムを使用しています。設定は優先度による上書きの仕組みを採用しており、開発・テスト・本番などの複数のデプロイ環境に対応し、柔軟な設定管理とデプロイを可能にします。本システムは幾何形状検出と計測機能向けに特に最適化された設定となっています。

⚙️ 設定ファイルの階層

設定の優先度（高い順）：

1. 実行時の設定更新 - API インターフェースから動的に変更
2. システム環境変数 - システムレベルの環境変数
3. YAML 設定ファイル - 基本設定ファイル
4. コードのデフォルト値 - ハードコードされたデフォルト値

📝 メイン設定ファイル

設定ファイルの場所

ファイルの場所

• メイン設定：config/object_config.yaml
• 設定管理：config/config_manager.py

完全な設定例

完全な設定例

# 物体检测应用配置文件
# Object Detection Application Configuration

# 应用基本信息
app:
  name: "物体检测应用"
  version: "1.0.0"
  environment: "development"

# 服务器配置
server:
  host: "0.0.0.0"
  port: 8004
  debug: false

# 日志配置
logging:
  level: "INFO"
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

# 模型配置
model:
  # 模型文件路径（相对于项目根目录）
  path: "models/yolo11n_shape_detect_bayese_320x320_nv12_fix_forward.bin"
  # 置信度阈值
  confidence_threshold: 0.7
  # IOU阈值
  iou_threshold: 0.45

# 摄像头配置
camera:
  # 设备ID（0为默认摄像头）
  device_id: 0
  # 分辨率
  width: 640
  height: 480
  # 帧率
  fps: 30
  # 是否使用异步捕获线程
  async_capture: true

# Web界面配置
web:
  # 视频流质量 (1-100)
  video_quality: 80
  # 视频流帧率
  stream_fps: 15
  # 是否显示检测框
  show_detection_boxes: true
  # 是否显示中心点
  show_center_point: true
  # 是否显示统计信息
  show_stats: true

# 检测配置
detection:
  # 检测类别名称
  class_names: ["orange", "green", "red"]
  # 检测框颜色 (BGR格式)
  box_colors:
    - [0, 165, 255]  # 橙色
    - [0, 255, 0]    # 绿色
    - [0, 0, 255]    # 红色
  # 文本颜色
  text_color: [255, 255, 255]  # 白色
  # 线条粗细
  line_thickness: 2
  # 字体大小
  font_scale: 0.6

# 测量配置
measurement:
  # 是否启用坐标系统
  enable_coordinate_system: true
  # 是否启用距离测量
  enable_distance_measurement: true
  # 是否启用尺寸测量
  enable_dimension_measurement: true
  # 坐标轴颜色
  axis_color: [255, 255, 255]  # 白色
  # 测量颜色
  measurement_color: [255, 255, 0]  # 黄色
  # 坐标轴长度百分比
  axis_length_percentage: 0.8
  # 坐标轴粗细
  axis_thickness: 2
  # 测量线条粗细
  measurement_line_thickness: 2

🔑 環境変数の設定

対応している環境変数

環境変数一覧

# 服务器配置
OBJECT_SERVER_HOST=0.0.0.0          # 服务监听地址
OBJECT_SERVER_PORT=8004              # 服务端口号
OBJECT_SERVER_DEBUG=false            # 调试模式

# 应用配置
OBJECT_APP_NAME="物体检测应用"         # 应用名称
OBJECT_APP_VERSION="1.0.0"           # 应用版本
OBJECT_APP_ENVIRONMENT=production     # 运行环境

# 模型配置
OBJECT_MODEL_PATH=/path/to/model.bin  # 模型文件路径
OBJECT_MODEL_CONFIDENCE=0.7           # 置信度阈值
OBJECT_MODEL_IOU=0.45                # IOU阈值

# 摄像头配置
OBJECT_CAMERA_DEVICE=0               # 摄像头设备ID
OBJECT_CAMERA_WIDTH=640              # 摄像头宽度
OBJECT_CAMERA_HEIGHT=480             # 摄像头高度
OBJECT_CAMERA_FPS=30                 # 摄像头帧率
OBJECT_CAMERA_ASYNC=true             # 异步捕获模式

# Web界面配置
OBJECT_WEB_QUALITY=80                # 视频流质量
OBJECT_WEB_STREAM_FPS=15             # 视频流帧率
OBJECT_WEB_SHOW_BOXES=true           # 显示检测框
OBJECT_WEB_SHOW_CENTER=true          # 显示中心点
OBJECT_WEB_SHOW_STATS=true           # 显示统计信息

# 检测配置
OBJECT_DETECTION_CLASSES="orange,green,red"  # 检测类别列表

# 测量配置
OBJECT_MEASUREMENT_COORDINATE=true    # 启用坐标系统
OBJECT_MEASUREMENT_DISTANCE=true     # 启用距离测量
OBJECT_MEASUREMENT_DIMENSION=true    # 启用尺寸测量

# 日志配置
OBJECT_LOG_LEVEL=INFO                # 日志级别
OBJECT_LOG_FORMAT="%(asctime)s - %(name)s - %(levelname)s - %(message)s"

環境変数の使用例

Docker でのデプロイ例

# Dockerfile示例
FROM python:3.9-slim

# 设置环境变量
ENV OBJECT_SERVER_HOST=0.0.0.0
ENV OBJECT_SERVER_PORT=8004
ENV OBJECT_SERVER_DEBUG=false
ENV OBJECT_MODEL_PATH=/app/models/yolo11n_shape_detect_bayese_320x320_nv12_fix_forward.bin
ENV OBJECT_CAMERA_DEVICE=0
ENV OBJECT_LOG_LEVEL=INFO
ENV OBJECT_MEASUREMENT_COORDINATE=true
ENV OBJECT_MEASUREMENT_DISTANCE=true

# 复制应用文件
COPY . /app
WORKDIR /app

# 安装依赖
RUN pip install -r requirements.txt

# 启动应用
CMD ["python", "main.py"]

Docker Compose の例

version: '3.8'
services:
  object-detection:
    build: .
    ports:
      - "8004:8004"
    devices:
      - /dev/video0:/dev/video0  # 摄像头设备
    environment:
      OBJECT_SERVER_HOST: "0.0.0.0"
      OBJECT_SERVER_PORT: 8004
      OBJECT_SERVER_DEBUG: "false"
      OBJECT_MODEL_CONFIDENCE: 0.8
      OBJECT_CAMERA_DEVICE: 0
      OBJECT_WEB_QUALITY: 90
      OBJECT_LOG_LEVEL: "INFO"
      OBJECT_MEASUREMENT_COORDINATE: "true"
      OBJECT_MEASUREMENT_DISTANCE: "true"
      OBJECT_MEASUREMENT_DIMENSION: "true"
    volumes:
      - ./models:/app/models
      - ./logs:/app/logs

システムサービスの例

# /etc/systemd/system/object-detection.service
[Unit]
Description=YOLO11 Object Detection Service
After=network.target

[Service]
Type=simple
User=object-detection
WorkingDirectory=/opt/object-detection
ExecStart=/opt/object-detection/venv/bin/python main.py
Restart=always
RestartSec=10

# 环境变量
Environment=OBJECT_SERVER_HOST=0.0.0.0
Environment=OBJECT_SERVER_PORT=8004
Environment=OBJECT_MODEL_PATH=/opt/object-detection/models/yolo11n_shape_detect_bayese_320x320_nv12_fix_forward.bin
Environment=OBJECT_CAMERA_DEVICE=0
Environment=OBJECT_LOG_LEVEL=INFO
Environment=OBJECT_MEASUREMENT_COORDINATE=true
Environment=OBJECT_MEASUREMENT_DISTANCE=true

[Install]
WantedBy=multi-user.target

📋 設定項目の詳細説明

1. アプリケーション設定 (app)

環境の種類:

• development: 開発環境。デバッグ機能を有効化
• testing: テスト環境。自動テストに使用
• production: 本番環境。パフォーマンス設定を最適化

2. サーバー設定 (server)

リッスンアドレスの説明:

• 0.0.0.0: すべてのネットワークインターフェースでリッスン
• 127.0.0.1: ローカルからのアクセスのみ
• 192.168.x.x: 特定のネットワークインターフェースを指定

ポートの説明:

• デフォルトポート 8004 は顔検出システム (8003) との競合を避けるためのものです
• ファイアウォールでこのポートへのアクセスが許可されていることを確認してください

3. モデル設定 (model)

パラメータの説明:

• 信頼度しきい値: 検出感度を制御します。幾何形状検出では 0.7-0.8 を推奨
• IOU しきい値: NMS 処理時の重なり度のしきい値。重複検出のフィルタリングに影響します
• モデルパス: 相対パスと絶対パスの両方に対応。幾何形状検出専用

4. カメラ設定 (camera)

デバイス ID の説明:

• 0: デフォルトのカメラ
• 1, 2, ...: その他のカメラデバイス
• Linux では /dev/video0、/dev/video1 などに対応

推奨解像度:

• 640x480: 標準解像度。リアルタイム検出に最適
• 1280x720: HD 解像度。より詳細な情報を提供
• 320x320: モデルの入力解像度。処理効率が最も高い

5. Web インターフェース設定 (web)

画質パラメータの推奨値:

• video_quality: 80-90 はネットワーク転送向け、90-100 はローカル表示向け
• stream_fps: 15fps で帯域幅を節約、25-30fps で滑らかな表示

6. 検出設定 (detection)

色設定の説明:

box_colors:
  - [0, 165, 255]  # 橙色检测框 (BGR格式)
  - [0, 255, 0]    # 绿色检测框
  - [0, 0, 255]    # 红色检测框

クラスの拡張:

• 新しいクラスを追加する場合は、class_names と box_colors を同時に更新する必要があります
• 色配列の順序はクラス名の順序と一致している必要があります

7. 計測設定 (measurement)

計測機能の説明:

• 座標系: 映像内に基準として X/Y 座標軸を表示
• 距離計測: 物体間のピクセル距離を計算して表示
• 寸法計測: 物体の境界ボックスの幅と高さを表示
• axis_length_percentage: 画像サイズに対する座標軸の割合 (0.0-1.0)

8. ログ設定 (logging)

ログレベル:

• DEBUG: 詳細なデバッグ情報（検出の詳細を含む）
• INFO: 一般的な情報（システム状態を含む）
• WARNING: 警告情報（検出異常など）
• ERROR: エラー情報（モデルの読み込み失敗など）
• CRITICAL: 重大なエラー（システムクラッシュなど）

✅ 設定の検証

起動時の検証

自動検証項目

システムの起動時に以下を自動的に検証します：

1. モデルファイル: 幾何形状検出モデルファイルが存在し、読み取り可能かを確認
2. カメラデバイス: カメラデバイスが利用可能かを検証
3. ポートの可用性: ポート 8004 が使用中でないかを確認
4. パラメータ範囲: 数値パラメータが有効範囲内にあるかを検証
5. 権限チェック: ファイルおよびデバイスへのアクセス権限を検証
6. クラス設定: 検出クラスと色設定の整合性を検証

検証失敗時の処理

# 配置验证示例
def validate_config(config):
    """配置验证函数"""
    errors = []

    # 验证模型文件
    if not Path(config.model.path).exists():
        errors.append(f"模型文件不存在: {config.model.path}")

    # 验证端口范围
    if not 1 <= config.server.port <= 65535:
        errors.append(f"端口号无效: {config.server.port}")

    # 验证置信度阈值
    if not 0.0 <= config.model.confidence_threshold <= 1.0:
        errors.append(f"置信度阈值超出范围: {config.model.confidence_threshold}")

    # 验证检测类别配置
    if len(config.detection.class_names) != len(config.detection.box_colors):
        errors.append("检测类别数量与颜色数量不匹配")

    # 验证测量配置
    if not 0.0 <= config.measurement.axis_length_percentage <= 1.0:
        errors.append(f"坐标轴长度百分比超出范围: {config.measurement.axis_length_percentage}")

    if errors:
        logger.error("配置验证失败:")
        for error in errors:
            logger.error(f"  - {error}")
        sys.exit(1)

設定のホットアップデート

ホットアップデートに対応した設定

• 検出パラメータ: 信頼度しきい値、IOU しきい値
• 表示オプション: 検出枠、中心点、統計情報の表示
• 計測オプション: 座標系、距離計測、寸法計測のオン/オフ
• 映像ストリームのパラメータ: 画質、フレームレート
• ログレベル: 実行時にログの詳細度を調整

ホットアップデート API

# 通过API更新配置
import requests

# 更新检测参数
response = requests.post('/api/settings', json={
    'confidence_threshold': 0.8,
    'show_detection_boxes': True,
    'show_center_point': False
})

print("配置更新结果:", response.json())

ホットアップデートに対応していない設定

以下の設定は、アプリケーションを再起動しないと反映されません：

• モデルファイルのパス
• カメラデバイスと解像度
• サーバーポート
• 検出クラスと色の設定

🎨 幾何形状検出専用の設定

色検出の最適化設定

オレンジ・緑・赤の幾何形状向けの専用設定：

# 专用几何形状检测配置
detection:
  class_names: ["orange", "green", "red"]

  # 优化的颜色配置 (BGR格式)
  box_colors:
    - [0, 165, 255]  # 橙色 - 温暖醒目
    - [0, 255, 0]    # 绿色 - 标准绿色
    - [0, 0, 255]    # 红色 - 警告红色

  # 文本显示配置
  text_color: [255, 255, 255]  # 白色文本，在所有背景下都清晰
  line_thickness: 2            # 适中粗细，清晰可见
  font_scale: 0.6             # 适中字体，不遮挡物体

  # 高置信度阈值，减少误检
  confidence_threshold: 0.7

  # 适中IOU阈值，处理重叠物体
  iou_threshold: 0.45

計測システム専用の設定

# 测量系统配置
measurement:
  # 坐标系统配置
  enable_coordinate_system: true
  axis_color: [255, 255, 255]      # 白色坐标轴
  axis_length_percentage: 0.8      # 占80%画面
  axis_thickness: 2                # 适中粗细

  # 距离测量配置
  enable_distance_measurement: true
  measurement_color: [255, 255, 0]  # 黄色测量线
  measurement_line_thickness: 2     # 清晰可见

  # 尺寸测量配置
  enable_dimension_measurement: true

  # 测量精度配置 (可扩展)
  distance_unit: "pixel"           # 距离单位
  dimension_unit: "pixel"          # 尺寸单位
  precision: 1                     # 小数精度

🔧 設定管理ツール

設定マネージャークラス

ConfigManager の実装

# config/config_manager.py
import yaml
import os
from pathlib import Path
from typing import Dict, Any
from dataclasses import dataclass

@dataclass
class ObjectDetectionAppConfig:
    """物体检测应用配置类"""

    @dataclass
    class AppConfig:
        name: str = "物体检测应用"
        version: str = "1.0.0"
        environment: str = "development"

    @dataclass 
    class ServerConfig:
        host: str = "0.0.0.0"
        port: int = 8004
        debug: bool = False

    @dataclass
    class ModelConfig:
        path: str = "models/yolo11n_shape_detect_bayese_320x320_nv12_fix_forward.bin"
        confidence_threshold: float = 0.7
        iou_threshold: float = 0.45

    @dataclass
    class CameraConfig:
        device_id: int = 0
        width: int = 640
        height: int = 480
        fps: int = 30
        async_capture: bool = True

    @dataclass
    class DetectionConfig:
        class_names: list = None
        box_colors: list = None
        text_color: list = None
        line_thickness: int = 2
        font_scale: float = 0.6

        def __post_init__(self):
            if self.class_names is None:
                self.class_names = ["orange", "green", "red"]
            if self.box_colors is None:
                self.box_colors = [[0, 165, 255], [0, 255, 0], [0, 0, 255]]
            if self.text_color is None:
                self.text_color = [255, 255, 255]

    @dataclass
    class MeasurementConfig:
        enable_coordinate_system: bool = True
        enable_distance_measurement: bool = True
        enable_dimension_measurement: bool = True
        axis_color: list = None
        measurement_color: list = None
        axis_length_percentage: float = 0.8
        axis_thickness: int = 2
        measurement_line_thickness: int = 2

        def __post_init__(self):
            if self.axis_color is None:
                self.axis_color = [255, 255, 255]
            if self.measurement_color is None:
                self.measurement_color = [255, 255, 0]

    app: AppConfig
    server: ServerConfig
    model: ModelConfig
    camera: CameraConfig
    detection: DetectionConfig
    measurement: MeasurementConfig

def load_config(config_path: str = "config/object_config.yaml") -> ObjectDetectionAppConfig:
    """加载配置文件"""

    # 1. 加载YAML配置
    config_file = Path(config_path)
    if config_file.exists():
        with open(config_file, 'r', encoding='utf-8') as f:
            yaml_config = yaml.safe_load(f)
    else:
        yaml_config = {}

    # 2. 应用环境变量覆盖
    config_dict = apply_env_overrides(yaml_config)

    # 3. 创建配置对象
    return create_config_object(config_dict)

def apply_env_overrides(config_dict: Dict[str, Any]) -> Dict[str, Any]:
    """应用环境变量覆盖"""

    env_mapping = {
        # 基础配置
        'OBJECT_SERVER_HOST': ['server', 'host'],
        'OBJECT_SERVER_PORT': ['server', 'port'],
        'OBJECT_SERVER_DEBUG': ['server', 'debug'],
        'OBJECT_MODEL_PATH': ['model', 'path'],
        'OBJECT_MODEL_CONFIDENCE': ['model', 'confidence_threshold'],
        'OBJECT_CAMERA_DEVICE': ['camera', 'device_id'],
        'OBJECT_LOG_LEVEL': ['logging', 'level'],

        # 几何形状检测专用
        'OBJECT_DETECTION_CLASSES': ['detection', 'class_names'],
        'OBJECT_MEASUREMENT_COORDINATE': ['measurement', 'enable_coordinate_system'],
        'OBJECT_MEASUREMENT_DISTANCE': ['measurement', 'enable_distance_measurement'],
        'OBJECT_MEASUREMENT_DIMENSION': ['measurement', 'enable_dimension_measurement'],
    }

    for env_var, config_path in env_mapping.items():
        if env_var in os.environ:
            value = os.environ[env_var]
            # 类型转换
            if config_path[1] in ['port', 'device_id']:
                value = int(value)
            elif config_path[1] in ['debug', 'enable_coordinate_system', 
                                    'enable_distance_measurement', 'enable_dimension_measurement']:
                value = value.lower() in ('true', '1', 'yes')
            elif config_path[1] in ['confidence_threshold', 'iou_threshold', 'axis_length_percentage']:
                value = float(value)
            elif config_path[1] == 'class_names' and isinstance(value, str):
                value = [name.strip() for name in value.split(',')]

            # 设置配置值
            set_nested_value(config_dict, config_path, value)

    return config_dict

🔧 トラブルシューティング

よくある設定の問題

よくある問題と解決方法

1. モデルファイルが見つからない

# 检查文件路径
ls -la models/
# 确认路径配置
echo $OBJECT_MODEL_PATH

1. カメラにアクセスできない

# 检查设备权限
ls -la /dev/video*
# 添加用户到video组
sudo usermod -a -G video $USER

1. ポートが使用中

# 检查端口占用
lsof -i :8004
# 或使用netstat
netstat -tulpn | grep 8004

1. 設定ファイルの形式エラー

# 验证YAML语法
python -c "import yaml; yaml.safe_load(open('config/object_config.yaml'))"

1. 検出クラスの設定が一致しない

# 检查类别和颜色配置是否一致
python -c "
import yaml
config = yaml.safe_load(open('config/object_config.yaml'))
classes = config['detection']['class_names']
colors = config['detection']['box_colors']
print(f'类别数量: {len(classes)}, 颜色数量: {len(colors)}')
if len(classes) != len(colors):
    print('错误: 类别和颜色数量不匹配')
"

デバッグ設定

デバッグモードの設定

# 调试配置示例
server:
  debug: true

logging:
  level: "DEBUG"
  format: "%(asctime)s - %(name)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s"

camera:
  async_capture: false  # 简化调试

web:
  stream_fps: 5  # 降低帧率便于观察

# 测量系统调试
measurement:
  enable_coordinate_system: true  # 始终显示坐标系
  enable_distance_measurement: true
  enable_dimension_measurement: true

環境変数のデバッグ

# 启用详细日志
export OBJECT_LOG_LEVEL=DEBUG
export OBJECT_SERVER_DEBUG=true

# 降低性能以便调试
export OBJECT_WEB_STREAM_FPS=5
export OBJECT_CAMERA_FPS=15

# 启用所有测量功能
export OBJECT_MEASUREMENT_COORDINATE=true
export OBJECT_MEASUREMENT_DISTANCE=true
export OBJECT_MEASUREMENT_DIMENSION=true

# 启动应用
python main.py

パフォーマンスチューニング設定

高性能設定

# 高性能配置示例
camera:
  async_capture: true
  fps: 30

web:
  stream_fps: 25
  video_quality: 85

model:
  confidence_threshold: 0.8  # 减少误检，提高性能

# 选择性启用测量功能
measurement:
  enable_coordinate_system: false  # 关闭坐标系提高性能
  enable_distance_measurement: true
  enable_dimension_measurement: false

# 线程配置
performance:
  capture_buffer_size: 3
  processing_threads: 2

低遅延設定

# 低延迟配置示例
camera:
  fps: 30
  async_capture: true

web:
  stream_fps: 30  # 与摄像头同步
  video_quality: 70  # 降低质量以减少编码时间

model:
  confidence_threshold: 0.7  # 平衡检测速度和精度

# 简化测量系统
measurement:
  enable_coordinate_system: false
  enable_distance_measurement: true  # 仅保留核心测量功能
  enable_dimension_measurement: true

高精度設定

# 高精度配置示例  
camera:
  width: 1280
  height: 720  # 更高分辨率

model:
  confidence_threshold: 0.8  # 更高阈值减少误检
  iou_threshold: 0.3        # 更低IOU提高检测精度

web:
  video_quality: 95  # 高质量视频流
  stream_fps: 15     # 适当降低帧率保证处理质量

# 启用完整测量系统
measurement:
  enable_coordinate_system: true
  enable_distance_measurement: true
  enable_dimension_measurement: true
  axis_length_percentage: 0.9  # 更大坐标系