EasyVQD/pkg/vqdcms/include/nxu_vqd_api.h
2026-01-23 18:05:36 +08:00

453 lines
18 KiB
C

/**
* @file nxu_vqd_api.h
* @brief VQD: Video Quality Diagnostic
*
* 视频质量诊断, 包括偏色, 过亮, 过暗, 模糊, 噪点等
*
* @author jwzhou (zhou24388@163.com)
* @version 1.0.0
* @date 2024-06-26
*
* @copyright Copyright (c) 2024 NXU Co,.Ltd.
*
* @par 修订历史:
* Date : 2024-07-17
* version : 2.0.0
* Author : jwzhou
* Log : 新增花屏和马赛克,内部识别增加深度学习版本
* copyright: Copyright (c) 2024 NXU Co,.Ltd.
*
* @par 修改日志:
* Date : 2024-06-29
* version : 1.0.1
* Author : jwzhou
* Log : 修改几个默认的值
* copyright: Copyright (c) 2024 NXU Co,.Ltd.
*/
#ifndef __NXU_VQD_API_H__
#define __NXU_VQD_API_H__
#include "nxu_common.h"
#include <stdio.h>
#ifdef __cplusplus
extern "C"
{
#endif
/* ********************************************************************** */
/* .............................. Para Start ........................ */
/* ********************************************************************** */
/* 偏色参数
NEW: 新增深度学习版本 20240717
*/
typedef struct __nxu_vqd_color_para_s
{
/* 偏色判断值, 大于该值即为偏色,
默认为0.18, 取值范围: 0~1, 建议范围: 0.1~0.5,
该值设置过小, 误报会增多, 值设置的越大, 越不灵敏, 就是偏色严重才算偏色
NEW: 新增深度学习版本 20240717
默认为 0.1 取值范围: 0~1, 建议范围: 0.1~0.9,
大于该值判定为偏色, 小于该值判定为正常,
*/
NXU_FLOAT f32ColorThr;
/* 偏色次数比例,
默认为0.5, 取值范围: 0~1, 建议范围: 0.3~0.9 */
NXU_FLOAT f32ColorAbnNumRatio;
NXU_FLOAT f32Resverd1; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd2; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd3; /* 保留,暂时不设置,默认 -999 */
} NXU_VQD_Color_Para_S;
/* 亮暗参数
NEW: 新增深度学习版本 20240717
*/
typedef struct __nxu_vqd_lightdark_para_s
{
/* 超过200的像素比例,过亮阈值,
默认 0.1, 取值范围: 0~1, 建议范围: 0.1~0.5,
值设置的越大, 越不灵敏, 就是非常亮才算过亮
值设置的越小, 越灵敏, 太小的话误报会很多
NEW: 新增深度学习版本 20240717
默认为 0.1 取值范围: 0~1, 建议范围: 0.1~0.9,
大于该值判定为偏色, 小于该值判定为正常,
*/
NXU_FLOAT f32LightThr;
/* 低于55的像素比例,过暗阈值,
默认 0.4, 取值范围: 0~1, 建议范围: 0.2~0.6
值设置的越大, 越不灵敏, 就是非常暗才算过暗
值设置的越小, 越灵敏, 太小的话误报会很多
NEW: 新增深度学习版本 20240717
默认为 0.1 取值范围: 0~1, 建议范围: 0.1~0.9,
大于该值判定为偏色, 小于该值判定为正常,
*/
NXU_FLOAT f32DarkThr;
/* 偏暗或者偏亮次数比例, 连续多次检测出现的次数比例
默认为0.5, 取值范围: 0~1, 建议范围: 0.3~0.9 */
NXU_FLOAT f32LgtDarkAbnNumRatio;
NXU_FLOAT f32Resverd1; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd2; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd3; /* 保留,暂时不设置,默认 -999 */
} NXU_VQD_LgtDark_Para_S;
/* 清晰度参数
NEW: 新增深度学习版本 20240717
*/
typedef struct __nxu_vqd_clarity_para_s
{
/* 清晰度判断阈值, 小于该值判定为模糊,
默认为0.4, 取值范围: 0~1, 建议范围: 0.3~0.99
值设置的越大, 越不灵敏, 太大的话误报模糊会很多
值设置的越小, 就是非常模糊才算模糊
NEW: 新增深度学习版本 20240717
默认为 0.1 取值范围: 0~1, 建议范围: 0.1~0.9,
大于该值判定为偏色, 小于该值判定为正常,
*/
NXU_FLOAT f32ClarityThr;
/* 清晰度异常次数比例,
默认为0.5, 取值范围: 0~1, 建议范围: 0.3~0.9 */
NXU_FLOAT f32ClarityAbnNumRatio;
NXU_FLOAT f32Resverd1; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd2; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd3; /* 保留,暂时不设置,默认 -999 */
} NXU_VQD_Clarity_Para_S;
/* 噪声参数
NEW: 新增深度学习版本 20240717
*/
typedef struct __nxu_vqd_noise_para_s
{
/* 噪声判断阈值,
默认为 0.3, 取值范围: 0~1, 建议范围: 0.2~0.8
设置过小, 容易误报, 设置过大, 容易漏报, 根据情况进行调整
NEW: 新增深度学习版本 20240717
默认为 0.1 取值范围: 0~1, 建议范围: 0.1~0.9,
大于该值判定为偏色, 小于该值判定为正常,
*/
NXU_FLOAT f32NoiseThr;
/* 噪声次数比例,
默认为0.6, 取值范围: 0~1, 建议范围: 0.3~0.9 */
NXU_FLOAT f32NoiseAbnNumRatio;
NXU_FLOAT f32Resverd1; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd2; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd3; /* 保留,暂时不设置,默认 -999 */
} NXU_VQD_Noise_Para_S;
/* 遮挡参数 */
typedef struct __nxu_vqd_occlusion_para_s
{
/* 遮挡判断阈值, 大于该值判定为遮挡
默认为0.1, 取值范围: 0~1, 建议范围: 0.05~0.5
设置过小, 容易误报, 设置过大, 容易漏报, 根据情况进行调整 */
NXU_FLOAT f32OcclusionThr;
/* 遮挡次数比例
默认为0.5, 取值范围: 0~1, 建议范围: 0.3~0.9 */
NXU_FLOAT f32OcclusionAbnNumRatio;
NXU_FLOAT f32Resverd1; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd2; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd3; /* 保留,暂时不设置,默认 -999 */
} NXU_VQD_Occlusion_Para_S;
/* 对比度参数
NEW: 新增深度学习版本 20240717
*/
typedef struct __nxu_vqd_contrast_para_s
{
/* 低对比度判断阈值, 低于此值判定为低对比度,
默认为 0.2, 取值范围: 0~1, 建议范围: 0.1~0.3
NEW: 新增深度学习版本 20240717
默认为 0.1 取值范围: 0~1, 建议范围: 0.1~0.9,
大于该值判定为偏色, 小于该值判定为正常,
*/
NXU_FLOAT f32CtraLowThr;
/* 高对比度判断阈值, 高于该值判定为高对比度,
默认为 0.8, 取值范围: 0~1, 建议范围: 0.7~0.9 */
NXU_FLOAT f32CtraHighThr;
/* 对比度异常次数比例,
默认为0.5, 取值范围: 0~1, 建议范围: 0.3~0.9 */
NXU_FLOAT f32CtraAbnNumRatio;
NXU_FLOAT f32Resverd1; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd2; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd3; /* 保留,暂时不设置,默认 -999 */
} NXU_VQD_Contrast_Para_S;
/* 蓝屏参数
NEW: 新增深度学习版本 20240717
*/
typedef struct __nxu_vqd_blue_para_s
{
/* 蓝屏判断阈值, 蓝色像素占图像面积比例,
默认为 0.6, 取值范围: 0~1, 建议范围 0.4~0.9
NEW: 新增深度学习版本 20240717
默认为 0.1 取值范围: 0~1, 建议范围: 0.1~0.9,
大于该值判定为偏色, 小于该值判定为正常,
*/
NXU_FLOAT f32BlueThr;
/* 蓝屏次数比例, 连续多帧中蓝色占比
默认为0.5, 取值范围: 0~1, 建议范围: 0.3~0.9 */
NXU_FLOAT f32BlueAbnNumRatio;
NXU_FLOAT f32Resverd1; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd2; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd3; /* 保留,暂时不设置,默认 -999 */
} NXU_VQD_Blue_Para_S;
/* 抖动参数, 做抖动检测, 尽量隔帧取帧做, */
typedef struct __nxu_vqd_shark_para_s
{
/* 抖动阈值参数
全局运动均值, 无论是目标移动还是画面抖动, 全局运动均值相对来讲都会比较大,
默认为 0.2, 取值范围: 0~10, 建议范围: 0.1~0.8 */
NXU_FLOAT f32SharkThr;
/* 出现抖动次数的比例,
默认为0.2, 取值范围: 0~1, 建议范围: 0.1~0.6 */
NXU_FLOAT f32SharkAbnNumRatio;
/* 全局运动幅度方差阈值, 理论上来讲, 抖动为全局画面移动, 方向幅度具有一致性, 方差应较小
默认为0.2, 取值范围: 0~1, 建议范围: 0.05~0.5
如果内部有很多运动目标, 该值较大, 所以设置较大, 会使得在有运动目标时, 判定为抖动 */
NXU_FLOAT f32Resverd1;
/* 全局运动方向方差阈值, 小于该值时, 判定为全局运动, 可能会抖动
默认为0.2, 取值范围: 0~1, 建议范围: 0.05~0.5
如果内部有很多运动目标, 该值较大, 所以设置较大, 会使得在有运动目标时, 判定为抖动 */
NXU_FLOAT f32Resverd2;
NXU_FLOAT f32Resverd3; /* 保留,暂时不设置,默认 -999 */
} NXU_VQD_Shark_Para_S;
/* 冻结参数 */
typedef struct __nxu_vqd_freeze_para_s
{
/* 冻结阈值参数
静止的像素比例, 默认为0.999, 取值范围: 0.8~1, 建议范围: 0.99~1
如果画面静止, 该值比较大, 甚至会接近于1, */
NXU_FLOAT f32FreezeThr; /* 冻结阈值 */
/* 冻结帧数占得比例, 尽量设置的大一些, 避免那些无运动目标的静止监控画面
默认为0.99, 取值范围: 0.8~1, 建议范围: 0.95~1, */
NXU_FLOAT f32FreezeAbnNumRatio;
NXU_FLOAT f32Resverd1; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd2; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd3; /* 保留,暂时不设置,默认 -999 */
} NXU_VQD_Freeze_Para_S;
/* 马赛克检测
NEW: 新增深度学习版本 20240717
*/
typedef struct __nxu_vqd_mosaic_para_s
{
/* 马赛克阈值参数
NEW: 新增深度学习版本 20240717
默认为 0.1 取值范围: 0~1, 建议范围: 0.1~0.9,
大于该值判定为偏色, 小于该值判定为正常,
*/
NXU_FLOAT f32MosaicThr;
/* 马赛克次数比例, 连续多帧中马赛克占比
默认为0.5,取值范围: 0~1, 建议范围: 0.3
连续多帧中马赛克占比 */
NXU_FLOAT f32MosaicAbnNumRatio;
NXU_FLOAT f32Resverd1; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd2; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd3; /* 保留,暂时不设置,默认 -999 */
} NXU_VQD_Mosaic_Para_S;
/* 花屏检测 NEW NEW NEW NEW NEW
NEW: 新增深度学习版本 20240717
*/
typedef struct __nxu_vqd_flower_para_s
{
/* 花屏阈值参数
NEW: 新增深度学习版本 20240717
默认为 0.1 取值范围: 0~1, 建议范围: 0.1~0.9,
大于该值判定为偏色, 小于该值判定为正常,
*/
NXU_FLOAT f32FlowerThr;
/* 花屏次数比例, 连续多帧中花屏占比
默认为0.5, 取值范围: 0~1, 建议范围: 0.3
连续多帧中花屏占比 */
NXU_FLOAT f32FlowerAbnNumRatio;
NXU_FLOAT f32Resverd1; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd2; /* 保留,暂时不设置,默认 -999 */
NXU_FLOAT f32Resverd3; /* 保留,暂时不设置,默认 -999 */
} NXU_VQD_Flower_Para_S;
typedef enum __nxu_vqd_func_enable_type_e
{
NXU_VQD_DISABLE_ALL = 0x00000000, /* 所有功能关闭 */
NXU_VQD_ENABLE_COLOR = 0x00000001, /* 偏色检测 */
NXU_VQD_ENABLE_LGTDARK = 0x00000002, /* 亮度检测 */
NXU_VQD_ENABLE_CLARITY = 0x00000004, /* 模糊检测 */
NXU_VQD_ENABLE_NOISE = 0x0000008, /* 噪声检测 */
NXU_VQD_ENABLE_CONTRAST = 0x00000010, /* 对比度检测 */
NXU_VQD_ENABLE_OCCLUSION = 0x00000020, /* 遮挡检测 */
NXU_VQD_ENABLE_BLUE = 0x00000040, /* 蓝屏检测 */
NXU_VQD_ENABLE_SHARK = 0x00000100, /* 抖动检测 */
NXU_VQD_ENABLE_FREEZE = 0x00000200, /* 冻结检测 */
NXU_VQD_ENABLE_MOSAIC = 0x00000400, /* 马赛克检测 NEW: 新增深度学习版本 20240717*/
NXU_VQD_ENABLE_FLOWER = 0x00000800, /* 花屏检测 NEW: 新增深度学习版本 20240717*/
NXU_VQD_ENABLE_ALL = 0x0FFFFFFF, /* 所有功能打开 */
} NXU_VQD_FuncEnable_Type_E;
/* 总参数 */
typedef struct __nxu_vqd_para_s
{
NXU_S32 s32VecFrmNum; /* 连续分析帧数(2-64), 默认为10, 最大为 64 */
NXU_S32 s32EnableFunc; /* 功能使能,默认为 NXU_VQD_ENABLE_ALL,多项功能用或 */
NXU_VQD_Color_Para_S stColorPara; /* 偏色参数 */
NXU_VQD_LgtDark_Para_S stLgtDarkPara; /* 亮暗参数 */
NXU_VQD_Clarity_Para_S stClarityPara; /* 清晰度参数 */
NXU_VQD_Noise_Para_S stNoisePara; /* 噪声参数 */
NXU_VQD_Contrast_Para_S stContrastPara; /* 对比度参数 */
NXU_VQD_Occlusion_Para_S stOcclusionPara; /* 遮挡参数 */
NXU_VQD_Blue_Para_S stBluePara; /* 蓝屏参数 */
NXU_VQD_Shark_Para_S stSharkPara; /* 抖动参数 */
NXU_VQD_Freeze_Para_S stFreezePara; /* 冻结参数 */
NXU_VQD_Mosaic_Para_S stMosaicPara; /* 马赛克参数 NEW: 新增深度学习版本 20240717*/
NXU_VQD_Flower_Para_S stFlowerPara; /* 花屏参数 NEW: 新增深度学习版本 20240717*/
NXU_BOOL bUseDeepLearning; /* 是否使用深度学习版本, 默认使用深度学习版本 NEW: 20240717*/
} NXU_VQD_Para_S;
/**
* 如果返回的是多个异常类型, 则可以用与或来确定具体异常类型
*/
typedef enum __nxu_vqd_abnormal_type_e
{
NXU_VQD_NORMAL = 0x00000000, /* 正常, 无异常 */
NXU_VQD_ABN_COLORDEV = 0x00000001, /* 偏色异常 */
NXU_VQD_ABN_LIGHT = 0x00000002, /* 过亮异常 */
NXU_VQD_ABN_DARK = 0x00000004, /* 过暗异常 */
NXU_VQD_ABN_CLARITY = 0x00000008, /* 清晰度异常 */
NXU_VQD_ABN_NOISE = 0x00000010, /* 噪声异常 */
NXU_VQD_ABN_CONTRAST = 0x00000020, /* 对比度异常 */
NXU_VQD_ABN_OCCLUSION = 0x00000040, /* 遮挡异常 */
NXU_VQD_ABN_BLUE = 0x00000080, /* 蓝屏异常 */
NXU_VQD_ABN_SHARK = 0x00000100, /* 抖动异常 */
NXU_VQD_ABN_FREEZE = 0x00000200, /* 冻结异常 */
NXU_VQD_ABN_MOSAIC = 0x00000400, /* 马赛克异常 NEW: 新增深度学习版本 20240717*/
NXU_VQD_ABN_FLOWER = 0x00000800, /* 花屏异常 NEW: 新增深度学习版本 20240717*/
NXU_VQD_ABN_ALL = 0x0FFFFFFF, /* 所有的异常 */
NXU_VQD_ABN_UNKNOWN = 0xF0000000, /* 序列不满时, 返回未知 */
} NXU_VQD_Abnormal_Type_E;
/* 异常结果
当前各异常返回出来的值,作为参考,外面也可以存到列表中进行应用 */
typedef struct __nxu_vqd_result_s
{
NXU_S32 s32AbnormalType; /* 异常类型,多种类型的,利用与或来确定异常类型 */
NXU_FLOAT f32ColorDev; /* 偏色检测 */
NXU_FLOAT f32LgtDark; /* 亮度检测 */
NXU_FLOAT f32Dark; /* 暗度检测 */
NXU_FLOAT f32Clarity; /* 清晰度检测 */
NXU_FLOAT f32Noise; /* 噪声检测 */
NXU_FLOAT f32Contrast; /* 对比度检测 */
NXU_FLOAT f32Blue; /* 蓝屏检测 */
NXU_FLOAT f32Occlusion; /* 遮挡检测 */
NXU_FLOAT f32Shark; /* 抖动检测 */
NXU_FLOAT f32Freeze; /* 冻结检测 */
NXU_FLOAT f32Mosaic; /* 马赛克检测 NEW: 新增深度学习版本 20240717*/
NXU_FLOAT f32Flower; /* 花屏检测 NEW: 新增深度学习版本 20240717*/
NXU_S32 s32Resverd1; /* 保留,暂时不设置,默认 -999 */
NXU_S32 s32Resverd2; /* 保留,暂时不设置,默认 -999 */
NXU_S32 s32Resverd3; /* 保留,暂时不设置,默认 -999 */
} NXU_VQD_Result_S;
/* ********************************************************************** */
/* .............................. API Start ........................ */
/* ********************************************************************** */
/**
* @brief 创建算法句柄,加载算法模型,只用创建一次,就可以循环使用,每一次创建对应一次销毁
*
* @param phVQD 算法句柄
* @return NXU_EXPORTS
*/
NXU_EXPORTS NXU_STATUS_CODE_E NXU_VQD_Create(NXU_HANDLE *phVQD);
/**
* @brief 销毁算法句柄,使用完后记得销毁算法句柄
*
* @param hVQD 算法句柄
* @return 算法状态
*/
NXU_EXPORTS NXU_STATUS_CODE_E NXU_VQD_Destroy(NXU_HANDLE hVQD);
/**
* @brief 获取算法的版本号
*
* @param pcLibVerStr 算法库版本号
* @return 算法状态
*/
NXU_EXPORTS NXU_STATUS_CODE_E NXU_VQD_GetLibVer(NXU_S8 *pcLibVerStr);
/**
* @brief 算法配置
*
* @param hVQD 算法句柄
* @param pstPara 算法参数
*
* @return 算法状态
*/
NXU_EXPORTS NXU_STATUS_CODE_E
NXU_VQD_Config(NXU_HANDLE hVQD, const NXU_VQD_Para_S *pstPara);
/**
* @brief 算法处理
*
* @param hVQD 算法句柄
* @param pstImage 图像数据
* @return 算法状态
*/
NXU_EXPORTS NXU_STATUS_CODE_E
NXU_VQD_Process(NXU_HANDLE hVQD, const NXU_IMAGE_S *pstImage);
/**
* @brief 获取结果
*
* @param hVQD 算法句柄
* @param pstVQDResult 结果
* @return 算法状态
*/
NXU_EXPORTS NXU_STATUS_CODE_E
NXU_VQD_GetResults(NXU_HANDLE hVQD, NXU_VQD_Result_S *pstVQDResult);
/* ********************************************************************** */
/* .............................. API END.............................. */
/* ********************************************************************** */
#ifdef __cplusplus
}
#endif
#endif // !__NXU_VQD_API_H__