UniMatch

UniMatchは1つのトランスフォーマーマッチャーでオプティカルフロー、ステレオ、深度推定を統一するモデルで(TPAMI 2023)、GMFlowはそのフローモデルです。LibreYOLOはGMFlowのチェックポイントとともに、MITの下でオプティカルフローのタスクを提供します。

タスク
optical flow
サイズ
s, l at 640 px
インストール
pip install libreyolo
サポートティア
推論のみ、v1.8.0以降。推論、検証、エクスポートのみです。学習機能は対象外です。
アップストリーム
Autonomous Vision Group (University of Tübingen)のUniMatch、MIT。論文、ソース
ライセンス
コード:MIT、重み:MIT。商用利用

GMFlowはオプティカルフローをグローバルマッチングの問題として扱います。トランスフォーマーが2枚のフレームの特徴量を比較し、すべての位置に対するsoftmaxでマッチを求め、必要に応じて局所的な回帰でリファインします。同梱しているアップストリームのコードにはステレオと深度の経路も含まれていますが、LibreYOLOで接続しているのはフローだけです。実世界の映像には、アップストリームの推奨どおりlを選んでください。

インストール

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

bash
pip install libreyolo

推論

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

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreUniMatchl-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("LibreUniMatchl-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=LibreUniMatchl-flow.pt source=frame_0001.jpg,frame_0002.jpg save=truelibreyolo predict model=LibreUniMatchl-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は下です。UniMatchは信頼度マップを出力しないため、flow.confidenceはNoneです。result.boxesはNoneです。save=TrueはMiddleburyのカラーホイールを出力し、arrows=Trueまたはwarp=Trueで他の表示を選び、save_flow=Trueは各組の生のフィールドも.floファイルとして出力します。ペイロードと表示の詳細はオプティカルフローのタスクページで説明しています。

バリアント

サイズアップストリームのチェックポイントファイル
sgmflow-scale1-things:1/8でのグローバルマッチング(Chairs、続いてThings)LibreUniMatchs-flow.pt
lgmflow-scale2-regrefine6-mixdata:2スケールで6回のリファインメントステップを行うGMFlow+(標準)LibreUniMatchl-flow.pt
lSintelでのファインチューニングLibreUniMatchl-flow-sintel.pt
lKITTI-2015でのファインチューニングLibreUniMatchl-flow-kitti.pt

SintelとKITTIのファインチューニング版があるのはlだけです。LibreUniMatchのデフォルトはサイズlです。前処理はアップストリームのinference_flowを再現します:縦長のフレームは横長に転置され、両方のフレームは各辺がサイズごとのパディング係数(sは16、lは32)の倍数に切り上がるようにリサイズされます。フィールドは元のサイズへリサイズし直され、ベクトルも再スケールされます。アップストリームに対する意図的な修正が1つあります:縦長のフレームでは、アップストリームは転置を戻した後もdxとdyを入れ替えたままにしますが、LibreYOLOはフィールドがフローの契約に従うようにそれらを入れ替えます。

学習は提供していません: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("LibreUniMatchl-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=LibreUniMatchl-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)とバックエンドのベクトル再スケールの契約がいずれかのファミリーで実装されるまで保留されています。

チェックポイント

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

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

ライセンス

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

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

原著作物
UniMatch, Autonomous Vision Group (University of Tübingen)
アップストリームのライセンス
MIT
アップストリームのソース
github.com/autonomousvision/unimatch
LibreYOLOのコード
MIT
重み
MIT、huggingface.co/LibreYOLOで再公開
解釈
MIT is a permissive license: the code and weights can be used in commercial and closed-source products, provided the copyright and license notice travel with copies. The upstream unimatch/ package at commit 943a9900 is vendored verbatim under libreyolo/models/unimatch/_vendor/ with its MIT LICENSE; LibreYOLO's wrapper code is also MIT. Upstream publishes the GMFlow checkpoints (gmflow-scale1-things as s, gmflow-scale2-regrefine6-mixdata as l, plus its Sintel and KITTI-2015 fine-tunes) without a separate weight license, so LibreYOLO hosts them on its Hugging Face org under the releasing project's MIT license: an implied grant, disclosed as LibreYOLO's interpretation and not confirmed by the publisher. No gating; only the optical flow task is wired, and training is out of scope.

UniMatchはAutonomous Vision Group(テュービンゲン大学)の成果です。アップストリームのunimatchパッケージはMITライセンスの下でそのまま同梱されています。アップストリームはGMFlowのチェックポイントを個別の重みライセンスなしで公開しているため、LibreYOLOはそれらを公開元プロジェクトのMITライセンスの下でホストしています。これは黙示の許諾であり、LibreYOLOの解釈で、公開元による確認は得ていません。アクセス制限はありません。MITは、著作権表示とライセンス表示を複製物に添える限り、商用利用およびクローズドソースでの利用を許可しています。

引用

@article{xu2023unifying,
  title={Unifying Flow, Stereo and Depth Estimation},
  author={Xu, Haofei and Zhang, Jing and Cai, Jianfei and Rezatofighi, Hamid and Yu, Fisher and Tao, Dacheng and Geiger, Andreas},
  journal={IEEE Transactions on Pattern Analysis and Machine Intelligence},
  year={2023}
}

著者によるgithub.com/autonomousvision/unimatch#citationの引用ブロックからコピーしています。

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