RAFT

RAFTはTeedとDengによる再帰型の全ペアオプティカルフローネットワークです(ECCV 2020)。2枚のフレームを受け取り、1枚目の各ピクセルについて2枚目への変位を返します。LibreYOLOはアップストリームの推論コードを移植し、flowタスク向けに公開済みの4つのチェックポイントをミラーしています。

タスク
optical flow
インストール
pip install libreyolo
サポートティア
推論のみ、v1.8.0以降。推論、検証、エクスポートのみです。学習機能は対象外です。
アップストリーム
Princeton Vision & Learning LabのRAFT、BSD-3-Clause。論文、ソース
ライセンス
コード:MIT、重み:BSD-3-Clause。商用利用

RAFTは2枚のフレームのすべてのピクセルの組の間に4D相関ボリュームを構築し、再帰的な更新ブロックで1つのフローフィールドをリファインします。SEA-RAFT、FlowSeek、MEMFOFをはじめ、後の多くのフローネットワークが出発点とするリファレンスです。よく知られたベースラインが欲しい場合や、KITTIまたはSintelに近い映像向けにそのファインチューニング版が欲しい場合に選んでください。

インストール

RAFTには追加のextraは不要です。インポートするものはすべて基本インストールに含まれています。

bash
pip install libreyolo

推論

重みは初回使用時にLibreYOLOのHugging Face organizationからダウンロードされます。モデルを直接構築したい場合は、LibreRAFTクラスもlibreyoloからエクスポートされています。

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreRAFTl-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("LibreRAFTl-flow.pt") # N フレームから N - 1 個の結果 結果 i はフレーム i から i + 1 へのフローfor result in model("video.mp4", stream=True, save=True, save_flow=True):    print(result.flow.max_magnitude)
CLI
libreyolo predict model=LibreRAFTl-flow.pt source=frame_0001.jpg,frame_0002.jpg save=truelibreyolo predict model=LibreRAFTl-flow.pt source=video.mp4 save=true arrows=true save_flow=true

フローには少なくとも2枚のフレームが必要です:画像1枚だけでは例外になります。画像のリスト、名前順に並べたディレクトリ、動画、ストリームはそれぞれ1つのシーケンスで、N枚のフレームからN - 1個の結果が得られます。result.flowは、最初のフレームの元のキャンバス上の(H, W, 2)のfloat32配列を持つFlowFieldです。flow.data[y, x]はピクセル単位の(dx, dy)で、+xは右、+yは下です。RAFTは信頼度マップを出力しないため、flow.confidenceはNoneです。result.boxesはNoneです。save=TrueはMiddleburyのカラーホイールを出力し、arrows=Trueまたはwarp=Trueで他の表示を選び、save_flow=Trueは各組の生のフィールドも.floファイルとして出力します。ペイロードと表示の詳細はオプティカルフローのタスクページで説明しています。

バリアント

サイズアップストリームのチェックポイントファイル
sraft-smallLibreRAFTs-flow.pt
lraft-things(標準)LibreRAFTl-flow.pt
lraft-sintelのファインチューニングLibreRAFTl-flow-sintel.pt
lraft-kittiのファインチューニングLibreRAFTl-flow-kitti.pt

LibreRAFTのデフォルトはサイズlです。推論はフレーム本来の解像度で行われ、アップストリームのInputPadderと同じく8の倍数にパディングされ、リファインメント反復は20回に固定されています(アップストリームのdemo.py)。imgszは長辺の上限を設定します。それより大きいフレームは縮小され、フィールドは元のキャンバスへ拡大し直されます。

学習は提供していません:train()はNotImplementedErrorを発生させます。

検証

val()はフローのデータセット(シーケンスフォルダーごとのフレームと、Middleburyの.flo、KITTIの16ビットPNG、または.npyの正解データ。データセット形式を参照)に対して共有のフローバリデーターを実行します。平均エンドポイント誤差metrics/epe、metrics/px1とmetrics/px3(誤差が1 pxおよび3 px未満の有効ピクセルの割合)、KITTIの外れ値率metrics/fl_allを報告します。

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreRAFTl-flow.pt")metrics = model.val(data="my_flow.yaml") print(metrics["metrics/epe"])      # 平均エンドポイント誤差 ピクセル単位print(metrics["metrics/px1"])      # 誤差が 1 px 未満のピクセルの割合print(metrics["metrics/fl_all"])   # KITTI の外れ値率
CLI
libreyolo val model=LibreRAFTl-flow.pt data=my_flow.yaml

エクスポート

タスクONNXTorchScriptExecuTorchTensorRTOpenVINOPaddleMNNRKNNAxelerancnnTFLiteCoreMLCore AI
Optical flowOptical flow to ONNX:非対応Optical flow to TorchScript:非対応Optical flow to ExecuTorch:非対応Optical flow to TensorRT:非対応Optical flow to OpenVINO:非対応Optical flow to Paddle:非対応Optical flow to MNN:非対応Optical flow to RKNN:非対応Optical flow to Axelera:非対応Optical flow to ncnn:非対応Optical flow to TFLite:非対応Optical flow to CoreML:非対応Optical flow to Core AI:非対応

エクスポートはまだどの形式でも利用できません。オプティカルフローのエクスポートは、flowタスクの2入力グラフ(image1、image2)とバックエンドのベクトル再スケールの契約がいずれかのファミリーで実装されるまで保留されています。

チェックポイント

このファミリーで公開されているすべての重みファイルです。

ファイル重みのライセンス
Optical flow
LibreRAFTl-flow.ptbsd-3-clause
LibreRAFTs-flow.ptbsd-3-clause
LibreRAFTl-flow-sintel.ptbsd-3-clause
LibreRAFTl-flow-kitti.ptbsd-3-clause

上記のすべてのファイルは現在LibreYOLO orgにあり、初回使用時にダウンロードされます。

ライセンス

ダウンロードする特定の重みについて、Hugging Faceリポジトリのライセンスを確認してください。LibreYOLO orgの各チェックポイントにはライセンスが付与されており、同じファミリー内でも常に同一とは限りません。そのリポジトリが正式な情報源です。以下の概要は、このページを最後に検証した時点で適用されていた内容を示します。

これは関連するライセンスの説明であり、法的助言ではありません。商用上重要な場合は、自分でライセンスを読み、専門家の助言を受けてください。

原著作物
RAFT, Princeton Vision & Learning Lab
アップストリームのライセンス
BSD-3-Clause
アップストリームのソース
github.com/princeton-vl/RAFT
LibreYOLOのコード
MIT
重み
BSD-3-Clause、huggingface.co/LibreYOLOで再公開
解釈
BSD-3-Clause is a permissive license: the code and weights can be used in commercial and closed-source products. Redistributions must keep the copyright notice, the license conditions and the disclaimer, and the authors' names may not be used to endorse derived products without permission. The upstream inference code from princeton-vl/RAFT at commit 2888e15 is vendored under libreyolo/models/raft/_vendor/ with its BSD-3-Clause LICENSE; LibreYOLO's own wrapper code is MIT. The four checkpoints (raft-things as l, raft-small as s, and the raft-sintel and raft-kitti fine-tunes of l) come from the upstream download script and are mirrored on the LibreYOLO Hugging Face org under the same BSD-3-Clause license, without gating. Only the tensors' wrapping changes; training is not offered for this family.

RAFTはPrinceton Vision & Learning LabのTeedとDengの成果です。アップストリームの推論コードはBSD-3-Clauseライセンスの下で同梱されており、アップストリームのダウンロードスクリプトにある4つのチェックポイントは、同じライセンスの下でLibreYOLOのHugging Face organizationにアクセス制限なしでミラーされています。BSD-3-Clauseは、著作権表示、条件、免責事項を残す限り、商用利用およびクローズドソースでの利用を許可しています。

引用

@misc{teed2020raftrecurrentallpairsfield,
      title={RAFT: Recurrent All-Pairs Field Transforms for Optical Flow}, 
      author={Zachary Teed and Jia Deng},
      year={2020},
      eprint={2003.12039},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2003.12039}, 
}

著者によるarxiv.org/abs/2003.12039の引用ブロックからコピーしています。

LibreYOLO v1.8.0で検証済みです。このページのサポート表、チェックポイント、ベンチマーク値は手作業で記述したものではなく、リリース済みライブラリと公開済みの重みから生成されています。