查看 Markdown

UniMatch

UniMatch 用一个 transformer 匹配器统一了光流、立体匹配和深度估计(TPAMI 2023);GMFlow 是其中的光流模型。LibreYOLO 用 GMFlow 检查点提供光流任务,采用 MIT 许可。

任务
optical flow
尺寸
s, l at 640 px
安装
pip install libreyolo
支持层级
仅推理,自 v1.8.0 起。仅支持预测、验证和导出。训练相关的功能不适用。
上游
UniMatch,由 Autonomous Vision Group (University of Tübingen) 发布,采用 MIT 许可。论文、源码
许可
代码采用 MIT,权重采用 MIT。商用

GMFlow 把光流当作一个全局匹配问题:一个 transformer 比较两帧的特征,对所有位置做 softmax 得到匹配结果,还可以再用局部回归细化。内置的上游代码也包含立体匹配和深度的路径,但 LibreYOLO 只接入了光流。像上游推荐的那样,处理真实世界素材时选 l。

安装

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

bash
pip install libreyolo

预测

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

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

变体

尺寸上游检查点文件
sgmflow-scale1-things:1/8 尺度上的全局匹配(先 Chairs,后 Things)LibreUniMatchs-flow.pt
lgmflow-scale2-regrefine6-mixdata:两个尺度、6 步细化的 GMFlow+(规范版本)LibreUniMatchl-flow.pt
lSintel 微调LibreUniMatchl-flow-sintel.pt
lKITTI-2015 微调LibreUniMatchl-flow-kitti.pt

只有 l 有 Sintel 和 KITTI 微调版本。LibreUniMatch 默认使用尺寸 l。预处理复现上游的 inference_flow:竖幅帧会被转置为横幅,两帧都会被缩放,使每条边向上取整到该尺寸的填充因子(s 为 16,l 为 32)。光流场再缩放回来,向量也相应重缩放。相对上游有一处有意的修正:对竖幅帧,上游在转置回来之后把 dx 和 dy 留在互换的状态;LibreYOLO 把它们换回来,让光流场符合光流约定。

不提供训练: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("LibreUniMatchl-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=LibreUniMatchl-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)和后端向量重缩放约定之前,光流导出都无法进行。

检查点

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

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

许可证

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

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

原始工作
UniMatch, Autonomous Vision Group (University of Tübingen)
上游许可
MIT
LibreYOLO 代码
MIT
权重
采用 MIT 许可,重新发布在 huggingface.co/LibreYOLO
解读
MIT is a permissive license: the code and weights can be used in commercial and closed-source products, provided the copyright and license notice travel with copies. The upstream unimatch/ package at commit 943a9900 is vendored verbatim under libreyolo/models/unimatch/_vendor/ with its MIT LICENSE; LibreYOLO's wrapper code is also MIT. Upstream publishes the GMFlow checkpoints (gmflow-scale1-things as s, gmflow-scale2-regrefine6-mixdata as l, plus its Sintel and KITTI-2015 fine-tunes) without a separate weight license, so LibreYOLO hosts them on its Hugging Face org under the releasing project's MIT license: an implied grant, disclosed as LibreYOLO's interpretation and not confirmed by the publisher. No gating; only the optical flow task is wired, and training is out of scope.

UniMatch 是自主视觉组(Autonomous Vision Group,图宾根大学)的工作。上游 unimatch 包按其 MIT 许可原样内置进来。上游发布 GMFlow 检查点(checkpoint)时没有单独的权重许可证,所以 LibreYOLO 按发布项目的 MIT 许可托管它们:这是一种默示授予,是 LibreYOLO 的解读,未经发布者确认。不需要申请访问。MIT 允许商用和闭源使用,只要副本附带版权和许可声明。

引用

@article{xu2023unifying,
  title={Unifying Flow, Stereo and Depth Estimation},
  author={Xu, Haofei and Zhang, Jing and Cai, Jianfei and Rezatofighi, Hamid and Yu, Fisher and Tao, Dacheng and Geiger, Andreas},
  journal={IEEE Transactions on Pattern Analysis and Machine Intelligence},
  year={2023}
}

复制自作者在 github.com/autonomousvision/unimatch#citation 上提供的引用块。

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