RAFT

RAFT 是 Teed 和 Deng 提出的循环全对光流网络(ECCV 2020)。它接收两帧,为第一帧的每个像素返回它到第二帧的位移。LibreYOLO 为光流任务移植了上游的推理代码,并镜像了四个已发布的检查点。

任务
optical flow
安装
pip install libreyolo
支持层级
仅推理,自 v1.8.0 起。仅支持预测、验证和导出。训练相关的功能不适用。
上游
RAFT,由 Princeton Vision & Learning Lab 发布,采用 BSD-3-Clause 许可。论文、源码
许可
代码采用 MIT,权重采用 BSD-3-Clause。商用

RAFT 在两帧的所有像素对之间构建一个 4D 相关体,并用一个循环更新模块细化同一个光流场。它是后来大多数光流网络的出发点,SEA-RAFT、FlowSeek 和 MEMFOF 都在其中。想要这个广为人知的基线时选它,素材接近 KITTI 或 Sintel 基准时选对应的微调版本。

安装

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

bash
pip install libreyolo

预测

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

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreRAFTl-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("LibreRAFTl-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=LibreRAFTl-flow.pt source=frame_0001.jpg,frame_0002.jpg save=truelibreyolo predict model=LibreRAFTl-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 向下。RAFT 不填充置信度图,所以 flow.confidence 为 None。result.boxes 为 None。save=True 写出 Middlebury 色轮图,arrows=True 或 warp=True 选择其他视图,save_flow=True 还会把每对帧的原始光流场写成 .flo 文件。光流任务页面完整介绍了载荷和各种视图。

变体

尺寸上游检查点文件
sraft-smallLibreRAFTs-flow.pt
lraft-things(规范版本)LibreRAFTl-flow.pt
lraft-sintel 微调LibreRAFTl-flow-sintel.pt
lraft-kitti 微调LibreRAFTl-flow-kitti.pt

LibreRAFT 默认使用尺寸 l。推理在帧的原生分辨率上运行,像上游的 InputPadder 一样填充到 8 的倍数,细化迭代固定为 20 次(上游 demo.py)。imgsz 限制长边:更大的帧会被缩小,光流场再缩放回原始画布。

不提供训练: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("LibreRAFTl-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=LibreRAFTl-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
LibreRAFTl-flow.ptbsd-3-clause
LibreRAFTs-flow.ptbsd-3-clause
LibreRAFTl-flow-sintel.ptbsd-3-clause
LibreRAFTl-flow-kitti.ptbsd-3-clause

上面的每个文件目前都在 LibreYOLO 组织中,并会在首次使用时下载。

许可证

请检查你所下载的具体权重在 Hugging Face 仓库中的许可。LibreYOLO 组织里的每个检查点都附有许可,同一家族内也不一定相同。该仓库是权威来源;以下摘要说明本页上次验证时适用的情况。

这里只说明涉及的许可证,不构成法律意见。如果答案对商用很重要,请自行阅读许可证并咨询法律顾问。

原始工作
RAFT, Princeton Vision & Learning Lab
上游许可
BSD-3-Clause
LibreYOLO 代码
MIT
权重
采用 BSD-3-Clause 许可,重新发布在 huggingface.co/LibreYOLO
解读
BSD-3-Clause is a permissive license: the code and weights can be used in commercial and closed-source products. Redistributions must keep the copyright notice, the license conditions and the disclaimer, and the authors' names may not be used to endorse derived products without permission. The upstream inference code from princeton-vl/RAFT at commit 2888e15 is vendored under libreyolo/models/raft/_vendor/ with its BSD-3-Clause LICENSE; LibreYOLO's own wrapper code is MIT. The four checkpoints (raft-things as l, raft-small as s, and the raft-sintel and raft-kitti fine-tunes of l) come from the upstream download script and are mirrored on the LibreYOLO Hugging Face org under the same BSD-3-Clause license, without gating. Only the tensors' wrapping changes; training is not offered for this family.

RAFT 是普林斯顿视觉与学习实验室(Princeton Vision & Learning Lab)的 Teed 和 Deng 的工作。上游推理代码按其 BSD-3-Clause 许可内置进来,上游下载脚本里的四个检查点(checkpoint)按同一许可镜像在 LibreYOLO 的 Hugging Face 组织上,不需要申请访问。BSD-3-Clause 允许商用和闭源使用,只要保留版权声明、条件和免责声明。

引用

@misc{teed2020raftrecurrentallpairsfield,
      title={RAFT: Recurrent All-Pairs Field Transforms for Optical Flow}, 
      author={Zachary Teed and Jia Deng},
      year={2020},
      eprint={2003.12039},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2003.12039}, 
}

复制自作者在 arxiv.org/abs/2003.12039 上提供的引用块。

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