name: Window : public AlgorithmBase
synopsis:

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

>     #include <Window.h>

>     Window(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, ALIGNMENT alignment = DEF_ALIGNMENT, NORMALIZATION normalization = DEF_NORMALIZATION, float duration = DEF_DURATION);
>     boolean setAlgorithm(ALGORITHM type);
>     boolean setNormalization(NORMALIZATION normalization);

quick start:

>     Window win(BLACKMAN);
>     VectorFloat input;
>     VectorFloat output;
>     win.setSize(10);
>     input.assign(L"2.0, 3.0, 8.0, 4.0, 2.0, 1.0, 1.0, 3.0, 4.0, 5.0");
>     win.compute(output, input);

description:
The Window class is used to design various types of windows. The following window functions are currently supported: rectangular, Bartlett, Blackman, Dolph-Chebyshev, Gaussian, Hamming, Hanning, Kaiser, and Lifter. A custom mode is also supported that allows user-defined windows to be used.
Many DSP textbooks contain extensive discussion of the theory of windowing. A good on-line reference on the application of time domain windows in speech recognition is:

J. Picone, "Signal Modeling Techniques in Speech Recognition", IEEE Proceedings, vol. 81, no. 9, pp. 1215-1247, September 1993.

The mathematical descriptions of the windows supported in this class are described below for reference purposes. The design parameters for these window functions are specified through a parameter vector that is passed to the object through the setConstants method. For each window type, the elements of this vector have a different meaning. The correspondence between the constants vector and the window design parameters is included in the description below.
Within the member functions that implement each window, which are private methods listed below, you will find detailed references to the textbooks from which the implementations were modeled. In addition to the basic shape of the window, a UNIT_ENERGY normalization mode is supported in which the window is normalized such that the sum of the squares of its values is equal to 1.0.
This class supports modes defined by the enumeration DMODE, which is in turn defined in the class AlgorithmBase. FRAME_INTERNAL is used when a user simply wants to window N points of data stored in a vector. CROSS_FRAME is used when dealing with a frame-based analysis of a time series. In this case, the window of data often extends outside the current frame, and suitable histories of signal samples must be maintained. The CROSS_FRAME mode, typically used in conjunction with the apply method, handles such cases. The CROSS_FRAME mode is used extensively by isip_transform.
The user can also control the alignment of the window with respect to the frame. Three choices are available: LEFT, CENTER, and RIGHT. The figure below demonstrates the basic concept of windowing:
In LEFT alignment mode, the first sample of the frame coincides with the first sample of the window (which means the window can extend into the future beyond the last sample in the frame). In RIGHT alignment mode, the last sample of the frame coincides with the last sample of the window (which means the window extends entirely in the past). In CENTER alignment mode, the center sample of the frame coincides with the center sample of the window. This means the window will typically extend into the previous and next frames of the signal. This mode is demonstrated in the figure above, and is the most popular mode for research systems. RIGHT alignment mode is popular for real-time systems since it minimizes system delay.
dependencies:

- AlgorithmBase
- Bessel
- Chebyshev

public constants:

- define the class name:

      static const String CLASS_NAME = L"Window";

- define algorithm choices:

      enum ALGORITHM { RECTANGULAR = 0, BLACKMAN, BARTLETT, DOLPH_CHEBYSHEV, GAUSSIAN, HAMMING, HANNING, KAISER, LIFTER, CUSTOM };

- define the implementation choices:

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

- define the alignment choices:

      enum ALIGNMENT { CENTER = 0, LEFT, RIGHT, DEF_ALIGNMENT = CENTER };

- define the normalization choices:

      enum NORMALIZATION { NONE = 0, UNIT_ENERGY, DEF_NORMALIZATION = NONE };

- define the static NameMap objects: the implementation name map is defined in the base class

      static const NameMap ALGO_MAP(L"RECTANGULAR, BLACKMAN, BARTLETT, DOLPH_CHEBYSHEV, GAUSSIAN, HAMMING, HANNING, KAISER, LIFTER, CUSTOM");

      static const NameMap IMPL_MAP(L"MULTIPLICATION");

      static const NameMap ALGN_MAP(L"CENTER, LEFT, RIGHT");

      static const NameMap NORM_MAP(L"NONE, UNIT_ENERGY");

- define i/o related variables:

      static const String DEF_PARAM = L"";

      static const String PARAM_ALGORITHM = L"algorithm";

      static const String PARAM_IMPLEMENTATION = L"implementation";

      static const String PARAM_ALIGNMENT = L"alignment";

      static const String PARAM_NORMALIZATION = L"normalization";

      static const String PARAM_DURATION = L"duration";

      static const String PARAM_CONSTANTS = L"constants";

      static const String PARAM_DATA = L"data";

- define default value(s) of the class data:

      static const float DEF_DURATION = 0.025;

- default arguments to methods:

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

- define other default constants:

      static const VectorFloat DEF_RECT_CONSTANTS(L"1.0");

      static const VectorFloat DEF_BART_CONSTANTS(L"1.0");

      static const VectorFloat DEF_BLCK_CONSTANTS(L"1.0, 0.42, 0.50");

      static const VectorFloat DEF_DCHB_CONSTANTS(L"1.0, 0.50");

      static const VectorFloat DEF_GAUS_CONSTANTS(L"1.0, 0.2618");

      static const VectorFloat DEF_HAMM_CONSTANTS(L"0.54");

      static const VectorFloat DEF_HANN_CONSTANTS(L"0.50");

      static const VectorFloat DEF_KAIS_CONSTANTS(L"1.0, 0.50");

      static const VectorFloat DEF_LIFT_CONSTANTS(L"1.0, 22.0, 11.0");

error codes:

- error code indicating Window class general error:

      static const long ERR = 72000;

- error code indicating invalid window parameters:

      static const long ERR_PRM = 72001;

protected data:

- data common to all algorithms and implementations:
  - algorithm name:

        ALGORITHM algorithm_d;

  - implementation name:

        IMPLEMENTATION implementation_d;

  - alignment name:

        ALIGNMENT alignment_d;

  - normalization name:

        NORM normalization_d;

  - window duration (in secs):

        Float window_duration_d;

  - static memory manager:

        static MemoryManager mgr_d;

- algorithm and implementation specific variables:
  - algorithm: non-CUSTOM
    modes: all
    - define a vector to store the design parameters for the window:

          VectorFloat constants_d;

  - algorithm: CUSTOM
    modes: all
    - define a vector to store the window values directly (since there is no parameterization):

          VectorFloat data_d;

required public methods:

- static methods:

      static const String& name();

      static boolean diagnose(Integral::DEBUG debug_level);

- debug methods: setDebug method is inherited from base class

      boolean debug(const unichar* message) const;

- destructor/constructor(s):

      ~Window();

      Window(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, ALIGNMENT alignment = DEF_ALIGNMENT, NORMALIZATION normalization = DEF_NORMALIZATION, float duration = DEF_DURATION);

      Window(const Window& arg);

- assign methods:

      boolean assign(const Window& arg);

- operator= methods:

      Window& operator= (const Window& 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 Window& 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:

- set methods:

      boolean setAlgorithm(ALGORITHM algorithm);

      boolean setImplementation(IMPLEMENTATION implementation);

      boolean setAlignment(ALIGNMENT alignment);

      boolean setNormalization(NORMALIZATION normalization);

      boolean setDuration(float duration);

      boolean setSize(long num_points);

      boolean setData(const VectorFloat& data);

      boolean set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, ALIGNMENT alignment = DEF_ALIGNMENT, NORMALIZATION normalization = DEF_NORMALIZATION, float duration = DEF_DURATION);

      boolean setConstants(const VectorFloat& constants);

- get methods:

      ALGORITHM getAlgorithm() const;

      IMPLEMENTATION getImplementation() const;

      ALIGNMENT getAlignment() const;

      NORMALIZATION getNormalization() const;

      float getDuration() const;

      long getSize() const;

      const VectorFloat& getData() const;

      boolean get(ALGORITHM& algorithm, IMPLEMENTATION& implementation, ALIGNMENT& alignment, NORMALIZATION& normalization, float& duration);

      const VectorFloat& getConstants() const;

- computation 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;

      boolean const String& className() const;

      boolean init();

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

      long getLeadingPad() const;

      long getTrailingPad() 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);

- windowing methods: common to all algorithms

      boolean computeCommon(VectorFloat& output, const VectorFloat& input);

      boolean computeCommon(VectorComplexFloat& output, const VectorComplexFloat& input);

- window generation methods:

      boolean generateRectangular(VectorFloat& output, const VectorFloat& params, long num_points);

      boolean generateBartlett(VectorFloat& output, const VectorFloat& params, long num_points);

      boolean generateBlackman(VectorFloat& output, const VectorFloat& params, long num_points);

      boolean generateDolphChebyshev(VectorFloat& output, const VectorFloat& params, long num_points);

      boolean generateGaussian(VectorFloat& output, const VectorFloat& params, long num_points);

      boolean generateGenralizedHanning(VectorFloat& output, const VectorFloat& params, long num_points);

      boolean generateKaiser(VectorFloat& output, const VectorFloat& params, long num_points);

      boolean generateLifter(VectorFloat& output, const VectorFloat& params, long num_points);

- window alignment and data-vector generation methods: common to all algorithms

      boolean compute(VectorFloat& output_a, const CircularBuffer& input_a, AlgorithmData::COEF_TYPE coef_type_a, long channel_index_a);

examples:

- This example shows how to create a Hamming window and then to apply that window to a vector:

      // declare a window
      //
      Window win;

      // set window type to be Hamming
      //
      win.setAlgorithm(Window::HAMMING);

      // create an input vector
      //
      VectorFloat input;
      input.assign(L"2.0, 3.0, 2.0, 1.0, 1.0, 8.0, 5.0, 2.0");

      // compute the windowed output
      //
      VectorFloat output;
      win.compute(output, input);

- This example shows how to use a user-defined window:

      // declare a custom window
      //
      Window win;
      win.setAlgorithm(CUSTOM);

      // set the window to a customized shape
      //
      VectorFloat data;
      data.assign(L"0.0, 1.0, 2.0, 3.0, 4.0, 3.0, 2.0, 1.0, 0.0");
      win.setData(data);

      // create an input vector
      //
      VectorFloat input;
      input.assign(L"1.0, 2.0, 3.0, 4.0, 5.0, 4.0, 3.0, 2.0, 1.0");

      // compute the windowed output
      //
      VectorFloat output;
      win.compute(output, input);

notes:

- none.