カメラ映像を用いた視線方向・サッカード・頭部姿勢推定ツール
プログラムの動作の様子の動画:[動画]
実行ファイル:[exe]
実行ファイル(exe)は、Chrome または Firefox を用いてダウンロードすることを推奨。初回実行時に、SmartScreenの「WindowsによってPCが保護されました」の警告画面が出ます。警告画面で「詳細情報」をクリック、「実行」をクリックで続行できます。
説明資料: [PDF], [PPTX] , [動画](クリックして再生開始), クレジット:動画は「VOICEVOX:青山龍星」、「Vrew」、「Gemini」を用いて作成
本資料とコードの作成にAIを使用。
目的
文章を読んでいる人の両眼の視線方向、サッカード(衝動性眼球運動)、瞬目を、赤外線照明を用いない市販のウェブカメラで計測し、CSV ファイルに記録する Windows 用の実験ツールである。カメラ 1 台で計測できる。チェスボードで較正した 2 台のカメラで計測する方式(以下、2 カメラ計測)では、視線方向の誤差が小さくなり、計測できる頭部の向きの範囲が広がる。
ウェブカメラは、フレームレートが通常 30〜60 fps と低く、視線方向の測定雑音も大きい。このため、検出できるサッカードは振幅が数度以上のものに限られる。黙読時の行内のサッカード(平均約 2°)を 1 回ずつ検出する用途には適さない。適するのは、改行時の大きな戻り、逆行(読み戻し)、行ごとの注視位置、瞬目、眼球運動の総量を指標とする用途である。
計測の原理
以下で、右眼・左眼は被験者自身の右眼・左眼を指す。フレームはカメラまたは動画の 1 枚の画像を、標本は解析した 1 フレームから得た値の組を指す。標本化周波数は、解析した標本の 1 秒あたりの数である。
視線方向
MediaPipe Face Landmarker(Google の学習済みモデル)で、顔画像から虹彩を含む 478 点の 3 次元の特徴点を推定する。表情でほとんど動かない約 50 点(額、鼻、目尻、頬骨など)を、本人の頭部の基準形状に Kabsch 法で重ね、頭部の 3 次元の姿勢を求める。頭部の基準形状は、20 フレームの特徴点の平均から作る。
眼球は半径 12 mm の球と仮定し、目尻と目頭の中点の約 4.5 mm 後方に眼球中心を置く。虹彩中心は、画像上の虹彩中心を通るカメラの光線と、眼球中心から 10.48 mm の球面との交点とする(10.48 mm は、眼球の半径と虹彩の半径 5.85 mm から三平方の定理で求めた値)。視線方向は眼球中心から虹彩中心へ向かう方向であり、眼球の光軸の推定値である。光軸は、実際に見ている方向(視軸)から数度ずれている(このずれを κ角という)。
視線方向は、頭部に固定した座標系の Fick 角で表す。水平角は鉛直軸まわりの回転で、正が被験者の左(画像の右)である。垂直角はその後の水平軸まわりの回転で、正が上である。この値は頭部に対する眼球の向きなので、頭部が回転すると、同じ文字を見ていても値が変わる。
較正と検証
カメラのレンズを注視したときの正しい視線方向は、眼球中心からレンズへ向かう方向(以下、レンズ方向)である。較正では、カメラのレンズを注視している間の推定した視線方向をレンズ方向へ重ねる回転を、眼ごとに求め、以後の視線方向に適用する。補正できるのは、κ角など、視線方向によらない一定の偏りだけである。視線方向によって変わる誤差(角度の倍率の誤差など)は補正できない。
検証では、カメラのレンズを注視している間の次の量を求める。
- 正確度:推定した視線方向とレンズ方向のなす角の平均
- 精度 RMS-S2S:連続する 2 標本の視線方向のなす角の二乗平均平方根。サッカード検出から除外した標本をまたぐ組は用いない。検出できるサッカードの振幅の下限の目安になる。
- 精度 SD:両眼を合わせた視線方向と、その平均方向とのなす角の二乗平均平方根
瞬目
まぶたの開き具合は EAR(Eye Aspect Ratio、Soukupová & Čech, 2016)で表す。EAR は、上まぶたと下まぶたの距離(2 組の平均)を、目尻と目頭の距離で割った値で、眼を閉じると小さくなる。
片眼ごとの瞬目は、頭部の前額面に投影した特徴点で求めた EAR で判定する。EAR が「0.75 × 基準値」を下回った時刻を開始、「0.85 × 基準値」以上に戻った時刻を終了とする(前後の標本から線形補間)。基準値は、その眼の開眼時の直近 300 標本の EAR の中央値である。EAR の固定の値ではなく基準値との比で判定するのは、開眼時の EAR が人と視線の上下で異なり、30 fps では瞬目の最も閉じた瞬間が写らないことが多いためである。持続 0.04〜0.9 秒を瞬目とし(直前の瞬目の終了から 0.12 秒以内は数えない)、0.9 秒を超える閉眼は長い閉眼とする。
瞬目中は虹彩の特徴点が動き、見かけのサッカードが生じる。そこで、次の 2 つの区間を、開始の 0.10 秒前から終了の 0.12 秒後まで、サッカード検出から除外する。
- 瞬目区間:eyeBlink 係数(MediaPipe が出力するまぶたの閉じ具合の係数。0〜1 の表情係数で、確率ではない)が大きいか、相対 EAR(画像上の EAR を本人の開眼時の値で割ったもの。両眼の平均)が小さい区間
- 閉眼区間:片眼ごとの瞬目の判定で、どちらかの眼が閉眼の区間
サッカードの判定は 0.25 秒以上遅れて確定するので、瞬目が始まる直前の標本も遡ってサッカード検出から除外できる。
サッカードの検出
Engbert & Kliegl (2003) の速度閾値法を、両眼平均の視線方向に適用する。サッカードでは両眼が同じ方向に動き、測定雑音は両眼で独立とみなせるので、両眼を平均すると測定雑音が相対的に小さくなる。以下で、角速度は水平・垂直の 2 成分をもつ量、角速さはその大きさを指す。
- 角速度:各標本の前後 m 標本ずつ(計 2m + 1 標本)に当てはめた最小二乗直線の傾き(1 次の Savitzky–Golay 微分)とする。標本の間隔が不規則でも求まる。窓の標本数は、窓の時間幅が 100 ms(注視の最小持続時間。Manor & Gordon, 2003)以下になるように、実測の標本化周波数から決める。15〜25 Hz で 3 標本、30〜50 Hz で 5 標本、60 Hz で 7 標本、120 Hz で 13 標本である。
- 速度閾値:角速度の水平・垂直の成分のそれぞれについて、直近 200 標本の角速度のばらつき(中央値を基準とする標準偏差)の λ 倍を速度閾値とする。両成分をそれぞれの速度閾値で割った点が単位円の外側にある標本を、候補の標本とする(楕円閾値)。角速度のばらつきは、速度閾値を超えた標本を除いて推定し直すことを繰り返して求める(Nyström & Holmqvist, 2010 に倣う)。サッカードが続く読解では、サッカード中の角速度が混じって速度閾値が上がり、検出漏れが起きるためである。
- 候補区間と振幅:候補の標本が続く区間を候補区間とする。平滑化で 1 つにつながった連続サッカードは、角速さの谷で 2 つの候補区間に分ける。振幅は、候補区間の前と後それぞれ 100 ms 分の標本の位置の中央値のなす角である。開始・終了時刻は、サッカード方向の変位が 10 %・90 % に達した時刻である。棄却されなかった候補区間をサッカードとする(棄却の条件は「入力と処理の流れ」に示す)。
- 継続時間とピーク角速度:サッカードの継続時間は、振幅 A [°] に対しておよそ 2.2·A + 21 ms である(主系列。Carpenter, 1988)。30 Hz の標本間隔 33 ms は、振幅 5° 以下のサッカードの継続時間より長い。このとき継続時間とピーク角速度は求まらない。そこで、ピーク角速度は標本化周波数が 200 Hz 以上の場合だけ、継続時間(変位 10〜90 % の時間)は標本間隔が主系列の継続時間の 1/4 以下の場合だけ記録し、それ以外は空欄にする。
入力と処理の流れ
入力は次の 3 種類から選ぶ。
- カメラ:実時間で処理する。常に最新のフレームだけを解析し、解析が間に合わなかったフレームは破棄する。露出を固定するため、カメラは DirectShow で、圧縮形式 MJPG を要求して開く(開けない場合は、理由を起動画面に表示する)。開始時に、フレームレート 300 → 120 → 60 → 30 fps の各段階について解像度 1920×1080 → 1280×720 → 640×480 の順に要求し、実際にフレームを取得してフレームレートを実測する(ドライバの報告値は実際と異なることがあるため。直前と同一の画像は新しいフレームとして数えない)。実測したフレームレートが最高値の 90 % 以上のモードのうち、解像度が最も高いものを使う。この確認には十数秒〜数十秒かかる。
- 動画ファイル:全フレームを欠落なく順に処理する。各フレームの時刻は、動画に記録された各フレームの表示時刻(PTS)で、最初のフレームを 0 とする。このため、可変フレームレートの動画でも時刻はずれない。表示時刻が単調に増えない動画は、そのフレームで解析を止め、理由を表示する。
- デモ動画:正面から撮影した、文章を読む人物の動画である。初回の選択時に自動でダウンロードする。
各フレームは次の順に処理する。
- 特徴点の推定。複数の顔が写っている場合は、計測する 1 人(以下、主対象)を選ぶ。顔は最大 4 人まで検出し、最も大きく写っている人を主対象とする。
- 頭部姿勢とカメラから顔までの距離の推定。頭部の基準形状は、追跡開始時、較正時、主対象の交替時に作る。頭部の基準形状を作るときのカメラから顔までの距離は、虹彩の水平径を 11.7 mm と仮定して、その見かけの大きさから求める。以後のカメラから顔までの距離は、頭部の基準形状に対する顔全体の見かけの大きさから求める。2 カメラ計測では、頭部の基準形状を 2 台のカメラの画像から三角測量で求めるので、虹彩の水平径の仮定を用いない。
- 視線方向の推定と、較正による補正
- 瞬目の判定と、瞬目区間・閉眼区間のサッカード検出からの除外
- サッカードの検出
- 表示と、記録中であれば CSV ファイルへの書き出し
次の標本はサッカード検出から除外する。
- いずれかの眼の視線方向が得られない標本
- 瞬目区間・閉眼区間(前後の余裕時間を含む)の標本
- 追跡開始直後と主対象の交替直後の標本。相対 EAR の基準値(eyeBlink 係数が 0.3 以下の 15 標本)と、速度閾値の推定に必要な 20 個の角速度がそろうまでで、処理の遅れを含めて 30 Hz で約 1.5 秒、60 Hz で約 0.9 秒である。
- 角速度の窓が標本の途切れ(0.2 秒と標本間隔の 2.5 倍の長い方を超える間隔)をまたぐ標本
次の候補区間は棄却する。
- 振幅が最小振幅未満の候補区間
- 候補区間とその前後で、頭部の回転の角速さが上限を超えた候補区間
- 候補区間とその前後で、主対象、2 カメラ計測で視線方向を求めた視点の組、または較正の補正が替わった候補区間。これらが替わると、注視中でも視線方向が段差状に変わるためである。
記録ファイル
プログラムと同じフォルダの gaze_logs フォルダに、次の 2 種類の CSV ファイル(UTF-8)を保存する。値が得られない欄は空欄になる。
- samples_日時.csv(以下、samples ファイル。標本ごとに 1 行):
- 時刻と通し番号:t_s、unix_s、frame_seq(PC 側で付けたフレームの通し番号)、skipped_frames_before(直前の行との間に破棄したフレーム数)
- 状態:face(顔検出の有無)、valid(頭部姿勢が有効か)、blink(瞬目区間か)、hold(表示の更新を止めているか)、head_status(頭部姿勢が無効な理由。有効なら ok)、n_faces(検出した顔の数)、subject_id(主対象の通し番号)、views(視線方向を求めた視点の組:A = カメラ 1、B = カメラ 2、AB = 2 台)、cam2_dt_ms(カメラ 2 とカメラ 1 のフレームの時刻差)
- 視線方向:両眼の水平角・垂直角 [°](az/el_R/L_deg)、カメラ座標系の単位ベクトル(gR/gL_x,y,z。x 右、y 下、z 前方)
- 頭部:頭部姿勢角(head_yaw/pitch/roll_deg。ヨーは正が被験者の左(画像の右)、ピッチは正が上、ロールは正が画像上で時計回り)、位置(head_x/y/z_mm)、カメラから顔までの距離(head_dist_mm)、頭部の回転の角速さ(head_ang_speed_deg_s)
- 瞬目の判定量:rel_EAR(相対 EAR)、blink_score(eyeBlink 係数の左右の大きい方)
- 片眼ごとの値(R_・L_ で始まる列):虹彩中心 [px]、虹彩の見かけの長径 [px]、眼球の角速さ(連続 2 標本の視線方向のなす角 / 時間間隔)[°/s]、EAR、eyeBlink 係数、開閉眼、瞬目の累積回数、視線方向を求めなかった理由(status。求めた場合は ok)
- events_日時.csv(以下、events ファイル。事象ごとに 1 行):type、eye(R、L、両眼は RL)、開始・終了時刻、継続時間、振幅、方向、ピーク角速度、事象付近の標本化周波数、検出に使った平滑化角速さの最大値。type は次のいずれかである。
- saccade:サッカード。方向は 0° が被験者の左(画像の右)、90° が上
- blink:片眼の瞬目。long_closure:長い閉眼。blink_gate:瞬目区間
- marker:マーカー。calibration:較正の完了。subject_change:主対象の交替
- param_lam・param_min_amp・param_head_gate:検出パラメータの値(記録の開始時と、計測中に変更した時)
時刻は 2 種類で記録する。t_s は計測開始からの秒である。unix_s は、カメラ入力では Unix 時刻であり、刺激提示ソフトウェアなど他のソフトウェアの記録と照合できる。動画入力では撮影時の実時刻が分からないので、unix_s は空欄にする。
画面操作およびキー操作
起動画面(「開始」タブ。「ヘルプ」タブに操作手順、計算方法、記録ファイルの列、ライセンスを記載)
- 入力:カメラ、動画ファイル、デモ動画のいずれかを選ぶ。カメラの場合は、カメラ番号と露出を指定する(解像度とフレームレートは自動で選ぶ)。露出は指数 x で指定し、多くのカメラでは露光時間 2x 秒に対応する(-6 は約 1/64 秒。対応はカメラによって異なる)。既定の「フレームレートに合わせる」は、実測したフレームレートの 1 フレーム間隔に収まる最長の露光時間(30 fps なら -5、60 fps なら -6)を選び、設定後に実測し直してフレームレートが下がった場合は 1 段ずつ(最大 3 段)短くする。数値を指定すると、その値で固定する。動画ファイルの場合は、「参照」ボタンでファイルを指定する。
- 第 2 カメラ番号:2 カメラ計測の場合に入力する(空欄なら 1 台で計測する)。先に、チェスボードの内側の交点数(横・縦)とマス目の一辺 [mm] を入力し、「2 カメラの較正(チェスボード)」ボタンで 2 カメラの較正を行う。印刷したチェスボードを両方のカメラに写し、向きと位置を変えては静止させると、20 姿勢を自動で撮影する。2 カメラの較正の結果は保存され、再投影誤差とカメラ間の距離が表示されるので、カメラ間の距離を物差しで測った値と比べて確認する。カメラ番号または解像度が 2 カメラの較正の時と異なると、計測を開始できない。
- 水平画角 [°](既定 62):カメラの水平方向の画角である。カメラから顔までの距離と眼球中心の位置の計算に使う。動画ファイルの場合は、その動画を撮影したカメラの値を指定する。2 カメラ計測では使わず、2 カメラの較正で求めた焦点距離を使う。
- 画面の大きさ:標準(縦 768 画素)または 4K(全画面)。計測中も F11 キーで切り替えられる。
- 閾値係数 λ(既定 6):速度閾値を、角速度のばらつきの何倍にするか。大きくすると誤検出は減るが、小さなサッカードの検出漏れが増える。
- 最小振幅 [°](既定 2):振幅がこの値未満の候補区間を棄却する。速度閾値の下限もこの値から決まる(測定雑音が極端に小さいときに速度閾値が 0 に近づくのを防ぐため)。
- 頭部回転の角速さの上限 [°/s](既定 150):候補区間とその前後で、頭部の回転の角速さがこの値を超えた候補区間を棄却する。
- 開始と同時にデータ記録を始める(既定はオン)
- 「開始」ボタン:計測を始める。初回は学習済みモデルを自動でダウンロードする。
- 「自己検証」ボタン:真値が既知の合成データで、幾何計算、サッカード検出、瞬目の判定、主対象の選択、2 カメラ計測と 2 カメラの較正を検証し、項目ごとに合格・不合格を表示する。参考として、窓の標本数の決め方の比較と、振幅別の再現率も表示する。カメラは不要で、完了まで 1〜2 分程度かかる。
計測画面(「計測」「集計」「ヘルプ」のタブ)
- カメラ画像:円は虹彩の輪郭で、瞬目区間では赤になる。緑の点は目尻と目頭である。矢印は推定した視線方向で、右眼が水色、左眼が橙である。矢印は表示用に平滑化しており(One Euro Filter)、視線がカメラに近い方向を向くほど短く見える。記録とサッカード検出には平滑化前の値を使う。複数の顔が写っている場合は、主対象を緑、他の人を灰色の枠で示す。
- 3D 表示:レンズの中心を原点とする座標系(単位 cm)で、特徴点、眼球モデル、視線方向を表示する。ドラッグで視点を回転し、マウスホイールで拡大・縮小する。表示が暗いときは、視線方向が無効であるか、表示の更新を止めている。
- 上段の右端:カメラの実測したフレームレート・解像度・露出指数(ドライバが受理したかと読み返し値)、解析のフレームレートの概数、3D 表示とカメラ画像の入り切り
- 状態表示:追跡中、瞬目区間、頭部姿勢が無効などの状態。「眼裂幅が小さいため、矢印と 3D 表示の視線方向の更新を停止中」の間は表示の更新を止めるが、標本はサッカード検出に使う。
- 計測情報タブ:「解析標本レート」(解析した標本の時刻の間隔から求めた標本化周波数で、カメラのフレームレートではない)、破棄したフレーム数、サッカード検出の標本化周波数と窓の標本数、検出した顔の数、頭部姿勢角、カメラから顔までの距離、片眼ごとの眼球の角速さ・EAR・eyeBlink 係数・虹彩の見かけの長径、値を求めなかった理由、棄却した候補区間の数
- 検証結果タブ:V キーによる検証の結果
- 検出パラメータタブ:閾値係数 λ、最小振幅、頭部回転の角速さの上限を、スライダーで計測中に変更できる。変更は以後に処理する標本に適用され(検出済みのサッカードは変わらない)、記録中であれば変更の時刻と値が events ファイルに残る。
- 時系列グラフ:直近 6 秒間。上段は水平角、中段は垂直角で、水色が右眼、橙が左眼である。下段の黄線は両眼平均の角速さ、赤線は速度閾値の目安(楕円閾値の 2 つの半径の幾何平均)である。灰色の帯は瞬目区間・閉眼区間、赤い帯はサッカードの区間である。候補の標本の判定は楕円閾値で行うので、黄線が赤線を超えても候補の標本にならない場合があり、その逆もある。
- サッカード一覧:直近のサッカードを新しい順に最大 8 件。「平滑化角速さの最大」は検出に使った角速さの区間内の最大値であり、ピーク角速度ではない。継続時間は、記録しない場合は「—」になる。
- 集計タブ:頭部追跡の開始からのすべてのサッカードの、方向(被験者から見た向き。扇形の面積が回数に比例)と振幅の分布、水平成分が被験者の左向き・右向きの回数
キー操作(大文字・小文字のどちらでもよい。同じ機能のボタンも画面にある)
- C:較正。1.5 秒の待機、頭部の基準形状の取得(20 フレーム)、標本の取得(1.5 秒以上かつ 20 標本以上)が順に行われる。その間は頭部を静止させ、カメラのレンズを注視し続ける。注視が安定して標本が集まると完了し、眼ごとの補正の回転角が表示される。2 カメラ計測では、カメラ 1(「カメラ番号」のカメラ)のレンズを注視する。
- V:検証。1.5 秒の待機の後、2 秒以上かつ 20 標本以上の標本を取得する。その間はカメラのレンズを注視し続ける(頭部は少し動かしてもよい)。終了後、正確度と精度(RMS-S2S、SD)が表示される。
- L:CSV ファイルへの記録の開始・停止。開始するたびに新しいファイルを作る。
- M:events ファイルにマーカーを記録する。記録を止めている間に押したマーカーは、画面の個数には加わるが、events ファイルには残らない。
- P:カメラ画像の表示の入り切り(切ると画像の縮小と重ね描きも止まる)。D:3D 表示の入り切り。この 2 つは処理の負荷が大きく、切ると解析のフレームレートが上がる。T:3D 表示の顔のメッシュの入り切り。R:3D 表示の視点を初期状態に戻す。
- F1:ヘルプとメイン画面の切り替え。F11:画面の大きさ(標準 ⇔ 4K 全画面)の切り替え。
- Esc:記録ファイルを閉じて終了する。
実行上の注意点
- 動作環境は Windows に限られる。
- 初回の開始時には、インターネット接続が必要である。学習済みモデルを models フォルダに、デモ動画を選んだ場合はデモ動画を demo フォルダに保存する。2 回目以降は保存済みのファイルを使う。
- 記録の前に C キーで較正する。較正前の視線方向には、κ角などによる眼ごとの一定の偏りが残る。頭部の基準形状と較正の補正は、人とカメラの配置によって異なるので、被験者が替わったときやカメラの位置を変えたときは、較正をやり直す。記録中に較正すると、その前後で角度の基準が変わるので、events ファイルの calibration の時刻で区間を区別する。較正が終わらない場合は、まばたきを控えてカメラのレンズを注視し続ける。C キーを押し直すと、最初からやり直せる。
- 測定精度を実験ごとに測定し、報告する。測定雑音は、被験者、照明、カメラによって異なる。較正の後に V キーで検証し、正確度と RMS-S2S を記録する。正確度はレンズ方向の 1 点で得た値であり、他の視線方向での正確度は保証されない。
- 検出性能の目安:次の値は合成データでの結果であり、実際の映像での性能を保証しない。現行版の値は「自己検証」で確認できる。
- 測定雑音の標準偏差 0.7°、瞬目の人工物を含む 300 秒のデータでの再現率:60 Hz では振幅 1° がほぼ 0 %、3° 以上がほぼ 100 %。30 Hz では 1° がほぼ 0 %、3° が約 85 %、5° 以上がほぼ 100 %。誤検出は 60 Hz で 1 件、30 Hz で 0 件であった。
- 読解に近いデータ(片眼の測定雑音の標準偏差 0.6°)で検出率が 50 % になる振幅:片眼の RMS-S2S の約 1.5 倍(60 Hz)、約 2.4 倍(30 Hz)、約 2.9 倍(20 Hz)。
- 視線方向を文章上の位置と対応させるには、顎台などで頭部を固定する。記録される視線方向は頭部に対する眼球の向きなので、頭部が回転すると値が変わる。
- 被験者は顔をカメラへ向け、両眼が映るようにする。いずれかの眼の視線方向が得られない標本は、サッカード検出から除外する。頭部の前後軸とカメラの光軸のなす角が 60° 以上の標本は無効になる(2 カメラ計測では、どちらかのカメラに対して 60° 未満なら有効)。
- 被験者以外の人がカメラの近くに来ないようにする。主対象より面積が 1.5 倍を超えて大きく写る顔が 1 秒以上続くと、または主対象が 1 秒以上写らず他の人が写っていると、主対象が替わる(写っている顔が 1 つだけで、大きさが直前の主対象の 1/1.5〜1.5 倍なら、同じ人とみなして計測を続ける)。主対象が替わると、頭部の基準形状、較正の補正、瞬目の基準値、角速度のばらつきの推定を取り直し、events ファイルに subject_change が残るので、C キーで較正し直す。
- 水平画角は、カメラの仕様書で確認して設定する。実際と異なる値では、カメラから顔までの距離と眼球中心の位置に誤差が生じ、視線方向に系統誤差が出る。
- 十分な照明を用意する。露光時間を固定して撮影するため、暗いと画像が暗くなる。自動露出を使わないのは、暗いと露光時間が延びてフレームレートが下がるためである。画像が暗い場合は、まず照明を明るくする。露出の指数を大きくしても明るくなるが、露光時間がフレーム間隔を超えるとフレームレートが下がる(指数 -5、約 1/32 秒ならフレームレートの上限は約 32 fps)。カメラによっては露出の設定が反映されない(反映されたかは画面上段の右端に表示される)。
- 刺激の提示は、追跡が始まってから 2 秒以上たってから始める。追跡開始直後(30 Hz で約 1.5 秒、60 Hz で約 0.9 秒)の標本は、サッカード検出から除外する。
- 破棄したフレームの数を確認する。「解析標本レート」がカメラの実測したフレームレートより低いのは、解析が間に合わずフレームを破棄しているためである。破棄したフレーム数は画面に表示され、samples ファイルでは skipped_frames_before 列と frame_seq の欠番として残る。破棄したフレームが多い場合は、他のアプリケーションを終了し、カメラ画像(P)と 3D 表示(D)を切る。
- 時刻の精度には限界がある。カメラ入力の時刻は PC がフレームを受け取った時刻であり、センサーの露光時刻に対して一定でない遅れを含む。マーカーは、キーを押した直後に解析を始めたフレームの時刻で記録される(このフレームはキーを押す前に取得されたものの場合もある)。刺激とミリ秒単位で同期する場合は、フォトダイオードなどで刺激の提示時刻を別に計測する。2 カメラ計測では、2 台のカメラは同期しておらず、フレームの時刻差(最大で標本間隔の半分程度)を cam2_dt_ms に記録する。
- 動画ファイルは、各フレームの表示時刻(PTS)が記録されたものを使う。表示時刻が単調に増えない動画は、そのフレームで解析が止まる。
- 計測は Esc キーまたは「終了」ボタンで終える。記録ファイルへの書き出しは約 1 秒ごとなので、異常終了すると直近の記録が失われる場合がある。
- 研究倫理の手続きへの記載:MediaPipe Tasks は、入力画像を端末内で処理し、Google のサーバーへ送信しない。一方で、API の性能と利用状況の指標(メトリクス)を Google へ送信する。MediaPipe の公式の説明は、これについてアプリの利用者から法令に従って同意を得る責任を、開発者に求めている。
exeファイルの作成手順
cd /d c:\users\user\proj\gaze_saccade
python -m venv venv
venv\Scripts\activate.bat
python -m pip install --upgrade pip
pip install -U --no-user pyinstaller pytest numpy mediapipe opencv-contrib-python
pyinstaller --onefile --clean --noconfirm --collect-all numpy --collect-all mediapipe --collect-all opencv-contrib-python gaze_saccade.py
実行ファイル:[exe]
実行ファイル(exe)は、Chrome または Firefox を用いてダウンロードすることを推奨。初回実行時に、SmartScreenの「WindowsによってPCが保護されました」の警告画面が出ます。警告画面で「詳細情報」をクリック、「実行」をクリックで続行できます。
ソースコード実行のための前準備
Python 3.12 のインストール
Pythonのインストールを行い、Pythonのプログラムを実行する環境を整える。扱う環境は、Windows搭載パソコンである。金子研究室では、Python 3.12.10を推奨する。
[Windows での Python 3.12 のインストール手順を見るには、ここをクリック]
Windows での Python 3.12 のインストール
以下のいずれかの方法でPython 3.12をインストールする。Pythonがインストール済みの場合、この手順は不要である。
方法 1:winget によるインストール
【インストールコマンドの実行方法】
管理者権限でコマンドプロンプトを起動する(手順:Windowsキーまたはスタートメニュー → cmd と入力 → 右クリック → 「管理者として実行」)。そして、コマンド全体をコマンドプロンプトにコピー&ペーストする。
--scope machine を指定することで、システム全体(全ユーザー向け)にインストールされる。このオプションの実行には管理者権限が必要である。インストール完了後、コマンドプロンプトを再起動するとPATHが反映される。
REM Python 3.12 をシステム領域にインストール
winget install --id Python.Python.3.12 -e --scope machine --silent --accept-source-agreements --accept-package-agreements --override "/quiet InstallAllUsers=1 PrependPath=1 Include_test=0 Include_pip=1 Include_launcher=1 InstallLauncherAllUsers=1 TargetDir=\"C:\Program Files\Python312\""
if not "%ERRORLEVEL%"=="0" ( color 0c & echo Python 3.12 のインストールに失敗しました & ping 127.0.0.1 -n 6 >nul & color )
REM Python と Scripts を PATH 先頭に追加
powershell -NoProfile -Command "$p='C:\Program Files\Python312'; $s=\"$p\Scripts\"; if(Test-Path $p){$k=[Microsoft.Win32.Registry]::LocalMachine.OpenSubKey('SYSTEM\CurrentControlSet\Control\Session Manager\Environment',$true); $c=$k.GetValue('Path','',[Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames); $t=$k.GetValueKind('Path'); $new=$c; if((';'+$new+';') -notlike \"*;$p;*\"){$new=$p+';'+$new}; if((';'+$new+';') -notlike \"*;$s;*\"){$new=$s+';'+$new}; if($new -ne $c){$k.SetValue('Path',$new,$t)}; $k.Close()}"
REM 現在のセッションにも反映(システムPATHを再取得して連結)
for /f "usebackq tokens=2,*" %A in (`reg query "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path`) do set "PATH=%B"
REM pip / wheel の更新
python -m pip install --no-user -U pip wheel
if not "%ERRORLEVEL%"=="0" ( color 0c & echo pip / wheel の更新に失敗しました & ping 127.0.0.1 -n 6 >nul & color )
方法 2:インストーラーによるインストール
- Python公式サイト(https://www.python.org/downloads/)にアクセスし、「Download Python 3.x.x」ボタンからWindows用インストーラーをダウンロードする。
- ダウンロードしたインストーラーを実行する。
- 初期画面の下部に表示される「Add python.exe to PATH」にチェックを入れてから「Customize installation」を選択する。このチェックを入れ忘れると、コマンドプロンプトから
pythonコマンドを実行できない。 - 「Install Python 3.xx for all users」にチェックを入れ、「Install」をクリックする。
インストールの確認
コマンドプロンプトで以下を実行する。
python --version
バージョン番号(例:Python 3.12.x)が表示されればインストール成功である。「'python' は、内部コマンドまたは外部コマンドとして認識されていません。」と表示される場合は、インストールが正常に完了していない。
Python の開発環境 Visual Studio Code のインストールと Python 用の設定
Python の開発環境Visual Studio Code(プログラムを編集するソフトウェア。以下、VS Code)を整える。
[Windows での Visual Studio Code のインストールと Python 用の設定手順を見るには、ここをクリック]
Windows での Visual Studio Code のインストールと Python 用の設定手順
1. VS Code と拡張機能のインストール
以下のコマンドにより,既存の VS Code を削除し,全ユーザー共有の設定で再インストールしたうえで,拡張機能(VS Code に機能を追加するソフトウェア)をまとめて導入する.
【インストールコマンドの実行方法】
管理者権限でコマンドプロンプトを起動する(手順:Windows キーまたはスタートメニュー → cmd と入力 → 右クリック → 「管理者として実行」)。そして,コマンド全体をコマンドプロンプトにコピー&ペーストする。
インストールコマンド
REM ============================================================
REM Microsoft Visual Studio Code
REM ============================================================
REM Build Tools + Desktop development with C++(VCTools)+ 追加コンポーネント(一括)
REM 未インストール時: winget で新規インストール
REM インストール済み時: setup.exe modify でコンポーネント追加(バージョンは変更しない)
winget list --id Microsoft.VisualStudio.BuildTools 2>nul | findstr /i "BuildTools" >nul 2>&1
if %ERRORLEVEL% EQU 0 (
for /f "usebackq delims=" %P in (`"C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe" -products Microsoft.VisualStudio.Product.BuildTools -property installationPath`) do start /wait "" "C:\Program Files (x86)\Microsoft Visual Studio\Installer\setup.exe" modify --installPath "%P" --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Workload.MSBuildTools --add Microsoft.VisualStudio.Component.VC.CMake.Project --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --add Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset --add Microsoft.VisualStudio.Component.Windows11SDK.26100 --add Microsoft.VisualStudio.Component.VC.v143.x86.x64 --includeRecommended --quiet --norestart --nocache
if not "%ERRORLEVEL%"=="0" ( color 0c & echo Build Tools のコンポーネント追加に失敗しました & ping 127.0.0.1 -n 6 >nul & color )
) else (
winget install --scope machine --id Microsoft.VisualStudio.BuildTools -e --silent --disable-interactivity --force --accept-source-agreements --accept-package-agreements --override "--quiet --wait --norestart --nocache --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --add Microsoft.VisualStudio.Workload.MSBuildTools --add Microsoft.VisualStudio.Component.VC.CMake.Project --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --add Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset --add Microsoft.VisualStudio.Component.Windows11SDK.26100 --add Microsoft.VisualStudio.Component.VC.v143.x86.x64"
if not "%ERRORLEVEL%"=="0" ( color 0c & echo Build Tools のインストールに失敗しました & ping 127.0.0.1 -n 6 >nul & color )
)
REM 全ユーザー共有の拡張機能フォルダ
if not exist "C:\ProgramData\vscode-extensions" mkdir "C:\ProgramData\vscode-extensions"
icacls "C:\ProgramData\vscode-extensions" /grant "Everyone:(OI)(CI)M" /T
REM スタートメニューのショートカットを --extensions-dir 付きで再作成
if exist "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code" rmdir /s /q "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code"
if exist "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code.lnk" del "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code.lnk"
powershell -NoProfile -Command "$s=New-Object -ComObject WScript.Shell; $lnk=$s.CreateShortcut('C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code.lnk'); $lnk.TargetPath='C:\Program Files\Microsoft VS Code\Code.exe'; $lnk.Arguments='--extensions-dir \"C:\ProgramData\vscode-extensions\"'; $lnk.Save()"
REM ショートカットの検証
powershell -NoProfile -Command "$s=New-Object -ComObject WScript.Shell; $lnk=$s.CreateShortcut('C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio Code.lnk'); Write-Host 'TargetPath:' $lnk.TargetPath; Write-Host 'Arguments:' $lnk.Arguments"
REM ファイル / フォルダ右クリックの「Code で開く」を登録
reg add "HKLM\SOFTWARE\Classes\*\shell\VSCode\command" /ve /d "\"C:\Program Files\Microsoft VS Code\Code.exe\" --extensions-dir \"C:\ProgramData\vscode-extensions\" \"%1\"" /f
reg add "HKLM\SOFTWARE\Classes\Directory\shell\VSCode\command" /ve /d "\"C:\Program Files\Microsoft VS Code\Code.exe\" --extensions-dir \"C:\ProgramData\vscode-extensions\" \"%1\"" /f
reg add "HKLM\SOFTWARE\Classes\Directory\Background\shell\VSCode\command" /ve /d "\"C:\Program Files\Microsoft VS Code\Code.exe\" --extensions-dir \"C:\ProgramData\vscode-extensions\" \"%V\"" /f
REM --extensions-dir 付きで起動する code.cmd ラッパを作成
REM (%* を echo で書くと対話的 cmd で失われるため、PowerShell で [char]37+'*' を書き出す)
powershell -NoProfile -Command "$pct=[char]37; $q=[char]34; $c='@echo off'+[char]13+[char]10+$q+'C:\Program Files\Microsoft VS Code\bin\code.cmd'+$q+' --extensions-dir '+$q+'C:\ProgramData\vscode-extensions'+$q+' '+$pct+'*'+[char]13+[char]10; [IO.File]::WriteAllText('C:\ProgramData\vscode-extensions\vscode.cmd',$c,[Text.Encoding]::ASCII)"
REM 拡張機能のインストール
set "CODE=C:\Program Files\Microsoft VS Code\bin\code.cmd"
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --uninstall-extension GitHub.copilot
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --uninstall-extension GitHub.copilot-chat
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension ms-python.python
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension ms-python.vscode-pylance
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension ms-python.debugpy
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension MS-CEINTL.vscode-language-pack-ja
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension saoudrizwan.claude-dev
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension rust-lang.rust-analyzer
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension tamasfe.even-better-toml
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension anthropic.claude-code
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --install-extension almenon.arepl
"%CODE%" --extensions-dir "C:\ProgramData\vscode-extensions" --list-extensions --show-versions
REM settings.json を作成(自動更新オフ、Python、Claude Code 設定)
if not exist "%APPDATA%\Code\User" mkdir "%APPDATA%\Code\User"
python -c "import json,os;data={'update.mode':'none','update.enableWindowsBackgroundUpdates':False,'extensions.autoUpdate':False,'python.defaultInterpreterPath':r'C:\Program Files\Python312\python.exe','claudeCode.environmentVariables':[{'name':'ANTHROPIC_API_KEY','value':'not-needed'},{'name':'ANTHROPIC_AUTH_TOKEN','value':'ollama'},{'name':'ANTHROPIC_BASE_URL','value':'http://localhost:11434'},{'name':'ANTHROPIC_MODEL','value':'glm-4.7-flash'},{'name':'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC','value':'1'}]};p=os.path.join(os.environ['APPDATA'],'Code','User','settings.json');open(p,'w',encoding='utf-8').write(json.dumps(data,indent=4));print('Done:',p)"
REM 自動更新の抑止ポリシー(settings.json に加えて、レジストリ側でも明示的にオフ)
reg add "HKLM\SOFTWARE\Policies\Microsoft\VSCode" /v "UpdateMode" /t REG_SZ /d "none" /f
echo === セットアップ完了 ===
2. Python インタプリタの選択
同一マシンに複数の Python がインストールされている場合,VS Code で使用する Python 本体(インタプリタ:Python プログラムを解釈・実行するソフトウェア)を選択する必要がある.
- コマンドパレット(コマンド名で機能を呼び出す VS Code の入力欄)を開く(
Ctrl+Shift+P) Python: Select Interpreterと入力する
- 表示される一覧から,使用する Python(例:
C:\Program Files\Python312\python.exe)を選択する.
必要なライブラリをシステム領域にインストール
管理者権限でコマンドプロンプトを起動する
(手順:Windowsキーまたはスタートメニュー → cmd と入力 → 右クリック → 「管理者として実行」)。
以下を実行する。
REM MediaPipe 標準機能のインストール
pip uninstall -y opencv-python-headless opencv-contrib-python-headless opencv-python
pip install -U --no-user numpy mediapipe opencv-contrib-python
ソースコード
保存し、Visual Studio Code などで実行する。