ir_auto 快速入门
1. 概述与作用
在光照条件不好（如夜晚）的场景，白天使用的滤光片成像效果不好，需要切换到红外滤光片，提升成像效果。本样例介绍如何实现自动切换滤光片的功能。
专业名词与缩写：
- IR — Infrared，红外光，用于夜视补光
- IR-CUT — 红外滤光片切换器，通过 GPIO 控制开/关
- ISP — Image Signal Processor，图像信号处理器
- AE — Auto Exposure，自动曝光
- AWB — Auto White Balance，自动白平衡
- WB Rgain/Bgain — 白平衡 R/G 与 B/G 增益比，用于判断 IR 场景
- ISO — 感光灵敏度量化值，本 sample 用 ISO 阈值切换 normal/IR
- CCM — Color Correction Matrix，色彩校正矩阵，IR 模式下设为对角矩阵使饱和度为 0
- VPSS / VENC / VI / GPIO — 视频处理/编码/输入/通用 IO
2. 执行准备
在编译本样例之前，请参照Hi3516CV610环境搭建指南和快速上手指南完成编译环境的搭建。
2.1 编译
进入样例目录执行 make 即可完成编译：
编译成功之后，在当前目录下会生成一个sample_ir_auto的可执行文件，可以放社区支持的开发板上运行。
2.2 加载 KO
ko加载脚本位于 output/mpp/ko/load_ko，有两个脚本，load3516cv610_20s和load3516cv610_20s_debug。区别为load3516cv610_20s_debug脚本会打开 logmpp_show=1（日志记录）、proc_show=1（proc信息打印），并将 mem_process_isolation 置为 0（不启用进程间mmz隔离）。
由于当前版本不支持进程间mmz隔离，因此需要在load3516cv610_20s脚本中将 mem_process_isolation 置为 0或者使用load3516cv610_20s_debug脚本，此处以load3516cv610_20s_debug脚本为例，20s内存大小为128MB，默认分配为 32MB OS、96MB MMZ，加载命令为：
必须带 -ir_auto 1，可以通过-h命令查看具体用法：
./load3516cv610_20s_debug -h
Usage: ./load3516cv610_20s_debug [-option] [-sensor0~1]
options:
-i insert modules
-r remove modules
-a remove modules first, then insert modules
-sensor0~1 sensor_name config sensor type [default: hy006_3814_0011]
-mmz_start config MMZ start addr [default: 0x42000000]
-mmz_size config MMZ mem size [unit: M, default: 96M]
-ir_auto config ir_auto enable [default: 0]
-profile config sys_profile [default: 0]
-h help information
Available sensors:hy006_3814_0011 bt1120/bt656/bt601
for example: ./load3516cv610_20s_debug -i -sensor0 hy006_3814_0011 -sensor1 hy006_3814_0011 -mmz_start 0x42000000 -mmz_size 96M -ir_auto 1
如果需要调整os和mmz的大小，需要参考《内存布局调整指南》对内存大小进行调整。
如果是使用社区默认提供的镜像，这些ko已经打包到文件系统中，烧录到单板上后位于
/ko目录下，在系统启动后会自动加载这些ko(默认不带-ir_auto 1)。
2.3 运行时依赖
在运行样例前，需要提前准备：
-
硬件：需IR-CUT切换器 + IR LED，通过
/sys/class/gpio/sysfs 控制。必须按《SYS_CONFIG 配置指南》的"IR_AUTO 引脚复用"章节进行配置(加载 KO时带-ir_auto 1会自动配置)。GPIO 未配置时会打印sample_ir_cut_gpio_write失败日志，但 ISP 流程仍可继续。IR LED代码未实现，需要参考IR-CUT切换代码自行适配或手动控制。 -
指定运行时依赖的so库路径
MPP样例依赖的so库位于soc/libs/musl下，需要将该目录下的so库拷贝到开发板上（或将这些so库所在的目录挂载到开发板上），并指定运行时依赖库的环境变量，假设这些so库位于/mnt/libs/，执行如下命令：
```shell
export LD_LIBRARY_PATH=/mnt/libs/:$LD_LIBRARY_PATH
```
如果是使用社区默认提供的镜像，这些so库已经打包到文件系统中，烧录到单板上后位于
/usr/lib目录下，该目录是系统默认搜索目录，不需要执行export LD_LIBRARY_PATH命令去指定。
- 启动MPP服务
当前MPP媒体模块处于用户态，通过一个独立进程提供相关接口的调用服务，该进程位于samples/mpp/sdk_server下，执行如下命令即可生成sdk_server可执行文件：
```shell
cd samples/mpp/sdk_server && make
```
在单板上执行./sdk_server &即可启动MPP服务。
- sdk_server同样依赖
soc/libs/musl下的so库，因此也需要参照上述export LD_LIBRARY_PATH指定路径；- 如果是使用社区默认提供的镜像，sdk_server进程已经打包到文件系统中，烧录到单板上后位于
/usr/bin目录下，并在系统启动时会自动启动sdk_server。
- 样例运行时候需要的资源文件
无。
2.4 运行样例
调用语法为 ./sample_ir_auto <mode> [normal2_ir_exp_thr ir2_normal_exp_thr rg_max rg_min bg_max bg_min ir_status]，可以执行./sample_ir_auto -h查看用法。
3. 支持的 Case 列表
本样例支持两种模式，0表示标定 rg/bg 范围（ir calibration），1表示使用参数自动切换（ir auto）。
3.1 ir calibration
参数标定，切到 IR 模式等 AE 稳定，获取红外场景下的WB的Rgain和Bgain范围，此范围为自动切换滤光片的判断标准。
调用命令
- 必须在红外滤光片 + IR LED 点亮环境下运行
- 若 KO 未带
-ir_auto 1加载，sample_ir_cut_gpio_write调用会失败，并打印错误码，但不会退出。
输出文件
无文件输出，仅控制台日志。
控制台日志
日志中会打印如下值：rg_max:%u, rg_min:%u, bg_max:%u, bg_min:%u。
按回车退出，退出时候绿色 program exit normally! 表示正常退出， 红色 program exit abnormally!表示异常退出。
正确性判断
- 记录打印的 4 个值，供 case 1 使用；4 个值应满足
rg_max > rg_min、bg_max > bg_min； - IR-CUT GPIO 写值应与硬件接线一致（开/关电平对应正确），例如gpio1_0 = 1 -> gpio1_0 = 0。
- 在[normal -> IR]时，滤光片成功切换为红外滤光片。（可通过观察或听电机是否工作来确认。）
软件配置流程
- 启动切换滤光片的线程
- 滤光片切换到红外滤光片
- 获取WB统计信息，计算出相关阈值并输出
3.2 ir auto
根据当前场景以及对应的参数范围，自动切换滤光片。
调用命令
- 请将ir calibaration中获取到的Rgain和Bgain范围值作为ir auto的参数输入。
- 默认 normal_to_ir_iso=16000、ir_to_normal_iso=400、rg/bg_max=280、min=190、ir_status=IR
- 若 KO 未带
-ir_auto 1加载，sample_ir_cut_gpio_write调用会失败，并打印错误码，但不会退出。
输出文件
无文件输出，仅控制台日志。
控制台日志
运行过程中会打印如下日志：
[normal -> IR] / [IR -> normal]
sample_ir_cut_gpio_write: gpioX_Y = Z
input anything to continue....
ISP is now running normally
按回车退出，退出时候绿色 program exit normally! 表示正常退出， 红色 program exit abnormally!表示异常退出。
正确性判断
- 在 IR LED 亮（可见光弱）环境下应见
normal -> IR切换、CCM 退化为对角矩阵、饱和度下降；在可见光恢复时应见IR -> normal。 - IR-CUT GPIO 写值应与硬件接线一致（开/关电平对应正确），例如gpio1_0 = 1 -> gpio1_0 = 0 / gpio7_7 = 1 -> gpio7_7 = 0。
- 在[normal -> IR]时，滤光片成功切换为红外滤光片；在[IR -> normal]时，滤光片成功切换为普通滤光片。（可通过观察或听电机是否工作来确认。）
软件配置流程
- 启动切换滤光片的线程
- 传入对应的ISO阈值、WB参数范围，获取切换状态(
ir_switch)，详细使用参考ss_mpi_isp_ir_auto接口（具体请参考《ISP开发参考》文档） -
切换状态为
OT_ISP_IR_SWITCH_TO_IR时，切换到ir(红外)状态- 调节饱和度为0、不做WB增益、调节CCM为线性
- 通过GPIO控制滤光片，切换到ir(红外)状态
-
切换状态为
OT_ISP_IR_SWITCH_TO_NORMAL时，切换到normal(自然光)状态- 通过GPIO控制滤光片，切换到normal(自然光)状态
- 调节饱和度、WB、CCM为自动模式
3.3 代码流程
- 配置
ir_auto管脚复用，参考《SYS_CONFIG 配置指南》"IR_AUTO管脚复用”章节。 - 启动数据通路，从前往后分别启动各媒体模块（VI、VPSS、VENC）。
- 启动切换滤光片的线程。
- 获取切换状态（
ir_switch），详细使用请参考ss_mpi_isp_ir_auto接口（具体参考《ISP开发参考》文档）。 - 根据切换状态（
ir_switch），切换滤光片并调整颜色参数（饱和度、WB和CCM的参数，红外场景为黑白场景，不需要调整颜色）。
代码流程如图1所示。
