マーカーレス動画解析 Webアプリ

要件定義書 + Claude Code 実装プロンプト | 2026-03-02

概要・目的
技術選定
アーキテクチャ
機能要件
画面設計
データ構造
非機能要件
実装フェーズ
参考 GitHub プロジェクト
Claude Code 実装プロンプト

1. 概要・目的

目的: スマホ/タブレットで撮影した動画をアップロードし、マーカーなしで人体の姿勢推定・関節角度計算・動作分析を行うWebアプリケーション。

主なユースケース:

リハビリテーション評価（関節可動域 ROM、歩行分析）
運動機能の経時変化記録
セラピスト・患者間での動作確認の共有

ターゲットユーザー: セラピスト（理学療法士・作業療法士）、リハビリ担当者

2. 技術選定

姿勢推定エンジン比較

ライブラリ	キーポイント	3D	ブラウザ動作	精度	ライセンス
MediaPipe BlazePose 推奨	33点	対応	対応 (WASM+GPU)	高	Apache 2.0
MoveNet Thunder	17点	非対応	対応 (TF.js)	中	Apache 2.0
YOLOv8 Pose	17点	非対応	対応 (ONNX)	高	AGPL-3.0
OpenPose	25-135点	対応	不可	最高	非商用

MediaPipe BlazePose を推奨する理由: 33キーポイント（業界最多クラス）、3D座標対応、ブラウザ完結可能、Apache 2.0ライセンス、Google公式サポート。リハビリに必要な関節角度（肩・肘・手首・股関節・膝・足首）を全てカバー。

技術スタック

レイヤー	技術	理由
フロントエンド	Vite + React + TypeScript	既存プロジェクトと統一、高速開発
姿勢推定	@mediapipe/tasks-vision	33キーポイント、3D、ブラウザ完結
動画処理	HTML5 Video API + Canvas	標準API、追加依存なし
グラフ描画	Recharts or Chart.js	React親和性、時系列データ表示
データ保存	Firebase Firestore	既存インフラ活用
デプロイ	Vercel	既存ワークフロー

サーバーサイド Python は不要: MediaPipe Tasks Vision はブラウザ内で完結するため、動画データをサーバーに送信しない。医療データのプライバシー保護の観点からも最適。

3. アーキテクチャ

┌─────────────────────────────────────────────────────────────┐ │ スマホ / タブレット │ │ ┌───────────┐ │ │ │ 動画撮影 │──── WiFi/USB ────┐ │ │ └───────────┘ │ │ └──────────────────────────────────┼───────────────────────────┘ │ ┌──────────────────────────────────▼───────────────────────────┐ │ PC ブラウザ (Chrome/Edge) │ │ │ │ ┌──────────┐ ┌──────────────┐ ┌──────────────────────┐ │ │ │ 動画 │ │ MediaPipe │ │ 関節角度計算 │ │ │ │ アップ │──▶│ BlazePose │──▶│ (三角関数) │ │ │ │ ロード │ │ WASM+GPU │ │ │ │ │ └──────────┘ └──────────────┘ └──────────┬───────────┘ │ │ │ │ │ ┌──────────────────────┐ ┌─────────────────▼────────────┐│ │ │ スケルトン描画 │ │ 結果表示 ││ │ │ (Canvas overlay) │ │ ・時系列グラフ ││ │ │ │ │ ・関節角度テーブル ││ │ └──────────────────────┘ │ ・CSV/PDFエクスポート ││ │ └──────────────────────────────┘│ │ │ │ └─────────────────────────────────────────┼─────────────────────┘ │ (結果のみ保存) ┌───────▼──────┐ │ Firestore │ │ (解析結果) │ └──────────────┘

ポイント: 動画データはブラウザ内のみで処理。サーバーには解析結果（JSON）のみ送信。

4. 機能要件

4.1 動画入力

ファイルアップロード（MP4, MOV, WebM）
ドラッグ&ドロップ対応
最大ファイルサイズ: 500MB
動画プレビュー（再生・一時停止・シーク）
解析範囲の指定（開始秒〜終了秒）

4.2 姿勢推定

MediaPipe BlazePose による33キーポイント検出
フレーム単位の処理（1-30 FPS選択可能）
進捗バー表示
Web Worker によるバックグラウンド処理（UI ブロックなし）

4.3 スケルトン描画

動画上にキーポイントとボーン（骨格線）をオーバーレイ
再生と同期したスケルトンアニメーション
キーポイントの信頼度に応じた色分け表示

4.4 関節角度計算

関節	計算に使う3点	臨床的意義
肩関節屈曲	肘 - 肩 - 腰	上肢リハビリ評価
肘関節屈曲	肩 - 肘 - 手首	上肢機能評価
股関節屈曲	肩 - 腰 - 膝	歩行・立ち上がり評価
膝関節屈曲	腰 - 膝 - 足首	歩行分析、TKA術後
足関節背屈	膝 - 足首 - つま先	歩行分析
体幹前傾	肩中点 - 腰中点 - 鉛直線	姿勢評価

4.5 結果表示・出力

関節角度の時系列グラフ（折れ線チャート）
フレームごとの角度テーブル
最大・最小・平均角度のサマリー
左右差の表示
CSVエクスポート
PDFレポート生成（任意、Phase 2）

4.6 履歴管理（Phase 2）

解析結果を Firestore に保存
過去の解析との比較表示
患者ごとの経時変化追跡

5. 画面設計

┌──────────────────────────────────────────────────────────────┐ │ ヘッダー: Motion Analyzer [履歴] [設定] │ ├──────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────┐ ┌────────────────────────┐│ │ │ │ │ 解析設定 ││ │ │ 動画プレーヤー │ │ ├ FPS: [5 ▼] ││ │ │ + スケルトンオーバーレイ │ │ ├ 対象関節: [全て ▼] ││ │ │ │ │ ├ 開始: [00:00] ││ │ │ ▶ ■ ━━━━━●━━━━ 01:23 │ │ └ 終了: [01:23] ││ │ │ │ │ ││ │ └─────────────────────────────┘ │ [▶ 解析開始] ││ │ │ ████████░░░ 78% ││ │ ┌─────────────────────────────┐ └────────────────────────┘│ │ │ 関節角度グラフ │ │ │ │ 180°┤ │ ┌────────────────────────┐│ │ │ 150°┤ /\ /\ │ │ サマリー ││ │ │ 120°┤ / \ / \ │ │ 右膝: 12° - 142° ││ │ │ 90°┤ / \/ \ │ │ 左膝: 15° - 138° ││ │ │ 60°┤ / \ │ │ 左右差: 最大4° ││ │ │ └────────────────── │ │ ││ │ │ 0s 5s 10s 15s │ │ [CSV] [PDF] ││ │ └─────────────────────────────┘ └────────────────────────┘│ └──────────────────────────────────────────────────────────────┘

6. データ構造

解析結果 JSON

{
  "id": "analysis_001",
  "createdAt": "2026-03-02T12:00:00Z",
  "videoMeta": {
    "name": "patient_walk_01.mp4",
    "duration": 15.2,
    "fps": 30,
    "width": 1920,
    "height": 1080
  },
  "settings": {
    "analysisFps": 5,
    "startTime": 0,
    "endTime": 15.2,
    "model": "blazepose_heavy"
  },
  "frames": [
    {
      "timestamp": 0.0,
      "landmarks": [
        { "x": 0.52, "y": 0.18, "z": -0.1, "visibility": 0.99 },
        ...  // 33 points
      ],
      "angles": {
        "rightShoulder": 45.2,
        "leftShoulder": 43.8,
        "rightElbow": 162.3,
        "leftElbow": 158.7,
        "rightHip": 168.4,
        "leftHip": 170.1,
        "rightKnee": 172.8,
        "leftKnee": 169.5,
        "rightAnkle": 88.2,
        "leftAnkle": 90.1,
        "trunkForwardLean": 5.3
      }
    }
  ],
  "summary": {
    "rightKnee": { "min": 12.3, "max": 172.8, "mean": 145.6, "rom": 160.5 },
    "leftKnee": { "min": 15.1, "max": 169.5, "mean": 142.3, "rom": 154.4 },
    ...
  }
}

7. 非機能要件

項目	要件
プライバシー	動画はブラウザ内のみで処理。サーバーに動画を送信しない
対応ブラウザ	Chrome 90+, Edge 90+, Safari 15+
処理速度	30秒の動画 (5FPS解析) を60秒以内に処理
ファイルサイズ	最大500MB
対応動画形式	MP4 (H.264), MOV, WebM
アクセシビリティ	本文16px以上、コントラスト比4.5:1以上
レスポンシブ	PC優先（解析はPC推奨）、結果閲覧はモバイル対応

8. 実装フェーズ

Phase 1: MVP（コア機能）

プロジェクト初期化（Vite + React + TS）
動画アップロード・プレビュー UI
MediaPipe BlazePose 統合
スケルトン描画（Canvas オーバーレイ）
関節角度計算エンジン
時系列グラフ表示
CSV エクスポート
Vercel デプロイ

Phase 2: 拡張機能

Firebase 連携（解析結果保存）
患者管理・履歴表示
過去データとの比較グラフ
PDF レポート生成
解析範囲指定 UI

Phase 3: 高度な分析

歩行分析（歩行周期、ストライド長推定）
バランス評価（重心動揺）
複数カメラ対応（将来）

9. 参考 GitHub プロジェクト

プロジェクト	用途	ライセンス
tfjs-models/pose-detection	TF.js 姿勢推定統合 API（MoveNet/BlazePose）	Apache 2.0
MediaPipe Tasks Vision (公式)	BlazePose Web 実装ガイド	Apache 2.0
perfanalytics/pose2sim	3Dキネマティクス参考実装（Python）	Apache 2.0
stanfordnmbl/opencap-core	Stanford 3D動作解析プラットフォーム	Apache 2.0
Yolov8-Pose on Browser	ONNX Runtime Web での姿勢推定参考	MIT

10. Claude Code 実装プロンプト

Phase 1 実装プロンプト（コピーして使用）

# マーカーレス動画解析 Webアプリ - Phase 1 実装

## 概要
スマホ/タブレットで撮影した動画をPCブラウザでアップロードし、
MediaPipe BlazePose で姿勢推定 → 関節角度計算 → グラフ表示する
Webアプリを作成してください。

## 技術スタック
- Vite + React + TypeScript
- @mediapipe/tasks-vision (PoseLandmarker)
- Recharts（時系列グラフ）
- Tailwind CSS
- デプロイ: Vercel

## 重要な制約
- 動画はブラウザ内のみで処理（サーバーに送信しない）
- モック・スタブ禁止（実際の MediaPipe モデルを使用）
- 日本語 UI
- アクセシビリティ: 本文16px以上、コントラスト比4.5:1以上

## 機能要件

### 1. 動画アップロード
- ファイル選択 + ドラッグ&ドロップ
- 対応形式: MP4, MOV, WebM
- 動画プレビュー（再生・一時停止・シーク）

### 2. 姿勢推定
- MediaPipe PoseLandmarker で33キーポイント検出
- 解析FPS選択: 1, 5, 10, 15, 30
- 進捗バー表示
- 解析中もUIがフリーズしないこと

### 3. スケルトン描画
- 動画上に Canvas でキーポイント + ボーンをオーバーレイ
- 再生と同期
- 信頼度に応じた色分け（高: 緑、中: 黄、低: 赤）

### 4. 関節角度計算
以下の関節角度を3点間のベクトル角度で算出:
- 肩関節屈曲（左右）: 肘-肩-腰
- 肘関節屈曲（左右）: 肩-肘-手首
- 股関節屈曲（左右）: 肩-腰-膝
- 膝関節屈曲（左右）: 腰-膝-足首
- 足関節背屈（左右）: 膝-足首-つま先
- 体幹前傾角: 肩中点-腰中点-鉛直線

### 5. 結果表示
- 時系列折れ線グラフ（関節ごと、左右比較可能）
- サマリーテーブル（最小・最大・平均・ROM）
- フレーム一覧テーブル
- CSVエクスポート

## ディレクトリ構成
```
src/
├── components/
│   ├── VideoUploader.tsx      # アップロード UI
│   ├── VideoPlayer.tsx        # 動画再生 + スケルトンオーバーレイ
│   ├── AnalysisControls.tsx   # 解析設定・開始ボタン
│   ├── AngleChart.tsx         # 時系列グラフ
│   ├── AngleSummary.tsx       # サマリーテーブル
│   └── FrameTable.tsx         # フレーム一覧
├── lib/
│   ├── pose-analyzer.ts       # MediaPipe 初期化・推論
│   ├── angle-calculator.ts    # 関節角度計算
│   ├── skeleton-renderer.ts   # Canvas 描画
│   └── csv-exporter.ts        # CSV出力
├── types/
│   └── analysis.ts            # 型定義
├── App.tsx
└── main.tsx
```

## MediaPipe キーポイントマッピング（参考）
```
0: nose, 11: left_shoulder, 12: right_shoulder,
13: left_elbow, 14: right_elbow,
15: left_wrist, 16: right_wrist,
23: left_hip, 24: right_hip,
25: left_knee, 26: right_knee,
27: left_ankle, 28: right_ankle,
31: left_foot_index, 32: right_foot_index
```

## 作業ディレクトリ
C:\Users\kawag\work\motion-analyzer

Generated by Claude Code | 2026-03-02