FIRSparse

滤波器就是对特定的频率或者特定频率以外的频率进行消除的电路，被广泛用于通信系统和信号处理系统中。从功能角度，数字滤波器对输入离散信号的数字代码进行运算处理，以达到滤除频带外信号的目的。而稀疏滤波是针对滤波器中具有较多的0值，只记录非0抽头的类型滤波器并进行信号处理。

滤波目标向量dst(y)通过滤波系数组nzTaps(b)与src(x)向量中采样信号x做卷积运算得。

计算公式如下：

$\text{[math]}$

dlyLine向量支持空值：如果dlyLine为空，该函数使用全零值的延迟线。

FIRSparse函数调用流程如下：

使用对应的FIRSparseInit函数进行初始化。
使用FIRSparse进行滤波操作。
再使用FIRSparseGetDlyLine或者FIRSparseSetDlyLine检索设置延迟线。
最后使用FIRSparseRelease对FIRSparseInit申请的内存进行释放。

函数接口声明如下：

初始化操作：
HmppResult HMPPS_FIRSparseInit_32f(const float *nzTaps, const int32_t *nzTapsPos, int32_t nzTapsLen, const float *dlyLine, HmppsFIRSparsePolicy_32f **policy);
获取延迟线操作：
HmppResult HMPPS_FIRSparseGetDlyLine_32f(const HmppsFIRSparsePolicy_32f *policy, float *dlyLine);;
设置延迟线操作：
HmppResult HMPPS_FIRSparseSetDlyLine_32f(HmppsFIRSparsePolicy_32f *policy, const float *dlyLine);
主函数操作：
HmppResult HMPPS_FIRSparse_32f(const float *src, float *dst, int32_t len, HmppsFIRSparsePolicy_32f *policy);
释放内存操作：
HmppResult HMPPS_FIRSparseRelease_32f(HmppsFIRSparsePolicy_32f *policy);

参数

参数名	描述	取值范围	输入/输出
nzTaps	指向包含非零抽头值的指针。	非空	输入
nzTapPos	指向包含非零抽头值位置(从0开始计)的指针。	非空，数组中的数据值需在[0, INT_MAX]范围内，且升序	输入
nzTapsLen	数组中具有非零抽头值的元素的数目。	(0, INT_MAX]	输入
dlyLine（init和setDly函数中）	指向包含延迟线值的指针。	数组中的元素数为nzTapPos[nzTapsLen - 1]，当dlyLine为NULL时，使用0填充	输入
dlyLine（getDly函数中）	指向延迟线值的指针。	非空	输出
src	指向源向量的指针。	非空	输入
len	源向量中的元素长度。	(0, INT_MAX]	输入
dst	指向目标向量的指针。	非空	输出
policy（init函数中）	指向内存存储FIRSparsePolicy的指针的指针。	非空	输出
policy（setDly函数中）	指向FIRSparsePolicy的指针。	非空	输出
policy（主函数、getDly函数和release函数中）	指向FIRSparsePolicy结构体的指针。	非空	输入

返回值

成功：返回HMPP_STS_NO_ERR。
失败：返回错误码。

错误码

错误码	描述
HMPP_STS_NO_ERR	表示没有错误。
HMPP_STS_NULL_PTR_ERR	当任何指定的指针为空时指示错误。
HMPP_STS_SIZE_ERR	当nzTapsLen或len小于或等于0时指示错误。
HMPP_STS_SPARSE_ERR	指示nzTapPos指针指向的数组内数值不是升序排序，或有负数或重复的数值出现。
HMPP_STS_OVERFLOW	指示计算溢出时错误。
HMPP_STS_MALLOC_FAILED	Init函数中进行算法模型所需内存申请失败。

注意

调用该接口计算之前，必须调用Init接口初始化FIRSparsePolicy规范结构。
FIRSparsePolicy结构体初始化需在Init函数中进行申请的，用户无法自己进行该结构体申请定义。
FIRSparsePolicy结构体初始化成功后，如果执行主函数失败，必须使用Release函数释放结构体。
src不能和dst是同一数组，否则结果正确性无法保证。

示例

#define TPAS_LEN_S 5
#define DLYLINE_LEN_S 8
#define SRC_LEN_S 7
void FIRSparseExample(void)
{
    int32_t nzTapsLen = TPAS_LEN_S;
    float nzTaps[TPAS_LEN_S] = { 0.1, 0.2, 0.3, 0.4, 0.5 };
    int32_t nzTapsPos[TPAS_LEN_S] = { 1, 3, 4, 6, DLYLINE_LEN_S };
    float *dlyLine1 = NULL;
    float dlyLine2[DLYLINE_LEN_S] = { 0.01, 0.02, 0.03, 0.04, 0.05, 0.06, 0.07, 0.08 };
    float dlyDst[DLYLINE_LEN_S] = { 0.0f };
    int32_t len = SRC_LEN_S;
    float src[SRC_LEN_S] = { 0.2107, -40.6842, 17.1776, -15.6654, -2.407, -0.8981, 0.2883 };
    float dst[SRC_LEN_S] = { 0.0f };

    HmppsFIRSparsePolicy_32f *policy = NULL;
    HmppResult result;

    result = HMPPS_FIRSparseInit_32f(nzTaps, nzTapsPos, nzTapsLen, dlyLine1, &policy);
    printf("HMPPS_FIRSparseInit_32f result = %d\n", result);
    if (result != HMPP_STS_NO_ERR) {
        return;
    }
    result = HMPPS_FIRSparseSetDlyLine_32f(policy, dlyLine2);
    printf("HMPPS_FIRSparseSetDlyLine_32f result = %d\n", result);
    if (result != HMPP_STS_NO_ERR) {
        HMPPS_FIRSparseRelease_32f(policy);
        return;
    }
    result = HMPPS_FIRSparse_32f(src, dst, len, policy);
    printf("HMPPS_FIRSparse_32f result = %d\n", result);
    if (result != HMPP_STS_NO_ERR) {
        HMPPS_FIRSparseRelease_32f(policy);
        return;
    }
    result = HMPPS_FIRSparseGetDlyLine_32f(policy, dlyDst);
    printf("HMPPS_FIRSparseGetDlyLine_32f result = %d\n", result);
    HMPPS_FIRSparseRelease_32f(policy);
    policy = NULL;
    if (result != HMPP_STS_NO_ERR) {
        return;
    }

    int32_t i;
    printf("len = %d\ndst =", len);
    for(i = 0; i < len; ++i){
        printf(" %f", dst[i]);
    }
    printf("\ndlyDstLen = %d\ndlyDst =", DLYLINE_LEN_S);
    for(i = 0; i < DLYLINE_LEN_S; ++i){
        printf(" %f", dlyDst[i]);
    }
    printf("\n");
}

运行结果：

HMPPS_FIRSparseInit_32f result = 0
HMPPS_FIRSparseSetDlyLine_32f result = 0
HMPPS_FIRSparse_32f result = 0
HMPPS_FIRSparseGetDlyLine_32f result = 0
len = 7
dst = 0.083000 0.089070 -4.014420 1.799900 -9.612170 -8.991440 2.024671
dlyDstLen = 8
dlyDst = 0.288300 -0.898100 -2.407000 -15.665400 17.177601 -40.684200 0.210700 0.010000

父主题： 滤波算法