Markdownで表示

NeuFlow v2

NeuFlow v2はNortheastern University Field Robotics Labによる高効率なオプティカルフローネットワークで、エッジデバイス向けに作られています。パラメータは約9Mで、固定サイズのキャンバス上で動作します。LibreYOLOのフローファミリーの中のエッジ向けモデルです。

タスク
optical flow
インストール
pip install libreyolo
サポートティア
推論のみ、v1.8.0以降。推論、検証、エクスポートのみです。学習機能は対象外です。
アップストリーム
Northeastern University Field Robotics LabのNeuFlow v2、Apache-2.0。論文、ソース
ライセンス
コード:MIT、重み:Apache-2.0。商用利用

NeuFlow v2は浅いCNNエンコーダーに2つのクロスアテンション層と1/16スケールでのグローバルなsoftmaxマッチングを組み合わせ、続いて1/16および1/8スケールでの軽量な畳み込みリファイナーと、学習された8倍のconvexアップサンプラーを使います。精度の最後の一押しよりも速度とメモリが重要な場合、たとえばフレームレートでの動画処理や小型のハードウェアで選んでください。

インストール

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

bash
pip install libreyolo

推論

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

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

バリアント

アーキテクチャは1つでサイズはs、同じネットワークに学習データの異なる3つのバリアントがあります。

ファイルアップストリームのチェックポイント
LibreNeuFlowv2s-flow.ptneuflow_mixed.pth、複数のデータセットで学習(標準)
LibreNeuFlowv2s-flow-sintel.ptneuflow_sintel.pth
LibreNeuFlowv2s-flow-things.ptneuflow_things.pth

他のフローファミリーとは異なり、NeuFlow v2は本来の解像度では動作しません。両方のフレームは固定サイズのキャンバスへ引き伸ばしてリサイズされ、デフォルトはアップストリームのinfer.pyと同じく432x768(高さ×幅)です。imgszには整数または(height, width)の組を指定でき、各辺は16の倍数です。ネットワークは1/16で1回、1/8で8回のリファインメントステップを実行し、フィールドは元のキャンバスへリサイズし直され、ベクトルの各成分はその軸のリサイズ比率で乗算されます。

学習は提供していません: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("LibreNeuFlowv2s-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=LibreNeuFlowv2s-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
LibreNeuFlowv2s-flow.ptapache-2.0
LibreNeuFlowv2s-flow-sintel.ptapache-2.0
LibreNeuFlowv2s-flow-things.ptapache-2.0

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

ライセンス

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

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

原著作物
NeuFlow v2, Northeastern University Field Robotics Lab
アップストリームのライセンス
Apache-2.0
アップストリームのソース
github.com/neufieldrobotics/NeuFlow_v2
LibreYOLOのコード
MIT
重み
Apache-2.0、huggingface.co/LibreYOLOで再公開
解釈
Apache-2.0 is a permissive license: the code and weights can be used in commercial and closed-source products. It asks you to keep the license text and attribution notices with redistributed copies, to mark modified files, and it grants a patent license. The upstream model code at commit 204b5e37 is vendored under libreyolo/models/neuflowv2/_vendor/ with its Apache-2.0 LICENSE; LibreYOLO's wrapper code is MIT. Upstream commits its three checkpoints (neuflow_mixed.pth as the canonical s, neuflow_sintel.pth and neuflow_things.pth as variants) to the Apache-2.0 repository with no separate weight license, so LibreYOLO mirrors them on its Hugging Face org under Apache-2.0, an implied grant from the releasing project. No gating; inference only.

NeuFlow v2はNortheastern University Field Robotics Labの成果です。アップストリームのモデルコードはApache-2.0ライセンスの下で同梱されています。アップストリームは3つのチェックポイントを個別の重みライセンスなしで同じApache-2.0のリポジトリにコミットしているため、LibreYOLOはそれらをApache-2.0の下で、アクセス制限なしでミラーしています。Apache-2.0は商用利用およびクローズドソースでの利用を許可しています。再配布の際はライセンス文と帰属表示を残してください。

引用

@misc{zhang2025neuflowv2pushhighefficiency,
      title={NeuFlow v2: Push High-Efficiency Optical Flow To the Limit}, 
      author={Zhiyong Zhang and Aniket Gupta and Huaizu Jiang and Hanumant Singh},
      year={2025},
      eprint={2408.10161},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2408.10161}, 
}

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

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