地平线 VP 接口工程实践（一）：hbVPRoiResize 接口功能、使用约束与典型问题总结

一、写在前面：为什么要写这篇文章

在 BPU 推理链路中，VP（Vision Pipeline）承担了大量图像前处理工作，例如裁剪、缩放、颜色格式转换等。
相比普通的软件图像处理接口，VP 接口直接面向硬件，性能优势明显，但也引入了严格且隐含的使用约束。

在实际项目中，hbVPRoiResize 是一个非常常用的接口，同时也是一个非常容易踩坑的接口。
本文基于一次真实的客户问题排查过程，对 hbVPRoiResize 的：

接口功能定位
ROI 与缩放比例的计算规则
YUV 场景下的关键约束
典型报错的根因与修正方式

进行一次工程化的系统整理，希望为后续遇到类似问题的开发者提供可直接参考的经验。

二、hbVPRoiResize 接口是做什么的

从功能上看，hbVPRoiResize 用于：

从输入图像（src）中指定一个 ROI 区域
对该 ROI 进行 等比例缩放
输出到目标图像（dst），必要时自动进行 padding

需要注意的是：

hbVPRoiResize 并不是一个“自由裁剪 + 任意 resize”的接口
它是一个严格受硬件约束的 ROI 等比缩放接口

这也是后续很多问题产生的根源。

三、ROI 的定义与有效区域计算

接口中使用的 ROI 一般定义为：

在实际处理时，VP 会先对 ROI 做一次 与原始图像 src 的交集裁剪，保证：

ROI 不越界
ROI 的有效宽高由交集区域决定

因此，传入的 ROI 参数并不一定就是最终参与计算的 ROI，但在不越界的情况下，两者通常一致。

四、等比例缩放的计算规则（核心逻辑）

hbVPRoiResize 只支持等比例缩放，其缩放比例的计算规则为：

分别计算宽、高方向的缩放比例：
选择较小的比例作为最终 scale：
一个方向会被完整填满，另一个方向不足的部分通过 padding 补齐

这一点非常关键：

不能人为指定非等比缩放，也不能单独控制 padding 行为
所有结果都由 scale 自动推导

五、YUV 场景下的关键使用约束

当输入或输出图像为 YUV（尤其是 NV12 / YUV420） 时，VP 接口会引入额外的硬件约束，这些约束往往是问题的根因：

1. 尺寸偶数约束

src / dst 的 width 和 height 必须是偶数
ROI 的宽高也需要满足对应的偶数要求

2. Padding 对齐约束（极易被忽略）

在 YUV 场景下：

dst 图像在 padding 方向（top+bottom 或 left+right）的总 padding 必须是 4 的倍数

这不是算法层面的要求，而是 VP 内部处理 Y/UV 子采样与硬件 block 对齐的结果。

六、一次典型问题的完整复盘

1. 问题现象

客户在调用 hbVPRoiResize 时遇到如下报错：

UCP 提交任务失败，返回错误码 -200004。

2. 输入参数

假设原始图像宽度为 3840，高度足够覆盖该 ROI。

3. 参数推导过程

ROI 宽度：
ROI 高度：
宽方向缩放比例：
高方向缩放比例：
最终 scale：
缩放后的 ROI 高度（内部取整后）：
需要的 padding 高度：

4. 为什么会报错

关键在于这一点：

在 YUV 场景下，VP 要求 上下 padding 的总高度必须是 4 的倍数。
当前参数组合下，padding_h = 75，不满足该约束，因此：

VP 判定 ROI scale 非法
任务参数校验失败
UCP 无法创建 taskHandle
后续访问 taskHandle 触发空指针报错

七、问题的修正思路（工程经验）

在不改变整体逻辑的前提下，通常有两类可行修正方式：

1. 微调 ROI（最推荐）

通过调整 ROI 的 top 或 bottom，使得：

例如，将 ROI 高度从约 1512 调整为 1516：

此时：

scaled_h ≈ 404
padding_h = 480 - 404 = 76
76 % 4 == 0，满足约束

2. 调整 dst 尺寸

如果输出尺寸可控，也可以通过调整 resize_height 使 padding 满足 4 的倍数约束（同时仍需满足偶数要求）。

八、示例工程说明

本文对应的示例工程包含：

ROI + Resize 调用示例
YUV 图像输入构造
VP 接口调用流程
交叉编译并在 ARM 端运行

工程文件结构包括：

main.cc
CMakeLists.txt
build.sh

示例代码可作为 最小可运行参考，用于验证 ROI、scale 与 padding 的关系。

（示例工程可通过链接获取：roi_resize_sample.tar.gz

九、小结

通过这次问题排查可以看到：

hbVPRoiResize 的报错往往不是接口 bug，而是参数组合违反硬件约束
ROI、scale、padding 三者是强相关的
在 YUV 场景下，padding 为 4 的倍数是一个必须显式考虑的工程约束

理解这些规则后，类似的 error -200004 问题可以在参数层面快速定位和解决。