# hbplayer 和 tuning_tool 工具使用指南

## hbplayer

hbplayer 是一个 Windows 应用程序，通过 HTTP 协议向主机发送请求并获取板端传输的图像数据。此应用程序的主要功能包含：

- 图像数据的实时显示

- 图像数据离线显示分析

![hbplayer_main](media/Hobot_Player_User_Guide/hbplayer_main.png)

### hbplayer 安装及配置

**安装：**

当前软件版本为 `v3.4.4`，安装步骤如下：

1. 从 SDK 交付包的 `software_tools/hobotplayer` 目录下获取 `x5_hbplayer_v3.4.4.zip` 压缩包，解压后的目录如下图
2. 进入解压路径，双击运行 out 目录下的 `hbplayer.exe`，即可打开主页面，如下图所示：

![dir_list](media/Hobot_Player_User_Guide/dir_list.png)

**网络配置：**

1. 点击左上角图标，在 `dynamic_init_config` 对话框中输出板端 IP 地址。板端的 IP 可以通过下面的方式进行配置和查询，进入到板端执行 ifconfig，查看下板端的 IP 地址并填写到 dynamic_init_config 输入框中。
2. 点击 `Apply`， 完成客户端 IP 配置

### hbplayer 主界面

![hbplayer_main2](media/Hobot_Player_User_Guide/hbplayer_main2.png)

| 编号 | 说明                        | 备注                                      |
| ---- | --------------------------- | ----------------------------------------- |
| 1    | 设备 IP 和端口号             | 端口号一般情况下不修改                    |
| 2    | 设置 online 模式 raw 的 pack 方式 | NA                                        |
| 3    | 配置 raw 图 msb/lsb 类型        | msb 为高位对齐， lsb 为低位对齐              |
| 4    | 打开配置页面                | NA                                        |
| 5    | 网络传输链接 / 断开链接       | dynamic-displayer 模式下，连接板侧 server. |
| 6    | 查看 raw 图，最多支持 dol4     | 传输 RAW 时可用                             |
| 7    | 保存 raw/yuv 图像信息        | 先设置保存的数量，然后再点击 enable        |
| 8    | 保存 yuv 图像信息为 bmp/jpg   | 该项支持单张图像保存，格式转换使用 opencv  |
| 9    | 配置信息保存                | 配置信息保存后才可以生效                  |
| 10   | raw_type 类型               | 支持不同 pattern 的 rggb 格式                 |

**hbplayer 静态图像查看功能说明**

hbplayer 工具支持多种格式（ raw/yuv/bmp/jpg ）的静态图像查看，并提供便捷的参数配置与操作功能。以下为操作步骤及注意事项：

**操作步骤（如下图所示）：**

1. **选择功能模块**
   点击图标 **1（static-display）** 进入静态图像查看功能界面。
2. **配置图像参数**
   点击图标 **2（fileconfig）** 进行参数配置。根据需要填写图像的具体参数（例如分辨率、格式等），完成后点击 **Apply** 保存配置。
3. **选择并显示图像**
   点击图标 **3**，选择要查看的图像文件，图像即会显示在界面中。
4. **图像缩放**
   在查看图像时，可按 **Ctrl + 滚轮** 对图像进行放大或缩小操作。

**配置选项说明：**

配置选项的详细说明请参考下方表格，确保参数填写正确以获得最佳查看效果。

**注意事项：**

- **raw/yuv 图像查看**
  打开 **raw** 或 **yuv** 格式图像时，必须正确配置图像的具体参数（例如宽度、高度、像素格式等）。参数错误将导致图像无法正确打开或显示异常。
- **raw preview 与 save_raw 功能**
  若需使用 **raw preview** 或 **save_raw** 功能，请确保以下条件：
  - **tuning_tool** 已发送 **raw 数据**。
  - 在 **hbplayer** 工具端启用 **raw_en** 功能。

![hbplayer_static_config](media/Hobot_Player_User_Guide/hbplayer_static_config.png)

| 编号 | 说明                          | 备注                                                         |
| ---- | ----------------------------- | ------------------------------------------------------------ |
| 1    | 切换静态图像显示 / 动态传输显示 | 在 static-display 模式下支持静态图像，在 dynamic-display 模式下支持显示数据流。 |
| 2    | 配置打开图像的信息            | 只支持框体中可选择的项，图像信息与实际图像不符合显示会异常   |
| 3    | 显示图像的大小信息            | 打开需要显示的文件                                           |

查看静态参数需要配置相应的图像参数，图像参数配置说明如表所示。

| pic_type | 该字段设置需要打开的图像类型                                 |
| -------- | ------------------------------------------------------------ |
| raw_type | 该字段设置 raw 图是 pack 还是 unpack 类型。 unpack 以 uint16_t 数据类型保存一个 pixel。 |
| yuv_type | yuv_nv12                                                     |
| width    | 图像宽度                                                     |
| height   | 图像高度                                                     |
| stride   | pic_raw 时使用，主要用于 pic_raw 每行后有若干 nop 字符填充。 |

hbplayer 查看静态图像时支持简单的图像显示调整功能。点击图标打开 calculation 显示并输入相应的参数，点击 enable 即可对图像进行简单调整。

![hbplayer_cal](media/Hobot_Player_User_Guide/hbplayer_cal.png)

**提示：**

- 通过鼠标滚轮或者 zoom 窗口，可以实现图像缩放。建议放大倍数不要超过 10 倍，否则对于图像缩放处理会变的较慢。

## tuning_tool

该程序主要为了调试图像质量而开发，所以数据流只跑到了 ISP，并且默认跑 SIF passthrough ISP 模式。

脚本位置：/app/platform_samples/tuning_tool/run_tuning.sh 建议通过 ssh 窗口运行，否则打印太多，不易分辨 tuning_tool 的打印。

### 运行方法

直接执行程序 `bash run_tuning.sh --help` 可以获得帮助信息：

#### 程序参数选项说明

```bash
bash run_tuning.sh --help
run_tuning.sh --list: list all case
run_tuning.sh --run [sensor_index]: run this sensor
run_tuning.sh --online/offline/mcm/: Open the data stream in online/offline/mcm/ mode
run_tuning.sh --tune 0/1: close/open tuning_server
run_tuning.sh --log 0/1: increase/decrease log level in logcat
run with [-w 2]: dump 20 yuv from the start
run with [-r 1]: send raw to hbplayer
run with [-f xx]: feedback raw list xx times
```

**选项：**

- `--list`：列出当前脚本支持的 sensor 列表
- `--run [sensor_index]` ：按照列表中的编号，运行对应的 sensor,支持 `--run x x`运行多路显示,带宽上建议不超过1920*1080 60fps
- `--online/offline/mcm/`：指定使用 online/offline/mcm 其中的一种模式去跑pipeline，默认使用offline
- `--tune 0/1`：使能或者关闭板端 vtuner server，用于连接 vtuner
- `--log`：修改 isp 的打印级别
- `-w 2`： dump 启流后的前 20 帧数据
- `-r 1`： 发送 yuv 数据的同时，也会发送 raw 数据给 hbplayer
- `-f, --feedback`：使用 feedback 去回灌isp

#### 使用步骤

**ISP tuning使用：**

- 1.执行`bash run_tuning.sh --list`查看当前支持的 sensor 列表，运行效果如下：

   ```bash
   # bash run_tuning.sh --list
   index: 0  sensor_name: sc1330t                  config_file:linear_1280x960_raw10_30fps_1lane.c
   index: 1  sensor_name: irs2875-tof              config_file:linear_208x1413_raw12_15fps_2lane.c
   index: 2  sensor_name: sc230ai-10fps            config_file:linear_1920x1080_raw10_10fps_1lane.c
   index: 3  sensor_name: sc230ai-30fps            config_file:linear_1920x1080_raw10_30fps_1lane.c
   index: 4  sensor_name: sc132gs-1280p            config_file:linear_1088x1280_raw10_30fps_1lane.c
   index: 5  sensor_name: sc035hgs                 config_file:linear_640x480_raw10_30fps_1lane.c
   index: 6  sensor_name: ov5640                   config_file:linear_1920x1080_raw10_30fps_2lane.c
   index: 7  sensor_name: f37                      config_file:linear_1920x1080_raw10_30fps_1lane.c
   index: 8  sensor_name: imx415-30fps-2lane       config_file:linear_3840x2160_raw10_30fps_2lane.c
   index: 9  sensor_name: imx415-30fps-4lane       config_file:linear_3840x2160_raw10_30fps_4lane.c
   index: 10  sensor_name: sc202cs-1600x1200       config_file:linear_1600x1200_raw10_30fps_1lane.c
   index: 11  sensor_name: irs2381c-tof            config_file:linear_224x1903_raw12_5fps_2lane.c
   index: 12  sensor_name: sc035hgs-vc0            config_file:linear_640x480_raw10_30fps_2lane_vc0.c
   index: 13  sensor_name: sc035hgs-vc1            config_file:linear_640x480_raw10_30fps_2lane_vc1.c
   index: 14  sensor_name: sc231ai-30fps           config_file:linear_1920x1080_raw10_30fps_2lane.c
   index: 15  sensor_name: imx586-30fps-4lane      config_file:linear_3840x2160_raw10_30fps_4lane.c
   index: 16  sensor_name: os08c10-30fps-2lane     config_file:linear_3840x2160_raw12_30fps_2lane.c
   index: 17  sensor_name: ar0233-30fps            config_file:linear_1920x1080_raw12_30fps_2lane.c
   index: 18  sensor_name: ar0820std-30fps         config_file:linear_3840x2160_yuv422_30fps_4lane.c
   index: 19  sensor_name: sc1336                  config_file:linear_1280x720_raw10_15fps_2lane.c
   index: 20  sensor_name: dummy                   config_file:dummy_sensor.c
   ```

- 2.以 sc230ai-30fps 为例，对应 index 为 3，执行`bash run_tuning.sh --run 3`进入交互模式，日志如下：

   ```bash
   # bash run_tuning.sh --run 3
   Executing: ./isp_tuning --offline -s sensor=3
   Offline mode enabled!!!
   Using index:3  sensor_name:sc230ai-30fps  config_file:linear_1920x1080_raw10_30fps_1lane.c
   [INFO] board_id is 0x0202, not need skip sci1.
   mipi mclk is configed.
   Searching camera sensor on device: /proc/device-tree/soc/cam/vcon@0 i2c bus: 4 mipi rx phy: 0
   INFO: Found sensor_name:sc230ai-30fps on mipi rx csi 0, i2c addr 0x30, config_file:linear_1920x1080_raw10_30fps_1lane.c
   Pipeline index 0:
         Sensor index: 3
         Sensor name: sc230ai-30fps
         Use mipi host: 0
   start_hbplayer_thread start success. pid 281473319076096
   create_socket_listen---176, listern 0xffff98001410
   create a listener, port is 10086
   create_socket_event---201, t_base 0x1ffc7080 event base is 0xffff98000c70, listener 0xffff98001410
   start_dump_server_thread start success.
   ```

- 3.连接 X5 hbplayer，tuning_tool 默认发送 yuv 给 hbplayer，启流后可以去 hbplayer 点击 connect，实时 preview 图像。想要结束时，按【q】键，然后回车即可。

   ![dir_list](media/Hobot_Player_User_Guide/hbplayer_connect.png)

**回灌使用：**

- dummy senor 只用于回灌，默认指定回灌 1920X1080 raw10 的图像，将要回灌的图像放到当前目录下，执行 `bash run_tuning.sh --run 20` 即可回灌。
- 使用其他分辨率的图像回灌时，步骤如下：
   - 1.修改 `run_tuning.sh` 中的 FEEDBACK_IMG_H、FEEDBACK_IMG_W 和 RAW_FORMAT。
   - 2.同时需要同步修改效果库 `dummy_tuning.json` 中的对应的分辨率才可以正常回灌。

### 功能

按【h】键回车，会提示当前支持的功能。

#### dump raw

该功能从 sif dump raw 数据。

运行起来后，按【s】键回车，会提示输入想到 dump 图像的数量，再按回车即可 dump 对应时刻的 raw 图，文件会保存到 /userdata 下。

#### dump yuv

运行起来后，按【y】键回车，会提示输入想到 dump 图像的数量，再按回车即可 dump 对应时刻的 yuv 图，文件会保存到 /userdata 下。

默认将图像保存到同一文件中，使用 yuvplayer 等工具可以连续查看图像。

#### dump raw and yuv

这个功能主要用于查看当前 连续的 raw 图 和 yuv 图对应的 isp 信息，一般用于 ISP 评估。

- 支持RAW + AE Info、RAW + YUV + AE Info、YUV + AE Info三种dump方式
- 自动计算当前内存文件系统 /tmp 支持的最大帧数，超过最大帧按照最大帧dump

运行起来后，按【a】键回车，会自动计算提示输入想 dump 图像的数量，再按回车即可 dump 对应时刻的 raw 和 yuv 图 和 AE 信息文件 AE_INFO.txt，文件会保存到内存文件系统 /tmp 下。

默认将图像保存到同一文件中，使用 yuvplayer 等工具可以连续查看图像。

<div class="note">
<strong> 注意：</strong> <br>
   1. 由于 X5 的 VIN 与 ISP 通过 pipeline 绑定，ISP 处理需要时间，因此在动态场景下dump下的raw和yuv帧id可能会偏移，观察效果时只需保证raw和yuv图像的时间戳与帧 ID 一致即可。 <br>
</div>

#### 其他功能

其他类似 AE AWB 3DNR 的功能大多对应 get set 两个功能， get 为获取当前的参数， set 为配置一些参数给 ISP，但一些模块参数较多，不方便输入参数，因此并没有实现
