# Filter libraryFilter.h

A digital filter is simply a discrete-time, discrete-amplitude convolver. Basic Fourier transform theory states that the linear convolution of two sequences in the time domain is the same as multiplication of two corresponding spectral sequences in the frequency domain. Filtering is in essence the multiplication of the signal spectrum by the frequency domain impulse response of the filter. For an ideal low-pass filter the pass band part of the signal spectrum is multiplied by one and the band-stop part of the signal by zero.

This library provides only Finite Impulse Response (FIR) filters. FIR filters may have linear phase and zero delay, which make them almost the best solution for data smoothing and trend extraction from time series and measured data.

## Contents

## Function list

C function name | Functions | C++ function name | Functions |
---|---|---|---|

Average | 2 functions | Average | 2 functions |

BandPass | 2 functions | BandPass | 2 functions |

BandStop | 2 functions | BandStop | 2 functions |

Diff | 2 functions | Diff | 2 functions |

Hilbert | 2 functions | Hilbert | 2 functions |

Max | 10 functions | Max | 10 functions |

Median | 10 functions | Median | 10 functions |

Min | 10 functions | Min | 10 functions |

C function name | Functions | C++ function name | Functions |

# Frequency range

Frequency values which are passed to the filters should be in range of [0,0.5]. The library provides defined constants that cover this range by named values.

- FREQ_MIN - Min frequency (0.0)
- FREQ_MAX - Max frequency (0.5)

# Window functions

Filters library defines its own type called **window_t** which is just an enumeration of available window functions which may be applied to FIR filter impulse response.

Item | Description |
---|---|

No window functions | |

WIN_NONE | Rectangle window (or no window) |

High-resolution window functions | |

WIN_SINE | Sine window |

WIN_HAMMING | Hamming window |

WIN_BLACKMAN | Blackman window |

Low-resolution window functions | |

WIN_BLACKMAN_NUTTALL | Blackman–Nuttall window |

# Linear filters

Linear filters process input signals to produce output signals, subject to the constraint of linearity. Most filters implemented in analog electronics, in digital signal processing, or in mechanical systems are classified as causal, time invariant, and linear signal processing filters. A linear time-invariant (LTI) filter can be uniquely specified by its impulse response `h`, and the output of any filter is mathematically expressed as the convolution of the input with that impulse response.

Typical filter design goals are to realize a particular frequency response, that is, the magnitude of the transfer function |`H(w)`|. The frequency response may be tailored to, for instance, eliminate unwanted frequency components from an input signal, or to limit an amplifier to signals within a particular band of frequencies.

The general concept of linear filtering is also used in statistics, data analysis, and mechanical engineering among other fields and technologies.

## Band-pass filter

Cbool Filter_BandPass_flt32 (flt32_t filter[], size_t size, flt32_t lowfreq, flt32_t highfreq, enum window_t window); bool Filter_BandPass_flt64 (flt64_t filter[], size_t size, flt64_t lowfreq, flt64_t highfreq, enum window_t window);

C++bool Filter::BandPass (flt32_t filter[], size_t size, flt32_t lowfreq, flt32_t highfreq, window_t window); bool Filter::BandPass (flt64_t filter[], size_t size, flt64_t lowfreq, flt64_t highfreq, window_t window);

Description: Calculate impulse response coefficients for chosen order FIR band-pass filter, using selected frequency range, then apply provided window function to computed coefficients, and put them into filter array. To hold all coefficients, the target array should have 2 * size + 1 elements. Frequency values should be in range of [0,0.5] and low frequency should be less than or equal to high frequency.

Actual cut-off frequency can be found by multiplying frequency in range of [0,0.5] to sample rate of the signal you are filtering. For Audio-CD (44100 Hz) filter [0.15,0.4] will be equal to [6615 Hz,17640 Hz] audio filter.

Parameters:

- filter - pointer to array to store coefficients (should be able to hold at least 2*size+1 elements)
- size - half of filter order
- lowfreq - low cut-off frequency [0,0.5]. All waves with less frequencies will be rejected by the filter.
- highfreq - high cut-off frequency [0,0.5]. All waves with greater frequencies will be rejected by the filter.
- window - window function to apply to filter impulse response

Return value:

- TRUE (1) if all parameters have correct values.
- FALSE (0) if frequency range is incorrect.

**Note:**Size is not a filter array size. It is half of filter order. For example to compute 80-th order filter (81 elements in filter array), the size variable should be 40.

## Band-stop filter

Cbool Filter_BandStop_flt32 (flt32_t filter[], size_t size, flt32_t lowfreq, flt32_t highfreq, enum window_t window); bool Filter_BandStop_flt64 (flt64_t filter[], size_t size, flt64_t lowfreq, flt64_t highfreq, enum window_t window);

C++bool Filter::BandStop (flt32_t filter[], size_t size, flt32_t lowfreq, flt32_t highfreq, window_t window); bool Filter::BandStop (flt64_t filter[], size_t size, flt64_t lowfreq, flt64_t highfreq, window_t window);

Description: Calculate impulse response coefficients for chosen order FIR band-stop (band-rejection) filter, using selected frequency range, then apply provided window function to computed coefficients, and put them into filter array. To hold all coefficients, the target array should have 2 * size + 1 elements. Frequency values should be in range of [0,0.5] and low frequency should be less than or equal to high frequency.

Actual cut-off frequency can be found by multiplying frequency in range of [0,0.5] to sample rate of the signal you are filtering. For Audio-CD (44100 Hz) filter [0.15,0.4] will be equal to [6615 Hz,17640 Hz] audio filter.

Parameters:

- filter - pointer to array to store coefficients (should be able to hold at least 2*size+1 elements)
- size - half of filter order
- lowfreq - low cut-off frequency [0,0.5]. All waves with less frequencies will be passed through the filter.
- highfreq - high cut-off frequency [0,0.5]. All waves with greater frequencies will be passed through the filter.
- window - window function to apply to filter impulse response

Return value:

- TRUE (1) if all parameters have correct values.
- FALSE (0) if frequency range is incorrect.

**Note:**Size is not a filter array size. It is half of filter order. For example to compute 80-th order filter (81 elements in filter array), the size variable should be 40.

## Hilbert filter

Cbool Filter_Hilbert_flt32 (flt32_t filter[], size_t size, flt32_t lowfreq, flt32_t highfreq, enum window_t window); bool Filter_Hilbert_flt64 (flt64_t filter[], size_t size, flt64_t lowfreq, flt64_t highfreq, enum window_t window);

C++bool Filter::Hilbert (flt32_t filter[], size_t size, flt32_t lowfreq, flt32_t highfreq, window_t window); bool Filter::Hilbert (flt64_t filter[], size_t size, flt64_t lowfreq, flt64_t highfreq, window_t window);

Description: Calculate impulse response coefficients for chosen order FIR Hilbert transform filter, using selected frequency range, then apply provided window function to computed coefficients, and put them into filter array. To hold all coefficients, the target array should have 2 * size + 1 elements. Frequency values should be in range of [0,0.5] and low frequency should be less than or equal to high frequency.

Actual cut-off frequency can be found by multiplying frequency in range of [0,0.5] to sample rate of the signal you are filtering. For Audio-CD (44100 Hz) filter [0.15,0.4] will be equal to [6615 Hz,17640 Hz] audio filter.

Parameters:

- filter - pointer to array to store coefficients (should be able to hold at least 2*size+1 elements)
- size - half of filter order
- lowfreq - low cut-off frequency [0,0.5]. All waves with less frequencies will be rejected by the filter.
- highfreq - high cut-off frequency [0,0.5]. All waves with greater frequencies will be rejected by the filter.
- window - window function to apply to filter impulse response

Return value:

- TRUE (1) if all parameters have correct values.
- FALSE (0) if frequency range is incorrect.

**Note:**Size is not a filter array size. It is half of filter order. For example to compute 80-th order filter (81 elements in filter array), the size variable should be 40.

## Differential filter

Cbool Filter_Diff_flt32 (flt32_t filter[], size_t size, flt32_t lowfreq, flt32_t highfreq, enum window_t window); bool Filter_Diff_flt64 (flt64_t filter[], size_t size, flt64_t lowfreq, flt64_t highfreq, enum window_t window);

C++bool Filter::Diff (flt32_t filter[], size_t size, flt32_t lowfreq, flt32_t highfreq, window_t window); bool Filter::Diff (flt64_t filter[], size_t size, flt64_t lowfreq, flt64_t highfreq, window_t window);

Description: Calculate impulse response coefficients for chosen order FIR differential filter, using selected frequency range, then apply provided window function to computed coefficients, and put them into filter array. To hold all coefficients, the target array should have 2 * size + 1 elements. Frequency values should be in range of [0,0.5] and low frequency should be less than or equal to high frequency.

Parameters:

- filter - pointer to array to store coefficients (should be able to hold at least 2*size+1 elements)
- size - half of filter order
- lowfreq - low cut-off frequency [0,0.5]. All waves with less frequencies will be rejected by the filter.
- highfreq - high cut-off frequency [0,0.5]. All waves with greater frequencies will be rejected by the filter.
- window - window function to apply to filter impulse response

Return value:

- TRUE (1) if all parameters have correct values.
- FALSE (0) if frequency range is incorrect.

**Note:**Size is not a filter array size. It is half of filter order. For example to compute 80-th order filter (81 elements in filter array), the size variable should be 40.

## Moving average filter

Cbool Filter_Average_flt32 (flt32_t response[], const flt32_t data[], size_t size, size_t order); bool Filter_Average_flt64 (flt64_t response[], const flt64_t data[], size_t size, size_t order);

C++bool Filter::Average (flt32_t response[], const flt32_t data[], size_t size, size_t order); bool Filter::Average (flt64_t response[], const flt64_t data[], size_t size, size_t order);

Description: Find average value among all values into filter lookup window and store it into filter response array. Moving average filters automatically correct phase shift of signal caused by filter response delay, and put average value into position of central element of lookup window.

Parameters:

- response - pointer to an array where to put filter response
- data - pointer to data array
- size - size of data array (count of elements)
- order - filter order. Filter lookup window is computed as 2 * order + 1.

Return value:

- TRUE (1) if all parameters have correct values.
- FALSE (0) if filter order is equal to zero, or data size is less than 2 * order + 1.

**Note:**Filter lookup window is computed as 2 * order + 1. To get 5 points moving average filtering use filter order equal to 2.

# Nonlinear filters

In signal processing, a nonlinear filter is a filter whose output is not a linear function of its input. If the filter outputs signals are `R` and `S` for two input signals `r` and `s` separately, it doesn't guarantee that output is `αR + βS` when the input is a linear combination `αr + βs`. Both continuous-domain and discrete-domain filters may be nonlinear.

An important example of nonlinear filter is the running-median filter, such that every output sample `R[i]` is the median of the last five input samples `r[i−2]`, `r[i−1]`, `r[i]`, `r[i+1]`, `r[i+2]`. All digital signal processing depends on non-linear filters (analog-to-digital converters) to transform analog signals to binary numbers. Median filters effectively process digital signals with steep fronts, and preserve their shape in opposite to linear and moving average filters, which smooth them.

Non-linear filters have many applications, especially in the removal of certain types of noise that are not additive. For example, the median filter is widely used to remove spike noise - that affects only a small percentage of the samples, possibly by very large amounts.

## Median filter

C Unsigned integer types bool Filter_Median_uint8 (uint8_t response[], const uint8_t data[], size_t temp[], size_t size, size_t order); bool Filter_Median_uint16 (uint16_t response[], const uint16_t data[], size_t temp[], size_t size, size_t order); bool Filter_Median_uint32 (uint32_t response[], const uint32_t data[], size_t temp[], size_t size, size_t order); bool Filter_Median_uint64 (uint64_t response[], const uint64_t data[], size_t temp[], size_t size, size_t order); Signed integer types bool Filter_Median_sint8 (sint8_t response[], const sint8_t data[], size_t temp[], size_t size, size_t order); bool Filter_Median_sint16 (sint16_t response[], const sint16_t data[], size_t temp[], size_t size, size_t order); bool Filter_Median_sint32 (sint32_t response[], const sint32_t data[], size_t temp[], size_t size, size_t order); bool Filter_Median_sint64 (sint64_t response[], const sint64_t data[], size_t temp[], size_t size, size_t order); Floating-point types bool Filter_Median_flt32 (flt32_t response[], const flt32_t data[], size_t temp[], size_t size, size_t order); bool Filter_Median_flt64 (flt64_t response[], const flt64_t data[], size_t temp[], size_t size, size_t order);

C++ Unsigned integer types bool Filter::Median (uint8_t response[], const uint8_t data[], size_t temp[], size_t size, size_t order); bool Filter::Median (uint16_t response[], const uint16_t data[], size_t temp[], size_t size, size_t order); bool Filter::Median (uint32_t response[], const uint32_t data[], size_t temp[], size_t size, size_t order); bool Filter::Median (uint64_t response[], const uint64_t data[], size_t temp[], size_t size, size_t order); Signed integer types bool Filter::Median (sint8_t response[], const sint8_t data[], size_t temp[], size_t size, size_t order); bool Filter::Median (sint16_t response[], const sint16_t data[], size_t temp[], size_t size, size_t order); bool Filter::Median (sint32_t response[], const sint32_t data[], size_t temp[], size_t size, size_t order); bool Filter::Median (sint64_t response[], const sint64_t data[], size_t temp[], size_t size, size_t order); Floating-point types bool Filter::Median (flt32_t response[], const flt32_t data[], size_t temp[], size_t size, size_t order); bool Filter::Median (flt64_t response[], const flt64_t data[], size_t temp[], size_t size, size_t order);

Description: Find median value among all values into filter lookup window and store it into filter response array. Median filters have almost the same meaning as moving average filters. They automatically correct phase shift of signal caused by filter response delay, and put median value into position of central element of lookup window.

Parameters:

- response - pointer to an array where to put filter response
- data - pointer to data array
- temp - pointer to temporary array, internally used by the filter (should be able to hold at least 9*order elements)
- size - size of data array (count of elements)
- order - filter order. Filter lookup window is computed as 2 * order + 1.

Return value:

- TRUE (1) if all parameters have correct values.
- FALSE (0) if filter order is equal to zero, or data size is less than 2 * order + 1.

**Note:**Filter lookup window is computed as 2 * order + 1. To get 5 points median filtering use filter order equal to 2.

## Min filter

C Unsigned integer types bool Filter_Min_uint8 (uint8_t response[], const uint8_t data[], size_t temp[], size_t size, size_t order); bool Filter_Min_uint16 (uint16_t response[], const uint16_t data[], size_t temp[], size_t size, size_t order); bool Filter_Min_uint32 (uint32_t response[], const uint32_t data[], size_t temp[], size_t size, size_t order); bool Filter_Min_uint64 (uint64_t response[], const uint64_t data[], size_t temp[], size_t size, size_t order); Signed integer types bool Filter_Min_sint8 (sint8_t response[], const sint8_t data[], size_t temp[], size_t size, size_t order); bool Filter_Min_sint16 (sint16_t response[], const sint16_t data[], size_t temp[], size_t size, size_t order); bool Filter_Min_sint32 (sint32_t response[], const sint32_t data[], size_t temp[], size_t size, size_t order); bool Filter_Min_sint64 (sint64_t response[], const sint64_t data[], size_t temp[], size_t size, size_t order); Floating-point types bool Filter_Min_flt32 (flt32_t response[], const flt32_t data[], size_t temp[], size_t size, size_t order); bool Filter_Min_flt64 (flt64_t response[], const flt64_t data[], size_t temp[], size_t size, size_t order);

C++ Unsigned integer types bool Filter::Min (uint8_t response[], const uint8_t data[], size_t temp[], size_t size, size_t order); bool Filter::Min (uint16_t response[], const uint16_t data[], size_t temp[], size_t size, size_t order); bool Filter::Min (uint32_t response[], const uint32_t data[], size_t temp[], size_t size, size_t order); bool Filter::Min (uint64_t response[], const uint64_t data[], size_t temp[], size_t size, size_t order); Signed integer types bool Filter::Min (sint8_t response[], const sint8_t data[], size_t temp[], size_t size, size_t order); bool Filter::Min (sint16_t response[], const sint16_t data[], size_t temp[], size_t size, size_t order); bool Filter::Min (sint32_t response[], const sint32_t data[], size_t temp[], size_t size, size_t order); bool Filter::Min (sint64_t response[], const sint64_t data[], size_t temp[], size_t size, size_t order); Floating-point types bool Filter::Min (flt32_t response[], const flt32_t data[], size_t temp[], size_t size, size_t order); bool Filter::Min (flt64_t response[], const flt64_t data[], size_t temp[], size_t size, size_t order);

Description: Find minimum value among all values into filter lookup window and store it into filter response array. Minimum filters automatically correct phase shift of signal caused by filter response delay, and put min value into position of central element of lookup window.

Parameters:

- response - pointer to an array where to put filter response
- data - pointer to data array
- temp - pointer to temporary array, internally used by the filter (should be able to hold at least 9*order elements)
- size - size of data array (count of elements)
- order - filter order. Filter lookup window is computed as 2 * order + 1.

Return value:

- TRUE (1) if all parameters have correct values.
- FALSE (0) if filter order is equal to zero, or data size is less than 2 * order + 1.

**Note:**Filter lookup window is computed as 2 * order + 1. To get 5 points minumum filtering use filter order equal to 2.

## Max filter

C Unsigned integer types bool Filter_Max_uint8 (uint8_t response[], const uint8_t data[], size_t temp[], size_t size, size_t order); bool Filter_Max_uint16 (uint16_t response[], const uint16_t data[], size_t temp[], size_t size, size_t order); bool Filter_Max_uint32 (uint32_t response[], const uint32_t data[], size_t temp[], size_t size, size_t order); bool Filter_Max_uint64 (uint64_t response[], const uint64_t data[], size_t temp[], size_t size, size_t order); Signed integer types bool Filter_Max_sint8 (sint8_t response[], const sint8_t data[], size_t temp[], size_t size, size_t order); bool Filter_Max_sint16 (sint16_t response[], const sint16_t data[], size_t temp[], size_t size, size_t order); bool Filter_Max_sint32 (sint32_t response[], const sint32_t data[], size_t temp[], size_t size, size_t order); bool Filter_Max_sint64 (sint64_t response[], const sint64_t data[], size_t temp[], size_t size, size_t order); Floating-point types bool Filter_Max_flt32 (flt32_t response[], const flt32_t data[], size_t temp[], size_t size, size_t order); bool Filter_Max_flt64 (flt64_t response[], const flt64_t data[], size_t temp[], size_t size, size_t order);

C++ Unsigned integer types bool Filter::Max (uint8_t response[], const uint8_t data[], size_t temp[], size_t size, size_t order); bool Filter::Max (uint16_t response[], const uint16_t data[], size_t temp[], size_t size, size_t order); bool Filter::Max (uint32_t response[], const uint32_t data[], size_t temp[], size_t size, size_t order); bool Filter::Max (uint64_t response[], const uint64_t data[], size_t temp[], size_t size, size_t order); Signed integer types bool Filter::Max (sint8_t response[], const sint8_t data[], size_t temp[], size_t size, size_t order); bool Filter::Max (sint16_t response[], const sint16_t data[], size_t temp[], size_t size, size_t order); bool Filter::Max (sint32_t response[], const sint32_t data[], size_t temp[], size_t size, size_t order); bool Filter::Max (sint64_t response[], const sint64_t data[], size_t temp[], size_t size, size_t order); Floating-point types bool Filter::Max (flt32_t response[], const flt32_t data[], size_t temp[], size_t size, size_t order); bool Filter::Max (flt64_t response[], const flt64_t data[], size_t temp[], size_t size, size_t order);

Description: Find maximum value among all values into filter lookup window and store it into filter response array. Maximum filters automatically correct phase shift of signal caused by filter response delay, and put max value into position of central element of lookup window.

Parameters:

- response - pointer to an array where to put filter response
- data - pointer to data array
- temp - pointer to temporary array, internally used by the filter (should be able to hold at least 9*order elements)
- size - size of data array (count of elements)
- order - filter order. Filter lookup window is computed as 2 * order + 1.

Return value:

- TRUE (1) if all parameters have correct values.
- FALSE (0) if filter order is equal to zero, or data size is less than 2 * order + 1.

**Note:**Filter lookup window is computed as 2 * order + 1. To get 5 points maxumum filtering use filter order equal to 2.