# 依頼：瞳孔・虹彩・眼球運動・生体情報のリアルタイム計測・AI体験プログラムの作成

あなたは卓越したソフトウェアアーキテクトであり、コンピュータビジョンおよび生体計測分野のAIエンジニアです。
以下の要件・理念・制約に基づき、Windows上で動作する「瞳孔・虹彩・眼球運動・脈波の計測とAIの仕組みを体験・学習・実験するための単一ファイルPython GUIプログラム」を設計し、完成したコード全体を出力してください。

---

## 1. 理念と設計姿勢

* **利用者価値の最優先**：コードを書き始める前に、利用者がこのプログラムを通じてどのような発見や納得を得るかを深く考え抜き、アーキテクチャとUI/UXを設計してください。
* **自律的な技術選定と実装**：具体的なアルゴリズムの実装方法、クラス設計、スレッド管理、数式処理、GUI構築の詳細は、あなた自身が最適解を判断して決定してください。
* **判断の優先順位**：設計や実装で迷った場合は、以下の優先順位を厳守してください。
**法令・ライセンス・安全性 ＞ Windowsで動作すること ＞ 主要機能の実現 ＞ AI体験の豊かさ**

---

## 2. ゴールと目指す利用者体験

Windows上で動作する、AIの体験・学習・実験のための実用的な計測プログラムを完成させます。利用者が単に数値を眺めるだけでなく、「触ってよかった」「期待以上だった」と実感できる以下の具体的な体験を実現してください。

1. **「自分の目と体の微細な反応が手に取るようにわかる」驚き（直感的な可視化体験）**
* Webカメラに向かって顔を動かしたり、視線を素早く動かしたり（サッカード）、まばたきをしたり、照明の明るさを変えたりした瞬間に、カメラ映像上のオーバーレイ（虹彩・瞳孔の輪郭や視線ベクトル）と複数段のリアルタイム時系列グラフが滑らかに連動する。


* 「まばたきをしている最中から終了までグラフ全体に灰色の半透明帯が引かれ、視線を素早く動かした区間に赤いサッカード帯が現れる」といった視覚的フィードバックにより、無意識の身体反応が複数の指標で同時にデータ化される面白さを直感的に味わえる。




2. **「AIが何を根拠にどう計算しているのかが腑に落ちる」納得感（ブラックボックスの解明）**
* 推定結果の数値だけでなく、AIモデルに入力されている「切り出された眼の拡大画像とセグメンテーションマスク」や、推論の分類スコア、さらには「なぜ今のフレームでは角度を計算しなかったのか（頭部の向きすぎ、残差過大、閉眼など）」という誠実な棄却理由がリアルタイムに明示される。


* 計算の内訳や中間変数（焦点距離、奥行きの尺度、幾何モデルの判別式、平滑化前後の値、脈波の周波数ピークとSNRなど）をいつでも覗き見ることができ、「AIや幾何モデルが裏側でどう働いているか」を実験しながら深く学べる。




3. **「パラメータを変えてAIの挙動を試せる」実験の楽しさ（インタラクティブな学習体験）**
* 分類スコアのしきい値やカメラの水平画角、視線の校正（キャリブレーション）、AI可視化のオン・オフなどをGUI上で即座に切り替えられ、「しきい値を下げると検出は増えるが誤検出も混じる」「校正を行うと光軸から視軸へ補正される」といったAI・計測工学の本質を、自分の顔やデモ動画を使って安全かつ快適に実験できる。





---

## 3. 実現すべき主要機能（最低限満たすべき仕様）

### 3.1 入力と実行環境

* **単一ファイルのPythonプログラム**として完結させ、標準的なコマンド（`python スクリプト名.py`）でGUIが起動し、すべての操作がGUI上で完結すること。また、`pyinstaller` 等での単一実行ファイル（exe）化も考慮したパス設計（スクリプトまたはexeと同じフォルダ配下に `models`、`demo`、`eye_logs` フォルダを配置）にすること。


* **3つの入力ソース**をGUIからいつでも切り替え・開始・停止できること：


1. **Webカメラ**：利用可能なカメラを検索し、**フレームレートが高いことを優先し、そのうえで解像度が最も高い**撮影モードを、実際にフレームを取得して実測したうえで自動選択する。

 * カメラの扱い
  1 リアルタイム・インタラクティブ処理
  2 DirectShow（CAP_DSHOW）で開く（露出を固定できるのは DirectShow だけであるため）。DirectShow でどの撮影モードも取得できない場合に限り、Media Foundation（CAP_MSMF）で開く（このとき露出は設定できず、カメラ側の設定のままとする）。Media Foundation の起動遅延を避けるため、cv2 の読み込み前に環境変数 `OPENCV_VIDEOIO_MSMF_ENABLE_HW_TRANSFORMS=0` を設定する。
  3 カメラの最高性能（特にフレームレート）を引き出す。撮影モードは次の手順で選ぶ。
    * 要求の順：フレームレート 300 → 120 → 60 → 30 fps の各段階について、解像度 1920×1080 → 1280×720 → 640×480 の順に要求する。1920×1080 を超える解像度は用いない。
    * 実測：ドライバの報告値（CAP_PROP_FPS など）は実際と異なることがあるため用いず、撮影モードの切り替え後 0.3 s 読み捨ててから 0.7 s の間実際にフレームを取得し、実測フレームレートと実際の解像度を求める。直前のフレームと画素が同一のフレーム（ドライバが同じ画像を繰り返し渡す場合。縦横とも 1/16 に間引いた画素で比較）は数えない。
    * 要求の設定：MJPG を指定する（無圧縮の YUY2 は USB の帯域のため、高解像度では高いフレームレートが出ないことが多い）。DirectShow では幅・高さを変えると形式が無圧縮に戻ることがある一方、MJPG の指定はその時点の幅・高さで再構成を起こすため、MJPG は幅・高さ・フレームレートの前と後の両方で指定する。CAP_PROP_BUFFERSIZE は 1 とする。
    * 省略：同じ方式・同じ解像度で、より高い要求ですでに今回の要求値の 90 % 以上が出ている要求は省く。1920×1080 で要求値の 90 % 以上が出た時点で、その方式の残りの要求は省く。
    * 選択：実測フレームレートが最高値の 90 % 以上のモードのうち、画素数が最大のものを使う。選んだモードで開き直せなければ、次の候補を試す。開き直した後の実測値を報告する。
    * 例外：撮影モードを切り替えると、ドライバによっては次の取得で OpenCV が例外（例：matrix.cpp の「_step >= minstep」）を出す。これはそのモードの失敗として扱い、カメラを開き直し、最初の取得の前に同じモードを要求して 1 回だけやり直す。それでも例外が出ればそのモードを 0 fps として次へ進む。例外でプログラムを止めない。計測中の取得で例外が出た場合も、そのフレームを捨てて取得を続ける。
    * 確認に十数秒〜数十秒かかるため、進み具合（試している方式・フレームレート・解像度）を状態表示に示す。
  4 grab() の直後に撮影日時を得る（露光時刻ではなく、grab() 直後のソフトウェア時刻）。直前と画素が同一のフレームは新しいフレームとして扱わない。
  5 すべての計算は実際の撮影日時で正確に行う
  6 ファイルへの結果の保存では、取得側で新しいフレームに付けた通し番号の欠番から、読み飛ばし（処理せずに破棄したフレーム数）について記録（カメラ・ドライバの内部で失われたフレームは OpenCV からは分からないので含まない）
  7 露出：カメラの自動露出は、暗いと露光時間を 1 フレーム間隔より長くしてフレームレートを下げるため用いず、露出を手動で固定する（DirectShow で CAP_PROP_AUTO_EXPOSURE = 0.25（手動）、CAP_PROP_EXPOSURE = 露出指数 x。露光時間 ≈ 2^x 秒）。露出指数は GUI の「露出指数」欄で選ぶ（選択肢：「フレームレートに合わせる」、−3、−4、−5、−6、−7、−8、−9。既定は「フレームレートに合わせる」）。
    * 「フレームレートに合わせる」：撮影モードの実測の間は、要求フレームレートの 1 フレーム間隔に収まる露出 x = floor(log2(1/fps))（−13〜−1 の範囲。30 fps → −5（約 1/32 秒）、60 fps → −6（約 1/64 秒））を設定する（露出のせいで撮影モードの実測値が下がらないようにする）。撮影モードを選んだ後、実測フレームレートから同じ式で x を求めて設定し、実測し直して、フレームレートが元の 90 % 未満に下がれば x を 1 段ずつ短くする（最大 4 回）。露出指数と露光時間の対応は機種で異なるためである。
    * 数値を選んだ場合：撮影モードの実測の間も選択後も、その露出指数で固定する。
    * 画像が暗い場合は照明を明るくするよう、ヘルプに記載する。
  8 状態表示（ステータスバー）に、カメラの番号、実測フレームレート（新しいフレームの実測値）・解像度・方式（DirectShow／Media Foundation）・露出（「露出 −5（約 1/32 秒）」、Media Foundation の場合は「露出 カメラ側の設定」）と、処理のフレームレート、処理せずに破棄したフレーム数、瞳孔推定の入・切と所要時間、グラフの描画の入・切、記録ファイル名を示す。状態表示が長くても窓の幅を変えない（折り返す）。
  9 負荷の大きい 2 つの処理（瞳孔推定〔Mask R-CNN〕とグラフの描画）を、「負荷の大きい処理:」の 2 つのチェックボックスで計測中にいつでも入り切りできるようにする。切ると処理のフレームレートが上がる。グラフの描画を切っても、計測値の算出と記録は続ける。

2. **任意の動画ファイル**：ローカルの動画ファイル（mp4, avi, mov, mkv等）を選択して全フレームを順次解析する。


3. **デモ動画**：インターネット上のサンプル動画（例：`[https://www.kkaneko.jp/ai/apps/gaze_saccade/reading_something.mp4](https://www.kkaneko.jp/ai/apps/gaze_saccade/reading_something.mp4)` 等）を初回に自動ダウンロードして再生・解析できる機能を備え、カメラがない環境でも即座に体験できるようにする。





### 3.2 計測・推定する項目

時刻はすべて計測開始（最初の処理フレーム）からの経過時間 `[s]` とし、「右眼」「左眼」は**被験者から見た左右**として扱うこと。

* **右眼・左眼のそれぞれについて求める量**：
* **頭部に対する眼球回転角** `[deg]`：Fick角の水平成分（正＝被験者の左）・垂直成分（正＝上）。球形眼球モデル（眼球半径 12.0 mm、成人の平均可視虹彩径 11.7 mm を仮定）と3次元頭部姿勢から算出する。平滑化前と平滑化後（One Euro Filter等）の双方を扱う。


* **虹彩中心座標** `[px]` と **虹彩の見かけの長径** `[px]`


* **頭部に対する眼球角速さ（角速度の大きさ）** `[deg/s]`：連続フレーム間の眼球方向の角距離÷時間。平滑化前の値と、平滑化後の値（指数移動平均等で平滑化）の双方を求める。閉眼・虹彩未検出・カメラ光線が眼球モデル球面と交わらないなどで角度が途切れた場合は、角度の平滑化フィルタと平滑化後の角速さ（指数移動平均）を初期化する（初期化しないと、開眼直後に途切れる前の角速さが残り、平滑化後の角度も途切れる前の値に引きずられる。瞬目の検出状態は初期化しない）。


* **EAR（眼裂縦横比：Eye Aspect Ratio）** `[無次元]`：顔の向きによる見かけの短縮を除くため、頭部の前額面に投影した座標で算出する。


* **eyeBlink 係数** `[無次元]`：0〜1の表情係数（Blendshapes）。


* **瞬目（まばたき）の開始・終了時刻** `[s]`：EARが閉眼しきい値（例：0.18）を下向きに横切った時刻を開始、再開眼しきい値（ヒステリシス付き、例：0.18×1.15）を上向きに横切った時刻を終了として線形補間で求める。持続時間（例：0.04〜0.9 s）と不応期（例：0.12 s）による瞬目判定、および「長い閉眼（0.9 s超）」の区別を行う。


* **瞳孔検出枠の中心座標** `[px]`（鏡像にしないカメラ画像座標）・**幅** `[px]`、**虹彩検出枠の幅** `[px]`


* **瞳孔虹彩径比** `[無次元]`（瞳孔半径 ÷ 虹彩半径）および **瞳孔径の換算値** `[mm]`（瞳孔虹彩径比 × 11.7 mm）


* **瞳孔・虹彩の分類スコア** `[無次元]`（しきい値未満の場合も最高スコアを記録）と推論処理時間 `[ms]`




* **両眼共通・頭部・生体情報として求める量**：
* **頭部姿勢角（ヨー・ピッチ・ロール）** `[deg]` および **頭部の回転角速さ** `[deg/s]`：開始直後の有効フレーム（例：20フレーム）から顔の基準形状を作成し、剛体点群（50点程度）の当てはめ（Kabsch法 / Procrustes法等）により算出する。


* **カメラから顔（剛体点群の重心）までの距離の推定値** `[mm]`


* **サッカード候補の開始・終了時刻** `[s]`、**振幅** `[deg]`、**方向** `[deg]`、**継続時間** `[ms]`、**最大角速さ** `[deg/s]`：Engbert & Kliegl (2003) の速度閾値法（楕円閾値）を、両眼平均の平滑化前の眼球回転角（水平角, 垂直角）に適用して検出する。両眼の角度が得られた標本のみ用いる（両眼の雑音が独立なら、両眼平均は雑音を約 1/√2 にする）。
  * 角速度：前後 2 標本を含む 5 標本の最小二乗直線の傾き（不規則な標本間隔を扱える。等間隔では (2, 1, 0, −1, −2)/(10Δt) の差分で、E&K の 5 点差分 (1, 1, 0, −1, −1)/(6Δt) とは重みが異なる）。5 標本のいずれかが無効、5 標本の時間幅が 0.6 s 超、または標本間隔が 0.2 s 超の場合は求めない。
  * 閾値：成分ごとの楕円閾値の半径 η = max(λ × 中央値基準の標準偏差, 10 deg/s)、λ = 6（E&K の値）。中央値基準の標準偏差は √(median(v²) − median(v)²) とし、直近 2 s の、候補でない標本の角速度から求める（候補の標本を雑音の推定から除くのは、サッカードが続く区間（読解など）で閾値が上がり検出漏れが起きるのを防ぐため。Nyström & Holmqvist, 2010 に倣う）。標本が 20 個たまるまでは判定しない。下限を 10 deg/s と低くするのは、5 標本の回帰が、標本間で完了する振幅 A のステップに 0.3·A/Δt（30 Hz で 9·A deg/s）の傾きしか与えないため（固定の 60 deg/s のような高い下限では、30 Hz で振幅 60/9 ≈ 6.7° 以下のサッカードを原理的に検出できない）。(v_h/η_h)² + (v_v/η_v)² > 1 の標本を候補の標本とする。
  * 区間：候補の標本の連続（1 標本の途切れは許す）。候補の標本が 2 個未満の区間は棄却する。平滑化で 1 区間につながった連続サッカードは、角速度の谷（谷の値が両側の最大値の小さい方の 0.5 倍未満）で分ける。
  * 振幅：区間の前後 3 標本の位置の中央値の間の角距離（谷で分けた場合は、谷とその前後の標本の中央値を境界とする）。方向：その変位ベクトル（水平角, 垂直角）の向き（0° = 被験者の左、90° = 上）。
  * 開始・終了時刻：サッカード方向への変位が 10 %・90 % に達した時刻（標本間は線形補間。補間しても時刻の確度は標本間隔程度にとどまる）。
  * 最大角速さ：区間内の 5 標本回帰の角速さの最大値（平滑化のため、低いフレームレートでは真の最大値より小さい）。
  * 除外と棄却：瞬目等に伴う見かけの高速変化を除外するため判定を 0.25 s 遅延させ、閉眼・虹彩未検出・顔未検出・eyeBlink 係数 0.5 以上のフレームの前 0.10 s〜後 0.12 s の標本を判定に用いない（判定前の標本を遡って除外する）。振幅 2° 未満、または区間の前後 2 標本を含む頭部の回転角速さの最大値が 150 deg/s を超える候補は棄却し、棄却数を数える。
  * λ 以外のしきい値（判定遅延 0.25 s、瞬目前後の除外 0.10 s / 0.12 s、閾値の下限 10 deg/s、最小振幅 2°、頭部角速さ 150 deg/s、区間を分ける比 0.5）は設計値であり、実測で検証した値ではないことをコード冒頭とヘルプに明記する。速度による判定であり、サッカードの確定ではないことをヘルプに明記する。


* **顔の皮膚領域（額・両頬）のRGB平均** `[0〜255]` と、非接触脈波（rPPG：POS法）による **脈拍数の推定値** `[bpm]` および **SNR** `[dB]`（参考値として算出・表示）。




* **誠実な無効判定と理由の明示**：
* 頭部の向きが大きすぎる場合（例：60°以上）や剛体当てはめ残差が大きすぎる場合（例：8 mm以上）、閉眼時、虹彩未検出時などは、根拠のない眼球回転角を出さずに「値を求めない」判断を行い、その理由（ステータス）を画面とログの双方に明記すること。





### 3.3 視線校正（キャリブレーション）機能

* 被験者がカメラレンズを一定時間（約1.5〜2秒）見つめることで、頭部の基準形状を取り直し、眼球の光軸と視軸のズレ（κ角など）を補正する眼ごとの回転補正行列を求める「校正（キー `C`）」および「校正の解除（キー `X`）」機能を備えること。



### 3.4 グラフ表示・瞬目とサッカードの表示・AI可視化機能（ON/OFF切替可能）

* **時系列グラフの明示的な構成（直近10秒間の7段表示）**：
メイン画面には、直近（例：10秒間、現在を `0s` とする横軸）の推移を示す以下の**7段の時系列グラフ**を縦に並べてリアルタイム描画すること。右眼と左眼の系列は明確に色分け（例：**右眼＝橙色、左眼＝青色**）し、欠測や一定時間（例：0.5秒）を超える途切れでは線を結ばず、孤立した標本は点として描くこと。


1. **頭部に対する眼球の水平回転角 `[deg]**`（Fick角、平滑化後、正＝被験者の左、縦軸目安：-35〜+35°）


2. **頭部に対する眼球の垂直回転角 `[deg]**`（Fick角、平滑化後、正＝上、縦軸目安：-25〜+25°）


3. **眼球角速さ `[deg/s]**`（片眼ごと、平滑化前、連続 2 フレームから。縦軸目安：0〜300 deg/s。サッカード候補の判定（両眼平均の 5 標本回帰と楕円閾値）とは異なる量であるため、しきい値の水平点線は表示しない。この違いをヘルプに明記する）


4. **EAR `[無次元]**`（縦軸目安：0〜0.45、閉眼しきい値と再開眼しきい値の水平点線を表示）


5. **eyeBlink 係数 `[0〜1]**`（縦軸目安：0〜1.0）


6. **瞳孔虹彩径比 `[無次元]**`（縦軸目安：0.1〜0.8、瞳孔セグメンテーションAIの推論が行われた時刻ごとの点プロット）


7. **脈波 `[無次元]**`（POS法による標準化波形、参考値、緑色等で表示、縦軸目安：-3〜+3）




* **瞬目（まばたき）とサッカード候補の視覚的な表示仕様**：
* **グラフ上の半透明帯（バンド）重畳表示**：上記7段すべてのグラフの背景（または前景）に、時間軸を揃えて「瞬目区間＝明るめの灰色の半透明の帯」**および**「サッカード候補区間＝赤色の半透明の帯」を重畳描画すること。確定した事象だけでなく、**現在進行中の閉眼や進行中のサッカード候補についてもリアルタイムに仮の帯を描画**し、今起きている反応が即座に視覚化されるようにすること。


* **数値・テキストでの状態表示**：メイン画面の数値表示欄に、現在の状態（閉眼判定の有無、サッカード候補の「検出中」表示）、右眼・左眼それぞれの**累積瞬目回数と直近の瞬目の開始〜終了時刻 `[s]`・持続時間 `[ms]**`、および**直近のサッカード候補の開始〜終了時刻 `[s]`・振幅 `[deg]`・最大角速さ `[deg/s]**` を明示すること（サッカード候補の欄の見出しには、判定法（Engbert & Kliegl の楕円閾値 λ = 6）と判定遅延 0.25 s を示す）。




* **カメラ映像とAI内部状態の可視化（ユーザ操作でON/OFF切替可能）**：
* カメラ映像上に、眼裂の輪郭（灰）、虹彩の円（緑）、瞳孔の円（桃：古い推論結果は現在の虹彩位置・大きさに追従させて細線で表示）、推定視線方向の矢印（右眼＝橙、左眼＝青）、脈波用の皮膚領域ポリゴン（黄）を重ねて描画すること。


* AI（Mask R-CNN等）による瞳孔推定機能のオン・オフや、可視化表示のオン・オフをユーザがGUI上で切り替えられること。また、AIに入力される「切り出された左右の眼領域の拡大画像」に、採用された**虹彩（緑）と瞳孔（桃）のセグメンテーションマスクおよび瞳孔円**を重ねてメイン画面上に並べて表示すること。


* **「計算の内訳（AIと幾何計算の仕組み）」タブ**：現在のフレームにおけるカメラモデル（焦点距離等）、頭部姿勢（奥行きの尺度、当てはめ残差、光軸との角度、オイラー角）、球形眼球モデル（眼球中心座標、光線ベクトル、交点の判別式、校正の補正角、平滑化前後のFick角と角速さ）、EARの分子・分母、AIの検出枠座標と最高スコア、サッカード判定（角速度の求め方、閾値の半径 η の現在値（水平・垂直）と雑音の推定に用いた標本数、楕円閾値の式、判定済み時刻、除外・棄却状況と棄却数）、rPPGの計算過程とSNRなど、**裏側の計算過程と数式・中間値をリアルタイム（例：0.3秒間隔、テキスト選択中は更新一時停止）に表示する専用タブ**を設けること。





### 3.5 データ記録・スナップショット機能

* `eye_logs` フォルダに、フレームごとの全計測値と未算出理由を記録するCSV（`eye_YYYYMMDD_HHMMSS.csv`）と、瞬目・長い閉眼・サッカード候補のイベントを記録するCSV（`eye_events_YYYYMMDD_HHMMSS.csv`）をUTF-8（BOM付き）で自動保存すること。


* 非同期の瞳孔推論結果や、遅延判定されるサッカード候補のフラグ（`saccade_candidate` 列）が、対応するフレームのCSV行に後から正しく書き込まれて出力されるように保持・フラッシュを制御すること。`saccade_candidate` は、サッカード候補の開始時刻以前の最後の行から終了時刻以後の最初の行までを 1 とする（開始・終了時刻は標本間の補間値であり、30 フレーム/秒では区間内にフレームが 1 つもないことがあるため、運動をはさむ前後のフレームを含める）。
* イベントCSVの列は `event, eye, start_s, end_s, duration_ms, amplitude_deg, direction_deg, peak_speed_deg_s` とする（`direction_deg` はサッカード候補の方向。0° = 被験者の左、90° = 上）。


* オーバーレイ描画付きの現在のカメラ画面をPNG画像として保存するスナップショット機能を備えること。



---

## 4. 厳守すべき制約条件

1. **Windowsでの完全動作**
* Windows環境で確実に動作すること。Windows特有の課題（カメラ起動時のMedia Foundationの遅延対策、OpenCVの `VideoCapture` における日本語・非ASCII文字パスの扱い、日本語フォントの描画、DPIスケーリングなど）に適切に対処すること。


* Windowsへの導入が困難なライブラリ（例：公式にWindowsをサポートしない `detectron2` 等）に依存せず、PyTorch / torchvision 等の標準的なパッケージのみでモデル構造と推論パイプラインを再現・実装すること。




2. **2023年以降の最新AI技術の調査と採用**
* 過去の記憶だけに頼らず、現時点の最新情報を調査した上で、2023年以降に発表された、または現在標準として提供されている最新のAI技術・学習済みモデルを選定して組み込むこと（例：Google MediaPipe Tasks API の `FaceLandmarker`（`.task` モデル形式）と、2024年発表の可視光瞳孔・虹彩セグメンテーションモデル `PupilSense`（Islam & Bae, 2024 の学習済み Mask R-CNN パラメータ）の組み合わせ、あるいは同等以上の精度と信頼性を持つ2023年以降のオープンな学習済みモデル）。


* 幾何学的な手法や信号処理（Kabsch法、球形眼球モデル、POS法など）とAI推論を融合させ、それらがどう協調しているかをプログラム内およびヘルプ画面で前提として明示すること。




3. **学習済みモデルの自動ダウンロードと検証の誠実な明記**
* 必要な学習済みモデル（およびデモ動画）は、プログラム起動時または必要時に公式の配布URLから自動ダウンロードして展開・保存する仕組みを実装すること（通信エラー時のリトライや途中ファイルの保護を含む）。


* 可能な限り実際にダウンロード先URLの有効性とモデルの動作を確認すること。もしあなたの実行環境の制約により実際のダウンロードや実機動作確認が行えなかった項目がある場合は、**絶対に確認済みと偽らず、出力の末尾またはヘルプ内に「未確認である点」を誠実に明記すること**。


4. **ライセンス・信頼性の確認と動作条件の明示**
* 使用する学習済みモデル、オープンデータ、ライブラリの配布元の信頼性とライセンス（Apache License 2.0、MIT License等）を確認すること。


* プログラムの動作に必要な条件（必要なディスク空き容量、メモリ容量、NVIDIA GPU / CUDA の有無による動作速度の違い、CPU実行時の推論レイテンシの目安、対応OS、Pythonおよび主要ライブラリの導入コマンド）を利用者に分かりやすく明示すること。




5. **品質の下限（堅牢性・正確性・可読性）**
* カメラが接続されていない、途中で抜かれた、顔が画面外に出た、動画が破損している、通信が切断された、ボタンが連打された等の想定外の入力や操作があってもクラッシュせず、GUIのステータスバー等で分かりやすく状態を通知すること。


* 重いAI推論（Mask R-CNN等）でGUIやカメラ取得がフリーズしないよう、適切なマルチスレッド設計（カメラでは最新フレーム優先、動画ファイルでは全フレームの正確な順次処理）を行うこと。


* コードは構造化され、定数の意味やアルゴリズムの根拠がコメントとして丁寧に記述された、読みやすく保守しやすいものにすること。
* コード冒頭のコメント（docstring）に、次の【計測の目的】【付随して記録する量】【用いた技術】【サッカード候補】【設計値の注意】を記載すること（★ を付けた量は、瞳孔と顔の皮膚の機能をもたない姉妹プログラム gaze_saccade.py にはない量であり、それ以外は両方のプログラムで共通であることも記載する）。
```
【計測の目的】Web カメラ映像または動画から、次の量をフレームごとに求め、表示し、CSV に記録する。
  ★ を付けた量は pupil_iris.py だけが求める（gaze_saccade.py には瞳孔と顔の皮膚の機能がない）。それ以外は両方のプログラムで共通。
  右眼・左眼（被験者から見た左右）のそれぞれについて
    頭部に対する眼球回転角（Fick 角の水平・垂直成分）[deg]
    虹彩の見かけの長径 [px]
    頭部に対する眼球角速さ（角速度の大きさ）[deg/s]
    EAR（眼裂縦横比）[無次元]
    eyeBlink 係数（MediaPipe の表情係数、0〜1）[無次元]
    瞬目の開始・終了時刻 [s]（EAR のしきい値の横切り時刻）
    ★ 瞳孔検出枠の中心 [px、カメラ画像座標（鏡像にしない）]・幅 [px]
    ★ 瞳孔虹彩径比 [無次元]
  両眼共通
    頭部姿勢角（ヨー・ピッチ・ロール）[deg]
    カメラから顔までの距離の推定値 [mm]
    サッカード候補の開始・終了時刻 [s]
  時刻はすべて計測開始からの経過時間 [s]。
【付随して記録する量】虹彩中心 [px]、視線方向ベクトル（カメラ座標系）、頭部の位置 [mm]・回転角速さ [deg/s]、
  サッカード候補の振幅 [deg]・方向 [deg]・継続時間 [ms]・最大角速さ [deg/s]、長い閉眼、
  値を求めなかった理由（head_status, R_status, L_status）、処理せずに破棄したフレーム数、
  ★ 瞳孔径の換算値 [mm]（瞳孔虹彩径比 × 11.7 mm）・分類スコア [無次元]、
  ★ 顔の皮膚の RGB 平均 [0〜255]、脈拍数の推定値 [bpm]・SNR [dB]（POS 法、参考値）
【用いた技術】虹彩: MediaPipe Face Landmarker、瞳孔: PupilSense（Islam & Bae 2024）の学習済み Mask R-CNN
【サッカード候補】Engbert & Kliegl (2003) の速度閾値法（楕円閾値、λ = 6）を両眼平均の眼球回転角に適用する。
【設計値の注意】頭部の向き 60°、当てはめ残差 8 mm、サッカードの判定遅延 0.25 s・瞬目前後の除外 0.10 s / 0.12 s・
  閾値の下限 10 deg/s・最小振幅 2°・頭部角速さ 150 deg/s・区間を分ける比 0.5 は設計値であり、実測で検証した値ではない。
```




6. **画面サイズと表示スケーリングの切り替え**
* メインウィンドウの表示について、ノートPC向けの標準表示（縦768画素に収まるレイアウト）と、高解像度ディスプレイ向けの4K / 全画面表示（2倍スケーリング等）を、ユーザがGUI上の操作でいつでも即座に切り替えられるようにすること。切り替え時はフォントサイズ、7段のグラフ、画像表示領域のすべてが破綻なくスケーリングされること。




7. **タブ切り替えによる「ヘルプ（説明）」画面とライセンス区別表示**
* メインGUI画面において、タブ切り替え（`ttk.Notebook` 等）で「計測（メイン）」「計算の内訳（AIの仕組み可視化）」「ヘルプ（説明）」の各画面にスムーズに切り替えられること。


* **「ヘルプ（説明）」画面には、以下の内容を漏れなく、簡潔かつ正確に記載すること**：
1. **マウス操作・キー操作の説明**：各ボタン、スライダー、チェックボックス、ショートカットキー（`C` で校正、`X` で校正解除など）の簡潔な操作ガイド。カメラの撮影モードの選び方（3.1 の手順、確認に十数秒〜数十秒かかること、状態表示の内容）、露出（自動露出を用いない理由、DirectShow で開く理由と Media Foundation の場合、「フレームレートに合わせる」の決め方、数値を選んだ場合、画像が暗い場合は照明を明るくすること）、負荷の大きい 2 つの処理の入り切りを含める。


2. **使用技術と計測定義の簡潔かつ正確な説明**：採用したAIモデル、3次元頭部姿勢・眼球回転角・EAR・瞬目・サッカード候補・rPPGの算出原理、グラフやオーバーレイの色・帯の意味、および精度上の限界や誠実な無効判定の基準。


3. **動作環境・システム要件**：必要なディスク容量、メモリ、GPUの有無による挙動の違い。


4. **使用しているオープンデータ・学習済みモデル・MediaPipe等のライセンスならびに使用条件の表示**：
* MediaPipe、瞳孔推定モデル（PupilSense等）、デモ動画などの各ライセンス（Apache 2.0、MIT等）を明記した上で、**「大学での授業・学術研究での利用の場合」と「商用利用の場合」のそれぞれにおける使用条件・留意点（著作権表示やライセンス条文の同梱義務、データの再配布条件、医療機器としての使用禁止、プライバシー配慮など）を明確に区別して表示**すること。







---

## 5. 出力形式

* **完成したPythonコード全体を、一切の省略（`# 略` や `...` など）をせず、1つのコードブロックとして出力してください。**
* コード以外の前置きや解説は最小限にとどめ、実行に必要なインストールコマンドと、万が一実環境でダウンロード・動作確認できなかった項目がある場合の「未確認事項の明記」のみを簡潔に添えてください。
