# GDC Bin API

## 模块描述

- 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 介绍 ](../multimedia_development/8.2-GDC_Tool_zh_CN.html)。

### 操作流程

使用 GDC Bin API 的大致流程：

1. 先使用 GDC Tool 生成 json 后，然后通过``hbn_gen_gdc_bin_json``生成 GDC bin 文件，参考示例[ generate_bin ](../samples/sample_gdc.html#generate_bin )。
2. 将生成的 GDC bin 文件读取到 hbmem 分配的内存中，然后通过``hbn_vnode_set_attr``配置应用到 GDC 节点上。
3. 启动 GDC 节点：开始处理图像，通过``dump_2plane_yuv_to_file``将处理后的文件保存到文件系统中。
4. 处理完成后通过``hbn_free_gdc_bin``释放存放 GDC bin 的 buffer。

使用 custom 变换的方式需要提前目标图像并生成标定参数，可以参考示例 [ custom-config ](../samples/sample_gdc.html#custom-config)提前生成标定参数，然后继续上述流程。

## 参考示例

- GDC 部分示例代码可以参考 [sample_gdc](../samples/sample_gdc.html)  章节

## API 参考

以下 API 用于 GDC BIN 生成， GDC 模块控制 API 见 [ GDC API](../multimedia_development/8.3-GDC_API_zh_CN.html)。

| API 接口                        | 接口功能                      |
|---------------------------------|------------------------------|
[hbn_gen_gdc_bin](#hbn_gen_gdc_bin)| 使用 window 的方式配置生成一个 gdc bin 文件，并将其存储在 cfg_buf 中，该二进制数据的大小会存储在 cfg_size 中 |
[hbn_gen_gdc_bin_json](#hbn_gen_gdc_bin_json)| 读取一个 JSON 配置文件，解析内容并生成一个二进制的 gdc bin 文件，最后将其写入到指定的文件中 |
[hbn_free_gdc_bin](#hbn_free_gdc_bin)| 释放 hbn_gen_gdc_bin() 或 hbn_gen_gdc_bin_json() 接口分配的存放 gdc bin 的 buffer |

<span id="hbn_gen_gdc_bin"/> </span>


### hbn_gen_gdc_bin

#### 【函数声明】

```c
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 。

- 失败：异常为负值错误码，参考 [ 返回值说明 ](./1-HBN_API_zh_CN.html#return_val)。

<span id="hbn_gen_gdc_bin_json"/> </span>

### hbn_gen_gdc_bin_json

#### 【函数声明】

```c
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 。

- 失败：异常为负值错误码，参考 [ 返回值说明 ](./1-HBN_API_zh_CN.html#return_val)。

#### 【兼容性】

硬件： X5

<span id="hbn_free_gdc_bin"/> </span>

### hbn_free_gdc_bin

#### 【函数声明】

```c
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

## 数据结构

**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 |      |

