UniMatch
UniMatch 用一个 transformer 匹配器统一了光流、立体匹配和深度估计(TPAMI 2023);GMFlow 是其中的光流模型。LibreYOLO 用 GMFlow 检查点提供光流任务,采用 MIT 许可。
- 任务
- optical flow
- 尺寸
- s, l at 640 px
- 安装
pip install libreyolo- 支持层级
- 仅推理,自 v1.8.0 起。仅支持预测、验证和导出。训练相关的功能不适用。
- 许可
- 代码采用 MIT,权重采用 MIT。商用
GMFlow 把光流当作一个全局匹配问题:一个 transformer 比较两帧的特征,对所有位置做 softmax 得到匹配结果,还可以再用局部回归细化。内置的上游代码也包含立体匹配和深度的路径,但 LibreYOLO 只接入了光流。像上游推荐的那样,处理真实世界素材时选 l。
安装
UniMatch 不需要任何可选 extra。它导入的一切都在基础安装里。
pip install libreyolo预测
权重在首次使用时从 LibreYOLO 的 Hugging Face 组织下载。如果你更想直接构建模型,libreyolo 也导出了 LibreUniMatch 类。
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)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 文件。光流任务页面完整介绍了载荷和各种视图。
变体
| 尺寸 | 上游检查点 | 文件 |
|---|---|---|
s | gmflow-scale1-things:1/8 尺度上的全局匹配(先 Chairs,后 Things) | LibreUniMatchs-flow.pt |
l | gmflow-scale2-regrefine6-mixdata:两个尺度、6 步细化的 GMFlow+(规范版本) | LibreUniMatchl-flow.pt |
l | Sintel 微调 | LibreUniMatchl-flow-sintel.pt |
l | KITTI-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。
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 离群率libreyolo val model=LibreUniMatchl-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 | |
| LibreUniMatchs-flow.pt | mit |
| LibreUniMatchl-flow.pt | mit |
| LibreUniMatchl-flow-sintel.pt | mit |
| LibreUniMatchl-flow-kitti.pt | mit |
上面的每个文件目前都在 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 上提供的引用块。