NeuFlow v2
NeuFlow v2 是美国东北大学野外机器人实验室(Field Robotics Lab)为边缘设备打造的高效光流网络。它约有 900 万参数,在固定画布上运行;它是 LibreYOLO 光流家族中的边缘模型。
- 任务
- optical flow
- 安装
pip install libreyolo- 支持层级
- 仅推理,自 v1.8.0 起。仅支持预测、验证和导出。训练相关的功能不适用。
- 许可
- 代码采用 MIT,权重采用 Apache-2.0。商用
NeuFlow v2 把一个浅层 CNN 编码器与两个交叉注意力层以及 1/16 尺度上的全局 softmax 匹配组合起来,之后是 1/16 和 1/8 尺度上的轻量卷积细化器,以及一个学习得到的 8 倍 convex 上采样器。当速度和内存比最后一点精度更重要时选它,比如按帧率处理视频,或者在小型硬件上运行。
安装
NeuFlow v2 不需要任何可选 extra。它导入的一切都在基础安装里。
pip install libreyolo预测
权重在首次使用时从 LibreYOLO 的 Hugging Face 组织下载。如果你更想直接构建模型,libreyolo 也导出了 LibreNeuFlowv2 类。
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光流至少需要两帧:只传一张图像会报错。图像列表、按文件名排序的目录、视频或流都算作一个序列,N 帧给出 N - 1 个结果。result.flow 是一个 FlowField,带有一个位于第一帧原始画布上的 (H, W, 2) float32 数组;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 文件。光流任务页面完整介绍了载荷和各种视图。
变体
一种架构,尺寸 s,同一个网络有三种训练数据变体:
| 文件 | 上游检查点 |
|---|---|
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(高 x 宽);imgsz 接受一个整数或一个 (height, width) 对,每条边都是 16 的倍数。网络在 1/16 上运行一步细化,在 1/8 上运行八步,光流场再缩放回原始画布,每个向量分量乘以对应轴的缩放比例。
不提供训练:train() 会抛出 NotImplementedError。
验证
val() 在光流数据集上运行共用的光流验证器(每个序列一个文件夹存放帧,真值(ground truth)为 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:不支持 |
目前还不支持导出任何格式。在某个家族实现光流任务的双输入计算图(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 组织中,并会在首次使用时下载。
许可证
请检查你所下载的具体权重在 Hugging Face 仓库中的许可。LibreYOLO 组织里的每个检查点都附有许可,同一家族内也不一定相同。该仓库是权威来源;以下摘要说明本页上次验证时适用的情况。
这里只说明涉及的许可证,不构成法律意见。如果答案对商用很重要,请自行阅读许可证并咨询法律顾问。
- 原始工作
- NeuFlow v2, Northeastern University Field Robotics Lab
- 上游许可
- Apache-2.0
- 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 是美国东北大学野外机器人实验室的工作。上游模型代码按其 Apache-2.0 许可内置进来。上游把它的三个检查点(checkpoint)提交在同一个 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 上提供的引用块。