name: Filter : public AlgorithmBase

synopsis:

g++ [flags ...] file ...-l /isip/tools/lib/$ISIP_BINARY/lib_algo.a

#include <Filter.h>

Filter(ALGORITHM algorithm = DEF_ALGORITHM);
Filter(const Filter& arg);
boolean setMACoeffs(const VectorFloat& ma_coef);
boolean setMACoeffs(const VectorFloat& ma_coef, const VectorLong& ma_lag);
boolean setARCoeffs(const VectorFloat& ar_coef);
boolean setARCoeffs(const VectorFloat& ar_coef, const VectorLong& ar_lag);
boolean setCoeffs(const VectorFloat& ma_coef, const VectorLong& ma_lag, const VectorFloat& ar_coef, const VectorLong& ar_lag);
boolean setCoeffs(const VectorFloat& ma_coef, const VectorFloat& ar_coef);
boolean compute(VectorFloat& output, const VectorFloat& input, AlgorithmData::COEF_TYPE coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

quick start:

VectorFloat in_vec;
VectorFloat out_vec;
VectorFloat ma_coef(L"1.0, 2.0, 0.5");
VectorFloat ar_coef(L"1.0");
Filter ft;
ft.setCoeffs(ma_coef, ar_coef);
in_vec.assign(L" 1.0, 1.0, 2.0, 1.0, 1.0");
ft.compute(out_vec, in_vec);

description:

Filter is a class that implements standard digital filtering techniques. A good reference for different ways to define and implement filters is:

Introduction to Signal Processing

This class currently supports only one algorithm choice: Linear Time Invariant (LTI). It also supports only one implementation choice: Constant Coefficient Difference Equation (CCDE). This is described in detail below:

This filter is implemented using a standard direct form implementation. Note that filter is specified using an array of filter coefficients and a matching array of lags. This allows only the non-zero coefficients of a filter to be specified, and allows both causal (negative lag values) and non-causal filters (positive lag values) to be implemented. See the programming example below for more details on how to specify filter coefficients.

dependencies:

public constants:

define the class name:

static const String CLASS_NAME = L"Filter";

define algorithm choices:

enum ALGORITHM { LTI = 0, DEF_ALGORITHM = LTI };

define implementation choices:

enum IMPLEMENTATION { CCDE = 0, DEF_IMPLEMENTATION = CCDE };

define static NameMap objects:

static const NameMap ALGO_MAP = L"LTI";

static const NameMap IMPL_MAP = L"CCDE";

i/o related constants:

static const String DEF_PARAM = L"";

static const String PARAM_ALGORITHM = L"algorithm";

static const String PARAM_IMPLEMENTATION = L"implementation";

static const String PARAM_MA_COEF = L"ma_coef";

static const String PARAM_AR_COEF = L"ar_coef";

static const String PARAM_MA_LAG = L"ma_lag";

static const String PARAM_AR_LAG = L"ar_lag";

static const String PARAM_CMODE = L"compute_mode";

static const String PARAM_DMODE = L"data_mode";

define default value(s) of the class data:

static const VectorFloat DEF_MA_COEF(L"1");

static const VectorFloat DEF_AR_COEF(L"-1");

static const VectorLong DEF_MA_LAG(L"0");

static const VectorLong DEF_AR_LAG(L"-1");

define default argument(s) for methods:

static const AlgorithmData::COEF_TYPE DEF_COEF_TYPE = AlgorithmData::GENERIC;

static const long DEF_CHANNEL_INDEX = 0;

error codes:

general error codes:

static const long ERR = 70600;

static const long ERR_DATA = 70601;

error code indicating an invalid autoregressive (AR) filter lag:
```
static const long ERR_AR_LAG = 70602;
```

protected data:

algorithm name:

ALGORITHM algorithm_d;

implementation type:

IMPLEMENTATION implementation_d;

VectorFloat ma_coef_d;

VectorFloat ar_coef_d;

VectorFloat ma_lag_d;

VectorFloat ar_lag_d;

circular delay lines for MA and AR coefficients:

Vector<CircularDelayLine<Float> > ma_mem_d;

Vector<CircularDelayLine<Float> > ar_mem_d;

static memory manager
```
static MemoryManager mgr_d;
```

required public methods:

static methods:

static const String& name();

static boolean diagnose(Integral::DEBUG debug_level);

debug methods: setDebug is inherited from base class
```
boolean debug(const unichar* message) const;
```

destructor/constructor(s) methods:

~Filter();

Filter(ALGORITHM algorithm = DEF_ALGORITHM);

Filter(const Filter& arg);

assign methods:
```
boolean assign(const Filter& arg);
```
operator= methods:
```
Filter& operator= (const Filter& arg);
```

i/o methods:

long sofSize() const;

boolean read(Sof& sof, long tag, const String& name = CLASS_NAME);

boolean write(Sof& sof, long tag, const String& name = CLASS_NAME) const;

boolean readData(Sof& sof, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

boolean writeData(Sof& sof, const String& pname = DEF_PARAM) const;

equality methods:
```
boolean eq(const Filter& arg) const;
```

memory management methods:

static void* operator new(size_t size);

static void* operator new[](size_t size);

static void operator delete(void* ptr);

static void operator delete[](void* ptr);

static boolean setGrowSize(long grow_size);

boolean clear(Integral::CMODE ctype = Integral::DEF_CMODE);

class-specific public methods:

standard set methods:

boolean setAlgorithm(ALGORITHM algorithm);

boolean setImplementation(IMPLEMENTATION implementation);

set methods for moving average (MA) coefficients:

boolean setMACoeffs(long lag, float val);

boolean setMACoeffs(const VectorFloat& ma_coef);

boolean setMACoeffs(const VectorFloat& ma_coef, const VectorLong& ma_lag);

set methods for autoregressive (AR) coefficients:

boolean setARCoeffs(float val, long lag);

boolean setARCoeffs(const VectorFloat& ar_coef);

boolean setARCoeffs(const VectorFloat& ar_coef, const VectorLong& ar_lag);

other set methods:

boolean setCoeffs(const VectorFloat& ma_coef, const VectorFloat& ar_coef);

boolean setCoeffs(const VectorFloat& ma_coef, const VectorLong& ma_lag, const VectorFloat& ar_coef, const VectorLong& ar_lg);

standard get methods:

ALGORITHM getAlgorithm() const;

IMPLEMENTATION getImplementation() const;

get methods for moving average (MA) coefficients:

const VectorFloat& getMACoeffs() const;

const VectorLong& getMALags() const;

get methods for autoregressive (AR) coefficients:

const VectorFloat getARCoeffs() const;

const VectorLong& getARLags() const;

other get methods:

long getLeadingNumSamp() const;

long getTrailingNumSamp() const;

computational methods:

boolean compute(VectorFloat& output, const VectorFloat& input, AlgorithmData::COEF_TYPE coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

boolean compute(VectorComplexFloat& output, const VectorComplexFloat& input, AlgorithmData::COEF_TYPE coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

AlgorithmBase interface contract methods:

boolean assign(const AlgorithmBase& arg);

boolean eq(const AlgorithmBase& arg) const;

const String& className() const;

boolean init();

boolean apply(Vector<AlgorithmData>& output, const Vector<AlgorithmData>& input);

long getLeadingPad() const;

long getTrailingPad() const;

CMODE getOutputDataFormat() const;

boolean setParser(SofParser* parser);

private methods:

common i/o methods:

boolean readDataCommon(Sof& sof, const String& pname, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

boolean writeDataCommon(Sof& sof, const String& pname) const;

algorithm and implementation specific computation methods: LTI/CCDE

boolean computeLtiCcdeFrameInternal(VectorFloat& output, const VectorFloat& input, long index = DEF_CHANNEL_INDEX);

boolean computeLtiCcdeCrossFrame(VectorFloat& output, const VectorFloat& input, long index = DEF_CHANNEL_INDEX);

methods to prepare data for filtering:

boolean computeBuffer(VectorFloat& output, const CircularBuffer<AlgorithmData>& input, long channel_index);

examples:

Consider a digital filter of the form:

This example shows how to implement this digital filter using this class:

// declare a filter object
//
Filter filt;

// set ma and ar coefficients
//
VectorFloat ma_coef(L"1.2, 0.5, 1.1, 1.0");
VectorLong ma_lag(L"-2, -1, -4, 0");
      
VectorFloat ar_coef(L"0.5, 2.0, 0.2");
VectorLong ar_lag(L"-2, -1, -5");
filt.setCoeffs(ma_coef, ma_lag, ar_coef, ar_lag);

// declare input vector
//
VectorFloat v_in(L"1, 2, 3");
VectorFloat v_out;

// compute filter
//
filt.compute(v_out, v_in);
v_out.debug(L"v_out");
}

notes:

none.