YOLOE-26 オープンボキャブラリー検出

プログラムの動作の様子の動画:[動画]

実行ファイル:[exe]

説明資料: [PDF], [PPTX] , [動画, クレジット: 「VOICEVOX:青山龍星」、「Vrew」、「Gemini」を用いて作成)

本資料とコードの作成にAIを使用。参考プロンプト: prompt.md (実際にはこのプロンプトを変更したり、追加のプロンプトを与えている場合がある)

このプログラムの目的

本プログラムは、映像中の物体を検出し、物体ごとの領域を塗り分け(インスタンスセグメンテーション)、追跡する Windows 用の GUI アプリケーションである。検出する対象は、学習時に決められた種類に限らず、利用者が指定できる。指定の方法は次の3つである。

本プログラムは、検出結果に加えて、検出結果が得られるまでの途中の値を、数値と図で示す。示す値は、モデルの中間出力・出力テンソルと、追跡器の内部状態から取り出した値そのものであり、平滑化もフレーム間の補間も加えない。正規化した図には、正規化の方法を明記する。

利用者は、次のことを確かめられる。

本プログラムは学習済みモデルによる推論だけを行い、学習・追加学習は行わない。

動作準備

自動でダウンロードするファイル

次のファイルは、初回の使用時に、スクリプトと同じフォルダへ自動でダウンロードする。2回目以降は、ダウンロード済みのファイルを使う。

パッケージを含めると、初回のダウンロードは約1〜1.5 GB(CUDA 版 PyTorch では約3〜4 GB)になるため、ネットワーク接続が必要である。

ダウンロード中のファイルは「.part」の付いた名前で保存する。次の検査に合格したファイルだけを、本来の名前に置き換える。このため、通信が途中で切れても、不完全なファイルが本来の名前で残ることはない。

ダウンロードに失敗した場合は、最大3回まで取り直す。それでも失敗した場合は、原因を表示する。

GPU と CPU

NVIDIA GPU と CUDA 版 PyTorch があれば GPU で(計算精度 FP16)、なければ CPU で(計算精度 FP32)推論する。推論は、画面とは別のスレッドで行う。CPU で推論する場合、論理プロセッサが4つ以上あれば、1つを画面の操作用に残す。既定の設定は次のとおりである。

テキストエンコーダの利用条件

初回の起動時に、テキストエンコーダ MobileCLIP2 の利用条件への同意を求める画面が表示される。選んだ結果は yoloe_lab_settings.json に保存され、次回からは表示されない。

処理の流れ

処理は次の順序で行う。

  1. 入力:デモ動画、カメラ(番号0〜9)、動画ファイル(mp4、avi、mov、mkv、wmv、webm など)、画像ファイル(jpg、png、bmp、webp、tif など)のいずれかから映像を読む。日本語を含むパスも開ける。動画は最後まで再生すると先頭に戻る。
  2. 前処理:縦横比を保って縮小し、灰色(画素値114)の余白を足して、一辺が入力サイズの正方形の画像にする(レターボックス)。
  3. 推論:モデルは、入力画像の上に間隔8・16・32画素の3つの格子(P3・P4・P5)を置き、格子の各点(アンカー点)ごとに次の3種類の値を出力する。
    • アンカー点から枠の4辺までの距離
    • 各クラスのスコア(クラススコア):sigmoid を適用した0〜1の値。クラスごとに独立に計算するため、全クラスの合計は1にならない。確率として校正された値ではない。
    • マスク係数32個
  4. 後処理:スコア閾値(既定 0.10)を使って、検出を決める(次節)。
  5. マスク:32枚のマスクプロトタイプ(全検出に共通の画像)と、検出ごとのマスク係数との重み付き和からマスクを作る。マスクを作るのはスコアの上位100件までで、101件目以降は枠だけを描く。
  6. 追跡:追跡器が、検出に追跡 ID を付ける。追跡器の更新は、推論した新しいフレームごとに1回行う。同じフレームを推論し直した場合は、追跡器を更新しない。
  7. 表示:結果を画面に描く。

座標

座標は次の3つを区別する。

格子の間隔(stride)は、P3 が8画素、P4 が16画素、P5 が32画素である。アンカー点の位置は、入力座標で ((gx+0.5)×stride, (gy+0.5)×stride) である。P3 は主に小さい物体を、P5 は主に大きい物体を受け持つ。

後処理:NMS あり/NMS なし

YOLOE-26 の検出ヘッドには、学習の方法が異なる次の2つの系統がある。

操作パネルの[後処理]で、どちらの系統の出力を使うかを選ぶ(既定は「NMS あり」)。

後処理を切り替えると、すぐに推論し直す。このため、一時停止中に切り替えれば、同じフレームで両方の結果を比べられる。テキスト・視覚プロンプト用のモデル(-seg)は推論のたびに両方の系統を計算し、プロンプトフリー用のモデル(-seg-pf)は選んだ系統だけを計算する。

この後処理は本プログラム独自の手順であるため、Ultralytics で同じ画像を予測した結果とは一致しない場合がある。

2つの閾値

スコア閾値(conf):既定 0.10、範囲 0.01〜0.90

後処理と追跡器に渡す検出を決める値で、この値を超える検出だけが残る。変更すると、すぐに推論し直す(一時停止中は、同じフレームで推論し直す)。値を下げると見逃しは減り誤検出は増え、上げると見逃しは増え誤検出は減る。

表示閾値:既定 0.25、範囲 0.01〜0.95

表示の区別だけに使う値で、変更しても推論し直さない。追跡にも影響しない。

表示閾値は、スコア閾値より低くできない。スコア閾値を上げて表示閾値を超えた場合は、表示閾値も同じ値に引き上げる。

追跡

追跡器は、操作パネルの[追跡器]で次の2つから選ぶ。どちらも、論文の記述に基づいて本プログラム内に実装したもので、原実装のコードは含まない。切り替えると、追跡 ID は振り直される。

2つの追跡器に共通の処理

BoostTrack++(手法 A)

Stanojević と Todorović(2024, arXiv:2408.13003)の構成に基づく。

  1. スコアが0.5未満の検出のスコア s を、s′ = s + (1 − s)×0.35×cos に引き上げる。cos は、その検出と IoU 0.2 を超えて重なる追跡との ReID のコサイン類似度の最大値(負のときは0)である。
  2. 追跡と検出の対応付けを、コストを最小にする1回の最適割当(SciPy の linear_sum_assignment、Jonker–Volgenant 法)で求める。コストが0.95以上の組は対応付けない。
  3. 対応付けられなかった検出のうち、引き上げ後のスコアが0.5以上のもの(ReID を使う場合は、特徴を計算できたものに限る)から、新しい追跡を作る。

TrackTrack(手法 B)

Shim ほか(CVPR 2025)の構成に基づく。

  1. 検出に加えて、後処理で残らなかった候補(「NMS あり」では NMS で除かれた候補、「NMS なし」では上位300件のうちスコア閾値以下の候補。それぞれ最大200件)も、既存の追跡との対応付けに使う。各候補のコストには、0.15×(1 − s) を加える(s はスコア)。
  2. コストの閾値を 0.90、0.75、0.60、0.45、0.30 の順に厳しくしながら、各段階で、互いに最もコストが小さい追跡と検出の組のうち、コストが閾値未満の組を対応付ける。
  3. 対応付けられなかったもののうち、スコアが0.5以上で、既存の追跡と IoU 0.55 を超えて重ならないものから、新しい追跡を作る。

ReID(人物再同定)

ReID は、検出の枠で切り抜いた画像を特徴ベクトル(L2 正規化済み)に変換する学習済みモデルである。特徴ベクトルどうしのコサイン類似度が大きいほど、同じ人物である可能性が高い。人物以外のクラスにも、同じ特徴を使う。幅6画素未満または高さ12画素未満の枠からは、特徴を計算しない。ReID モデルは、操作パネルの[ReID モデル]で次の3つから選ぶ。[ReID を使う]をオフにすると、ReID なしで追跡する。

判定閾値の初期値は、デモ動画「屋外の歩行者」で、別人どうしの組が閾値を超える割合が1〜2%になるように定めた値であり、配布元の値ではない。撮影条件・解像度・人物の向きが変わると、別人を同じ ID にまとめる誤り(誤統合)と、同じ人物に別の ID を付ける誤り(分断)が増減する。ReID の重みのダウンロードや読み込みに失敗した場合は、原因を表示し、ReID なしで追跡する。同じ ReID モデルを選び直すと、もう一度ダウンロードを試みる。

ReID の特徴は、次のように使う。

追跡とスコア閾値の関係

追跡器に渡るのは、スコア閾値を超える検出(TrackTrack では、後処理で残らなかった候補を含む)である。表示閾値は追跡に影響しない。新しい追跡を作るスコアの下限は0.5であるため、スコアが0.5未満の検出は、既存の追跡を続けるためにだけ使われる。

カメラ移動の補償は行わない。このため、カメラが大きく動く場面では、ID の入れ替わりが増える可能性がある。

画面の構成

画面は[実行画面]と[ヘルプ(H)]の2つのタブに分かれる。実行画面の左には操作パネル、中央にはメイン映像、右には解析画面がある。ヘルプ画面には、操作手順、使用技術、ライセンスを記載している。ヘルプ画面から実行画面に戻るには、ヘルプ画面の上部にある[実行画面に戻る(H)]ボタン、[実行画面]タブ、H キーのいずれかを使う。ヘルプ画面の[実行条件をコピー(再現用)]は、現在の実行条件をテキストとしてクリップボードにコピーする。

画面の下端には、次の内容が表示される。

メイン映像の上部には、モデル名、入力サイズ、表示閾値以上の検出数、後処理の方式、一時停止中であることが表示される。必要に応じて、その下に次の注記が表示される。

デモ動画の出典は、メイン映像の左下に表示される。

画面の大きさは、[ノートPC表示(768)](ウィンドウを最大1366×768にし、文字サイズを100%に戻す)と[全画面(F11)]で変えられる。起動時に、画面の作業領域(タスクバーを除いた領域)の高さが800論理画素(表示スケールを考慮した画素数)以下なら、ノートPC表示で始まる。文字サイズは、起動時に作業領域の高さから次のように決まり、[文字サイズ]で70〜250%の範囲で変えられる。

Windows の高 DPI 対応(Per-Monitor DPI Aware)を有効にしているため、表示スケールが100%を超える画面でも、OS による拡大で文字や映像がぼやけることはない。

操作パネル

入力

デモ動画

3本のデモ動画から選ぶ。テキスト・視覚プロンプト用のモデルを使っている場合は、選んだ動画に合うテキストプロンプトが自動で設定される。起動時は「店舗の通路(食器売り場)」が開く。

カメラ番号/カメラを開く

番号(0〜9)を選んで、[カメラを開く]を押す。[入力]の欄には、解像度と、カメラが報告したフレームレートが表示される。Windows では DirectShow を優先して開き、開けない場合は Media Foundation、その他の方式の順に試す。MJPG 形式・120 fps・バッファ1枚を要求し、この設定で映像が届かない機種では、設定せずに開き直す(カメラが対応していない値は、カメラ側で対応できる値になる)。開けない場合は、次の順に試す。

  1. 番号を変える。
  2. ほかのアプリがカメラを使っていないか確認する。
  3. Windows のカメラのプライバシー設定を確認する。

各フレームの取得時刻は、grab() の直後に記録する。入力の fps、撮影から結果までの遅延、保存する取得日時は、この時刻で計算する。DirectShow(OpenCV)ではカメラ側の通し番号を得られないため、撮影間隔が直近の撮影間隔の中央値の1.5倍を超えたところで、その間に取得できなかったフレーム(取得漏れ)があったと推定し、その数を数える。一時停止中の間隔は数えない。

動画・画像ファイルを開く…

ファイルを選んで開く。入力を切り替えると、前の入力の推論結果は表示されなくなり、選択と追跡もリセットされる。入力を開けなかった場合は、それまでの入力を続けたまま、理由を表示する。

検出対象

テキスト・視覚プロンプト(-seg)/プロンプトフリー(内蔵語彙, -seg-pf)

使うモデルの種類を切り替える。テキストプロンプトと視覚プロンプトは、テキスト・視覚プロンプト用のモデル(-seg)で同時に使える。プロンプトフリーには、プロンプトフリー用のモデル(-seg-pf)を使う。プロンプトフリーでは、テキストの入力欄が無効になり、内蔵語彙のクラス数が表示される。

テキストの入力欄/適用

英語の語句をカンマで区切って入力し、Enter か[適用]で反映する。入力は次のように整える。

一度計算した語句の埋め込みは再利用する。日常的な物体の名前に近い英語の語句ほど検出されやすく、状態・位置関係・比較を表す語句(「壊れた」「いちばん左の」など)は検出の手がかりになりにくい。検出されない場合は、語句を言い換える、スコア閾値を下げる、視覚プロンプトを使う、のいずれかを試す。

囲んで追加(V)

視覚プロンプトを登録する。手順は次のとおりである。

  1. テキスト・視覚プロンプト用のモデル(-seg)を選んでおく。プロンプトフリー用のモデルでは使えない。
  2. V キーか[囲んで追加(V)]を押す。映像は自動で一時停止する。
  3. 登録する物体の全体をドラッグで囲む。囲んだ範囲の幅か高さが、入力サイズ320の入力画像の上で12画素(P3 の格子の1.5マス)に満たない場合は、囲み直すよう表示される。この場合も、登録の状態は続く。
  4. 表示される入力欄にクラス名を入力する。既定の名前は「例1」「例2」…で、日本語の名前も使える。既存のクラスと同じ名前のときは、「_2」などが付く。
  5. 登録後も一時停止が続くので、Space で再開し、同じ種類の物体が検出されるかを確かめる。

選択を削除/視覚を全削除

[選択を削除]は、クラス一覧で選んだクラスを削除する。[視覚を全削除]は、視覚プロンプトをすべて削除する。

クラス一覧/クラスを検索

クラス一覧は、クラスの種類を T(テキストプロンプト)、V(視覚プロンプト)、PF(内蔵語彙)で区別して表示する。色はクラス名から一意に決まる。検索欄に入力すると、その文字を含むクラスだけが表示される。

テキストの利用条件…

テキストエンコーダの利用条件への同意・不同意を変更する。テキストプロンプトを使うには、同意が必要である。

モデル・推論

大きさ(テキスト用)/大きさ(プロンプトフリー用)

モデルの大きさを n、s、m、l、x から選ぶ。大きいほど処理時間は長くなる。未入手のモデルは、選んだ時点でダウンロードする。ダウンロードや読み込みに失敗した場合は、元のモデルのまま推論を続ける。

入力サイズ

「自動」では、GPU なら学習時の入力サイズ(640)、CPU なら480を使う。320〜1280 の中から選ぶこともできる。値を下げると処理時間は短くなるが、小さい物体は検出されにくくなる。

後処理

「NMS あり」と「NMS なし」を切り替える。

追跡器/ReID モデル/ReID を使う

追跡器と ReID モデルを選び、ReID を使うかどうかを決める。ReID モデルを替えると、判定閾値はそのモデルの初期値に戻る。

スコア閾値(conf)/表示閾値

スコア閾値と表示閾値を、スライダーか数値の入力欄で設定する。

動画の全フレームを推論

オンにすると、推論が終わるまで動画は次のフレームに進まない。このため、推論が遅い場合、動画は実時間より遅く進む。オフにすると、推論が映像に追いつかない場合は、間のフレームを飛ばして最新のフレームを推論する。動画を開くとオン、カメラを開くとオフになる。オンでも、推論できない状態(AI ライブラリやモデルの読み込み中、ダウンロード中など)では、待たずに再生を続ける。このとき推論しなかったフレームの数は、保存する JSON に記録される。

見失い中の追跡を削除するまでの回数と、削除後の復帰の保持期間は、追跡器の更新の回数で決まる。オフにして推論しないフレームが生じると、同じ回数の更新がより長い時間に当たる。ID の切り替わりなどをフレーム単位で評価する場合は、オンにする。

最新フレームを表示(ライブ)

オンにすると、常に最新の映像を表示する。このため、推論が遅いと、映像と検出結果の時刻がずれる。オフにすると、推論したフレームそのものを表示するので、ずれは生じない。この設定は表示だけを変え、どのフレームを推論するかには影響しない。CPU で推論する場合は、起動時にオフになる。

表示

マスク(M)/閾値未満(C)/追跡(T)/推定枠(K)/軌跡

それぞれの表示をオン・オフする。既定では、推定枠だけがオフである。[追跡(T)]は表示だけでなく、追跡器そのものをオン・オフする。

重ね描き

メイン映像に、クラススコア(P3、P4、P5、3スケールの最大)または特徴マップ(P3、P4、P5)の L2 ノルムを、凡例とカラーバーを添えて重ねる。

対象クラス

クラススコアの図(② クラススコアと重ね描き)で表示するクラスを選ぶ。既定は「全クラスの最大」である。

解析画面(AI の仕組み)を表示

解析画面の表示をオン・オフする。オフにすると、メイン映像を広く表示できる。

マウス操作とキー操作

マウス操作

左クリック(検出の上)

検出を選ぶ。

選んだ検出は、次の推論結果以降も追い続ける。同じ追跡 ID の検出があればその検出を、なければ同じクラスで IoU が0.3を超える枠のうち最も重なるものを追う。どちらも見つからない推論結果では、強調表示が消える。31回続けて見つからない場合は、選択を解除する。

左クリック(選べる検出がない場所)

その位置に印を付け、その位置を含む P3・P4・P5 の格子のマスを枠で示す。解析画面は ① 内訳に切り替わり、3スケールの格子点のクラススコアが表示される。

右クリック

選択を解除する。視覚プロンプトの登録中は、登録を取り消す。

ドラッグ(視覚プロンプトの登録中)

囲む範囲を指定する。

キー操作

文字や数値の入力欄(テキストの入力欄、閾値、文字サイズ、カメラ番号など)にカーソルがあるときに効くキーは、視覚プロンプトの登録中の Esc だけである。ほかのキーを使うには、メイン映像の上をクリックして、カーソルを入力欄から外す。Ctrl・Alt と組み合わせたキーには反応しない。

解析画面

解析画面は①〜⑨の9つのタブからなる。

① 内訳

選んだ検出について、次の内容を表示する。

マージンが小さいほど、そのアンカー点の出力が2つのクラスのどちらにも近い。マージンは確率ではない。

アンカー点は、出力テンソルから次の手順で特定する。まず、検出のクラスのクラススコアが検出のスコアと 1e-4 以内で一致するアンカー点を候補にする。次に、その中で、枠との L1 差が最小のアンカー点を選ぶ。特定したアンカー点が、後処理で選ばれたアンカー点と一致するかどうかも表示する。

選べる検出がない場所をクリックした場合は、その位置を含む3スケールの格子点のクラススコアを表示する。

② クラススコア

各アンカー点のクラススコアを、0〜1の値のまま着色する(正規化しない)。表示するクラスは[対象クラス]で選ぶ。

暗いマスは、レターボックスの余白を表す。斜線は、値を保持していない格子点を表す。値を保持しない格子点は、次の2つの場合に生じる。

③ 特徴マップ

検出ヘッドに入る P3・P4・P5 の特徴マップについて、各位置のチャネル方向の L2 ノルムを表示する。特徴マップごとに最小〜最大で正規化しているため、特徴マップどうしで色の濃さは比べられない。値の範囲は、見出しの数値で確認する。

④ マスク合成

選んだ検出のマスクが作られる過程を、次の順に示す。この手順は、推論でマスクを作る手順と同じである。

  1. 32枚のマスクプロトタイプ Pi(解像度は見出しに表示。入力サイズの1/4)
  2. マスク係数 ci
  3. 重み付き和 ΣciPi
  4. 重み付き和のうち枠の内側だけを残し、入力サイズへ双線形で拡大したもの
  5. 完成したマスク(枠の内側で0を超える画素)

マスクプロトタイプ、重み付き和、拡大したものの図は、それぞれ絶対値の最大で割り、青(負)〜白(0)〜赤(正)で着色する。マスクは入力サイズの1/4の解像度で作られるため、物体の境界は1〜4画素程度の幅でぼやける。

⑤ 埋め込み

クラスを表すベクトル(クラス埋め込み、L2 正規化済み)どうしのコサイン類似度の行列と、視覚プロンプトで囲んだ範囲の縮小画像を表示する。テキストプロンプトの埋め込みは、テキストエンコーダの出力を補助ネットワーク RepRTA で変換したものであり、視覚プロンプトの埋め込みは、囲んだ範囲から SAVPE が求めたものである。同じ物体をテキストプロンプトと視覚プロンプトの両方で与え、近いベクトルになるかを確かめられる。クラスが24を超える場合は、先頭の24クラスだけを表示する。

プロンプトフリー用のモデルでは表示しない。内蔵語彙の埋め込みは分類層に融合されており、独立した埋め込みとして取り出せないためである。

⑥ スコア分布

候補が絞り込まれる過程を、件数の対数に比例する幅の棒で示す。段階は次の4つである。

  1. アンカー点の総数
  2. スコア閾値を超えるアンカー点の数
  3. 後処理後の検出数(「NMS あり」では NMS 後、「NMS なし」では上位300件の選択後)
  4. そのうち表示閾値以上の検出数

あわせて、後処理前の各アンカー点の最大クラススコアのヒストグラム(縦軸は対数)を表示する。値は、「NMS あり」では one-to-many の系統、「NMS なし」では one-to-one の系統の出力である(プロンプトフリー用のモデルでは、物体らしさで絞り込んだアンカー点だけの値)。図には、スコア閾値と表示閾値を線で示す。追跡器が一度でも動いた後は、新しい追跡を作るスコアの下限(0.5、凡例は「新規追跡の下限」)も線で示す。下段には、検出の一覧を表示する。

⑦ 追跡

追跡器の設定(追跡器の名前、ReID モデルと判定閾値、削除までの回数、特徴バンクの上限、類似度に使う上位の件数、削除後の復帰の保持期間、コストの重み)と、状態ごとの件数を表示する。あわせて、各追跡について次の値を表示する。いずれも追跡器の内部状態そのものである。

上部の[バンク上限](1〜256)と[上位 k](1〜10)で、特徴バンクの上限と類似度に使う上位の件数を変更できる。[強調 ID]で追跡 ID を指定すると、その追跡の軌跡を太く、ほかの追跡の軌跡を細く表示する。

⑧ 処理時間

モデル・入力サイズ・後処理・デバイス・表示閾値の組み合わせごとに、次の値の平均を記録する。

読むときの注意点は次のとおりである。

⑨ 特徴空間

追跡器が保持している追跡(状態を問わない)の特徴バンクと、削除後の復帰のために保持している特徴バンクの ReID 特徴ベクトルを、主成分分析(PCA)で2次元に落とし、追跡 ID ごとに色分けして表示する。同じ人物の点が近くに、別の人物の点が離れて集まるほど、判定閾値で区別しやすい。右のヒストグラムは、同じ ID の特徴ベクトルどうし(青)と、別の ID の特徴ベクトルどうし(橙)のコサイン類似度の分布で、縦線が現在の判定閾値である。

保存

[保存(S)]または S キーで、スクリプトと同じフォルダの snapshots に、既存のファイルを上書きしない名前(「日時_連番」)で次のファイルを保存する。保存後は、保存先と保存したファイル名が表示される。

次回の起動時に引き継がれるのは、テキストエンコーダの利用条件への同意・不同意だけである。閾値、表示の設定、テキストプロンプト、視覚プロンプトは、起動のたびに既定の状態に戻る。実験の条件を再現するには、保存した JSON の値を記録として使う。

使用技術

YOLOE-26(Ultralytics)

検出とインスタンスセグメンテーションを行うモデルである。Ultralytics の YOLO26 に、オープンボキャブラリー(学習時に決めた種類に限らず、指定した対象を検出する方式)の仕組み YOLOE(Wang ほか, 2025, arXiv:2503.07465)を組み込んでいる。重みは次の2種類である。

RepRTA(テキストプロンプト)

テキストエンコーダ MobileCLIP2(mobileclip2_b.ts)が出力した語句の埋め込みを、補助ネットワークで検出用の埋め込みに変換し、L2 正規化する仕組みである。語句のトークン化には、CLIP のトークナイザを使う。

SAVPE(視覚プロンプト)

囲んだ範囲(P3 の格子上のマスク)と特徴マップから、視覚プロンプトの埋め込みを求める仕組みである。テキストエンコーダは使わない。埋め込みはモデルと入力サイズに依存するため、モデルの大きさや入力サイズを変えると計算し直す。計算できなかった視覚プロンプトは外し、その名前を表示する。

LRPC(プロンプトフリー)

物体らしさでアンカー点を絞り込み、絞り込んだアンカー点だけを内蔵語彙(4,585クラス)と照合する仕組みである。内蔵語彙が分類層に融合されているため、プロンプトもテキストエンコーダも使わずに検出できる。

ライブラリ

ライセンス

ヘルプ画面には、配布元で確認したライセンスの要点を、大学の授業での使用と商用での使用に分けて記載している。主な内容は次のとおりである。これらは法的な助言ではない。正式な条件は、各配布元で確認する。

exeファイルの作成手順


cd /d c:\users\user\proj\yoloe26track
python -m venv venv
venv\Scripts\activate.bat
python -m pip install --upgrade pip
pip install -U --no-user pyinstaller pytest PySide6 opencv-python ultralytics torch torchvision scipy onnxruntime ftfy regex
pip install -U --no-user https://github.com/ultralytics/CLIP/archive/refs/heads/main.zip
pyinstaller --onefile --clean --noconfirm  --collect-all PySide6 --collect-all cv2 --collect-all ultralytics --collect-all lap --collect-all torch --collect-all torchvision --collect-all scipy --collect-all onnxruntime --collect-all ftfy --collect-all regex --collect-all clip yoloe26track.py

実行ファイル:[exe]

ソースコード実行のための前準備

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:インストーラーによるインストール

  1. Python公式サイト(https://www.python.org/downloads/)にアクセスし、「Download Python 3.x.x」ボタンからWindows用インストーラーをダウンロードする。
  2. ダウンロードしたインストーラーを実行する。
  3. 初期画面の下部に表示される「Add python.exe to PATH」にチェックを入れてから「Customize installation」を選択する。このチェックを入れ忘れると、コマンドプロンプトから python コマンドを実行できない。
  4. 「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 プログラムを解釈・実行するソフトウェア)を選択する必要がある.

  1. コマンドパレット(コマンド名で機能を呼び出す VS Code の入力欄)を開く(Ctrl+Shift+P)
  2. Python: Select Interpreter と入力する
  3. 表示される一覧から,使用する Python(例:C:\Program Files\Python312\python.exe)を選択する.

必要なライブラリをシステム領域にインストール

管理者権限でコマンドプロンプトを起動する (手順:Windowsキーまたはスタートメニュー → cmd と入力 → 右クリック → 「管理者として実行」)。

以下を実行する。

REM PyTorch をインストール(GPU対応版)
set "CUDA_TAG=cu128"
pip install --no-user -U numpy torch torchvision --index-url https://download.pytorch.org/whl/%CUDA_TAG%
pip install -U --no-user PySide6 opencv-python ultralytics scipy onnxruntime ftfy regex https://github.com/ultralytics/CLIP/archive/refs/heads/main.zip

ソースコード

保存し、Visual Studio Code などで実行する。