Markdownで表示

オプティカルフロー

オプティカルフローは、あるフレームの各ピクセルが次のフレームでどこへ移動するかを予測します。LibreYOLOは1.8.0の新機能であるflowタスクとして提供します:フレームの組を入力すると、ピクセル変位の密なフィールドが1つ出力され、8つのファミリーが同じ呼び出しで使えます。

定義

flowタスクはフレームのシーケンスを受け取り、連続する各組について、フレームtからフレームt + 1への各ピクセルの変位を予測します。別名のoptical-flow、optical_flow、opticalflowもこのタスクに解決され、チェックポイントには-flowの接尾辞が付きます。

推論結果はresult.flowに入ります。これは最初のフレームの元のキャンバス上の(H, W, 2)のfloat32配列を保持するFlowFieldです。flow.data[y, x]はピクセル単位の(dx, dy)で、+xは右、+yは下です。.dx、.dy、.magnitude、.angle、.max_magnitude、.mean_magnitudeでこれを読み取り、.warp(image)はフィールドを使って画像を逆方向にワープします。flow.confidenceは[0, 1]の範囲の省略可能な(H, W)マップで、これを予測するファミリー(不確実性ヘッドを持つSEA-RAFT)だけが値を入れ、それ以外はNoneのままにします。flow.next_frameはワープ表示用に2枚目のフレームを保持します。result.boxesはNoneです。

モデル

flowには8つのファミリーがあります。まだどれにもモデルページはないため、以下のスニペットのようにチェックポイント名で読み込んでください。

ファミリーサイズ重みのライセンス
SEA-RAFTs, m, lBSD-3-Clause
RAFTs, l、およびSintelとKITTIのバリアントBSD-3-Clause
NeuFlow v2s、およびSintelとThingsのバリアントApache-2.0
WAFTt, s, m, lBSD-3-Clause。tはDINOv3を使うため、DINOv3 Licenseが適用されます
FlowSeekt, s, m, ltとsはApache-2.0。mとlは非商用(CC BY-NC、Depth Anything V2エンコーダー)
DPFlowm、およびSintel、KITTI、Springのバリアント非商用(CC BY-NC-SA 4.0)
UniMatchs, l、およびSintelとKITTIのバリアントMIT
MEMFOFm、および5つのバリアントBSD-3-Clause

チェックポイント名はLibre<Family><size>-flow.ptの形式で、たとえばLibreSEARAFTm-flow.pt、LibreRAFTl-flow-kitti.pt、LibreNeuFlowv2s-flow.ptです。非商用の重みは読み込み時に通知を表示します。NeuFlow v2は小型のエッジ向けモデルです。MEMFOFは1組あたり3枚のフレームを読み込み、ランナーはシーケンスの先頭と末尾で端のフレームを繰り返します。8つすべてがアップストリームのコードに対するパリティを記録済みで、重みはLibreYOLOのHugging Face organizationにミラーされています。

推論

2枚のフレーム
from libreyolo import LibreYOLO model = LibreYOLO("LibreSEARAFTm-flow.pt")results = model(["frame_0001.jpg", "frame_0002.jpg"]) flow = results[0].flowprint(flow.data.shape)           # (H, W, 2) float32、ピクセル単位の(dx, dy)print(flow.mean_magnitude)       # ピクセル単位の平均変位
動画またはフレームのリスト
from libreyolo import LibreYOLO model = LibreYOLO("LibreNeuFlowv2s-flow.pt") # Nフレームから N - 1 個の結果。結果iはフレームiからi + 1へのフローfor result in model("video.mp4", stream=True, vid_stride=2):    print(result.flow.max_magnitude)
表示形式と生のフィールド
from libreyolo import LibreYOLO model = LibreYOLO("LibreRAFTl-flow.pt")frames = ["frame_0001.jpg", "frame_0002.jpg", "frame_0003.jpg"] model(frames, save=True)                    # カラーホイール(デフォルト)model(frames, save=True, arrows=True)       # フレーム上に矢印model(frames, save=True, warp=True)         # ワープによる確認results = model(frames, save=True, save_flow=True)   # .floも出力 results[0].flow.save("pair0.npy")           # .floまたは.npy

画像1枚だけでは例外になります:フローには少なくとも2枚のフレームが必要です。画像のリストまたはタプル、名前順に並べたディレクトリ、動画、ストリームはそれぞれ1つのシーケンスとして扱われ、N枚のフレームからN - 1個の結果が得られます。結果iはフレームiからフレームi + 1へのフローを持ち、orig_imgはフレームiです。動画ではvid_strideでフレームの間隔を設定し、stream=Trueで1組ごとに1つの結果を返します。

表示形式は3つあります。デフォルトはMiddleburyのカラーホイールで、色相が方向、彩度が大きさを表し、動きがゼロの箇所は白になります。arrows=Trueは16ピクセルごとに1本の矢印を付けてフレームを描画します。warp=Trueはフレームtと、それに向けて逆方向にワープしたフレームt + 1を並べて表示し、フィールドが正しければ2つのパネルが一致します。save=Trueは選んだ表示を出力し、save_flow=Trueは各組の生のフィールドも<frame stem>_<frame index>.floという名前のMiddlebury形式の.floファイルとして出力します。FlowField.save(path)は.floまたは.npyを直接書き出します。

シェルからは、フレームをカンマ区切りのsourceとして渡し、arrows=true、warp=true、save_flow=trueを追加します:

CLI
libreyolo predict model=LibreSEARAFTm-flow.pt source=frame_0001.jpg,frame_0002.jpg save=truelibreyolo predict model=LibreSEARAFTm-flow.pt source=video.mp4 save=true arrows=true save_flow=truelibreyolo val model=LibreSEARAFTm-flow.pt data=my_flow.yaml

ソースとストリーミングについては推論を、CLIのすべてのフラグについてはlibreyolo predictを参照してください。

データセット形式

フローのデータセットはフレームのシーケンスの集まりです。フレームはimages/<split>/<sequence>/の下に置かれ、ファイル名順に並べられます。1つのシーケンスディレクトリ内の連続する各組が1つのサンプルで、その正解データはflows/の下に、同じ相対パスと最初のフレームのstemで置かれます。

dataset/  data.yaml  images/    val/alley_1/frame_0001.png    val/alley_1/frame_0002.png    val/alley_1/frame_0003.png  flows/    val/alley_1/frame_0001.flo    val/alley_1/frame_0002.flo
yaml
path: datasetval: images/valflows_dir: flowsflow_format: flo

flow_formatはflo(Middlebury、デフォルト)、kitti(青チャンネルを有効マスクとする16ビットRGB PNG)、npy(非有限値が無効を表す(H, W, 2)のfloat配列)のいずれかです。省略可能な組ごとのマスク<stem>_valid.pngは、有効なピクセルを非ゼロで示します。flow_valid_suffixでこの接尾辞を変更できます。シーケンスの最後のフレームにはフローファイルがなく、異なるディレクトリのフレームが組になることはありません。

学習

フローは推論のみを提供します。フローのファミリーでtrain()を呼ぶとNotImplementedErrorが送出されます。

検証

val()は、有効なピクセル上で予測ベクトルと正解ベクトルを位置合わせなしで直接比較します。

検証して指標キーを読み取る
from libreyolo import LibreYOLO model = LibreYOLO("LibreSEARAFTm-flow.pt")metrics = model.val(data="my_flow.yaml") print(metrics["metrics/epe"])      # 平均エンドポイント誤差、ピクセル単位print(metrics["metrics/px1"])      # 誤差が1 px未満のピクセルの割合print(metrics["metrics/px3"])print(metrics["metrics/fl_all"])   # KITTIの外れ値率

metrics/epeは平均エンドポイント誤差で、予測ベクトルと真のベクトルのピクセル単位のユークリッド距離であり、低いほど良好です。metrics/px1とmetrics/px3は、誤差が1ピクセル未満と3ピクセル未満の有効ピクセルの割合です。metrics/fl_allはKITTIの外れ値率で、誤差が3ピクセルと真の大きさの5パーセントの両方を超えるピクセルの割合です。品質とともに増加するため、ベストチェックポイントの評価値にはmetrics/px1を使います。

エクスポート

フローのエクスポートは、あるファミリーで2入力のグラフとバックエンドの再スケール契約が実装されるまで、すべてのフォーマットでブロックされています。エクスポート対応表を参照してください。

LibreYOLO v1.8.0で検証済みです。