WAFT

WAFT(Warping-Alone Field Transforms)是 Wang 和 Deng 提出的光流方法(ICLR 2026)。它用高分辨率特征 warp 和一个 ViT 细化循环取代了 RAFT 的代价体。LibreYOLO 移植了上游代码,并镜像了它的四个零样本检查点,每个特征编码器一个。

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

WAFT 去掉了 RAFT 及其后继构建的相关体,改为在每一步细化之前,用当前的光流估计对第二帧的高分辨率特征做 warp。全部四个检查点(checkpoint)都是上游的零样本模型(先 TartanAir,再 Chairs,再 Things)。除非你有理由选择某个特定编码器,否则选 m,也就是上游 README 推荐用于下游任务的 a1 检查点。

安装

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

bash
pip install libreyolo

预测

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

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

变体

尺寸上游检查点参数量文件
ta2,DINOv3 ViT-S/16 编码器56.5 MLibreWAFTt-flow-dinov3.pt
sa2,Depth Anything V2 ViT-S56.9 MLibreWAFTs-flow-dav2.pt
ma1,Depth Anything V2 ViT-S64.2 MLibreWAFTm-flow.pt
la2,Twins-SVT-Large 编码器136.0 MLibreWAFTl-flow-twins.pt

编码器就是文件名里的权重变体,每个尺寸只以表中的名字存在;任何其他组合都会报错,并给出已发布的名字。LibreWAFT 默认使用尺寸 m。预测在原生分辨率上运行:网络根据编码器把这对帧填充到 112、32 或 16 的倍数,再把光流裁剪回来。细化迭代固定为五次,即上游的评估默认值。imgsz 限制长边(默认 8192,实际上等于不限制)。

不提供训练: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("LibreWAFTm-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=LibreWAFTm-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
LibreWAFTm-flow.ptbsd-3-clause
LibreWAFTt-flow-dinov3.ptDINOv3 License
LibreWAFTs-flow-dav2.ptbsd-3-clause
LibreWAFTl-flow-twins.ptbsd-3-clause

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

许可证

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

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

原始工作
WAFT, Princeton Vision & Learning Lab
上游许可
BSD-3-Clause (s, m and l checkpoints); DINOv3 License (t checkpoint)
LibreYOLO 代码
MIT
权重
采用 BSD-3-Clause (s, m and l checkpoints); DINOv3 License (t checkpoint) 许可,重新发布在 huggingface.co/LibreYOLO
解读
The license depends on the size, because each checkpoint embeds a different encoder. The s, m and l checkpoints are BSD-3-Clause, a permissive license that allows commercial and closed-source use as long as the copyright notice, conditions and disclaimer are kept on redistribution; their encoders are Apache-2.0 (Depth Anything V2 Small for s and m, Twins-SVT-Large from timm for l), which is also permissive. The t checkpoint contains a DINOv3 ViT-S/16 fine-tuned by the WAFT authors, so Meta's DINOv3 License applies to it: a custom license, not OSI-approved, with its own use restrictions and conditions; read it before relying on t commercially. Upstream publishes no separate weight license, so LibreYOLO hosts the checkpoints under the repository's BSD-3-Clause license plus the encoder license. The code from princeton-vl/WAFT at commit b152ff1 is vendored under libreyolo/models/waft/_vendor/ (BSD-3-Clause); the encoders reuse code already in LibreYOLO (Depth Anything V2, Apache-2.0; DINOv3 from the DEIMv2 vendor, DINOv3 License) and a plain-torch Twins copy derived from timm (Apache-2.0). LibreYOLO's wrapper code is MIT. Weights come from the upstream Google Drive model zoo and are mirrored on the LibreYOLO Hugging Face org without gating. Inference only.

WAFT 是普林斯顿视觉与学习实验室(Princeton Vision & Learning Lab)的 Wang 和 Deng 的工作。上游代码按其 BSD-3-Clause 许可内置进来。上游没有发布单独的权重许可证,所以 LibreYOLO 按仓库的 BSD-3-Clause 许可,加上每个检查点内嵌编码器的许可证来镜像这些检查点,不需要申请访问。

  • s、m 和 l 采用 BSD-3-Clause 许可。它们的编码器采用 Apache-2.0 许可(s 和 m 是 Depth Anything V2 Small,l 是源自 timm 的一份 Twins-SVT-Large 副本)。允许商用和闭源使用。
  • t 包含一个由 WAFT 作者微调的 DINOv3 ViT-S/16,所以它适用 Meta 的 DINOv3 License:一份未经 OSI 批准的自定义许可证,有自己的使用限制和贸易管制条款。在商用 t 之前,请先读一遍。

引用

@article{wang2025waft,
  title={WAFT: Warping-Alone Field Transforms for Optical Flow},
  author={Wang, Yihan and Deng, Jia},
  journal={arXiv preprint arXiv:2506.21526},
  year={2025}
}

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

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