查看 Markdown

SEA-RAFT

SEA-RAFT(Simple, Efficient, Accurate RAFT)是 Wang、Lipson 和 Deng 提出的 RAFT 后继(ECCV 2024)。它预测两帧之间的稠密光流,而且与 LibreYOLO 里的其他光流家族不同,还会给出逐像素置信度图。LibreYOLO 移植了上游的推理代码,并镜像了它的 S 和 M 检查点。

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

SEA-RAFT 保留了 RAFT 的全对相关金字塔,直接回归一个初始光流,用 ConvNeXt 更新模块细化它,并用混合拉普拉斯损失函数训练。LibreYOLO 正是把预测出的混合方差转成 flow.confidence。光流任务页面的示例用的就是这个家族;想在光流旁边得到逐像素置信度时选它。

安装

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

bash
pip install libreyolo

预测

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

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreSEARAFTm-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("LibreSEARAFTm-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=LibreSEARAFTm-flow.pt source=frame_0001.jpg,frame_0002.jpg save=truelibreyolo predict model=LibreSEARAFTm-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 向下。flow.confidence 是一张取值在 [0, 1] 内的 (H, W) 图,由预测出的混合方差推导而来:值越高,表示网络对该像素处的向量越有把握。result.boxes 为 None。save=True 写出 Middlebury 色轮图,arrows=True 或 warp=True 选择其他视图,save_flow=True 还会把每对帧的原始光流场写成 .flo 文件。光流任务页面完整介绍了载荷和各种视图。

变体

尺寸编码器细化迭代次数文件
sResNet184LibreSEARAFTs-flow.pt
mResNet344LibreSEARAFTm-flow.pt
lResNet34,即 m 的权重12LibreSEARAFTl-flow.pt

上游没有单独提供 L 权重:l 就是用 12 次而不是 4 次迭代运行的 m 检查点(checkpoint)。三者都是上游的 Tartan-C-T-TSKH-spring540x960 检查点。LibreSEARAFT 默认使用尺寸 m。长边不超过 960 px(即训练裁剪宽度)的帧在原生分辨率上运行,填充到 8 的倍数;更大的帧会被缩小,光流场再缩放回来。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("LibreSEARAFTm-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=LibreSEARAFTm-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
LibreSEARAFTs-flow.ptbsd-3-clause
LibreSEARAFTm-flow.ptbsd-3-clause
LibreSEARAFTl-flow.ptbsd-3-clause

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

许可证

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

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

原始工作
SEA-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. An inference subset of the upstream core/ package at commit 9137517b is vendored under libreyolo/models/searaft/_vendor/ with its BSD-3-Clause LICENSE; LibreYOLO's wrapper code is MIT. The weights are the upstream Tartan-C-T-TSKH-spring540x960 S and M checkpoints (MemorySlices on Hugging Face), which upstream publishes without a separate weight license; LibreYOLO mirrors them under the repository's BSD-3-Clause license and states that on the cards. Size l reuses the m weights with 12 refinement iterations instead of 4. No gating; inference only.

SEA-RAFT 是普林斯顿视觉与学习实验室(Princeton Vision & Learning Lab)的 Wang、Lipson 和 Deng 的工作。上游代码中用于推理的子集按其 BSD-3-Clause 许可内置进来。上游发布 S 和 M 权重时没有单独的权重许可证;LibreYOLO 按仓库的 BSD-3-Clause 许可镜像它们,不需要申请访问。BSD-3-Clause 允许商用和闭源使用,只要保留版权声明、条件和免责声明。

引用

@article{wang2024sea,
  title={SEA-RAFT: Simple, Efficient, Accurate RAFT for Optical Flow},
  author={Wang, Yihan and Lipson, Lahav and Deng, Jia},
  journal={arXiv preprint arXiv:2405.14793},
  year={2024}
}

复制自作者在 github.com/princeton-vl/SEA-RAFT 上提供的引用块。

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