Hi3403开发文档
前言¶
本文为使用HNR的软件开发工程师和图像质量开发工程师而写，目的是为您在开发过程中提供使用指导和帮助。
说明： 本文以SS928V100描述为例，未有特殊说明，SS927V100与SS928V100内容一致。
与本文档相对应的产品版本如下。
修订记录累积了每次文档更新的说明。最新版本的文档包含以前所有文档版本的更新内容。
概述¶
概述¶
HNR（hypersensitive noise reduction）是一种新型的去噪算法，它能使成像设备在更低照度时噪声去除更干净，细节保留更多，从而提高成像设备极低照度的感光能力。本文主要介绍HNR的接口说明和使用注意事项。
HNR参考帧普通模式性能支持3840 x 2160@30fps，无参考帧模式支持3840 x 2160@40fps，HNR支持的最高帧率为100fps。
基本概念¶
sfs (spatial filter strength)，即空域去噪强度。
tfs (temporal filter strength)，即时域去噪强度。
性能¶
线性OT_HNR_REF_MODE_NORM模式性能数据如下。
API参考¶
该功能模块为用户提供以下API：
ss_mpi_hnr_init：初始化HNR模块。
ss_mpi_hnr_exit：去初始化HNR模块。
ss_mpi_hnr_load_cfg：加载HNR的配置文件。
ss_mpi_hnr_unload_cfg：卸载HNR的配置文件。
ss_mpi_hnr_set_alg_cfg：设置HNR算法相关配置参数。
ss_mpi_hnr_get_alg_cfg：获取HNR算法相关配置参数。
ss_mpi_hnr_enable：使能HNR数据流开关。
ss_mpi_hnr_disable：关闭HNR数据流开关。
ss_mpi_hnr_set_attr：设置HNR的属性。
ss_mpi_hnr_get_attr：获取HNR的属性。
ss_mpi_hnr_set_input_depth：设置HNR输入队列的缓存深度。
ss_mpi_hnr_set_thread_attr：设置HNR线程属性。
ss_mpi_hnr_get_thread_attr：获取HNR线程属性。
ss_mpi_hnr_attach_out_vb_pool：HNR输出绑定到某个视频缓存VB池。
ss_mpi_hnr_detach_out_vb_pool：HNR输出与视频缓存VB池解除绑定。
ss_mpi_hnr_init¶
【描述】
初始化HNR模块。
【语法】
td_s32 ss_mpi_hnr_init(td_void);
【参数】
无
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
不支持多进程调用。
调用此接口前需要先初始化VI、ISP模块。
【举例】
无
【相关主题】
无
ss_mpi_hnr_exit¶
【描述】
去初始化HNR模块。
【语法】
td_void ss_mpi_hnr_exit(td_void);
【参数】
无
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
不支持多进程调用。
调用此接口去初始化HNR模块前，需要关闭HNR数据流开关。
【举例】
无
【相关主题】
无
ss_mpi_hnr_load_cfg¶
【描述】
加载HNR的配置文件。
【语法】
td_s32 ss_mpi_hnr_load_cfg(const ot_hnr_cfg *cfg, td_s32 *cfg_id);
【参数】
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
调用该接口前必须先调用ss_mpi_hnr_init初始化HNR模块。
调用该接口前HNR数据流需要保持关闭状态。
相同类型的配置文件，如果图像宽高相等时，不能重复加载。
支持多个配置文件的加载，或者同一配置文件、不同分辨率多次加载。
不支持多进程调用。
WDR模式不支持加载抓拍模型。
【举例】
无
【相关主题】
无
ss_mpi_hnr_unload_cfg¶
【描述】
卸载HNR的配置文件。
【语法】
td_s32 ss_mpi_hnr_unload_cfg(td_s32 cfg_id);
【参数】
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
应用程序退出前，需调用此接口释放已加载配置文件的内存资源，或者调用ss_mpi_hnr_exit接口释放HNR的所有资源。
不支持多进程调用。
调用此接口前需要关闭HNR数据流开关。
【举例】
无
【相关主题】
无
ss_mpi_hnr_set_alg_cfg¶
【描述】
设置HNR算法相关配置参数。
【语法】
td_s32 ss_mpi_hnr_set_alg_cfg(ot_vi_pipe vi_pipe, const ot_hnr_alg_cfg *cfg)
【参数】
|
取值范围：[0, OT_VI_MAX_PIPE_NUM)。详见《MPP 媒体处理软件V5.0 开发参考》“视频输入”章节。 |
||
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
调用该接口前必须先调用ss_mpi_hnr_init初始化HNR模块。
调用该接口前需要已创建pipe，并且已初始化ISP。
调用该接口时HNR数据流需要保持关闭状态。
如果未调用此接口，默认为有参考帧模式。
如果是拍照场景，必须调用此接口设置为无参考帧模式。
HNR参考帧普通模式支持的最大分辨率为4096×4096；HNR无参考帧模式（OT_HNR_REF_MODE_NONE和OT_HNR_REF_MODE_NONE_ADVANCED）支持的最大分辨率为8192×8192。
当前版本HNR 的无参考帧模式（OT_HNR_REF_MODE_NONE和OT_HNR_REF_MODE_NONE_ADVANCED）不支持BGGR和GRBG的Bayer图像的数据格式。
WDR模式不支持HNR无参考帧模式（OT_HNR_REF_MODE_NONE和OT_HNR_REF_MODE_NONE_ADVANCED）。
OT_HNR_REF_MODE_NONE_ADVANCED模式仅支持在VI视频模式为OT_VI_VIDEO_MODE_ADVANCED时使用。
OT_HNR_REF_MODE_NONE_ADVANCED模式仅支持送帧方式，推荐使用RunOnce方式。
OT_HNR_REF_MODE_NONE_ADVANCED模式的输入帧仅支持非压缩格式。
如果在非主进程中调用此接口，必须先调用ss_mpi_isp_mem_share或ss_mpi_isp_mem_share_all接口，共享ISP相关MMZ buffer。
【举例】
无
【相关主题】
无
ss_mpi_hnr_get_alg_cfg¶
【描述】
获取HNR算法相关配置参数。
【语法】
td_s32 ss_mpi_hnr_get_alg_cfg(ot_vi_pipe vi_pipe, ot_hnr_alg_cfg *cfg);
【参数】
|
取值范围：[0, OT_VI_MAX_PIPE_NUM)。详见《MPP 媒体处理软件V5.0 开发参考》“视频输入”章节。 |
||
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
调用该接口前必须先调用ss_mpi_hnr_init初始化HNR模块。
调用该接口前需要已创建pipe，并且已初始化ISP。
如果在非主进程中调用此接口，必须先调用ss_mpi_isp_mem_share或ss_mpi_isp_mem_share_all接口，共享ISP相关MMZ buffer。
【举例】
无
【相关主题】
无
ss_mpi_hnr_enable¶
【描述】
使能HNR数据流开关。
【语法】
td_s32 ss_mpi_hnr_enable(ot_vi_pipe vi_pipe);
【参数】
|
取值范围：[0, OT_VI_MAX_PIPE_NUM)，详见《MPP 媒体处理软件V5.0 开发参考》“视频输入”章节。 |
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
主进程调用该接口前必须先调用ss_mpi_hnr_init初始化HNR模块，并调用ss_mpi_hnr_load_cfg接口加载HNR配置文件。
其他非主进程（例如PQTools）支持使用该接口打开HNR数据流，无需初始化HNR；但需要主进程初始化HNR模块，否则无法实际打开数据流。
如果在非主进程中调用此接口，必须先调用ss_mpi_isp_mem_share或ss_mpi_isp_mem_share_all接口，共享ISP相关MMZ buffer。
enable hnr前有如下限制条件：
对应的pipe必须已经创建。
需要用户调用函数去分配VB池，VB大小计算使用函数ot_hnr_get_pic_buf_size，详见《MPP 媒体处理软件V5.0 开发参考》“系统控制”章节，且分配的VB池需要attach对应的PIPE上。
如果更改了输入Bayer图像的数据格式，需要ss_mpi_hnr_disable关闭之后，在重新调用本接口使能HNR数据流才会生效。
HNR使能之后，有参考帧模式延迟4帧生效，无参考帧模式延迟2帧生效。
HNR仅支持12bit的Bayer图像数据处理。如果sensor输入非12bit的Bayer图像，需设置VI PIPE输出的图像数据格式为Bayer 12bit。
HNR的线性模式使用有如下限制：
如果另一路使用WDR模式，则VI视频模式需要设置为OT_VI_VIDEO_MODE_NORM模式，否则会影响WDR路的BNR效果；
HNR的WDR模式使用有如下限制：
只能在VI离线时生效；
VI视频模式必须设置为OT_VI_VIDEO_MODE_NORM模式；
HNR建议绑定长帧所在的pipe，不能是虚拟pipe；
pipe通路不能开压缩；
当前版本HNR 的WDR模式不支持BGGR和GRBG的Bayer图像的数据格式；
不支持normal_blend模式；
超性能场景可能会出现WDR长短帧丢帧不同步，进而导致WDR融合效果异常。
【举例】
无
【相关主题】
无
ss_mpi_hnr_disable¶
【描述】
关闭HNR数据流开关。
【语法】
td_s32 ss_mpi_hnr_disable(ot_vi_pipe vi_pipe);
【参数】
|
取值范围：[0, OT_VI_MAX_PIPE_NUM)。详见《MPP 媒体处理软件V5.0 开发参考》“视频输入”章节。 |
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
主进程调用该接口前必须先调用ss_mpi_hnr_init初始化HNR模块，并调用ss_mpi_hnr_load_cfg接口加载HNR配置文件。
其他非主进程（例如PQTools）支持使用该接口关闭HNR数据流，无需初始化HNR。
如果在非主进程中调用此接口，必须先调用ss_mpi_isp_mem_share或ss_mpi_isp_mem_share_all接口，共享ISP相关MMZ buffer。
在VI模块销毁对应的pipe之前，需要先调用该接口关闭HNR功能，否则可能出现VB泄漏。
【举例】
无
【相关主题】
无
ss_mpi_hnr_set_attr¶
【描述】
设置HNR的属性。
【语法】
td_s32 ss_mpi_hnr_set_attr(ot_vi_pipe vi_pipe, const ot_hnr_attr *attr);
【参数】
|
取值范围：[0, OT_VI_MAX_PIPE_NUM)。详见《MPP 媒体处理软件V5.0 开发参考》“视频输入”章节。 |
||
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
调用该接口前必须先调用ss_mpi_hnr_init初始化HNR模块，并调用ss_mpi_hnr_load_cfg接口加载HNR配置文件。
使能HNR数据流开关之后才能调用此接口成功设置HNR属性。
VI视频模式为OT_VI_VIDEO_MODE_NORM时，当attr->enable为TD_FALSE时，bnr_bypass必须为TD_FALSE。
VI视频模式为OT_VI_VIDEO_MODE_ADVANCED时，bnr_bypass不起作用。
VI视频模式为OT_VI_VIDEO_MODE_NORM时，并且bnr_bypass为TD_FALSE时，才能开启normal_blend。
VI视频模式为OT_VI_VIDEO_MODE_NORM时，normal_blend开启，不支持获取HNR处理后的raw，不支持ISP RunOnce方式使用HNR，因为BE灌的raw没有经过HNR处理。
VI视频模式为OT_VI_VIDEO_MODE_NORM时，normal_blend关闭，支持获取HNR处理后的raw, 支持ISP RunOnce方式使用HNR。
如果在非主进程中调用此接口，必须先调用ss_mpi_isp_mem_share或ss_mpi_isp_mem_share_all接口，共享ISP相关MMZ buffer。
【举例】
无
【相关主题】
无
ss_mpi_hnr_get_attr¶
【描述】
获取HNR的属性。
【语法】
td_s32 ss_mpi_hnr_get_attr(ot_vi_pipe vi_pipe, ot_hnr_attr *attr);
【参数】
|
取值范围：[0, OT_VI_MAX_PIPE_NUM)。详见《MPP 媒体处理软件V5.0 开发参考》“视频输入”章节。 |
||
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
使能HNR数据流开关之后才能调用此接口成功获取HNR属性。
如果在非主进程中调用此接口，必须先调用ss_mpi_isp_mem_share或ss_mpi_isp_mem_share_all接口，共享ISP相关MMZ buffer。
【举例】
无
【相关主题】
无
ss_mpi_hnr_set_input_depth¶
【描述】
设置HNR输入队列的缓存深度。
【语法】
td_s32 ss_mpi_hnr_set_input_depth(ot_vi_pipe vi_pipe, td_u32 depth);
【参数】
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
调用该接口前必须先调用ss_mpi_hnr_init初始化HNR模块，并且对应的pipe必须已经创建。
【举例】
无
【相关主题】
无
ss_mpi_hnr_set_thread_attr¶
【描述】
设置HNR线程属性。
【语法】
td_s32 ss_mpi_hnr_set_thread_attr(const ot_hnr_thread_attr *thread_attr);
【参数】
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
调用该接口支持在调用ss_mpi_hnr_init初始化HNR模块前或开启HNR通路后动态修改。
【举例】
无
【相关主题】
无
ss_mpi_hnr_get_thread_attr¶
【描述】
获取HNR线程属性。
【语法】
td_s32 ss_mpi_hnr_get_thread_attr(const ot_hnr_thread_attr *thread_attr);
【参数】
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
无
【举例】
无
【相关主题】
无
ss_mpi_hnr_attach_out_vb_pool¶
【描述】
将HNR输出绑定到某个视频缓存VB池。
【语法】
td_s32 ss_mpi_hnr_attach_out_vb_pool(ot_vi_pipe vi_pipe, ot_vb_pool vb_pool);
【参数】
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
调用该接口前必须先调用ss_mpi_hnr_init初始化HNR模块。
调用该接口前HNR数据流需要保持关闭状态。
只推荐在VI stagger输入场景且VI视频模式为OT_VI_VIDEO_MODE_NORM时使用；其他场景使用会造成vb利用率下降。
【举例】
无
【相关主题】
无
ss_mpi_hnr_detach_out_vb_pool¶
【描述】
将HNR输出与某个视频缓存VB池解绑定。
【语法】
td_s32 ss_mpi_hnr_detach_out_vb_pool(ot_vi_pipe vi_pipe);
【参数】
【返回值】
失败，请参见错误码。 |
【需求】
头文件：ss_mpi_hnr.h
库文件：libss_hnr.a
【注意】
调用该接口前必须先调用ss_mpi_hnr_init初始化HNR模块。
调用该接口前HNR数据流需要保持关闭状态。
【举例】
无
【相关主题】
无
数据类型¶
HNR模块相关数据类型定义如下：
OT_HNR_MAX_CFG_NUM：定义HNR配置文件最大支持加载数。
ot_hnr_mem_info：定义HNR配置文件内存信息。
ot_hnr_cfg：定义HNR配置文件信息。
ot_hnr_param：定义HNR图像效果参数。
ot_hnr_manual_attr：定义HNR手动参数。
ot_hnr_attr：定义HNR属性。
ot_hnr_ref_mode：定义HNR参考帧模式。
ot_hnr_alg_cfg：定义HNR算法配置参数。
ot_hnr_thread_attr：定义HNR线程配置参数。
OT_HNR_MAX_CFG_NUM¶
【说明】
定义HNR配置文件最大支持加载数。
【定义】
#define OT_HNR_MAX_CFG_NUM 32
【注意事项】
无
【相关数据类型及接口】
无
ot_hnr_mem_info¶
【说明】
HNR配置文件内存信息。
【定义】
typedef struct {
td_phys_addr_t phys_addr;
td_void *virt_addr;
td_u32 size;
} ot_hnr_mem_info;
【成员】
【注意事项】
无
【相关数据类型及接口】
ot_hnr_cfg¶
【说明】
HNR配置文件信息。
【定义】
typedef struct {
ot_hnr_mem_info mem_info;
ot_size image_size;
td_bool is_wdr_mode;
} ot_hnr_cfg;
【成员】
【注意事项】
用户需要保证内存中所存储的配置文件信息的完整性和正确性，否则可能导致运行异常。
配置文件加载时需指定所支持的图像分辨率。
支持的图像分辨率宽高都必须是4的整数倍。
HNR参考帧模式支持的图像分辨率宽高与VI PIPE离线图像大小范围一致。详细请参考《MPP 媒体处理软件 V5.0 开发参考》“视频输入”章节。
【相关数据类型及接口】
无
ot_hnr_param¶
【说明】
定义HNR图像效果参数。
【定义】
typedef struct {
td_u32 sfs;
td_u32 tfs;
} ot_hnr_param;
【成员】
【注意事项】
当前版本，tfs参数暂未生效。参数调节请参考《HNR调优指南》。
【相关数据类型及接口】
ot_hnr_manual_attr¶
【说明】
定义HNR手动参数。
【定义】
typedef struct {
ot_hnr_param param;
} ot_hnr_manual_attr;
【成员】
【注意事项】
无
【相关数据类型及接口】
ot_hnr_attr¶
【说明】
定义HNR属性。
【定义】
typedef struct {
td_bool enable;
td_bool bnr_bypass;
td_bool normal_blend;
ot_op_mode op_type;
ot_hnr_manual_attr manual_attr;
ot_hnr_auto_attr auto_attr;
} ot_hnr_attr;
【成员】
【注意事项】
本版本暂只支持手动模式参数，不支持自动模式参数配置。
【相关数据类型及接口】
无
ot_hnr_ref_mode¶
【说明】
定义HNR参考帧模式。
【定义】
typedef enum {
OT_HNR_REF_MODE_NORM = 0,
OT_HNR_REF_MODE_NONE,
OT_HNR_REF_MODE_NONE_ADVANCED,
OT_HNR_REF_MODE_NORM_FACE,
OT_HNR_REF_MODE_BUTT
} ot_hnr_ref_mode;
【成员】
【注意事项】
如果是拍照场景，需选用HNR无参考帧模式，或HNR无参考帧的高级模式。
【相关数据类型及接口】
ot_hnr_alg_cfg¶
【说明】
定义HNR算法配置参数。
【定义】
typedef struct {
ot_hnr_ref_mode ref_mode;
} ot_hnr_alg_cfg;
【成员】
【注意事项】
无
【相关数据类型及接口】
无
ot_hnr_thread_attr¶
【说明】
定义HNR线程属性。
【定义】
typedef struct {
td_u32 cpu_id;
} ot_hnr_thread_attr;
【成员】
【注意事项】
无
【相关数据类型及接口】
无
Proc调试信息¶
概述¶
调试信息采用了Linux下的proc文件系统，可实时反映当前系统的运行状态，所记录的信息可供问题定位及分析时使用。
【文件目录】
/proc/umap
【信息查看方法】
在控制台上可以使用cat命令查看信息，cat /proc/umap/isp或cat /proc/umap/pqp；也可以使用其他常用的文件操作命令，例如 cp /proc/umap/isp ./或cp /proc/umap/pqp ./，将文件拷贝到当前目录。
在应用程序中可以将上述文件当作普通只读文件进行读操作，例如fopen、fread等。
取值为{0, 1}的参数，如未列出具体取值和含义的对应关系，则参数为1时表示肯定，为0时表示否定。
取值为{aaa, bbb, ccc}的参数，未列出具体取值和含义的对应关系，但可直接根据取值aaa、bbb或ccc判断参数含义。
Proc信息说明¶
HNR调试信息说明¶
【调试信息】
# cat /proc/umap/isp
[ISP] Version: [MPP_Vx.x.x.x B0xx Release], Build Time[mm dd yyyy, hh:mm:ss]
----------------------------------------hnr info------------------------------------------------------------------------
hnr_en attr_en sfs set_bnr_bypass bnr_bypass_status long_frame_mode normal_blend normal_blend_status
1 1 31 1 0 N 0 0
cfg_id width height is_wdr ref_mode version_id
0 3840 2160 N norm 2021082801
vi_pipe iso handle busy_node free_node ref_mode input_depth ref_cnt work_time slp_cnt slp_time
0 3521 1 2 1 norm 8 1 12226 26 12231
【注意事项】
当HNR数据流首次使能之后，才能查看到HNR相关的proc信息。
【调试信息分析】
记录当前HNR工作状态资源信息，主要包括HNR用户设置信息，加载的配置文件信息，任务状态信息。
【参数说明】
PQP调试信息说明¶
【调试信息】
# cat /proc/umap/pqp
[PQP] Version: [Vx.x.x.x B0xx Release], Build Time[mm dd yyyy, hh:mm:ss]
----------------------------------------pqp module param------------------------------
dev_id high_profile
0 N
-------------------------------- pqp task queue info----------------------------------
dev_id wait_queue_id work_queue_id wait_head_idx wait_tail_idx
0 0 -1 0 0
work_head_idx work_tail_idx
0 0
-------------------------------------- pqp task info -----------------------------------
dev_id handle task_send task_finish last_finish_id start_task_id handle_wrap
0 0 0 0 0 0 0
finish_wrap
0
-------------------------------------- pqp perf info------------------------------------
dev_id irq_num_per_sec last_irq_time max_irq_time last_task_time
0 0 0 0 0
--------------------------------------- pqp err info-------------------------------------
dev_id query_timeout_num hw_timeout_num hw_err_num
0 0 0 0
【调试信息分析】
记录当前PQP工作状态资源信息，主要包括PQP队列状态信息，任务状态信息，性能信息和错误信息。
【参数说明】
错误码¶
HNR错误码如下所示。
表 1 HNR API错误码