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:

S.J. Orfanidis, Introduction to Signal Processing, Prentice-Hall, Upper Saddle River, New Jersey, USA, pp. 269, ISBN 0-13-209172-0, 1996.

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:

- AlgorithmBase
- VectorFloat
- VectorLong
- Vector
- CircularDelayLine
- Float
- MemoryManager

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;

- parameters related to the filter specification:

      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.