5.10.3. GDC Bin API
5.10.3.1. 模块描述
GDC bin API 用于指导如何生成 GDC bin 文件。
GDC bin API 通过
hbn_gen_gdc_bin_json或者hbn_gen_gdc_bin接口生成 GDC bin，通过hbn_free_gdc_bin释放GDC bin的 buffer。GDC bin API 使用时通常和仿真工具 GDC Tool 结合起来使用， GDC Tool 所有的变换模式生成的
layout.json文件都可以通过GDC Bin API生成 GDC bin文件。
GDC Tool 使用请参考 GDC Tool 介绍 。
操作流程
使用 GDC Bin API 的大致流程：
先使用 GDC Tool 生成 json 后，然后通过
hbn_gen_gdc_bin_json生成 GDC bin 文件，参考示例 generate_bin 。将生成的 GDC bin 文件读取到 hbmem 分配的内存中，然后通过
hbn_vnode_set_attr配置应用到 GDC 节点上。启动 GDC 节点：开始处理图像，通过
dump_2plane_yuv_to_file将处理后的文件保存到文件系统中。处理完成后通过
hbn_free_gdc_bin释放存放 GDC bin 的 buffer。
使用 custom 变换的方式需要提前目标图像并生成标定参数，可以参考示例 custom-config 提前生成标定参数，然后继续上述流程。
5.10.3.2. 参考示例
GDC 部分示例代码可以参考 sample_gdc 章节
5.10.3.3. API 参考
以下 API 用于 GDC BIN 生成， GDC 模块控制 API 见 GDC API。
| API 接口 | 接口功能 |
|---|---|
| hbn_gen_gdc_bin | 使用 window 的方式配置生成一个 gdc bin 文件，并将其存储在 cfg_buf 中，该二进制数据的大小会存储在 cfg_size 中 |
| hbn_gen_gdc_bin_json | 读取一个 JSON 配置文件，解析内容并生成一个二进制的 gdc bin 文件，最后将其写入到指定的文件中 |
| hbn_free_gdc_bin | 释放 hbn_gen_gdc_bin() 或 hbn_gen_gdc_bin_json() 接口分配的存放 gdc bin 的 buffer |
hbn_gen_gdc_bin
【函数声明】
int32_t hbn_gen_gdc_bin(const param_t *gdc_param, const window_t *windows, uint32_t wnd_num, uint32_t **cfg_buf, uint64_t *cfg_size);
【功能描述】
使用 window 的方式生成一个 gdc bin 文件，并将其存储在 cfg_buf 中，该二进制数据的大小会存储在 cfg_size 中。
【参数描述】
[IN] param_t *gdc_parm： gdc 对应参数，包括分辨率，格式等。
[IN] window_t *wnds： gdc 内部区域参数。
[IN] uint32_t wnd_num： window 数目。
[OUT] uint32_t **cfg_buf：生成的 gdc cfg bin，内部分配。
[OUT] uint64_t *cfg_size： gdc cfg bin 文件的大小。
【返回值】
成功： HBN_STATUS_SUCESS 0 。
失败：异常为负值错误码，参考 返回值说明 。
hbn_gen_gdc_bin_json
【函数声明】
int32_t hbn_gen_gdc_bin_json(const char *layout_file, char *config_file, uint32_t **cfg_buf, uint64_t *config_size);
【功能描述】
读取一个 JSON 配置文件，解析其中内容并生成一个二进制的 gdc bin 文件，最后将其写入到指定的文件中。
【参数描述】
[IN] const char *layout_file： json 文件路径，生成 gdc bin 的参数配置。
[IN] char *config_file：指定一个文件路径，用于存放生成的 gdc bin，可为 NULL。
[OUT] uint32_t **cfg_buf：生成的 gdc cfg bin，内部分配。
[OUT] uint64_t *cfg_size： gdc cfg bin 文件的大小。
【返回值】
成功： HBN_STATUS_SUCESS 0 。
失败：异常为负值错误码，参考 返回值说明 。
【兼容性】
硬件： X5
hbn_free_gdc_bin
【函数声明】
void hbn_free_gdc_bin(uint32_t *cfg_buf);
【功能描述】
释放 hbn_gen_gdc_bin() 或 hbn_gen_gdc_bin_json() 接口分配的存放 gdc bin 的 buffer。
【参数描述】
[IN] uint32_t *cfg_buf： gdc bin 的 buffer 地址。
【返回值】
无。
【兼容性】
硬件： X5
5.10.3.4. 数据结构
typedef struct param_t
| 名称 | 类型 | 最小值 | 最大值 | 默认值 | 含义 | 必选 |
|---|---|---|---|---|---|---|
| format | frame_format_t | - | - | - | 处理图像格式 | 是 |
| in | resolution_t | - | - | - | 实际输入图像尺寸 | 是 |
| out | resolution_t | - | - | - | 实际输出图像尺寸 | 是 |
| x_offset | int32_t | 0 | - | 0 | 输入区域沿 x 轴的偏移像素数 | 是 |
| y_offset | int32_t | 0 | - | 0 | 输入区域沿 y 轴的偏移像素数 | 是 |
| diameter | int32_t | 0 | 定义矩形输入图像上包含实际鱼眼照片的输入圆形区域的像素直径。对于某些相机，此圆形图像区域的直径可以大于或小于矩形画布的尺寸（ 有时可能会被裁剪 ）, 一般情况下 diameter 应保持与 input.height 一致 | 是 | ||
| fov | double | 0 | 视场定义输入图像的可视角度，影响源网格的曲率。视场越大 , 透视变形越大 | 是 |
typedef enum frame_format frame_format_t
| 名称 | 类型 | 最小值 | 最大值 | 默认值 | 含义 | 必选 |
|---|---|---|---|---|---|---|
| FM T_UNKNOWN | - | - | - | - | 未知格式 | - |
| FMT_LUMINANCE | - | - | - | - | 暂不支持 | - |
| FMT_PLANAR_444 | - | - | - | - | 暂不支持 | - |
| FMT_PLANAR_420 | - | - | - | - | 暂不支持 | - |
| FMT_SEMIPLANAR_420 | - | - | - | - | nv12 | - |
| FM T_GDC_MAX | - | - | - | - | - | - |
typedef struct resolution_s resolution_t
| 名称 | 类型 | 最小值 | 最大值 | 默认值 | 含义 | 必选 |
|---|---|---|---|---|---|---|
| w | uint32_t | - | - | - | 宽度（ 像素 ） | - |
| h | uint32_t | - | - | - | 高度（ 像素 ） | - |
typedef struct window_t
| 名称 | 类型 | 最小值 | 最大值 | 默认值 | 含义 | 必选 |
|---|---|---|---|---|---|---|
| out_r | rect_t | - | - | - | 输出数据大小信息 | - |
| transform | transformation_t | 0 | 6 | 0 | 使用的转换模式 | - |
| input_roi_r | rect_t | roi 区域 | ||||
| pan | int32_t | 以输出图像为中心的水平方向目标位移（ 像素单位 ） | ||||
| tilt | int32_t | 以输出图像为中心的垂直方向目标位移（ 像素单位 ） | ||||
| zoom | double | 目标缩放系数 | ||||
| strength | double | 1.0 | x 方向变换的非负变换强度参数 | |||
| strengthY | double | 1.0 | y 方向变换的非负变换强度参数 | |||
| angle | double | 0 | 主投影轴绕自身旋转的角度 | |||
| elevation | double | 0 | 指定主投影轴的角度 | |||
| azimuth | double | 0 | 指定主投影轴的角度，从北方向顺时针计数 | |||
| keep_ratio | int32_t | 1 | 在水平方向和垂直方向保持相同的拉伸强度 | |||
| FOV_h | double | 90 | 输出视场的垂直尺寸以度数表示 | |||
| FOV_w | double | 90 | 输出视场的水平尺寸以度数表示 | |||
| cylindricity_y | double | 0 | 目标在垂直方向上的投影形状的圆柱度水平 | |||
| cylindricity_x | double | 0 | 目标在水平方向上的投影形状的圆柱度水平 | |||
| custom_file[128] | char | custom 模式下的自定义转换描述文件 | ||||
| custom | custom_tranformation_t | 自定义模式下的转换信息 | ||||
| trapezoid_left_angle | double | 0 | 梯形底与斜边之间的左锐角 | |||
| trapezoid_right_angle | double | 0 | 梯形底与斜边之间的右锐角 | |||
| check_compute | uint8_t | 暂时无用 |
typedef struct rect_s rect_t
| 名称 | 类型 | 最小值 | 最大值 | 默认值 | 含义 | 必选 |
|---|---|---|---|---|---|---|
| x | int32_t | - | - | - | 起始点 x 坐标，必须是偶数 | - |
| y | int32_t | - | - | - | 起始点 y 坐标，必须是偶数 | - |
| w | int32_t | 宽度，必须是偶数 | ||||
| h | int32_t | 高度，必须是偶数 |
typedef enum gdc_transformation transformation_t
| 名称 | 类型 | 最小值 | 最大值 | 默认值 | 含义 | 必选 |
|---|---|---|---|---|---|---|
| PANORAMIC | - | - | - | - | 全景变换 | |
| CYLINDRICAL | - | - | - | - | NA | |
| STEREOGRAPHIC | - | - | - | - | 畸变校正与全景变换相同，但输出图像是圆柱全景图，而不是平面图。 | |
| UNIVERSAL | - | - | - | - | Equidistant 等距变换 | |
| CUSTOM | - | - | - | - | 用户定制的变换，可定制用于变换的网格 | |
| AFFINE | - | - | - | - | 线性变换 | |
| DEWARP_KEYSTONE | - | - | - | - | 相对于等距变换，可以选择非等距，等距变换 equidistant 只是它特殊参数的一种 |
typedef struct point_s point_t
| 名称 | 类型 | 最小值 | 最大值 | 默认值 | 含义 | 必选 |
|---|---|---|---|---|---|---|
| x | double | - | - | - | x 坐标 | - |
| y | double | - | - | - | y 坐标 | - |
typedef struct custom_tranformation_s custom_tranformation_t
| 名称 | 类型 | 最小值 | 最大值 | 默认值 | 含义 | 必选 |
|---|---|---|---|---|---|---|
| full_tile_calc | uint8_t | - | - | - | 是否开启分块计算；如果使能 fulltile， libgdcbin 会额外分块做 min max 计算， tile 分块越多，精度越高，效果越好，同时生成 bin 的时间越长 | - |
| tile_incr_x | uint16_t | - | - | - | tile increase in x | - |
| tile_incr_y | uint16_t | - | - | - | tile increase in y | - |
| w | int32_t | 自定义转换网格中水平方向上的数字或点 | ||||
| h | int32_t | 自定义转换网格中垂直方向的数字或点 | ||||
| centerx | double | center along x axis，通常是水平方向坐标点数的 2 分之一 | ||||
| centery | double | center along y axis，通常是垂直方向坐标点数的 2 分之一 | ||||
| *points | point_t | config.txt 转换序列，数量 = w*h |