DPFlow
DPFlow 是 Henrique Morimitsu 等人提出的自适应光流估计器(CVPR 2025)。它的双金字塔编码器会根据输入尺寸调整深度,所以在低分辨率上训练的模型可以泛化到 4K 和 8K 帧。LibreYOLO 从 ptlflow 移植了它;权重采用 CC BY-NC-SA 4.0 许可,仅限非商用。
- 任务
- optical flow
- 安装
pip install libreyolo- 支持层级
- 仅推理,自 v1.8.0 起。仅支持预测、验证和导出。训练相关的功能不适用。
- 许可
- 代码采用 Apache-2.0,权重采用 CC-BY-NC-SA-4.0。商用
DPFlow 根据图像对角线选择金字塔层数:1K 左右用三层,分辨率每翻一倍多加一层。LibreYOLO 保留了这条规则,并默认在帧的原生分辨率上运行,自适应深度正是在这里起作用。做高分辨率素材的研究时选它;它的权重仅限非商用。
安装
DPFlow 不需要任何可选 extra。它导入的一切都在基础安装里。
pip install libreyolo预测
权重在首次使用时从 LibreYOLO 的 Hugging Face 组织下载。如果你更想直接构建模型,libreyolo 也导出了 LibreDPFlow 类。
from libreyolo import LibreYOLO model = LibreYOLO("LibreDPFlowm-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("LibreDPFlowm-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=LibreDPFlowm-flow.pt source=frame_0001.jpg,frame_0002.jpg save=truelibreyolo predict model=LibreDPFlowm-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 向下。DPFlow 不填充置信度图,所以 flow.confidence 为 None。result.boxes 为 None。save=True 写出 Middlebury 色轮图,arrows=True 或 warp=True 选择其他视图,save_flow=True 还会把每对帧的原始光流场写成 .flo 文件。光流任务页面完整介绍了载荷和各种视图。
变体
一种架构,尺寸 m,共四个检查点(checkpoint):
| 文件 | 训练阶段 |
|---|---|
LibreDPFlowm-flow.pt | FlyingThings3D(things),用于泛化的检查点(规范版本) |
LibreDPFlowm-flow-sintel.pt | Sintel 微调 |
LibreDPFlowm-flow-kitti.pt | KITTI 微调 |
LibreDPFlowm-flow-spring.pt | Spring 微调 |
迭代计划固定为上游的测试设置,每个金字塔层级 4 次细化迭代。每对帧都独立估计:不使用上游跨帧的热启动。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。
from libreyolo import LibreYOLO model = LibreYOLO("LibreDPFlowm-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=LibreDPFlowm-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 | |
| LibreDPFlowm-flow.pt | cc-by-nc-sa-4.0 |
| LibreDPFlowm-flow-sintel.pt | cc-by-nc-sa-4.0 |
| LibreDPFlowm-flow-kitti.pt | cc-by-nc-sa-4.0 |
| LibreDPFlowm-flow-spring.pt | cc-by-nc-sa-4.0 |
上面的每个文件目前都在 LibreYOLO 组织中,并会在首次使用时下载。
许可证
请检查你所下载的具体权重在 Hugging Face 仓库中的许可。LibreYOLO 组织里的每个检查点都附有许可,同一家族内也不一定相同。该仓库是权威来源;以下摘要说明本页上次验证时适用的情况。
这里只说明涉及的许可证,不构成法律意见。如果答案对商用很重要,请自行阅读许可证并咨询法律顾问。
- 原始工作
- DPFlow, Henrique Morimitsu (ptlflow)
- 上游许可
- CC-BY-NC-SA-4.0
- LibreYOLO 代码
- MIT
- 权重
- 采用 CC-BY-NC-SA-4.0 许可,重新发布在 huggingface.co/LibreYOLO
- 解读
- The code and the weights carry different licenses. The weights were trained within ptlflow and are released under CC BY-NC-SA 4.0: commercial use is not allowed, redistribution needs attribution, and anything you build from the weights and share must carry the same license; the DPFlow README adds that the weights are for academic and research purposes only, because of the training datasets' licenses. Treat all four checkpoints (things as the canonical m, and the sintel, kitti and spring fine-tunes) as research weights. The code is Apache-2.0: ptlflow's models/dpflow at commit 43cdc2b5 is vendored under libreyolo/models/dpflow/_vendor/, with timm-derived helpers (Apache-2.0) and an input padder adapted from RAFT (BSD-3-Clause); LibreYOLO's wrapper code is MIT. The weights come from the ptlflow weights1 release and are mirrored on the LibreYOLO Hugging Face org with the license text and a non-commercial banner, without gating. Training is out of scope.
DPFlow 是 Henrique Morimitsu 等人的工作,发布在 ptlflow 中。代码和权重的许可证不同。
- 代码采用 Apache-2.0 许可:ptlflow 的
models/dpflow连同源自 timm 的辅助代码(Apache-2.0)和改编自 RAFT 的输入填充器(BSD-3-Clause)一起被内置进来。 - 权重采用 CC BY-NC-SA 4.0 许可:仅限非商用,需要署名,而且你基于它们构建并分享的任何东西都必须采用相同的许可。DPFlow 的 README 还补充说,由于训练数据集的许可,这些权重仅用于学术和研究目的。请把全部四个检查点都当作研究用权重。
LibreYOLO 镜像这些权重时附上了许可证文本和非商用提示横幅,不需要申请访问,并在加载时打印一条提示。
引用
@InProceedings{Morimitsu2025DPFlow,
author = {Morimitsu, Henrique and Zhu, Xiaobin and Cesar-Jr., Roberto M. and Ji, Xiangyang and Yin, Xu-Cheng},
booktitle = {The IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
title = {{DPFlow}: Adaptive Optical Flow Estimation with a Dual-Pyramid Framework},
year = {2025},
}复制自作者在 github.com/hmorimitsu/ptlflow/tree/43cdc2b5fc7228e7090009a66e8e28e0b48e31ba/ptlflow/models/dpflow#citation 上提供的引用块。