J5 DVB实战教程（7）-基于J5芯片的GDC GUI TOOL工具使用说明

1. GDC GUI TOOL 工具介绍

GDC GUI TOOL 是一种可在 PC 上进行处理效果仿真的工具。用户可准备 jpg 模式的图像，load 到 gdc-tool 中进行离线校正，校正完成后可以直接保存 config.bin 文件用于硬件校正，也可用保存 layout.json 文件生成 config.bin 进行硬件校正。

2. gdc-tool 安装

2.1 Windows 环境

• 列表项列表项下载 nodejs 并安装。
  下载链接：https://nodejs.org/en/download/
• 安装组件。
  打开 Win 命令行并执行：

• 解压gdc-tool-gui-0.23-76-windows.zip

• 打开Win命令行，到gdc-tool-gui-0.23-76-windows目录下，安装express
  npm install express
• 运行app.js
  node app.js
• 启动浏览器，打开http://localhost:3000/

  2.2 Linux环境（Ubuntu）

• 安装nodejs。
  sudo apt install nodejs -y
• 安装nodejs包管理器npm
  sudo apt install npm -y
• 解压gdc-tool-gui-0.23-76-linux.zip
  unzip gdc-tool-gui-0.23-76-linux.zip
• 进入gdc-tool-gui-0.23.76-linux目录
  cd gdc-tool-gui-0.23-76-linux
• 安装express包
  npm install express
• 运行app.js
  node app.js
• ubuntu中用浏览器打开http://localhost:3000/

3. gdc-tool启动

• window 环境u3000u3000
  启动应用：在 win 命令行进入文件目录（如 gdc-tool-gui-xxxx-windows），执行 node app.js，Chrome 浏览器登陆 http://localhost:3000/
  
• linux 环境u3000
  启动应用：执行 node app.js，登陆 http://localhost:3000/
  

  4. gdc-tool使用说明

  4.1 GUI TOOL中的变换模式

  GUI 中的变换模式有 Affine, Equisolid, Equisolid(cylinder), Equidistant, Custom, Keystone+dewarping 六种变换供选择
  下表是各个变换的用途：

  变换模式	用途
  Affine	一种线性变换，简单的图像翻转功能，没有畸变校正
  Equisolid	全景变换
  Equisolid(cylinder)	圆柱形变换
  Equidistant	等距变换，变换后的距离等距。
  Custom	用户定制变换
  Keystone+dewarping	相对于等距变换，可以选择非等距，等距变换equidistant只是它特殊参数的一种

• Affine
  功能描述：提供线性的变换。
  
  成员说明：

  成员	含义
  int32_t pan	default 0, 不修改
  int32_t tilt	default 0, 不修改
  zoom	按提供的因子缩放转换输出
  double angle(rotation)	0/90/180/270

  Note：输入输出尺寸的宽应保持 16 字节对齐。

• Equisolid
  功能描述：此转换提供等实体（全景 panoramic）校正，并将结果显示为平面上的投影。
  
  成员说明：

  成员	含义
  int32_t pan	default 0, 不修改
  int32_t tilt	default 0, 不修改
  zoom	按提供的因子缩放转换输出
  double strength	沿X轴的变换强度（非负参数）
  double strengthY	沿Y轴的变换强度（非负参数）
  double angle(rotation)	0/90/180/270

  Note：输入输出尺寸的宽应保持 16 字节对齐。

  strength x 调试效果，在 X 轴的转换强度，取值(0, +∞)。如下所示：
  
  strength y 调试效果，在 Y 轴的转换强度，取值(0, +∞)。如下所示：
  
  Rotation 调试效果，取值(-180, 180)。如下所示：
  
• Equisold(cylinder)
  功能描述：此变换为将结果图像投影到柱面全景图的完整鱼眼帧提供等实体校正。
  
  成员说明：

  成员	含义
  int32_t pan	default 0, 不修改
  int32_t tilt	default 0, 不修改
  zoom	按提供的因子缩放转换输出
  strength	转换的强度
  double angle(rotation)	0/90/180/270

  Note：输入输出尺寸的宽应保持 16 字节对齐。
  strength 调试效果，转换的强度（0，+∞)。如下所示：
  
  rotation 调试效果，取值范围（-180,+180)。如下所示：
  
• Equidistant
  功能描述：等距变换包含许多参数，这些参数允许它为投影提供一系列不同的目标平面。这使用户可以更自由地选择要变换的鱼眼帧的所需区域。
  
  成员说明：

  成员	含义
  int32_t pan	default 0, 不修改
  int32_t tilt	default 0, 不修改
  zoom	按提供的因子缩放转换输出
  double angle(rotation)	0/90/180/270
  double elevation	定义了投影轴的倾斜度
  double azimuth	定义了投影轴的旋转角度。当此参数旋转轴而不是栅格时，如果“仰角”为0，则“方位角”将没有可见效果
  int32_t keep_ratio	当“保持比率”参数打开时，FOV高度参数将被忽略，其值将自动计算，以在水平和垂直方向上保持相同的拉伸强度
  double FOV_h	描述垂直维度中输出视图字段的大小（以度为单位）。有效值的范围是从0到180
  double FOV_w	描述垂直维度中输出视图字段的大小（以度为单位）。有效值的范围是从0到180
  double cylindricity_y	描述目标投影沿Y轴的球面度。此值从0到1，其中1是球形的。如果此值设置为1，而“圆柱度X”值设置为0，则投影将沿Y轴形成圆柱体
  double cylindricity_x	描述目标投影沿X轴的球面度。此值从0到1，其中1是球形的。如果此值设置为1，并且“圆柱度Y”值设置为0，则投影将沿X轴形成圆柱体。

  Note1 : 输入输出尺寸的宽应保持 16 字节对齐。
  Note2: 正常的视力值大约是 90 度。对于圆柱度（见下文）等于“0”的变换，视场宽度和高度 180 的值将导致图像无限拉伸。
  Note3: 如果 cylindricity_x 和 cylindricity_y 圆柱度值都设置为 1，则投影将是球形的。如果两者都是 0，则变换将是矩形的
  elevation 调试效果:
  
  azimuth 调试效果:
  
  rotation 调试效果:
  
  cylindricity x 调试效果：
  描述目标投影沿 X 轴的球形。该值的范围为 0 到 1，其中 1 为球形。如果该值设置为 1，圆柱度 Y 值设置为 0，则投影将沿 X 轴形成圆柱。如下所示：
  
  cylindricity y 调试效果
  描述目标投影沿 Y 轴的球形程度。该值的范围为 0 到 1，其中 1 为球形。如果该值设置为 1，圆柱度 X 值设置为 0，则投影将沿 Y 轴形成一个圆柱体。如下所示：
  
• Custom
  功能描述：采用 custom 变换后，输入图像中的每个多边形都会变换为正方形。换句话说，任何形状的任何四个邻近输入点在转换后都是正方形，如下图所示。但是，多边形的形状和位置在变换后会发生变化。
  
  它们用于创建任何提供的转换都无法描述的转换。为了纠正任意失真，必须向 GDC 工具提供一个特殊的校准文件。如下图 config0.txt：
  
  成员说明：

  成员	含义
  int32_t pan	见2.3.1.1
  int32_t tilt	见2.3.1.2
  zoom	按提供的因子缩放转换输出
  char custom_file[128]	config.txt文件名称
  custom_tranformation_t custom	解析的自定义转换结构

  config.txt解释：
  Config file 的规则大致需要注意一下几点：

  1. 第一行是 full tile calculation 标志位，目前暂未使用到。

  2. 第二行是第一行相应的 x，y 方向的参数，目前暂未使用到。

  3. 第三行是垂直方向和水平方向标定点的个数， 7 指的是垂直方向有 7 个标定点，28 指的是水平方向有 28 个标定点

  4. 第四行 3 和 13.5 是选中区域的中心点，通常是垂直方向标定点 (Y-1)/2 和水平方向标定点(X-1)/2。
     eg.下图是我截取的其中的一部分数据图片，第三行到第九行就是标定点在源图的坐标值，格式是 Y: X。以下图为例， 一共有 7x28 个标志点。
     Config.txt 的内容如下：
     
  5. 由于标定点必须是等距离的，这意味着输出图片的分辨率取决于标志点的点数。
     (Size X)/(Size Y)=(Number of X points-1)/(Number of Y points-1)
     eg. 输出图片的 Width = 1280， Height 的计算如下：1280/Height = (28-1)/(7-1), height = 284
     下图是更简单的 3x3 坐标点转换的示例图：
     
     GDC custom mode 对 input point 的坐标的要求：
     （1）必须是正的 int 或者 float type；
     （2）尽量保持同一行里面的采样点是平滑过渡的，如果某两点之间过渡急剧变化，样条线的精度将不足以处理它；
     （3）不能相邻两行采样点重复；
     （4）不能 4 个采样点组成三角形,尽量避免相邻点坐标重；
     （5）如果采样精度不足（可能导致锯齿，扭曲等情况）：
     a.使用浮点坐标；
     b.增加采样点；
     （6）output 最小支持的 size 是 100x100。
• Keystone+dewarping
  功能描述：
  
  成员说明：

  成员	含义
  int32_t pan
  int32_t tilt
  zoom	按提供的因子缩放转换输出
  double angle(rotation)	旋转的角度
  double elevation	定义了投影轴的倾斜度
  double azimuth	定义了投影轴的旋转角度。当此参数旋转轴而不是栅格时，如果“仰角”为0，则“方位角”将没有可见效果
  int32_t keep_ratio	当“保持比率”参数打开时，FOV高度参数将被忽略，其值将自动计算，以在水平和垂直方向上保持相同的拉伸强度
  double FOV_h	描述垂直维度中输出视图字段的大小（以度为单位）。有效值的范围是从0到180
  double FOV_w	描述垂直维度中输出视图字段的大小（以度为单位）。有效值的范围是从0到180
  double cylindricity_y	描述目标投影沿Y轴的球面度。此值从0到1，其中1是球形的。如果此值设置为1，而“圆柱度X”值设置为0，则投影将沿Y轴形成圆柱体
  double cylindricity_x	描述目标投影沿X轴的球面度。此值从0到1，其中1是球形的。如果此值设置为1，并且“圆柱度Y”值设置为0，则投影将沿X轴形成圆柱体。
  double trapezoid_left_angle	默认90；0.1到90 ；见实际效果
  double trapezoid_right_angle	默认90；0.1到90 ；见实际效果

4.2 变换模式的基本参数效果

所有转换类型都有以下三个常用参数（举例：等距变换，输入/输出分辨率 1280x720）： 以下输出图像中的蓝色矩形表示仅将特殊参数设置为该值， 并且一个转换中的其他参数保持默认值。

• Pan 调试效果
  水平方向 (-1280, +1280) 通过给定的像素数，偏移变换网格。如下所示：
  
• Tile调试效果
  垂直方向 (-720, +720) 通过给定的像素数，偏移变换网格。如下所示：
  
• Zoom调试效果
  按提供的因子 (0, +∞) 缩放变换输出，*(0, 1) 表示值大于 0 且小于 1。如下所示：
  

  5. 配置文件说明

  5.1 配置文件参数

  配置文件可由 gdc tool 生成，以 layout.json 存在。以输入 1080p-输出 1080p（Custom 模式除外） 为例，说明各种模式下配置的参数：
  Note 1: j5 ecc mode 统一填写 ecc is disable。GUI 可选 ecc mode 使能，但没有实际效果。
  Note 2: 当参数为小数时，保证精度为浮点运算以后 8 位小数及以上，否则可能生成的 bin 不一致。
  Note 3: 用户填充数据结构或者 json 时填充的信息应该包含各种模式示例所有项。
  Note 4: 配置文件中的 roi 参数代表输入图片的 roi。
  Note 5: 配置文件中的 position 参数代表输出图片的 roi。

5.2 配置文件示例

• Affine
  配置文件内容如下：
  
  输入图片加变换网格如下：
  
  输出图片如下：
  
• Equisolid
  配置文件内容如下：
  
  输入图片加变换网格如下：
  
  输出图片如下：
  
• Equisolid(cylinder)
  配置文件内容如下：
  
  输入图片加变换网格如下：
  
  输出图片如下：
  
• Equidistant
  配置文件内容如下：
  
  输入图片加变换网格如下：
  
  输出图片如下：
  
• Custom
  输入 1280x720，输出 560x258。配置文件内容如下：
  
  需要配备 config.txt 一起使用,如上图的/app/bin/vps/vpm/res/camera_0_gdc_config_3.1.txt。
  输入图片加变换网格如下：
  
  输出图片如下：
  
• Keystone+dewarpin
  配置文件内容如下
  
  输入图片加变换网格如下：
  
  输出图片如下：