blender-mask-peoples/docs/debugging.md

デバッグガイド

処理プロセスの単体デバッグ

顔検出処理をBlenderアドオンから独立してテストできます。

セットアップ

# 仮想環境をアクティベート
source .venv/bin/activate

# 必要なパッケージがインストールされていることを確認
pip install ultralytics opencv-python torch

基本的な使い方

画像ファイルで検出をテスト

# 検出結果を画面に表示
python debug_detector.py --image path/to/image.jpg

# 検出結果を保存
python debug_detector.py --image path/to/image.jpg --output result.jpg

# マスク画像も保存
python debug_detector.py --image path/to/image.jpg --output result.jpg --save-mask

動画ファイルで検出をテスト

# 特定のフレームをテスト
python debug_detector.py --video path/to/video.mp4 --frame 100

# フレーム範囲をテスト（画面表示）
python debug_detector.py --video path/to/video.mp4 --start 0 --end 10

# フレーム範囲を処理して動画保存
python debug_detector.py --video path/to/video.mp4 --start 0 --end 100 --output result.mp4

パラメータ調整

# 信頼度閾値を調整（デフォルト: 0.5）
python debug_detector.py --image test.jpg --conf 0.3

# NMS IoU閾値を調整（デフォルト: 0.45）
python debug_detector.py --image test.jpg --iou 0.5

# マスクサイズを調整（デフォルト: 1.5）
python debug_detector.py --image test.jpg --mask-scale 2.0

# マスクのぼかし半径を調整（デフォルト: 20）
python debug_detector.py --image test.jpg --feather-radius 30

カスタムモデルの使用

python debug_detector.py --image test.jpg --model path/to/custom_model.pt

推論サーバーの単体起動

推論サーバーを単独で起動してテストすることもできます。

サーバー起動

# 仮想環境をアクティベート
source .venv/bin/activate

# サーバーを起動（ポート8181）
python server/main.py

APIテスト

別のターミナルで：

# サーバー状態を確認
curl http://127.0.0.1:8181/status

# マスク生成をリクエスト
curl -X POST http://127.0.0.1:8181/generate \
  -H "Content-Type: application/json" \
  -d '{
    "video_path": "/path/to/video.mp4",
    "output_dir": "/tmp/masks",
    "start_frame": 0,
    "end_frame": 10,
    "conf_threshold": 0.5,
    "iou_threshold": 0.45,
    "mask_scale": 1.5
  }'

# タスクの状態を確認（task_idは上記レスポンスから取得）
curl http://127.0.0.1:8181/tasks/{task_id}

# タスクをキャンセル
curl -X POST http://127.0.0.1:8181/tasks/{task_id}/cancel

トラブルシューティング

GPU（ROCm）が認識されない

# PyTorchがROCmを認識しているか確認
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"

# ROCm環境変数を確認
echo $ROCM_PATH
echo $HSA_OVERRIDE_GFX_VERSION

環境変数が設定されていない場合：

source .envrc
# または
eval "$(direnv export bash)"

モデルが見つからない

デフォルトモデルは models/yolov8n-face-lindevs.pt に配置する必要があります。

ls -l models/yolov8n-face-lindevs.pt

メモリ不足エラー

大きな動画を処理する場合、メモリ不足になる可能性があります：

• フレーム範囲を小さく分割して処理
• --conf 閾値を上げて検出数を減らす
• より小さいモデルを使用

デバッグのベストプラクティス

1. まず画像でテスト: 動画よりも画像の方が早く結果を確認できます
2. パラメータの影響を理解: --conf、--mask-scale などを変えて結果を比較
3. 小さいフレーム範囲から始める: 動画テストは最初は5-10フレーム程度で
4. 結果を保存して比較: --output オプションで結果を保存し、パラメータごとに比較