NeuFlow v2
NeuFlow v2はNortheastern University Field Robotics Labによる高効率なオプティカルフローネットワークで、エッジデバイス向けに作られています。パラメータは約9Mで、固定サイズのキャンバス上で動作します。LibreYOLOのフローファミリーの中のエッジ向けモデルです。
- タスク
- optical flow
- インストール
pip install libreyolo- サポートティア
- 推論のみ、v1.8.0以降。推論、検証、エクスポートのみです。学習機能は対象外です。
- ライセンス
- コード:MIT、重み:Apache-2.0。商用利用
NeuFlow v2は浅いCNNエンコーダーに2つのクロスアテンション層と1/16スケールでのグローバルなsoftmaxマッチングを組み合わせ、続いて1/16および1/8スケールでの軽量な畳み込みリファイナーと、学習された8倍のconvexアップサンプラーを使います。精度の最後の一押しよりも速度とメモリが重要な場合、たとえばフレームレートでの動画処理や小型のハードウェアで選んでください。
インストール
NeuFlow v2には追加のextraは不要です。インポートするものはすべて基本インストールに含まれています。
pip install libreyolo推論
重みは初回使用時にLibreYOLOのHugging Face organizationからダウンロードされます。モデルを直接構築したい場合は、LibreNeuFlowv2クラスもlibreyoloからエクスポートされています。
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)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.pt | neuflow_mixed.pth、複数のデータセットで学習(標準) |
LibreNeuFlowv2s-flow-sintel.pt | neuflow_sintel.pth |
LibreNeuFlowv2s-flow-things.pt | neuflow_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を報告します。
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 の外れ値率libreyolo val model=LibreNeuFlowv2s-flow.pt data=my_flow.yamlエクスポート
| タスク | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | Axelera | ncnn | TFLite | CoreML | Core AI |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Optical flow | Optical 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.pt | apache-2.0 |
| LibreNeuFlowv2s-flow-sintel.pt | apache-2.0 |
| LibreNeuFlowv2s-flow-things.pt | apache-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の引用ブロックからコピーしています。