前言¶

产品版本

与本文档相对应的产品版本如下。

产品名称	产品版本
SS928	V100
SS927	V100

说明： 本文以SS928V100描述为例，未有特殊说明，SS927V100与SS928V100内容一致。

修订记录

修订记录累积了每次文档更新的说明。最新版本的文档包含以前所有文档版本的更新内容。

文档版本	发布日期	修改说明
00B01	2025-09-15	第1次临时版本发布。

消费类抓拍方案使用指南¶

概述¶

消费类抓拍方案主要面向消费类电子产品中的拍照功能，支持Normal、PRO的抓拍模式，可以抓拍单张或者多张不同曝光时间的照片。消费类抓拍方案也支持HDR、SFNR、MFNR和DE的后处理算法。

抓拍的数据通路分为单pipe和双pipe，每个pipe可以在线，也可以离线，每种数据通路适用的场景都有些差异。

重要概念¶

单pipe模式

拍照和预览使用同一ISP通路。
双pipe模式

拍照和预览使用不同的ISP通路。
PRO(Professional)模式

专业模式拍照，这种模式下ISP会控制sensor曝光，得到多张曝光时间和增益可调的图片。可以用于HDR算法做多张不同曝光的照片合成，也可以用于拍摄固定曝光时间的照片。
ZSL(Zero Shutter Lag)

零延时拍照。可以减少因为快门延迟或其他因素导致的延时，可以拍摄到触发拍照瞬间的图像。

抓拍数据通路¶

VI的pipe工作模式分为离线模式、在线模式，拍照的数据通路建立在VI之上，所以也分这两种模式。

在拍照的场景中，一般视频预览和抓拍的分辨率是不一样的；而且拍照的ISP效果处理要对人脸肤色等做优化处理，也会和视频预览通路的不一样。所以拍照的数据通路又分为单pipe和双pipe两种。

另外消费类电子产品中还有ZSL模式拍照这种特殊场景下的拍照通路。

须知： VI和VPSS之间的在线、离线关系只影响拍照的YUV输出的位置，不影响拍照的控制流，所以下文说的在线和离线，都是指的拍照的那个VI pipe是在线或者离线。

综上，拍照的数据通路就会有很多种，每种数据通路的适用场景不一样，我们推荐客户采用双pipe离线模式的拍照方案，这种方案在功耗控制上是最优的，拍照的耗时也较短。

下面介绍每种数据通路的优缺点。

双pipe离线模式拍照¶

双pipe离线模式拍照的数据通路如图1所示。

图 1 双pipe离线拍照数据通路

图1所标示的分辨率只是示意分辨率，实际分辨率根据客户不同的场景可能会有差异。后面的数据通路中所标示分辨率也是同样的意思。

双pipe离线的数据通路是一个sensor进来的数据，经过VI Dev时序解析后，分别绑定到2个不同的pipe，上面的pipe用于视频预览和录像，下面的pipe用于拍照。视频预览和录像的pipe是离线的；拍照的pipe也是离线的。

预览和录像的分辨率一般比较小，所以经过了BAS，做了Bayer Scale，主要目的是减小上面的pipe处理的分辨率，从而降低功耗。DV产品中预览用的LCD屏分辨率一般都很小，但需要预览通路一直存在。

拍照的分辨率一般都比较大，但用户并不会一直拍照，所以下面的pipe用于拍照，一般是在客户需要拍照时才启动下面的pipe的通路。

Sensor的曝光控制是由上面的视频pipe的ISP来控制的。

用户设置拍照相关的属性和触发拍照接口，用的pipe号都是下面那个拍照用的pipe，内部的数据同步由VI和ISP的驱动来完成。

这种数据通路可以用于NORMAL和PRO模式的拍照。PRO模式是在用户调用ss_mpi_snap_trigger_pipe接口之后才开始控制sensor进行长短曝光的。

双pipe离线时，拍照的pipe在用户调用ss_mpi_snap_trigger_pipe接口时才打开中断做数据处理，并且只处理抓拍的那几帧数据，抓拍完成后可以调用ss_mpi_snap_disable_pipe停止数据处理。这样处理是为了降低拍照那个pipe的功耗。
双pipe离线时，用户拍摄正常曝光的照片，从调用ss_mpi_snap_trigger_pipe接口到VI输出第一张正常YUV数据，理论上的耗时在3帧左右，可以满足大部分客户场景的需求。所以，我们推荐客户采用双pipe离线的数据通路来实现拍照的方案。

单pipe离线模式拍照¶

单pipe离线模式拍照的数据通路如图1所示。

图 1 单pipe离线拍照数据通路

单pipe离线数据通路是视频预览和拍照共用一个pipe。
单pipe离线模式拍照使用的方法是平时只有视频预览时整个通路可以采用比较小的分辨率，只有切换到拍照模式时才将sensor和VI等通路切换到大的拍照分辨率。这样可以节省一定的功耗。
单pipe离线模式拍照应用的场景是当客户的产品有多个sensor同时输入将VI pipe全部占用，无法做到一个sensor输入绑定两个pipe时，就需要用这种模式来拍照。

这种数据通路可以拍摄NORMAL和PRO模式的照片。

当录像和拍照的分辨率一样，客户又不需要对拍照的ISP做特殊的调节时，可以从单pipe的视频流里面取YUV编成jpeg来实现拍照的方案。这种方案并不需要VI和ISP的驱动做额外的事情，所以不需要调拍照相关的MPI接口。

单pipe在线模式拍照¶

单pipe在线模式拍照的数据通路如图1所示。

图 1 单pipe在线拍照数据通路

单pipe在线拍照的数据通路和单pipe离线的类似，区别是数据通路是在线的。这种数据通路可以拍摄NORMAL和PRO模式的照片。

须知： SS928V100的VI模块目前只支持1个pipe在线，如果多于1个sensor输入的场景，所有sensor要离线处理。

ZSL模式拍照¶

ZSL模式的拍照通路和双pipe离线模式的拍照通路一样，区别是VI驱动内部会缓存一个RAW数据的队列。在调用ss_mpi_snap_enable_pipe接口后，VI内部就开始缓存RAW数据，调用ss_mpi_snap_trigger_pipe接口会选择ZSL的拍照帧，然后将拍照的帧送给ISP做处理。

ZSL模式拍照，只支持拍摄NORMAL模式的照片。

功能描述¶

连拍时的帧率控制¶

连拍时可以做帧率控制，是通过ss_mpi_vi_create_pipe或者ss_mpi_vi_set_pipe_attr接口设置的ot_vi_pipe_attr中的帧率控制来实现的。

说明： 以上接口请参考《MPP 媒体处理软件V5.0 开发参考》“视频输入”章节。

API参考¶

该模块提供以下MPI：

ss_mpi_snap_set_pipe_attr：设置拍照属性。
ss_mpi_snap_get_pipe_attr：获取拍照属性。
ss_mpi_snap_enable_pipe：使能拍照的pipe。
ss_mpi_snap_disable_pipe：停止拍照的pipe。
ss_mpi_snap_trigger_pipe：触发抓拍。

ss_mpi_snap_set_pipe_attr¶

【描述】

设置拍照的属性。

【语法】

td_s32 ss_mpi_snap_set_pipe_attr(ot_vi_pipe vi_pipe, const ot_snap_attr *snap_attr);

【参数】

参数名称	描述	输入/输出
vi_pipe	VI的pipe号。取值范围：0, OT_VI_MAX_PHYS_PIPE_NUM)。 OT_VI_MAX_PHYS_PIPE_NUM定义请参考《MPP 媒体处理软件 V5.0 开发参考》“视频输入”章节。	输入
snap_attr	拍照参数的属性结构体指针。	输入

参数名称

描述

输入/输出

vi_pipe

VI的pipe号。

取值范围：0, OT_VI_MAX_PHYS_PIPE_NUM)。

OT_VI_MAX_PHYS_PIPE_NUM定义请参考《MPP 媒体处理软件 V5.0 开发参考》“视频输入”章节。

输入

snap_attr

拍照参数的属性结构体指针。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【解决方案差异】

无。

【需求】

头文件：ot_common_snap.h、ss_mpi_snap.h
库文件：libss_snap.a

【注意】

PIPE必须已创建。
拍照参数必须合法，具体请参见[ot_snap_attr。
双pipe离线模式下，若拍照参数设置的重复送帧数不为0，在调用ss_mpi_vpss_get_chn_frame及ss_mpi_vpss_get_grp_frame接口（具体请参考《MPP媒体处理软件V5.0开发参考》“视频处理子系统”章节）从抓拍通路中获取帧时，会获取到重复帧。若将获取到的帧用于编码，VENC模块会自动删除重复帧，但若将获取到的帧用于图像处理，则需要手动删除重复帧。
WDR模式不支持拍照。
ZSL拍照模式下，设置的depth需要大于重复送帧的次数，否则可能因为VI处理不及时缓存队列里面的帧被冲掉而导致丢帧。
在调用ss_mpi_snap_enable_pipe接口之后，再次调用ss_mpi_snap_set_pipe_attr接口时，只能修改成员ot_snap_attr的pro_attr属性，修改其他属性都会报错。

【举例】

无

【相关主题】

ss_mpi_snap_get_pipe_attr

ss_mpi_snap_get_pipe_attr¶

【描述】

获取拍照的属性。

【语法】

td_s32 ss_mpi_snap_get_pipe_attr(ot_vi_pipe vi_pipe, ot_snap_attr *snap_attr);

【参数】

参数名称	描述	输入/输出
vi_pipe	VI的pipe号。取值范围：[0, OT_VI_MAX_PHYS_PIPE_NUM)。	输入
snap_attr	拍照参数的属性结构体指针。	输出

参数名称

描述

输入/输出

vi_pipe

VI的pipe号。

取值范围：[0, OT_VI_MAX_PHYS_PIPE_NUM)。

输入

snap_attr

拍照参数的属性结构体指针。

输出

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【解决方案差异】

无。

【需求】

头文件：ot_common_snap.h、ss_mpi_snap.h
库文件：libss_snap.a

【注意】

PIPE必须已创建。
snap属性已设置。

【举例】

无

【相关主题】

ss_mpi_snap_set_pipe_attr

ss_mpi_snap_enable_pipe¶

【描述】

使能拍照的pipe。

【语法】

td_s32 ss_mpi_snap_enable_pipe(ot_vi_pipe vi_pipe);

【参数】

参数名称	描述	输入/输出
vi_pipe	VI的pipe号。取值范围：[0, OT_VI_MAX_PHYS_PIPE_NUM)。	输入

参数名称

描述

输入/输出

vi_pipe

VI的pipe号。

取值范围：[0, OT_VI_MAX_PHYS_PIPE_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【解决方案差异】

无。

【需求】

头文件：ot_common_snap.h、ss_mpi_snap.h
库文件：libss_snap.a

【注意】

PIPE必须已创建。
拍照的属性必须已经设置。
此接口不支持单PIPE拍照场景，调用ss_mpi_vi_start_pipe之后直接使用ss_mpi_snap_trigger_pipe接口即可拍照。
双pipe拍照场景，使能拍照PIPE只能调用ss_mpi_snap_enable_pipe，而不能调用ss_mpi_vi_start_pipe接口，ss_mpi_vi_start_pipe的详细功能描述，请参考《MPP 媒体处理软件V5.0 开发参考》中“视频输入”章节的说明。
不支持重复使能拍照的PIPE。
双PIPE拍照时，ss_mpi_snap_enable_pipe和ss_mpi_snap_trigger_pipe两个接口的调用间隔要大于2帧的曝光时间，才能使拍照的ISP处理效果正常。
PRO模式拍照时，ss_mpi_snap_disable_pipe和ss_mpi_snap_enable_pipe两个接口的调用间隔要大于4帧，即两次拍照的间隔，在低帧率下间隔过小，第二次拍照的帧可能不是期望的曝光帧。

【举例】

无

【相关主题】

ss_mpi_snap_set_pipe_attr

ss_mpi_snap_disable_pipe¶

【描述】

停止拍照的pipe，也可以用于中断正在拍照的数据流。

【语法】

td_s32 ss_mpi_snap_disable_pipe(ot_vi_pipe vi_pipe);

【参数】

参数名称	描述	输入/输出
vi_pipe	VI的pipe号。取值范围：[0, OT_VI_MAX_PHYS_PIPE_NUM)。	输入

参数名称

描述

输入/输出

vi_pipe

VI的pipe号。

取值范围：[0, OT_VI_MAX_PHYS_PIPE_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【解决方案差异】

无。

【需求】

头文件：ot_common_snap.h、ss_mpi_snap.h
库文件：libss_snap.a

【注意】

PIPE必须已创建。
单pipe拍照场景，不支持此接口。
抓拍场景需保证VI通路有帧数据，否则会出现抓拍数据流内部死等帧数据，造成退出抓拍时异常卡住。

【举例】

无

【相关主题】

ss_mpi_snap_enable_pipe

ss_mpi_snap_trigger_pipe¶

【描述】

触发拍照。

【语法】

td_s32 ss_mpi_snap_trigger_pipe(ot_vi_pipe vi_pipe);

【参数】

参数名称	描述	输入/输出
vi_pipe	VI的pipe号。取值范围：[0, OT_VI_MAX_PHYS_PIPE_NUM)。	输入

参数名称

描述

输入/输出

vi_pipe

VI的pipe号。

取值范围：[0, OT_VI_MAX_PHYS_PIPE_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【解决方案差异】

无。

【需求】

头文件：ot_common_snap.h、ss_mpi_snap.h
库文件：libss_snap.a

【注意】

PIPE必须已创建。
拍照 PIPE必须已使能，单pipe模式下拍照的属性必须已经设置。
正在拍照过程中，不能再次触发拍照。
双pipe Pro模式拍照时，由于调节曝光会导致视频通路拍照过程中有几帧闪烁，可参考《MPP 媒体处理软件 V5.0 开发参考》“视频输入”章节 ss_mpi_vi_get_pipe_param设置抓拍时丢弃曝光帧，减弱闪烁效果。

【举例】

无

【相关主题】

ss_mpi_snap_enable_pipe

数据类型¶

拍照相关数据类型定义如下：

ot_snap_attr：定义拍照参数的结构体。
ot_snap_type：定义拍照类型的枚举。
ot_snap_norm_attr：定义Normal类型拍照参数的结构体。
ot_snap_pro_attr：定义PRO类型拍照参数的结构体。
ot_snap_pro_param：定义PRO类型ISP相关参数结构体。
ot_snap_pro_auto_param：定义PRO类型ISP自动模式参数结构体。
ot_snap_pro_manual_param：定义PRO类型ISP手动模式参数结构体。

ot_snap_attr¶

【说明】

定义拍照参数的结构体。

【定义】

typedef struct {
    ot_snap_type snap_type;
    td_bool      load_ccm_en;
    union {
        ot_snap_norm_attr norm_attr;
        ot_snap_pro_attr  pro_attr;
    };
} ot_snap_attr;

【成员】

成员名称	描述
snap_type	拍照类型的枚举值。
load_ccm_en	是否使用外部的CCM值。 TD_TRUE：使用外部输入的ISP_CONFIG_INFO_S中的CCM信息。 TD_FALSE：不使用外部输入的CCM信息，用ISP算法自己计算生成的CCM。
norm_attr	Normal类型拍照的参数结构体。
pro_attr	PRO模式拍照的参数结构体。

【注意事项】

无

【相关数据类型及接口】

ss_mpi_snap_set_pipe_attr
ss_mpi_snap_get_pipe_attr

ot_snap_type¶

【说明】

定义拍照类型的枚举。

【定义】

typedef enum {
    OT_SNAP_TYPE_NORM,
    OT_SNAP_TYPE_PRO,
    OT_SNAP_TYPE_BUTT
} ot_snap_type;

【成员】

成员名称	描述
OT_SNAP_TYPE_NORM	Normal类型，可以拍正常曝光的照片。
OT_SNAP_TYPE_PRO	专业类型，可以拍不同长短曝光的照片。

【注意事项】

无

【相关数据类型及接口】

ot_snap_attr

ot_snap_norm_attr¶

【说明】

定义Normal类型拍照参数的结构体。

【定义】

typedef struct {
    td_u32  frame_cnt;
    td_u32  repeat_send_times;
    td_bool  zsl_en;
    td_u32  frame_depth;
    td_u32  rollback_ms;
    td_u32  interval;
} ot_snap_norm_attr;

【成员】

成员名称	描述
frame_cnt	拍照的张数。取值范围：(0, 0xFFFFFFFF]
repeat_send_times	重复送首帧RAW的次数。当VI的pipe离线时，ISP里面的某些算法需要将拍照的首帧RAW重复送多次，用于生成参考信息。单pipe模式不支持重复送帧。取值范围：[0, 3]
zsl_en	是否使用ZSL模式拍照。
frame_depth	ZSL模式缓存队列的深度。取值范围：[1, 8]
rollback_ms	ZSL模式下，用户调用Trigger接口时往前回退多少毫秒。由于ZSL的缓存最多有8帧，当回退后的时间超过缓存队列里面最早那一帧的时间时，选择缓存最早的那一帧；当回退之后的时间位于缓存队列里面两帧的中间时，选择较新的那一帧。取值范围：[0, 0xFFFFFFFF] 注意：由于缓存队列长度有限，回退的时间太大是没有意义的；在重复送帧场景下，原则上最多回退的帧数为frame_depth - repeat_send_time，超过该时间缓存队列的帧被冲掉导致第二帧出现丢帧。
interval	ZSL模式下，缓存队列里面的帧可以再做一次帧率控制。该值代表在缓存队列里面找到首帧拍照帧后，间隔多少帧之后再取一帧作为拍照帧。取值范围：[0, 0xFFFFFFFF]

【注意事项】

无

【相关数据类型及接口】

ot_snap_attr

ot_snap_pro_attr¶

【说明】

定义PRO类型拍照参数的结构体。

【定义】

typedef struct {
    td_u32  frame_cnt;
    td_u32  repeat_send_times;
    ot_snap_pro_param  pro_param;
} ot_snap_pro_attr;

【成员】

成员名称	描述
frame_cnt	拍照的张数。取值范围：(0, OT_ISP_PRO_MAX_FRAME_NUM] OT_ISP_PRO_MAX_FRAME_NUM定义请参考《ISP 开发参考》
repeat_send_times	重复送首帧RAW的张数。当VI的pipe离线时，ISP里面的某些算法需要将拍照的首帧RAW重复送多次，用于生成参考信息。单pipe模式不支持重复送帧。取值范围：[0, 3]
pro_param	PRO模式ISP参数结构体。

成员名称

描述

frame_cnt

拍照的张数。

取值范围：(0, OT_ISP_PRO_MAX_FRAME_NUM]

OT_ISP_PRO_MAX_FRAME_NUM定义请参考《ISP 开发参考》

repeat_send_times

重复送首帧RAW的张数。当VI的pipe离线时，ISP里面的某些算法需要将拍照的首帧RAW重复送多次，用于生成参考信息。

单pipe模式不支持重复送帧。

取值范围：[0, 3]

pro_param

PRO模式ISP参数结构体。

【注意事项】

无

【相关数据类型及接口】

ot_snap_attr

ot_snap_pro_param¶

【说明】

定义PRO类型中ISP参数的结构体。

【定义】

typedef struct {
    ot_op_mode               op_mode;
    ot_snap_pro_auto_param    auto_param;
    ot_snap_pro_manual_param  manual_param;
} ot_snap_pro_param;

【成员】

成员名称	描述
op_mode	设置参数类型的枚举，自动模式或者手动模式。 ot_op_mode定义请参考《MPP 媒体处理软件V5.0 开发参考》“系统控制”章节。
auto_param	PRO拍照时ISP自动模式的参数。
manual_param	PRO拍照时ISP手动模式的参数。

成员名称

描述

op_mode

设置参数类型的枚举，自动模式或者手动模式。

ot_op_mode定义请参考《MPP 媒体处理软件V5.0 开发参考》“系统控制”章节。

auto_param

PRO拍照时ISP自动模式的参数。

manual_param

PRO拍照时ISP手动模式的参数。

【注意事项】

无

【相关数据类型及接口】

ot_snap_pro_attr

ot_snap_pro_auto_param¶

【说明】

定义PRO类型ISP自动模式参数结构体。

【定义】

typedef struct {
    td_u16 exp_step[OT_ISP_PRO_MAX_FRAME_NUM];
} ot_snap_pro_auto_param;

【成员】

成员名称	描述
exp_step	PRO拍照时ISP自动模式每帧的曝光等级。取值范围：[0, 0xFFFF]，与曝光时间的计算公式见注意事项。曝光时间范围上限与sensor相关，如果按照设置值计算后的曝光时间超过sensor的范围上限，则按照sensor的上限生效。

成员名称

描述

exp_step

PRO拍照时ISP自动模式每帧的曝光等级。

取值范围：[0, 0xFFFF]，与曝光时间的计算公式见注意事项。

曝光时间范围上限与sensor相关，如果按照设置值计算后的曝光时间超过sensor的范围上限，则按照sensor的上限生效。

【注意事项】

exp_step是以当前预览通道的曝光量为基准，增益保持不变，根据曝光等级调整曝光时间。

ExpTime_i = ExpTime_base* exp_step[i]/256

ExpTime_base代表基准曝光时间，ExpTime_i代表专业拍照第i帧的曝光时间。
- 当ExpTime_i大于当前设置的最大曝光时间时，ISP会自动进入慢快门模式，使曝光时间等于ExpTime_i；
- 当ExpTime_i小于设置的最小曝光时间时，实际曝光时间等于设置的最小曝光时间。
- 当前预览通路的基准曝光量是指AE在自动模式下的曝光量，不支持手动AE设置基准曝光量。

【相关数据类型及接口】

ot_snap_pro_param

ot_snap_pro_manual_param¶

【说明】

定义PRO类型ISP手动模式参数结构体。

【定义】

typedef struct {
    td_u32 exp_time[OT_ISP_PRO_MAX_FRAME_NUM];
    td_u32 sys_gain[OT_ISP_PRO_MAX_FRAME_NUM];
} ot_snap_pro_manual_param;

【成员】

成员名称	描述
exp_time	PRO拍照时ISP手动模式的曝光时间，单位为微秒。取值范围：[0, 0xFFFFFFFF]，范围上限与sensor相关，如果设置值超过sensor的范围上限，则按照sensor的上限生效。
sys_gain	PRO拍照时ISP手动模式的系统增益，10bit精度。取值范围：[0x400, 0xFFFFFFFF]，范围上限与sensor相关，如果设置值超过sensor的范围上限，则按照sensor的上限生效。

成员名称

描述

exp_time

PRO拍照时ISP手动模式的曝光时间，单位为微秒。

取值范围：[0, 0xFFFFFFFF]，范围上限与sensor相关，如果设置值超过sensor的范围上限，则按照sensor的上限生效。

sys_gain

PRO拍照时ISP手动模式的系统增益，10bit精度。

取值范围：[0x400, 0xFFFFFFFF]，范围上限与sensor相关，如果设置值超过sensor的范围上限，则按照sensor的上限生效。

【注意事项】

无

【相关数据类型及接口】

ot_snap_pro_param

错误码¶

SNAP模块API错误码如下所示。

表 1 SNAP模块API错误码

错误代码	宏定义	描述
0xa0538002	OT_ERR_SNAP_INVALID_PIPE_ID	PIPE号无效
0xa0538007	OT_ERR_SNAP_ILLEGAL_PARAM	输入非法参数
0xa053800a	OT_ERR_SNAP_NULL_PTR	输入参数空指针错误
0xa053800c	OT_ERR_SNAP_NOT_SUPPORT	操作不支持
0xa053800d	OT_ERR_SNAP_NOT_PERM	操作不允许
0xa0538014	OT_ERR_SNAP_NO_MEM	未分配到内存
0xa0538018	OT_ERR_SNAP_NOT_READY	未初始化

拍照后处理算法¶

概述¶

PHOTO代表消费类抓拍方案中的拍照后处理算法，包括HDR、MFNR、SFNR、DE这几种。

拍照后，运行于CPU和DSP上的软件处理算法。

重要概念¶

HDR(High Dynamic Range)

HDR图像后处理算法，能提升图像的动态范围；通过拍照的PRO模式拍照，得到多张曝光时间和增益可调的图片，然后经过HDR算法模块合成一张具有高动态范围的图像，相比普通的图像，HDR可以提供更多的动态范围和图像细节。
SFNR(Single frame noise reduction)

单帧降噪。
MFNR(Multi-frame noise reduction)

多帧降噪。
DE(Detail enhancement)

细节增强。ISP中的BNR处理，会造成图像中一些细节信息的丢失，DE算法可以补偿这些丢失的图像细节信息。DE算法的输入是一张YUV和BNR写出的RAW，输出是一张细节增强过的YUV。

功能描述¶

PHOTO模块的运行依赖DSP的资源，PHOTO的库默认编译到DSP0的镜像中，所以在调用PHOTO的接口之前，请确保已经调用了ss_mpi_svp_dsp_load_bin接口加载了DSP0的镜像。（ss_mpi_svp_dsp_load_bin的具体描述，请参考《SVP2.0 API 参考》）

HDR合成当前仅支持三合一，就是输入三帧不同曝光的连续YUV，输出一帧高动态范围的YUV。三帧的输入顺序依次是短曝光的YUV，正常曝光的YUV，长曝光的YUV。
HDR算法支持对人脸区域的图像效果做特殊优化处理。图像中的人脸区域坐标需要提前通过人脸检测的智能算法检测出来。
MFNR当前仅支持四合一，输入是四帧连续的正常曝光的YUV，输出是一帧经过时域和空域降噪的YUV。
DE算法需要BNR RAW数据，SS928V100暂不支持获取BNR RAW数据
MFNR算法做完后，可以再对输出后的YUV做一次DE算法处理。DE算法需要的BNR RAW数据可以是MFNR输入的四帧YUV里面任意一帧YUV对应的BNR RAW；SS928V100暂不支持获取BNR RAW数据，因此不支持MFNR+DE的算法处理。
算法处理输入和输出帧数据的Stride必须是128Byte对齐，并且帧数据的像素宽高必须是8的倍数。
算法处理的输入YUV数据，仅支持处理NV21格式（也就是OT_PIXEL_FORMAT_YVU_SEMIPLANAR_420格式）的非压缩数据，输入图像的动态范围仅支持OT_DYNAMIC_RANGE_SDR8的。
拍照后处理是一个原子任务，该原子任务包含完整的init->process->deinit流程（不同算法需要调用的process次数可能不同），仅支持在同一个进程或线程中以原子任务为单位串行处理，不支持多个原子任务并行处理，不支持前一个原子任务未结束就启动下一个原子任务。
PHOTO中算法运行依赖DSP，由于当前DSP使用32bit地址总线，只能访问4GB的内存地址空间。所以，PHOTO算法使用的Public内存，输入、输出帧存都必须位于4GB的内存地址空间中。详细的地址范围限制说明请参考《SVP2.0 开发指南》。

API参考¶

该模块提供以下MPI：

ss_mpi_photo_alg_init：初始化某个PHOTO算法。
ss_mpi_photo_alg_deinit：去初始化某个PHOTO算法。
ss_mpi_photo_alg_process：启动某个PHOTO算法的处理。
ss_mpi_photo_set_alg_coef：设置某个PHOTO算法的图像效果调节系数。
ss_mpi_photo_get_alg_coef：获取某个PHOTO算法的图像效果调节系数。

ss_mpi_photo_alg_init¶

【描述】

初始化某个PHOTO算法。

【语法】

td_s32 ss_mpi_photo_alg_init(ot_photo_alg_type alg_type, const ot_photo_alg_init *photo_init);

【参数】

参数名称	描述	输入/输出
alg_type	算法的枚举值。	输入
photo_init	Photo算法的初始化参数。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【解决方案差异】

无。

【需求】

头文件：ot_common_photo.h、ss_mpi_photo.h
库文件：libss_photo.a

【注意】

调用该接口之前需要确保DSP端的bin文件已经加载成功。
该接口传入的内存是已经从MMZ中分配好的。
不同算法，不同分辨率需要的Public内存大小不同，建议使用ot_common_photo.h中定义的hdr_get_public_mem_size，mfnr_get_public_mem_size，sfnr_get_public_mem_size，de_get_public_mem_size这几个函数来获取不同分辨率对应的算法Public内存大小。

【举例】

无

【相关主题】

ss_mpi_photo_alg_deinit

ss_mpi_photo_alg_deinit¶

【描述】

去初始化某个PHOTO算法。

【语法】

td_s32 ss_mpi_photo_alg_deinit(ot_photo_alg_type alg_type);

【参数】

参数名称	描述	输入/输出
alg_type	算法的枚举值。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【解决方案差异】

无

【需求】

头文件：ot_common_photo.h、ss_mpi_photo.h
库文件：libss_photo.a

【注意】

无

【举例】

无

【相关主题】

ss_mpi_photo_alg_init

ss_mpi_photo_alg_process¶

【描述】

启动某个PHOTO算法的处理。这个接口是阻塞接口，当前帧处理完成之后才返回。

多帧合成的算法需要调用多次，比如HDR三合一需要调用三次这个接口，每次传一帧输入的帧数据信息，调用后当前帧就开始处理。

【语法】

td_s32 ss_mpi_photo_alg_process(ot_photo_alg_type alg_type, const ot_photo_alg_attr *photo_attr);

【参数】

参数名称	描述	输入/输出
alg_type	算法的枚举值。	输入
photo_attr	算法处理的属性结构体。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【解决方案差异】

无。

【需求】

头文件：ot_common_photo.h、ss_mpi_photo.h
库文件：libss_photo.a

【注意】

对应算法必须初始化成功后，才能调用该接口。

【举例】

无

【相关主题】

ss_mpi_photo_alg_init

ss_mpi_photo_set_alg_coef¶

【描述】

设置某个PHOTO算法的图像效果调节系数。

这个接口不是必设的接口，PHOTO内部保存了一套默认的系数，如果不设置，就使用默认的值。

【语法】

td_s32 ss_mpi_photo_set_alg_coef(ot_photo_alg_type alg_type, const ot_photo_alg_coef *alg_coef);

【参数】

参数名称	描述	输入/输出
alg_type	算法的枚举值。	输入
alg_coef	算法系数的结构体。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【解决方案差异】

无。

【需求】

头文件：ot_common_photo.h、ss_mpi_photo.h
库文件：libss_photo.a

【注意】

该接口可在算法处理第一帧之前，初始化之后调用。

【举例】

无

【相关主题】

ss_mpi_photo_get_alg_coef

ss_mpi_photo_get_alg_coef¶

【描述】

获取某个PHOTO算法的图像效果调节系数。

【语法】

td_s32 ss_mpi_photo_get_alg_coef(ot_photo_alg_type alg_type, ot_photo_alg_coef *alg_coef);

【参数】

参数名称	描述	输入/输出
alg_type	算法的枚举值。	输入
alg_coef	算法系数的结构体。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【解决方案差异】

无。

【需求】

头文件：ot_common_photo.h、ss_mpi_photo.h
库文件：libss_photo.a

【注意】

无

【举例】

无

【相关主题】

ss_mpi_photo_set_alg_coef

数据类型¶

PHOTO相关数据类型定义如下：

ot_photo_alg_type：定义PHOTO算法类型的枚举。
ot_photo_alg_init：定义PHOTO算法初始化的结构体。
ot_photo_alg_attr：定义PHOTO算法处理的属性结构体。
ot_photo_hdr_attr：定义HDR算法处理的结构体。
ot_photo_sfnr_attr：定义SFNR算法处理的结构体。
ot_photo_mfnr_attr：定义MFNR算法处理的结构体。
ot_photo_de_attr：定义DE算法处理的结构体。
ot_photo_face_info：定义人脸区域信息的结构体。
ot_photo_alg_coef：定义PHOTO算法系数的结构体。
ot_photo_hdr_coef：定义HDR算法系数的结构体。
ot_photo_image_fusion_param：定义图像融合参数的结构体。
ot_photo_dark_motion_detection_param：定义HDR中鬼影检测参数的结构体。
ot_photo_sfnr_coef：定义SFNR算法系数的结构体。
ot_photo_sfnr_iso_strategy：定义SFNR算法ISO策略的结构体。
ot_photo_mfnr_coef：定义MFNR算法系数的结构体。
ot_photo_mfnr_3dnr_param：定义MFNR算法中时域降噪系数的结构体。
ot_photo_mfnr_3dnr_iso_strategy：定义MFNR算法时域降噪系数中每个ISO档位的结构体。
ot_photo_mfnr_2dnr_param：定义MFNR算法中空域降噪系数的结构体。
ot_photo_mfnr_2dnr_iso_strategy：定义MFNR算法空域降噪系数中每个ISO档位的结构体。
ot_photo_de_coef：定义DE算法系数的结构体。
ot_photo_de_iso_strategy：定义DE算法每个ISO档位对应策略的结构体。
OT_PHOTO_HDR_FRAME_NUM：定义HDR合成的帧数目。
OT_PHOTO_MFNR_FRAME_NUM：定义MFNR合成的帧数目。
OT_PHOTO_HDR_ISO_LEVEL_CNT：定义调节HDR图像效果的ISO档位数目。
OT_PHOTO_SFNR_ISO_LEVEL_CNT：定义调节SFNR图像效果的ISO档位数目。
OT_PHOTO_MFNR_ISO_LEVEL_CNT：定义调节MFNR图像效果的ISO档位数目。
OT_PHOTO_DE_ISO_LEVEL_CNT：定义调节DE图像效果的ISO档位数目。
OT_PHOTO_MAX_FACE_NUM：定义算法处理中最大的人脸区域的数目。
OT_PHOTO_MIN_WIDTH：定义算法处理支持的最小图像分辨率的宽。
OT_PHOTO_MIN_HEIGHT：定义算法处理支持的最小图像分辨率的高。
OT_PHOTO_MAX_WIDTH：定义算法处理支持的最大图像分辨率的宽。
OT_PHOTO_MAX_HEIGHT：定义算法处理支持的最大图像分辨率的高。

ot_photo_alg_type¶

【说明】

定义PHOTO算法类型的枚举。

【定义】

typedef enum {
    OT_PHOTO_ALG_TYPE_HDR = 0x0,
    OT_PHOTO_ALG_TYPE_SFNR = 0x1,
    OT_PHOTO_ALG_TYPE_MFNR = 0x2,
    OT_PHOTO_ALG_TYPE_DE = 0x3,
    OT_PHOTO_ALG_TYPE_BUTT
} ot_photo_alg_type;

【成员】

成员名称	描述
OT_PHOTO_ALG_TYPE_HDR	HDR合成算法。
OT_PHOTO_ALG_TYPE_SFNR	SFNR单帧降噪算法。
OT_PHOTO_ALG_TYPE_MFNR	MFNR多帧降噪算法。
OT_PHOTO_ALG_TYPE_DE	DE细节增强算法。

【注意事项】

无

【相关数据类型及接口】

ss_mpi_photo_alg_init
ss_mpi_photo_alg_deinit
ss_mpi_photo_alg_process
ss_mpi_photo_set_alg_coef
ss_mpi_photo_get_alg_coef

ot_photo_alg_init¶

【说明】

定义PHOTO算法初始化的结构体。

【定义】

typedef struct {
    td_u64 public_mem_phy_addr;
    td_u64 public_mem_vir_addr;
    td_u32 public_mem_size;
    td_bool print_debug_info;
} ot_photo_alg_init;

【成员】

成员名称	描述
public_mem_phy_addr	给算法处理的内存起始物理地址。这块内存需要用户提前从MMZ区域分配。
public_mem_vir_addr	给算法处理的内存起始虚拟地址，这个值当前无效，PHOTO内部并没有使用。
public_mem_size	给算法处理的内存区域的长度。
bPrintDebugInfo	是否开启打印调试信息。 TD_TRUE：打印算法的版本号等调试信息。 TD_FALSE：除异常错误信息外，不打印其他的调试信息。

【注意事项】

无

【相关数据类型及接口】

ss_mpi_photo_alg_init

ot_photo_alg_attr¶

【说明】

定义PHOTO算法处理的属性结构体。

typedef struct {
    union {
        ot_photo_hdr_attr hdr_attr;
        ot_photo_sfnr_attr sfnr_attr;
        ot_photo_mfnr_attr mfnr_attr;
        ot_photo_de_attr de_attr;
    };
} ot_photo_alg_attr;

【成员】

成员名称	描述
hdr_attr	HDR算法处理的结构体。
sfnr_attr	SFNR算法处理的结构体。
mfnr_attr	MFNR算法处理的结构体。
de_attr	DE算法处理的结构体。

【注意事项】

无

【相关数据类型及接口】

ss_mpi_photo_alg_process

ot_photo_hdr_attr¶

【说明】

定义HDR算法处理的结构体。

【定义】

typedef struct {
    ot_video_frame_info src_frm;
    ot_video_frame_info des_frm;
    td_u32 frm_index;
    td_u32 iso;
    td_u32 face_num;
    ot_photo_face_info face_info[OT_PHOTO_MAX_FACE_NUM];
} ot_photo_hdr_attr;

【成员】

成员名称	描述
src_frm	每次HDR处理的源图像帧信息。（结构体的定义请参考《MPP 媒体处理软件V5.0 开发参考》“系统控制”章节的描述）
des_frm	HDR处理的输出图像帧信息。需要用户提前从VB池中分配。第一帧HDR处理时需要传入，后面两帧处理时需与第一帧的值一致。
frm_index	HDR处理的帧序号，从0开始。三帧HDR合成，该值应该依次为0, 1, 2；
iso	当前处理帧的ISO值。三帧的ISO值应该保持一致。
face_num	图像中检测到的人脸的个数。以中间那帧正常曝光帧上的人脸个数为准，其他两帧无效。取值范围：[0, 10]
face_info	人脸区域的信息的结构体。

【注意事项】

无

【相关数据类型及接口】

ot_photo_alg_attr

ot_photo_sfnr_attr¶

【说明】

定义SFNR算法处理的结构体。

【定义】

typedef struct {
    ot_video_frame_info frm;  /* src & des */
    td_u32 iso;
} ot_photo_sfnr_attr;

【成员】

成员名称	描述
frm	SFNR单帧降噪的源图帧信息结构体。 SFNR处理之后，将输出的图像写回到源图这块帧存。结构体的定义请参考《MPP 媒体处理软件V5.0 开发参考》文档“系统控制”章节的描述。
iso	当前处理帧的ISO值。

成员名称

描述

frm

SFNR单帧降噪的源图帧信息结构体。

SFNR处理之后，将输出的图像写回到源图这块帧存。

结构体的定义请参考《MPP 媒体处理软件V5.0 开发参考》文档“系统控制”章节的描述。

iso

当前处理帧的ISO值。

【注意事项】

无

【相关数据类型及接口】

ot_photo_alg_attr

ot_photo_mfnr_attr¶

【说明】

定义MFNR算法处理的结构体。

【定义】

typedef struct {
    ot_video_frame_info src_frm;
    ot_video_frame_info des_frm;
    ot_video_frame_info raw_frm;
    td_u32 frm_index;
    td_u32 iso;
} ot_photo_mfnr_attr;

【成员】

成员名称	描述
src_frm	每次MFNR处理的源图像帧信息。结构体的定义请参考《MPP 媒体处理软件V5.0 开发参考》文档“系统控制”章节的描述。
des_frm	MFNR处理的输出图像帧信息。需要用户提前从VB池中分配。第一帧MFNR处理时就需要传入，后面三帧处理时需与第一帧的值一致。
raw_frm	如果MFNR处理之后不需要做DE算法，那么该结构体不需要赋值。如果MFNR处理之后需要做DE算法，那么该结构体为DE算法需要的RAW数据的结构体。 MFNR的四帧处理中，只使用了frm_index为0的那帧对应的RAW数据，其余三帧传入的RAW数据结构体需要保持和frm_index为0的那帧RAW数据一致。
frm_index	MFNR处理的帧序号，从0开始。四帧MFNR处理，该值应该依次为0, 1, 2, 3；
iso	当前处理帧的ISO值。

【注意事项】

无

【相关数据类型及接口】

ot_photo_alg_attr

ot_photo_de_attr¶

【说明】

定义DE算法处理的结构体。

【定义】

typedef struct {
    ot_video_frame_info frm;  /* src & des */
    ot_video_frame_info raw_frm;
    td_u32 iso;
} ot_photo_de_attr;

【成员】

成员名称	描述
frm	DE细节增强算法的源图YUV数据帧信息结构体。DE处理之后，将输出的YUV图像写回到源图这块帧存。结构体的定义请参考《MPP 媒体处理软件V5.0 开发参考》文档“系统控制”章节的描述。
raw_frm	DE细节增强算法需要的RAW数据帧信息结构体。
iso	当前处理帧的ISO值。

成员名称

描述

frm

DE细节增强算法的源图YUV数据帧信息结构体。DE处理之后，将输出的YUV图像写回到源图这块帧存。

结构体的定义请参考《MPP 媒体处理软件V5.0 开发参考》文档“系统控制”章节的描述。

raw_frm

DE细节增强算法需要的RAW数据帧信息结构体。

iso

当前处理帧的ISO值。

【注意事项】

无

【相关数据类型及接口】

ot_photo_alg_attr

ot_photo_face_info¶

【说明】

定义人脸区域信息的结构体。

【定义】

typedef struct {
    td_u32 id;
    ot_rect face_rect;
    ot_rect left_eye_rect;
    ot_rect right_eye_rect;
    td_u32 blink_score;
    td_u32 smile_score;
} ot_photo_face_info;

【成员】

成员名称	描述
id	当前人脸区域的ID。
face_rect	当前人脸区域的坐标信息。结构体的定义请参考《MPP 媒体处理软件V5.0 开发参考》文档“系统控制”章节的描述。
left_eye_rect	当前人脸中左眼的坐标信息。保留，暂时无效。
right_eye_rect	当前人脸中右眼的坐标信息。保留，暂时无效。
blink_score	当前人脸中眼睛闭合程度的值。保留，暂时无效。
smile_score	当前人脸中笑脸检测的程度的值。保留，暂时无效。

【注意事项】

无

【相关数据类型及接口】

ot_photo_hdr_attr

ot_photo_alg_coef¶

【说明】

定义PHOTO算法系数的结构体。

【定义】

typedef struct {
    union {
        ot_photo_hdr_coef hdr_coef;
        ot_photo_sfnr_coef sfnr_coef;
        ot_photo_mfnr_coef mfnr_coef;
        ot_photo_de_coef de_coef;
    };
} ot_photo_alg_coef;

【成员】

成员名称	描述
hdr_coef	HDR算法系数的结构体，默认参数： #define FLOAT_INT_SHIFT (1ULL<<32) ot_photo_hdr_coef g_hdr_coef = { .ajust_ratio =128, .image_scale_method =1, .motion_detection_param = { {160, 10, 20, 6.0* FLOAT_INT_SHIFT, 15}, {240, 10, 20, 6.0* FLOAT_INT_SHIFT, 15}, {320, 10, 20, 6.0* FLOAT_INT_SHIFT, 15}, {640, 10, 20, 6.0* FLOAT_INT_SHIFT, 15}, {960, 10, 20, 6.0* FLOAT_INT_SHIFT, 15}, {1280, 15, 25, 6.0* FLOAT_INT_SHIFT, 15}, {1600, 20, 30, 6.0* FLOAT_INT_SHIFT, 15}, {1920, 25, 35, 6.0* FLOAT_INT_SHIFT, 15}, {2560, 30, 40, 6.0* FLOAT_INT_SHIFT, 15}, {6400, 30, 50, 6.0* FLOAT_INT_SHIFT, 15}, }, .hdr_image_fusion_param = { {160, 16, 1, 0, 160, 128, 128, 0.25* FLOAT_INT_SHIFT}, {240, 16, 1, 0, 150, 128, 128, 0.25* FLOAT_INT_SHIFT}, {320, 16, 1, 0, 140, 128, 128, 0.25* FLOAT_INT_SHIFT}, {640, 16, 1, 0, 130, 128, 128, 0.25* FLOAT_INT_SHIFT}, {960, 16, 1, 0, 128, 128, 128, 0.25* FLOAT_INT_SHIFT}, {1280, 16, 1, 0, 128, 128, 128, 0.25* FLOAT_INT_SHIFT}, {1600, 16, 1, 0, 128, 128, 128, 0.25* FLOAT_INT_SHIFT}, {1920, 16, 1, 0, 128, 128, 128, 0.25* FLOAT_INT_SHIFT}, {2560, 16, 1, 0, 128, 128, 128, 0.25* FLOAT_INT_SHIFT}, {6400, 16, 1, 0, 128, 128, 128, 0.25* FLOAT_INT_SHIFT} } };
sfnr_coef	SFNR算法系数的结构体，默认参数： ot_photo_sfnr_coef g_sfnr_coef = { .ast_iso_strat = { {100, -100, -85, -85, -90}, {200, -95, -85, -75, -85}, {400, -90, -75, -75, -80}, {600, -80, -70, -65, -70}, {800, -70, -60, -60, -65}, {1200, -65, -60, -55, -60}, {1600, -60, -60, -50, -55}, {3200, -50, -40, -45, -50} } };
mfnr_coef	MFNR算法系数的结构体，默认参数： ot_photo_mfnr_coef g_mfnr_coef = { .de_enable = TD_FALSE, .image_scale = TD_TRUE, .mfnr_2dnr.iso_2dnr_param= { {100, -90, -90, -90, 3}, {200, -90, -85, -90, 3}, {400, -90, -85, -90, 3}, {800, -80, -80, -90, 3}, {1600, -80, -78, -60, 3}, {3200, -80, -75, -60, 3}, {4800, -80, -75, -55, 3}, {6400, -80, -65, -50, 1}, }, .mfnr_3dnr.iso_3dnr_param= { {100, 240, 4, 0, 80, 12, 4, 12, 3}, {200, 210, 4, 0, 100, 12, 5, 12, 3}, {400, 180, 4, 0, 130, 12, 6, 12, 4}, {800, 160, 4, 0, 160, 12, 7, 12, 4}, {1600, 150, 4, 0, 190, 12, 8, 12, 5}, {3200, 136, 4, 32, 220, 12, 9, 12, 5}, {6400, 128, 4, 48, 255, 12, 10, 12, 6}, {12800, 128, 4, 64, 255, 12, 12, 12, 8} } };
de_coef	DE算法系数的结构体，默认参数： ot_photo_de_coef g_de_coef = { .de_iso_strat = { {100, 164, 9, 9, 9, 70, 210, 32, 140, 200, 160}, {200, 164, 9, 9, 9, 70, 210, 32, 140, 200, 160}, {400, 164, 9, 9, 9, 70, 210, 32, 140, 200, 160}, {800, 164, 9, 9, 9, 70, 210, 32, 140, 200, 160}, {1600, 164, 9, 9, 9, 70, 210, 32, 140, 200, 160}, {3200, 164, 9, 9, 9, 70, 210, 32, 140, 200, 160}, {4800, 164, 9, 9, 9, 70, 210, 32, 140, 200, 160}, {6400, 164, 9, 9, 9, 70, 210, 32, 140, 200, 160} } };

【注意事项】

无

【相关数据类型及接口】

ss_mpi_photo_set_alg_coef
ss_mpi_photo_get_alg_coef

ot_photo_hdr_coef¶

【说明】

定义HDR算法系数的结构体。

【定义】

typedef struct {
    td_s32 ajust_ratio;
    td_s32 image_scale_method;
    ot_photo_dark_motion_detection_param motion_detection_param[OT_PHOTO_HDR_ISO_LEVEL_CNT];
    ot_photo_image_fusion_param hdr_image_fusion_param[OT_PHOTO_HDR_ISO_LEVEL_CNT];
} ot_photo_hdr_coef;

【成员】

成员名称	描述
ajust_ratio	人脸系数衰减长曝和短曝帧的权重。取值范围：[0, 255]
image_scale_method	输出图像缩放插值方式。 0：双线性插值； 1：Lanczos插值。
motion_detection_param	鬼影检测参数结构体。
hdr_image_fusion_param	图像融合参数的结构体。

【注意事项】

无

【相关数据类型及接口】

ot_photo_alg_coef

ot_photo_image_fusion_param¶

【说明】

定义图像融合参数的结构体。

【定义】

typedef struct {
    td_s32 iso_speed;
    td_s32 pyramid_top_size;
    td_s32 weight_curve_method;
    td_s32 weight_calc_method;
    td_s32 blend_uv_gain;
    td_s32 detail_enhance_ratio_l0;
    td_s32 detail_enhance_ratio_l1;
    td_float blend_sigma;
    ot_photo_hdr_fusion_mode fusion_mode;
} ot_photo_image_fusion_param;

【成员】

成员名称	描述
iso_speed	算法每个档位的ISO值。取值范围：[160, 6400]
pyramid_top_size	金字塔最顶层宽/高大小限制取值范围：[16, 128]
weight_curve_method	权重曲线： 0：公用一个高斯曲线以亮度为变量的正态分布曲线，标准差为blend_sigma 1：分别设置各自曲线，分段方式每帧各自生成，每个曲线衰减部分由blend_sigma控制，越大衰减越快
weight_calc_method	权重查表： 0：表示各自帧按照亮度查各自对应曲线 1：表示在权重曲线weight_calc_method=1时候，只用中曝光亮度查三条曲线
blend_uv_gain	融合后UV增强系数。取值范围：[128,255]
detail_enhance_ratio_l0	金字塔重建，第0层回叠系数。取值范围：[0,1024] 增强大边
detail_enhance_ratio_l1	金字塔重建，第1层回叠系数。取值范围：[0,1024] 增强细节
blend_sigma	正态分布曲线标准差。取值范围：[0.00,4.00]
fusion_mode	hdr融合模式取值范围：[OT_PHOTO_HDR_FUSION_AUTO, OT_PHOTO_HDR_FUSION_ALL]

【注意事项】

无

【调试建议】

图 1 公用曲线

图 2 各自曲线

融合模式(weight_curve_method, weight_calc_method)

当融合模式为(weight_curve_method = 0, weight_calc_method = 0) 选择公用曲线，短帧，中帧，长帧分别以公用曲线算对应融合权重。
当融合模式为(weight_curve_method = 0, weight_calc_method = 1) 选择公用曲线，只用中帧算对应权重，相当于短帧，中帧，长帧的平均，短帧，中帧，长帧权重都一样。注意：当blend_sigma值非常小时（如小于0.1时），融合权重会以中帧为主。
当融合模式为(weight_curve_method = 1, weight_calc_method = 0) 选择各自曲线，短帧选择high曲线，中帧选择mid曲线，长帧选择dark曲线得到融合权重。
当融合模式为(weight_curve_method = 1, weight_calc_method = 1) 选择各自曲线，只用中帧计算融合权重，中帧选择high曲线作为短帧权重，中帧选择mid曲线作为中帧权重，中帧选择dark曲线作为长帧权重。

【相关数据类型及接口】

ot_photo_hdr_coef

ot_photo_dark_motion_detection_param¶

【说明】

定义HDR中鬼影检测参数的结构体。

【定义】

typedef struct {
    td_s32 iso_speed;
    td_s32 motion_low_gray;
    td_s32 motion_high_gray;
    td_float motion_ratio;
    td_s32 night_average_luma;
} ot_photo_dark_motion_detection_param;

【成员】

成员名称	描述
iso_speed	算法每个档位的ISO值。取值范围：[160, 6400]
motion_low_gray	参考帧暗区，运动检测阈值取值范围：[0, 255]
motion_high_gray	参考帧亮区，运动检测阈值取值范围：[0, 255]
motion_ratio	运动区域比例阈值，若大于阈值则不做运动矫正，丢弃当前处理帧取值范围：[0, 100]
night_average_luma	参考帧亮度判断夜景阈值取值范围：[0, 255]

【注意事项】

无

【相关数据类型及接口】

ot_photo_hdr_coef

ot_photo_sfnr_coef¶

【说明】

定义SFNR算法系数的结构体。

【定义】

typedef struct {
    ot_photo_sfnr_iso_strategy  ast_iso_strat[OT_PHOTO_SFNR_ISO_LEVEL_CNT];
} ot_photo_sfnr_coef;

【成员】

成员名称	描述
ast_iso_strat	算法每ISO档位对应的结构体。

【注意事项】

无

【相关数据类型及接口】

ot_photo_alg_coef

ot_photo_sfnr_iso_strategy¶

【说明】

定义SFNR算法ISO策略的结构体。

【定义】

typedef struct {
    td_s32 iso_value;
    td_s32 luma;
    td_s32 chroma;
    td_s32 luma_hf;
    td_s32 chroma_hf;
} ot_photo_sfnr_iso_strategy;

【成员】

成员名称	描述
iso_value	算法每个档位的ISO值。取值范围：[100, 3200]
luma	亮度低频去噪强度，数字越大去噪强度越强取值范围：[-100, 0]
chroma	色度低频去噪强度，数字越大去噪强度越强取值范围：[-100, 0]
luma_hf	亮度中高频去噪强度，数字越大去噪强度越强取值范围：[-100, 0]
chroma_hf	色度中高频去噪强度，数字越大去噪强度越强取值范围：[-100, 0]

【注意事项】

无

【相关数据类型及接口】

ot_photo_sfnr_coef

ot_photo_mfnr_coef¶

【说明】

定义MFNR算法系数的结构体。

【定义】

typedef struct {
    td_bool image_scale;
    ot_photo_mfnr_3dnr_param mfnr_3dnr;
    ot_photo_mfnr_2dnr_param mfnr_2dnr;
    td_bool de_enable;
    ot_photo_de_coef mfnr_de_coef;
} ot_photo_mfnr_coef;

【成员】

成员名称	描述
bImageScale	MFNR输出的结果是否将配准公共区域裁出缩放到原图大小。 TD_TRUE：表示缩放配准的公共区域； TD_FALSE：不缩放，公共区域外采用填充方式；
mfnr_3dnr	MFNR算法中时域降噪系数的结构体。
mfnr_2dnr	MFNR算法中空域降噪系数的结构体。
de_enable	MFNR处理之后，是否再做DE算法。
mfnr_de_coef	DE算法系数的结构体。

【注意事项】

无

【相关数据类型及接口】

ot_photo_alg_coef

ot_photo_mfnr_3dnr_param¶

【说明】

定义MFNR算法中时域降噪系数的结构体。

【定义】

typedef struct {
    ot_photo_mfnr_3dnr_iso_strategy  iso_3dnr_param[OT_PHOTO_MFNR_ISO_LEVEL_CNT];
} ot_photo_mfnr_3dnr_param;

【成员】

成员名称	描述
iso_3dnr_param	MFNR算法时域降噪系数中每个ISO档位对应的结构体。

【注意事项】

无

【相关数据类型及接口】

ot_photo_mfnr_coef

ot_photo_mfnr_3dnr_iso_strategy¶

【说明】

定义MFNR算法时域降噪系数中每个ISO档位的结构体。

【定义】

typedef struct {
    td_s32 iso_value;
    td_s32 stnr;
    td_s32 tnr_frm_num;
    td_s32 stnr_dark_less;
    td_s32 stnr_ghost_less;
    td_s32 luma_alpha;
    td_s32 luma_delta;
    td_s32 chroma_alpha;
    td_s32 chroma_delta;
} ot_photo_mfnr_3dnr_iso_strategy;

【成员】

成员名称	描述
iso_value	算法每个档位的ISO值取值范围：[100, 12800]
stnr	使用时域与空域的强度比，数字越大使用越多时域效果。取值范围：[0, 255]
tnr_frm_num	参与时域降噪的帧数。取值范围：[1, 4]
stnr_dark_less	暗处使用空域效果的强度，像素值小于此值时使用较多空域效果。取值范围：[0, 255]
stnr_ghost_less	鬼影区域模糊强度，数字越大越模糊。取值范围：[0, 255]
luma_alpha	亮度比阈值，当两帧亮度比大于此阈值时，执行去噪或去鬼影。取值范围：[0, 255]
luma_delta	亮度差阈值，当两帧亮度之差大于此阈值时，执行去噪或去鬼影。取值范围：[0, 255]
chroma_alpha	色度比阈值，当两帧色度比大于此阈值时，执行去噪或去鬼影取值范围：[0, 255]
chroma_delta	色度差阈值，当两帧色度之差大于此阈值时，执行去噪或去鬼影。取值范围：[0, 255]

【注意事项】

无

【相关数据类型及接口】

ot_photo_mfnr_3dnr_param

ot_photo_mfnr_2dnr_param¶

【说明】

定义MFNR算法中空域降噪系数的结构体。

【定义】

typedef struct {
    ot_photo_mfnr_2dnr_iso_strategy  iso_2dnr_param[OT_PHOTO_MFNR_ISO_LEVEL_CNT];
} ot_photo_mfnr_2dnr_param;

【成员】

成员名称	描述
iso_2dnr_param	MFNR算法空域降噪系数中每个ISO档位对应的结构体。

【注意事项】

无

【相关数据类型及接口】

ot_photo_mfnr_coef

ot_photo_mfnr_2dnr_iso_strategy¶

【说明】

定义MFNR算法空域降噪系数中每个ISO档位的结构体。

【定义】

typedef struct {
    td_s32 iso_value;
    td_s32 luma;
    td_s32 chroma;
    td_s32 luma_hf2;
    td_s32 detail_min;
} ot_photo_mfnr_2dnr_iso_strategy;

【成员】

成员名称	描述
iso_value	算法每个档位的ISO值取值范围：[100, 12800]
luma	亮度低频去噪强度，数字越大去噪强度越强。取值范围：[-100, 0]
chroma	色度低频去噪强度，数字越大去噪强度越强。取值范围：[-100, 0]
luma_hf2	亮度中高频去噪强度，数字越大去噪强度越强。取值范围：[-100, 0]
detail_min	亮度高频保留强度，数字越大保留越多。取值范围：[0, 8]

【注意事项】

无

【相关数据类型及接口】

ot_photo_mfnr_2dnr_param

ot_photo_de_coef¶

【说明】

定义DE算法系数的结构体。

【定义】

typedef struct {
    ot_photo_de_iso_strategy  de_iso_strat[OT_PHOTO_DE_ISO_LEVEL_CNT];
} ot_photo_de_coef;

【成员】

成员名称	描述
de_iso_strat	DE算法中每个ISO档位对应策略的结构体。

【注意事项】

无

【相关数据类型及接口】

ot_photo_alg_coef

ot_photo_de_iso_strategy¶

【说明】

定义DE算法每个ISO档位对应策略的结构体。

【定义】

typedef struct {
    td_s32 iso_value;
    td_s32 global_gain;
    td_s32 gain_lf;
    td_s32 gain_hf_pos;
    td_s32 gain_hf_neg;
    td_s32 luma_scale_x0;
    td_s32 luma_scale_x1;
    td_s32 luma_scale_y1;
    td_s32 satu_gain_x0;
    td_s32 satu_gain_x1;
    td_s32 satu_gain_y1;
} ot_photo_de_iso_strategy;

【成员】

成员名称	描述
iso_value	算法每个档位的ISO值取值范围：[100, 6400]
global_gain	全局细节强度系数，数字越大越强。取值范围：[0, 255]
gain_lf	低频比例，数字越大越强。取值范围：[0, 255]
gain_hf_pos	高频白点比例，数字越大越强。取值范围：[0, 255]
gain_hf_neg	高频黑点比例，数字越大越强。取值范围：[0, 255]
luma_scale_x0	亮度拉伸低阈值。取值范围：[0, 255]
luma_scale_x1	亮度拉伸高阈值。取值范围：[0, 255]
luma_scale_y1	亮度拉伸高阈值，对应衰减系数。取值范围：[0, 255]
satu_gain_x0	饱和度低阈值。取值范围：[0, 255]
satu_gain_x1	饱和度高阈值。取值范围：[0, 255]
satu_gain_y1	饱和度高阈值，对应衰减系数。取值范围：[0, 255]

【注意事项】

无

【相关数据类型及接口】

ot_photo_de_coef

ot_photo_hdr_fusion_mode¶

【说明】

定义HDR融合模式。

【定义】

typedef enum {
    OT_PHOTO_HDR_FUSION_AUTO = 0,
    OT_PHOTO_HDR_FUSION_SHORT_MEDIAN = 1,
    OT_PHOTO_HDR_FUSION_MEDIAN_LONG = 2,
    OT_PHOTO_HDR_FUSION_ALL = 3,
    OT_PHOTO_HDR_FUSION_BUTT
} ot_photo_hdr_fusion_mode;

【成员】

成员名称	描述
OT_PHOTO_HDR_FUSION_AUTO	自动模式，算法自动选择融合方式
OT_PHOTO_HDR_FUSION_SHORT_MEDIAN	强制短帧与中帧融合
OT_PHOTO_HDR_FUSION_MEDIAN_LONG	强制中帧与长帧融合
OT_PHOTO_HDR_FUSION_ALL	强制短帧、中帧和长帧融合

【注意事项】

当自动模式选择不做融合，直接输出中帧时，如果暗区亮度不足时，可以选择使用OT_PHOTO_HDR_FUSION_MEDIAN_LONG，OT_PHOTO_HDR_FUSION_ALL模式提高暗区亮度。
当自动模式选择不做融合，直接输出中帧时，如果亮区过亮时，可以选择使用OT_PHOTO_HDR_FUSION_SHORT_MEDIAN模式压制亮区亮度。
具体融合权重参考weight_curve_method, weight_calc_method参数的调试建议。

【相关数据类型及接口】

ot_photo_image_fusion_param

OT_PHOTO_HDR_FRAME_NUM¶

【说明】

定义HDR合成的帧数目。

【定义】

#define OT_PHOTO_HDR_FRAME_NUM 3

【注意事项】

无。

【相关数据类型及接口】

无。

OT_PHOTO_MFNR_FRAME_NUM¶

【说明】

定义MFNR合成的帧数目。

【定义】

#define OT_PHOTO_MFNR_FRAME_NUM 4

【注意事项】

无。

【相关数据类型及接口】

无。

OT_PHOTO_HDR_ISO_LEVEL_CNT¶

【说明】

定义调节HDR图像效果的ISO档位数目。

【定义】

#define OT_PHOTO_HDR_ISO_LEVEL_CNT 10

【注意事项】

无。

【相关数据类型及接口】

无。

OT_PHOTO_SFNR_ISO_LEVEL_CNT¶

【说明】

定义调节SFNR图像效果的ISO档位数目。

【定义】

#define OT_PHOTO_SFNR_ISO_LEVEL_CNT 8

【注意事项】

无。

【相关数据类型及接口】

无。

OT_PHOTO_MFNR_ISO_LEVEL_CNT¶

【说明】

定义调节MFNR图像效果的ISO档位数目。

【定义】

#define OT_PHOTO_MFNR_ISO_LEVEL_CNT    8

【注意事项】

无。

【相关数据类型及接口】

无。

OT_PHOTO_DE_ISO_LEVEL_CNT¶

【说明】

定义调节DE图像效果的ISO档位数目。

【定义】

#define OT_PHOTO_DE_ISO_LEVEL_CNT 8

【注意事项】

无。

【相关数据类型及接口】

无。

OT_PHOTO_MAX_FACE_NUM¶

【说明】

定义算法处理中最大的人脸区域的数目。

【定义】

#define OT_PHOTO_MAX_FACE_NUM  10

【注意事项】

无。

【相关数据类型及接口】

无。

OT_PHOTO_MIN_WIDTH¶

【说明】

定义算法处理支持的最小图像分辨率的宽。

【定义】

#define OT_PHOTO_MIN_WIDTH     1280

【注意事项】

无。

【相关数据类型及接口】

无。

OT_PHOTO_MIN_HEIGHT¶

【说明】

定义算法处理支持的最小图像分辨率的高。

【定义】

#define OT_PHOTO_MIN_HEIGHT    720

【注意事项】

无。

【相关数据类型及接口】

无。

OT_PHOTO_MAX_WIDTH¶

【说明】

定义算法处理支持的最大图像分辨率的宽。

【定义】

#define OT_PHOTO_MAX_WIDTH     8192

【注意事项】

无。

【相关数据类型及接口】

无。

OT_PHOTO_MAX_HEIGHT¶

【说明】

定义算法处理支持的最大图像分辨率的高。

【定义】

#define OT_PHOTO_MAX_HEIGHT    6144

【注意事项】

HDR算法的最大图像分辨率的高由OT_PHOTO_HDR_MAX_HEIGHT定义。

【相关数据类型及接口】

无。

OT_PHOTO_HDR_MAX_HEIGHT¶

【说明】

定义HDR算法处理支持的最大图像分辨率的高。

【定义】

#define OT_PHOTO_HDR_MAX_HEIGHT    8192

【注意事项】

无。

【相关数据类型及接口】

无。

错误码¶

PHOTO模块API错误码如下所示。

表 1 PHOTO模块API错误码

错误代码	宏定义	描述
0xa0268001	OT_ERR_PHOTO_INVALID_DEVID	拍照算法设备号无效
0xa0268003	OT_ERR_PHOTO_INVALID_CHNID	拍照算法通道号无效
0xa0268007	OT_ERR_PHOTO_ILLEGAL_PARAM	输入参数设置无效
0xa0268008	OT_ERR_PHOTO_EXIST	拍照算法已存在
0xa0268009	OT_ERR_PHOTO_UNEXIST	拍照算法不存在
0xa026800a	OT_ERR_PHOTO_NULL_PTR	输入参数空指针错误
0xa026800b	OT_ERR_PHOTO_NOT_CFG	拍照算法属性未配置
0xa026800c	OT_ERR_PHOTO_NOT_SUPPORT	操作不支持
0xa026800d	OT_ERR_PHOTO_NOT_PERM	操作不允许
0xa0268014	OT_ERR_PHOTO_NO_MEM	分配内存失败
0xa0268015	OT_ERR_PHOTO_NO_BUF	分配缓存失败
0xa0268016	OT_ERR_PHOTO_BUF_EMPTY	缓存为空
0xa0268018	OT_ERR_PHOTO_NOT_READY	系统未初始化
0xa0268022	OT_ERR_PHOTO_BUSY	系统忙

视频采集类抓拍方案使用指南¶

概述¶

视频采集类抓拍方案主要是面向视频采集产品中的电子警察、卡口视频采集等场景下的抓拍解决方案。视频采集类抓拍方案和消费类抓拍的显著区别是客户的定制化程度较高，与外设的交互也很多。

数据通路¶

视频采集类抓拍机的产品形态较多，典型的数据通路如图1所示。

图 1 视频采集类抓拍机典型数据通路

视频采集类抓拍机需要控制外部设备爆闪灯和频闪灯，同时需要接收交通信号灯信号、抓拍触发信号等。sensor的时序控制和AE调节需要和交通信号灯保持同步，因此需要使用客户自定义的ISP 3A算法。

实时性要求较高的场景，一般是由客户实现的FPGA来完成sensor时序的控制，爆闪灯和频闪灯的控制等。抓拍帧的标记也是由FPGA来完成，一般是在sensor输入的有效数据后额外增加几行有效数据，在里面标识是否是抓拍帧，以及其他一些客户需要的自定义信息。

从Pipe0-FE采集的RAW数据需要识别抓拍帧，同时送给不同的Pipe做后续处理。在送BE做处理之前，需要客户自己将RAW数据中额外增加的那几行自定义信息裁剪掉，防止对BE处理的图像效果有影响。当前VI Pipe要求FE写出的宽高和BE处理的宽高必须一致，所以Pipe0那一路FE写出的RAW经过裁剪后无法再送到Pipe0那一路的BE做处理，可以再起一个新的Pipe来替代Pipe0-BE。

抓拍帧的处理和视频帧不同，视频帧的ISP图像效果参数配置可以参考前一帧的统计信息计算当前帧的配置。但是抓拍帧只有一帧，没用参考帧，因此需要将抓拍帧的RAW送到Pipe2-BE两次，第一次用于生成抓拍帧的统计信息，然后根据统计信息计算出ISP的参数配置信息，再用正确的参数配置信息和抓拍帧RAW数据再做一次BE的处理，才能生成正确的抓拍帧YUV数据。

ISP算法的运行一般是由每帧的帧起始中断来驱动，但是在抓拍机的场景中都是离线送RAW数据给BE做处理的，并不适合用帧起始中断，因此需要用户程序来驱动ISP运行。在每次送RAW数据给BE做处理之前，需要调用ss_mpi_isp_run_once生成当前帧需要的寄存器配置信息，替代ss_mpi_isp_run函数做的处理。

ss_mpi_isp_run_once会获取ISP处理完上一帧图像时生成的统计信息，因此，需要保证上一帧图像已经处理完成，才调用ss_mpi_isp_run_once，否则获取ISP统计信息是旧的，可能导致图像效果不符合预期。如何保证？我们可以调用ss_mpi_vi_get_chn_frame(VPSS离线)或者ss_mpi_vpss_get_chn_frame(VPSS在线)接口获取通道数据成功来保证上一帧已经处理完成。

程序调用流程¶

程序调用流程请参考mpp/sample/ traffic_capture中的代码实现。

程序中用到的接口请参考《ISP 开发参考》和《MPP 媒体处理软件V5.0 开发参考》。