# 依頼：オープンボキャブラリー物体検出の「体験・学習・実験」用 Windows アプリの作成

あなたは、Windows 上で動く、AI の体験・学習・実験のためのプログラムを一から作るソフトウェア開発者です。参考にする既存ツールのコードはありません。必要な仕様はすべてこの依頼文に書いてあります。この依頼文だけを根拠に設計し、実装してください。

---

## 1. 作るもの

文字（テキストプロンプト）、映像上で囲んだ例（視覚プロンプト）、プロンプトフリーの 3 通りの方法で、任意の物体を検出・セグメンテーション・追跡します。あわせて、AI の内部で何が起きているかを、実際の数値と図で見せる GUI アプリを作ります。

想定する利用場面は、大学の授業（教員による説明、学生の実習）、研究室での実験、AI に興味がある人の体験です。

---

## 2. 実現する機能（最低限の要件）

以下は、参考にした既存ツールの仕様です。ここに書かれている機能は、すべて実現してください。具体的な数値や名前は既定値・参考値です。調査の結果、より良い選択肢があればあなたが判断して構いません。ただし、変えた場合は理由を示してください。

### 2-1. AI 技術の構成（参考構成）

**検出・セグメンテーション：YOLOE-26（Ultralytics）**
- オープンボキャブラリーの物体検出とインスタンスセグメンテーションを行います。
- テキストプロンプト、視覚プロンプト、プロンプトフリーの 3 方式に対応します。
- Ultralytics 8.4 以降が必要です。
- 重みの入手先：`https://github.com/ultralytics/assets/releases/download/v8.4.0/`
  - テキスト・視覚プロンプト用：`yoloe-26{n,s,m,l,x}-seg.pt`
  - プロンプトフリー用：`yoloe-26{n,s,m,l,x}-seg-pf.pt`
- 検出ヘッドは one-to-many（NMS で重複を除く）と one-to-one（NMS 不要。YOLO26 本来の推論）の 2 系統を持ちます。両方を切り替えて比べられるように、Ultralytics 標準の fuse()（使わない側のヘッドを削除する）は使わず、Conv と BatchNorm の融合だけを行います。

**テキストプロンプトの埋め込み：MobileCLIP2 のテキストエンコーダ**
- ファイルは `mobileclip2_b.ts` です。モデルによっては `mobileclip_blt.ts` を使います（モデルに記録された text_model から自動で選びます）。入手先は上と同じです。
- エンコーダの出力を YOLOE の RepRTA（補助ネットワークを通した後に L2 正規化）で、検出用の埋め込みに変換します。
- MobileCLIP / MobileCLIP2 の重みは研究目的に限定されたライセンスで提供されているため、初回起動時に利用条件を示して同意を求めます。同意しない場合はテキストエンコーダをダウンロードせず、視覚プロンプトとプロンプトフリーだけで動きます。同意の内容は設定ファイルに保存し、いつでも変更できます。

**視覚プロンプトの埋め込み：SAVPE（YOLOE に内蔵）**
- 映像上で囲んだ領域（P3 の格子上のマスク）から埋め込みを求めます。テキストエンコーダは使いません。

**複数物体の追跡：ByteTrack**
- Ultralytics の ByteTrack 実装で追跡します。
- 設定は Ultralytics 標準の bytetrack.yaml を使います。

### 2-2. 起動と準備

- `python ファイル名.py` で起動する、Python の 1 ファイル構成にしてください。
- 足りないパッケージは、起動時に自動でインストールします。インストール中であることは画面に表示します。
- AI モデルの重み、テキストエンコーダ、デモ動画は、初回の使用時にスクリプトと同じフォルダへ自動でダウンロードします。
  - 進捗（ファイル名、MB 数、割合、残り時間の目安）を表示します。
  - 通信が途切れても、壊れたファイルを残さないようにします（一時ファイルに書き、完全性を確かめてから置き換えます。モデルとテキストエンコーダは zip 形式であることも確かめます）。
- NVIDIA GPU と CUDA 版 PyTorch があれば GPU（FP16）で推論し、なければ CPU で推論します。
  - CPU のときは、GUI の操作への反応が遅れないように配慮します（推論は別スレッドで行い、4 コア以上なら 1 コアを GUI 用に残します）。また、結果と映像がずれないよう「推論したフレームを表示」を既定にします。
  - 既定値の参考：GPU のときはモデル s・入力 640、CPU のときはモデル n・入力 480
- 高 DPI の画面でも、文字や映像がぼやけないようにします。

### 2-3. 入力

**デモ動画（3 本）**

デモ動画は、表示名・推奨テキストプロンプト・出典表記をセットで持ちます。デモ動画を選ぶと、その推奨プロンプトを自動で設定します（プロンプトフリーのモデルを使っているときも設定しておき、テキスト用のモデルに戻したときに使います）。

| 表示名 | URL | 推奨プロンプト | 出典 |
|---|---|---|---|
| 店舗の通路（食器売り場） | `https://raw.githubusercontent.com/intel-iot-devkit/sample-videos/master/store-aisle-detection.mp4` | person, hat, backpack, shelf, picture frame, bowl, cardboard box | Intel IoT DevKit sample-videos（CC BY 4.0） |
| 屋外の歩行者 | `https://raw.githubusercontent.com/opencv/opencv/master/samples/data/vtest.avi` | person, car, van, tripod, traffic cone, street lamp, backpack | OpenCV のサンプルデータ |
| 駐車場（人・自転車・車） | `https://raw.githubusercontent.com/intel-iot-devkit/sample-videos/master/person-bicycle-car-detection.mp4` | person, bicycle, car | Intel IoT DevKit sample-videos（CC BY 4.0） |

**カメラ・ファイル**
- カメラは番号を選べるようにします（0〜9）。
- 動画ファイル（mp4、avi、mov、mkv、wmv、webm）と画像ファイル（jpg、png、bmp、webp、tif）を開けます。
- ASCII 以外の文字（日本語など）を含むパスも扱えるようにします。

**入力の動作**
- 動画は、最後まで再生したら先頭に戻って繰り返します。
- 入力を開けなかったときは、それまでの入力を続け、理由と対処を表示します。
- 入力を切り替えたら、前の入力の推論結果は表示しません。追跡もリセットします。

### 2-4. 検出対象の指定

**テキストプロンプト**
- 英語の語句をカンマ区切りで入力し、Enter または［適用］で反映します。
- 全角の読点・カンマ・セミコロンも区切りとして受け付けます。
- 重複と余分な空白は除きます。
- 英語以外の文字が含まれる場合は、テキストエンコーダが主に英語で学習されているため英語を推奨する、と表示します。
- 一度計算した語句の埋め込みは再利用します。

**視覚プロンプト**
- 一時停止し、映像上をドラッグして物体を囲みます。囲んだ後に名前（任意。日本語も可）を付けます。
- 範囲が小さすぎる場合（入力座標で 12 画素未満、または P3 の格子に 1 マスもかからない場合）は、登録モードのままやり直しを促します。
- Esc（または右クリック）で取り消せます。
- 個別削除と全削除ができます。

**プロンプトフリー**
- -pf のモデルを選ぶと、モデルに内蔵された語彙で検出します。
- このときはプロンプトの入力欄を無効にし、内蔵語彙のクラス数を表示します。

**クラス一覧**
- 種類を T（テキスト）、V（視覚）、PF（内蔵語彙）で区別して表示します。
- 色は、クラス名から一意に決まる固定色にします。

### 2-5. 推論の設定

- **モデルの大きさ**：n、s、m、l、x の 5 段階を、テキスト用とプロンプトフリー用それぞれで選べます。
- **入力サイズ**：既定は自動です（GPU はモデルの学習時の入力サイズ、CPU はそれと 480 の小さい方）。32 の倍数から手動でも選べます。
- **後処理**：「NMS あり（one-to-many＋クラスごとの NMS、IoU 0.7、上限 300）」と「NMS なし（one-to-one、上位 300 件）」を切り替えられます。既定は NMS ありです。スコア閾値と NMS で候補が絞られる過程を ⑥ で観察しやすいためです。
- **スコア閾値（conf）**：後処理に渡す値です（既定 0.10、範囲 0.01〜0.90）。変更すると、同じフレームで再推論します。
- **表示閾値**：表示の区別だけに使い、再推論しません（既定 0.25、範囲 0.01〜0.95）。スコア閾値を上げたときは、表示閾値がそれを下回らないようにします。
- **動画の全フレームを推論**：オンにすると、推論が終わるまで次のフレームに進みません（モデルの準備ができていないときは待ちません）。
- **最新フレームを表示（ライブ）**：オフにすると、推論したフレームそのものを表示し、結果と映像がずれません。

### 2-6. メイン映像への表示

**検出結果**
- 表示閾値以上の検出は、枠と、ラベル（クラス名、スコア、追跡 ID）で描きます。
- マスクは、半透明の塗りと輪郭で描きます。
- 表示閾値未満の検出は、破線と淡い色で描きます。表示はオン・オフできます。

**追跡**
- 追跡には ByteTrack を使います。軌跡は、追跡 ID ごとの枠の中心の履歴（追跡中のものだけ。直近 30 回の更新分）で描きます。
- カルマンフィルタによる推定枠を重ねられます（K）。

**選択とクリック**
- 選択した検出は強調して描きます。その検出を出したアンカー点の位置と格子セルを、「アンカー点 P3 (gx, gy)」のように示します。アンカー点から枠の 4 辺までの距離（モデルが予測する量）も線で示します。
- 検出のない場所をクリックしたときは、その位置に印を付け、その位置を含む 3 スケールの格子セルを示します。

**重ね描き**
次のいずれかを映像に重ねられます。凡例とカラーバーを添えます。
- クラススコアマップ：P3、P4、P5、3 スケールの最大。対象クラスは「全クラスの最大」か特定のクラスを選べます。
- 特徴マップ P3、P4、P5 の L2 ノルム

**情報表示**
- 画面上部に、モデル名、入力サイズ、表示閾値以上の検出数、後処理の方式、一時停止中であることを表示します。
- ライブ表示で表示中のフレームと推論したフレームが異なるときは、「何 ms 前のフレームの結果か」を表示します。
- 同じフレームを再推論して追跡を更新しなかったときは、その旨を表示します。
- デモ動画の出典を画面の左下に表示します。

### 2-7. AI の仕組みを見せる解析画面

各画面には、その図が何を表しているかを説明文で添えてください。

**① 検出の内訳**
- 検出をクリックすると、次の内容を表示します。
  - 検出の切り抜き画像
  - クラス、種類、スコア、追跡 ID、枠（元画像座標と入力座標）
  - その検出を出したアンカー点（スケール、格子番号、入力座標での位置、予測した 4 辺までの距離）
  - そのアンカー点での全クラスのスコア（降順の横棒と、表示閾値とスコア閾値の線）
- アンカー点は、出力テンソルから次の条件で特定します。
  - 検出のクラスのスコアが、検出のスコアと一致する（差 1e-4 以内）。
  - そのうえで、デコード後の枠が検出の枠に最も近い（L1 差が最小）。
  - 候補の数と、後処理が保持した番号と一致したかも示します。
- 検出のない場所をクリックした場合は、その位置を含む 3 スケールの格子点のスコアを表示します。

**② クラススコア**
- 検出ヘッドが各アンカー点で出したクラススコア（sigmoid 後）を、0〜1 の絶対値で着色します。正規化はしません。
- 上段に格子そのもの、下段に元画像へ投影した図を並べます。投影は最近傍で拡大し、補間しません。
- レターボックスの余白は暗く表示します。値のない格子点は斜線で表示します（プロンプトフリーでは、LRPC が候補から外してスコアを計算しなかったアンカー点が該当します）。
- 各スケールの最大値を表示します。

**③ 特徴マップ**
- 検出ヘッドに入る P3、P4、P5 特徴マップについて、各位置のチャネル方向の L2 ノルムを表示します。
- 各マップの中で最小〜最大に正規化して着色します。マップ同士で色の濃さを比較できないことを明記します。
- 格子の大きさ、チャネル数、ノルムの範囲を表示します。

**④ マスクの合成**
- 次の過程を図で示します。
  1. 32 枚のマスクプロトタイプ P_i（入力の 1/4 解像度）
  2. 選択した検出のマスク係数 c_i
  3. 重み付き和 Σ c_i P_i
  4. 入力解像度へ双線形で拡大
  5. 0 を超える画素を、枠の内側だけ残して完成したマスク
- プロトタイプは、それぞれ絶対値の最大で割り、青（負）〜白〜赤（正）で着色します。
- この順序は Ultralytics の process_mask_native と同じです。Ultralytics の既定（retina_masks=False の process_mask）は、低解像度のまま枠の外を除いてから拡大するため、境界の画素がわずかに異なることがあります。この点を明記します。

**⑤ クラス埋め込み**
- クラス埋め込み（L2 正規化後）のコサイン類似度の行列を表示します。テキストは RepRTA で変換したもの、視覚プロンプトは SAVPE の出力です。色は -1〜+1 の絶対値で、正規化はしません。
- クラスが多いときは、先頭の一部だけを表示し、その旨を明記します。
- 視覚プロンプトに使った領域のサムネイルを表示します。
- プロンプトフリーのモデルでは表示しません。内蔵語彙の埋め込みは分類層（LRPC の 1×1 畳み込みの重み）に融合されており、RepRTA・L2 正規化を経た独立のクラス埋め込みとしては保持されていないためです。その理由を表示します。

**⑥ スコア分布**
- 漏斗のように、次の件数を順に示します。
  1. アンカー点の総数
  2. スコア閾値を超えるアンカー点の数
  3. 後処理（NMS または top-k 選択）後の検出数
  4. そのうち表示閾値以上の数
- 後処理前の全アンカー点の最大スコアのヒストグラム（縦軸は対数）に、スコア閾値、表示閾値、追跡の 1 段目・2 段目・新しい追跡の開始の閾値を線で示します。
- 検出の一覧（順位、クラス、種類、スコア、表示閾値以上か未満か、追跡 ID、アンカー点）を表示します。

**⑦ 追跡**
- ByteTrack の設定値を表示します（1 段目・2 段目・新しい追跡の開始の各閾値、見失った追跡を保持する回数、対応付けのコスト）。
- 状態ごとの件数（追跡中、未確定、見失い）を表示します。
- 各追跡の ID、状態、クラス、スコア、経過した更新回数（開始から）、連続して対応付けた回数、未観測の回数、カルマンフィルタによる速度（画素／更新）、推定枠を表で示します。

**⑧ 精度と速度の比較**
- モデルの大きさ・入力サイズ・後処理・デバイスの組み合わせごとに、推論回数、モデルの処理時間、合計の処理時間、推論 fps、表示閾値以上の検出数と平均スコアの平均を記録して表で示します。記録は消去できます。

**語彙が大きいモデル（プロンプトフリー）の扱い**
- 全アンカー点×全クラスのスコアを持つと重くなるため、各アンカー点で上位のクラスだけを保持し、「対象クラス」で選んだクラスは全点のスコアを保持します。
- 値のない部分を図の上で区別し（斜線）、その旨を明記します。

### 2-8. 可視化の正確さ（守るべき原則）

- 表示する中間結果は、すべてモデルの実際の出力テンソルと、追跡器の実際の内部状態から取り出してください。
- 値を変える平滑化や、フレーム間の補間はしないでください。
- 正規化した図には、正規化の方法を必ず明記してください。
- 座標系は次の 4 つを区別し、取り違えないでください。
  - 元画像座標：カメラ・動画・画像の画素座標
  - 入力座標：レターボックス（縦横比を保った縮小と余白の追加）後の、モデル入力の画素座標
  - 格子座標：P3 は stride 8、P4 は stride 16、P5 は stride 32
  - アンカー点：格子の各点。入力座標で ((gx + 0.5)·stride, (gy + 0.5)·stride) の位置にあり、ここから枠の 4 辺までの距離を予測します。

### 2-9. 操作

**キー操作**

| キー | 動作 |
|---|---|
| Space | 一時停止／再開 |
| → | コマ送り（一時停止中） |
| V | 視覚プロンプトを追加 |
| S | 保存 |
| H | ヘルプ |
| 1〜8 | 解析画面 ①〜⑧ の切り替え |
| M | マスクの表示 |
| C | 表示閾値未満の検出の表示 |
| T | 追跡のオン・オフ |
| K | 追跡の推定枠の表示 |
| Esc | 視覚プロンプトの登録を取り消す（登録中でなければ全画面を解除） |
| F11 | 全画面の切り替え |

文字の入力欄にいるときは、ショートカットを効かせないでください（視覚プロンプトの登録中の Esc を除く）。

**マウス操作**
- 左クリック：検出を選びます。重なっている場合は、表示閾値以上で面積が最小のものを優先します。検出のない場所をクリックすると、その位置のスコアを調べます。
- 右クリック：選択を解除します（視覚プロンプトの登録中は登録を取り消します）。
- 選択した検出は、次のフレームでも、追跡 ID（なければ同じクラスで最も重なる枠）で追い続けます。

### 2-10. 保存

- 次のファイルを、上書きしない名前で `snapshots` フォルダに保存します。
  - 画像：表示中のメイン画面、表示中の解析画面、元のフレーム（推論したフレーム）
  - JSON：
    - モデル、デバイス、精度、入力サイズ、レターボックスの値、スコア閾値、表示閾値、後処理の方式
    - クラス一覧（名前と種類。プロンプトフリーでも全件）
    - 処理時間、各段の件数
    - 各検出のクラス、スコア、枠（元画像座標と入力座標）、追跡 ID、アンカー点（スケール、stride、格子番号、上位クラスのスコア）
    - 追跡の設定と、各追跡の ID、状態、枠、スコア、速度、経過した更新回数、連続して対応付けた回数、未観測の回数

### 2-11. 状態表示

- 入力・推論・表示の各 fps、遅延、デバイスと精度を常に表示します。
- 処理中の内容（モデルの準備中、埋め込みの計算中など）、ダウンロードの進捗、操作の結果やエラーのメッセージも表示します。

---

## 3. ゴール

- 2 の機能をすべて実現した、Windows で動くプログラムを完成させてください。
- 利用者が「触ってよかった」「期待以上だった」と感じる体験をつくってください。具体的には、次のような場面と感情を想定しています。
  - **初回起動**：準備中も、何をしていて、あとどのくらいかがわかり、不安にならない。準備が終わると、設定をしなくてもデモ映像の上で人や物が囲まれ、塗り分けられ、ID 付きで追われ始める。「もう動いた」と驚く。
  - **言葉で探す**：学生が "umbrella" や "red cup" など思いついた英語を打ち込むと、映像の中でその物が見つかる。「決められた種類しか探せないと思っていたのに、言葉で探せるのか」と体感する。
  - **例で教える**：名前を知らない物をマウスで囲むだけで、同じ種類の物が次々に見つかる。類似度の図で、テキストと例が AI の中でどれだけ近いかを確かめ、「言葉を使わなくても教えられる」と納得する。
  - **理由をたどる**：検出をクリックすると、どの格子点がその検出を出したのか、他のクラスとのスコア差、プロトタイプからマスクが組み上がる過程を順にたどれる。教員が授業で「AI の判断はこう作られている」と、実際の数値で説明できる。
  - **実験する**：閾値を動かすと、検出の増減と、分布の上で閾値の線が動く様子が同時に見える。「見逃しと誤検出のトレードオフ」を自分の手で確かめられる。モデルの大きさ・入力サイズ・後処理を変えると、精度と速度の関係が数値で見える。
  - **画面に合わせる**：ノート PC の狭い画面でも、教室の 4K 投影でも、文字と図がはみ出さず読める。
  - **ヘルプを見る**：迷ったらヘルプ画面を開けば、操作、仕組み、授業や商用での使用条件がわかる。安心して授業や研究に持ち込める。
  - **安心して試す**：性能の低い PC でも操作への反応が止まらない。誤操作や異常（カメラがない、壊れたファイル、通信の切断、GPU メモリ不足、フォントがない、モデルの読み込み失敗など）があっても落ちない。原因と次の手順が示される。
  - **持ち帰る**：保存した画像と数値を、そのままレポートや実験記録に使える。

## 4. 理念

- 利用者にとっての価値を最優先にしてください。実装の前に、誰が（初めて触る学生、授業をする教員、実験をする研究者）、どの場面で、何を知りたいのかを考え抜き、設計を深めてください。
- 実現方法（ライブラリ、GUI の種類、構成、アルゴリズム、画面の部品、配置など）は、あなたが自分で決めてください。この依頼は「何を実現するか」を示すもので、「どう作るか」は指示しません。

## 5. 制約

1. Windows で動作すること。
2. 2023 年以降の最新の AI 技術を調査すること。記憶に頼らず、現時点の情報を調べて選んでください。2-1 の構成より適したモデルや版がある場合は、主要機能を損なわない範囲で採否を判断し、理由を簡潔に示してください。
3. 学習済みモデルをダウンロードして使うこと。実際にダウンロードして動作を確認することが望ましいです。確認できなかった場合は、確認済みと偽らず、未確認であることを明記してください。
4. 2 に書かれた制約を守ること。具体的には、Python の 1 ファイル構成、Windows 用 GUI、パッケージとモデルの自動準備、GPU がない場合の CPU での推論、可視化の正確さの原則、デモ動画の出典表示です。
5. モデル、ライブラリ、データのライセンスと配布元の信頼性を確認すること。あわせて、必要なディスク容量、メモリ、GPU の有無と推奨構成、初回のダウンロード量などの動作条件を、利用者に明示してください。研究目的に限定されたモデル（MobileCLIP2 など）は、使う前に利用条件を示して同意を得てください。
6. 品質の下限として、動作が正確であること、想定外の入力や操作でも壊れにくいこと、コードが読みやすいことを満たすこと。
7. AI を使わない機能がある場合も、主要機能を損なわない範囲で AI 技術を取り入れ、その旨を前提として明示すること。
8. 使用中の AI の最新の結果と、AI の仕組みの可視化を備えること。利用者が操作でオン・オフを切り替えられるようにしてください。
9. 縦 768 画素の表示（ノート PC を想定）と全画面表示（4K ディスプレイを想定）を、利用者が切り替えられることが望ましい。
10. メイン画面からタブ切り替えなどで「ヘルプ」画面に移れることが望ましい。ヘルプ画面には次の内容を載せてください。
    - キー操作とマウス操作の簡潔な説明
    - 使用技術の、簡潔で正確な説明
    - 使用しているオープンデータ（デモ動画など）と MediaPipe のライセンス、および使用条件。大学の授業で使う場合と商用で使う場合を区別して表示してください。MediaPipe を使わない場合は、使っていないことを明記してください。モデルとライブラリのライセンスも同じ形式で載せてください。
    - ライセンスの記載は、調査で確認した内容だけにしてください。確認できなかった項目は「未確認」と表示し、法的な助言ではないことと、正式な条件は配布元で確認すべきことを添えてください。

## 6. 判断に迷ったときの優先順位

法令・ライセンス・安全性 ＞ Windows で動作すること ＞ 主要機能の実現 ＞ AI 体験の豊かさ

## 7. 出力形式

- 完成したコードは、省略せずに全体を出力してください（「以下同様」「省略」は禁止です）。
- コード以外の説明は最小限にしてください。書くのは次の 4 点だけです。
  - 起動方法
  - 動作条件
  - 採用した技術とライセンスの要点
  - 動作確認済みの項目と未確認の項目
