查看 Markdown

NeuFlow v2

NeuFlow v2 是美国东北大学野外机器人实验室(Field Robotics Lab)为边缘设备打造的高效光流网络。它约有 900 万参数,在固定画布上运行;它是 LibreYOLO 光流家族中的边缘模型。

任务
optical flow
安装
pip install libreyolo
支持层级
仅推理,自 v1.8.0 起。仅支持预测、验证和导出。训练相关的功能不适用。
上游
NeuFlow v2,由 Northeastern University Field Robotics Lab 发布,采用 Apache-2.0 许可。论文、源码
许可
代码采用 MIT,权重采用 Apache-2.0。商用

NeuFlow v2 把一个浅层 CNN 编码器与两个交叉注意力层以及 1/16 尺度上的全局 softmax 匹配组合起来,之后是 1/16 和 1/8 尺度上的轻量卷积细化器,以及一个学习得到的 8 倍 convex 上采样器。当速度和内存比最后一点精度更重要时选它,比如按帧率处理视频,或者在小型硬件上运行。

安装

NeuFlow v2 不需要任何可选 extra。它导入的一切都在基础安装里。

bash
pip install libreyolo

预测

权重在首次使用时从 LibreYOLO 的 Hugging Face 组织下载。如果你更想直接构建模型,libreyolo 也导出了 LibreNeuFlowv2 类。

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

光流至少需要两帧:只传一张图像会报错。图像列表、按文件名排序的目录、视频或流都算作一个序列,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.ptneuflow_mixed.pth,在多个数据集上训练(规范版本)
LibreNeuFlowv2s-flow-sintel.ptneuflow_sintel.pth
LibreNeuFlowv2s-flow-things.ptneuflow_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。

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:不支持

目前还不支持导出任何格式。在某个家族实现光流任务的双输入计算图(image1、image2)和后端向量重缩放约定之前,光流导出都无法进行。

检查点

这个家族已发布的全部权重文件。

文件权重许可
Optical flow
LibreNeuFlowv2s-flow.ptapache-2.0
LibreNeuFlowv2s-flow-sintel.ptapache-2.0
LibreNeuFlowv2s-flow-things.ptapache-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 上提供的引用块。

已针对 LibreYOLO v1.8.0 验证。本页的支持表、检查点和基准测试数据由已发布的库和权重生成,并非手工编写。