ノートPCカメラの1名動画から「手・体・口（表情）」を自動解析：鏡像補正つきオーバーレイ動画とCSVを一発生成（Google Colab＋MediaPipe）

TL;DR（最初に要点）

• やること：ノートPCカメラで撮った1名の人物動画を、手（左右21点）・体（33点）・口（唇の外周/内周）で自動解析。

• 成果物：

  1. 詳細オーバーレイ動画（色分け＋番号ラベル）

  2. 簡易オーバーレイ動画（見やすさ優先）

  3. フレーム×部位の長い形式（tidy）CSV

  4. 口の開き・肘角度・手の開き等の要約CSV

  5. 色・ラベル凡例を収めたJSON（第三者と仕様共有に便利）

• 鏡像対策：解析のときだけ左右反転→保存は元向き（動画/座標とも）。プレビューが鏡像でも、出力は常に元の向きで揃います。

こんな人向け

• 自分の説明や発話の“手振り・口の開き”を定量化して振り返りたい

• 研究や教育で姿勢・ジェスチャ・口の開閉のタイムスタンプ付きログが欲しい

• インストール不要で、ブラウザだけで動くワークフローが欲しい（Google Colab）

いますぐ試す（Open in Colab）

GitHubのノートブック：

★ Googleアカウントがあれば無料で実行OK。GPUは不要（CPUで動きます）。

必要なもの

• 解析したい動画ファイル（.mp4等）

  • ノートPCのカメラアプリで撮影した1名のみが映る動画を推奨

  • プレビューは鏡像でもOK（記録動画は通常、非反転で保存されます）

• Googleアカウント（Colabを使うため）

手順（3ステップ）

1. Colabを開く
   上のOpen in Colabボタンを押してノートブックを開く。
2. セルを上から順に実行
   1つ目のセルで必要ライブラリ（mediapipe==0.10.14 など）を自動インストールします。
3. 解析対象の動画をアップロード
   ノートブック中ほどの「動画アップロード」セルの実行時に、ファイル選択ダイアログが出ます。解析したい.mp4等を1ファイル選んでアップロード。

実行完了後、成果物は /content/output_＜元ファイル名＞/ にまとまって出力されます。

出力されるファイルと見方のコツ

① 詳細オーバーレイ動画：*_overlay_detailed.mp4

• 色分け＋番号ラベルで、どの点がどの部位かが一目で分かります。

• 色の意味（BGR）：体=黄色, 左手=緑, 右手=赤, 唇外周/内周=マゼンタ。この割当てはJSONにも保存されます。

• ラベル例：P11=左肩、L8=左手 人差し指先端、R4=右手 親指先端、Lo3/Li3=唇外周/内周のインデックス。

黄色い線が目や口の近くにも出る理由：体（Pose）には顔まわり（鼻・目・口角・耳）も含まれるため、顔周辺に黄色い線が表示されます。口の形そのものはマゼンタで描かれる唇輪郭です（正常挙動）。

② 簡易オーバーレイ動画：*_overlay_simple.mp4

• 太線のみで見やすさ優先。検出できているかの動作確認に最適。

③ 長い形式CSV（tidy）：*_landmarks_long.csv

後解析の主役。Excel/スプレッドシート/統計ツールで扱いやすい行方向に長い形式です。
主な列：

• frame / time_ms：フレーム番号 / ミリ秒

• part："pose" | "hand" | "lips_outer" | "lips_inner"

• side：手のみ "Left" | "Right"（元の向き基準）

• landmark_index / name：点のインデックスと名称（体・手は付与）

• x, y：ピクセル座標（左上原点, 右が+X, 下が+Y）

• z_norm：MediaPipeの正規化z

• visibility：Poseのみ（0〜1の見えやすさ指標）

鏡像対策の仕様：解析時だけ左右反転→保存は元向きへ戻すので、CSVの座標も動画と同じ向きで解釈できます（学会共有・共同研究でも混乱しにくい）。

④ 要約CSV：*_summary_metrics.csv

• mouth_open_px：上唇(13)–下唇(14)距離

• mouth_width_px：口角(61)–(291)距離

• mouth_open_ratio：開口/横幅（発話や開口の指標に）

• left/right_hand_open：手首–指先距離の平均を基準長で正規化（手の開き具合）

• left/right_elbow_deg：肩-肘-手首の肘角度（°）

⑤ 凡例JSON：*_schema_and_legend.json

• 色の割当て、体・手のインデックス→部位名、唇の外周/内周のインデックス、座標系の注記（鏡像→元向き）がまとまっています。図表や報告書に書き写すときの“正”として使えます。

なぜ「鏡像補正」が要るの？

• Windowsのカメラアプリはプレビューが鏡像（左右反転）でも、記録ファイルは非反転が一般的。

• 本ノートブックは推論入力だけ左右反転し、検出座標は x→(1−x) で元向きに戻して保存しています。

• だから、出力動画もCSVも“元の向き”で統一。後工程（解析・統合・論文化）で向きの混乱が起きません。

すぐできる活用例（レシピ）

例1：開口の大きい瞬間（上位5箇所）を探す

import pandas as pd
df = pd.read_csv('/content/output_xxx/xxx_summary_metrics.csv')
top5 = df.nlargest(5, 'mouth_open_ratio')[['frame','time_ms','mouth_open_ratio']]
top5

→ 発話の強調点や「あ・い・う」などの口型の大きい箇所の当たりを付けられます。

例2：右肘角度が大きく曲がったタイミングを抽出

import pandas as pd
df = pd.read_csv('/content/output_xxx/xxx_summary_metrics.csv')
hit = df[df['right_elbow_deg'] < 70]  # 例：70°未満を曲げとみなす
hit[['frame','time_ms','right_elbow_deg']].head()

→ ジェスチャの山を効率的に拾えます。

例3：画面外で手が消えた区間をチェック（NaN判定）

import pandas as pd
df = pd.read_csv('/content/output_xxx/xxx_summary_metrics.csv')
missing = df['left_hand_open'].isna().sum()
print('左手が検出できなかったフレーム数:', missing)

→ カメラ位置やフレーミングの改善に役立ちます。

よくある質問 & トラブルシューティング

Q1. 動画を選んだのに処理が始まらない

A. セルを上から順に実行してください（インストール→アップロード→解析）。インストールに時間がかかる場合があります。

Q2. 右手しか検出されない／片方がずっとNaN

A. 画面外・遮蔽・暗さが原因です。フレーミングや照明を調整してください。片手のみ映っている動画でも正常動作です（right_hand_openだけ値が入る等）。

Q3. 出力動画が再生できない／真っ黒

A. ダウンロードしてローカルで再生してください。Colabプレビューが不安定な場合があります。
また、動画コーデックは mp4v を使用しています。再エンコードで改善することもあります。

Q4. 黄とマゼンタが重なって見づらい

A. 口の形そのものはマゼンタ（唇輪郭）、黄色は体（Pose）の顔まわりです。気になる場合は顔の黄色線を非表示にする設定が可能です（下のカスタマイズ参照）。

Q5. FPSが0になってタイムスタンプがおかしい

A. 一部動画でFPSが取得できないことがあるため、ノートブック側で安全策として30FPSを用います。実測FPSに合わせたい場合は、動画の正確なFPSを指定するようコードを調整してください。

見た目＆出力のカスタマイズ

A. 顔の黄色線（Poseの顔だけ）を隠す

HIDE_POSE_FACE = True
FACE_LANDMARKS = set(range(0, 11))  # nose/eyes/ears/mouth_left/right

# POSE_CONNECTIONS を描くループ内で
for (i, j) in POSE_CONNECTIONS:
    if HIDE_POSE_FACE and (i in FACE_LANDMARKS and j in FACE_LANDMARKS):
        continue
    cv2.line(detailed, pi, pj, COLOR_POSE, thk)

B. 色の割当てを変更（例：体=シアン）

COLOR_POSE = (255, 255, 0)  # BGR（既定は黄色= (0,255,255)）

色の割当ては凡例JSONにも保存されるので、発表資料や論文の凡例と常に一致させられます。

C. 指標を追加（例：肩幅・手の速度・膝角度 など）

summary_rows に列を追加して、summary_metrics.csv に追記するだけ。
速度/加速度はフレーム差分で求められます（平滑化には移動平均推奨）。

プライバシー・倫理的配慮

• 本人同意のある動画のみを解析する

• JSONの凡例・スクリーンショット等も、個人が特定されない範囲で共有

ライセンス / 環境

• 実行環境：Google Colab（ブラウザのみ、GPU不要）

• 主要依存：mediapipe==0.10.14, opencv-python, pandas, numpy, pyarrow, tqdm

• 出力：MP4 2種 + CSV 2種 + JSON（凡例）

• JSONには色・部位名・座標系の注記が含まれます（再現性・第三者共有の要）。

参考：ノートブック

GitHub: https://github.com/cSAS3/MediaPipe-usage-codes/blob/main/LaptopCam_1Person_Holistic_Analyzer.ipynb

Colabで開く:

さいごに

このワークフローは、手・体・口の動きを一括で可視化→CSV化できるのが強みです。「見える化」→「数値化」→「活用」という流れを、Colabだけで完結できます。
授業・発表・面接練習・医療研究の予備検討など、動画×動作データの裾野を広げる足がかりにしてください。

凡例JSON（色・部位名・座標系）に関する記述は、このノートブックが出力する *_schema_and_legend.json の内容に基づいています。（体=黄色、左手=緑、右手=赤、唇外周/内周=マゼンタ、解析は鏡像→保存は元向き、など）