name: Connection : public AlgorithmBase
synopsis:

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

>     #include <Connection.h>

>     Connection();
>     Connection(const Connection& arg);
>     boolean eq(const Connection& arg);
>     boolean setAlgorithm(ALGORITHM algorithm);

quick start:

>     Connection conn;
>     conn.setAlgorithm(Connection::INPUTS);
>     conn.setImplementation(Connection::CONCATENATION);

>     AlgorithmData in;
>     in.makeCombination().setLength(2);
>     in.getCombination()(0).makeVector().assign(L"0, 1, 2, 3");
>     in.getCombination()(1).makeVector().assign(L"5, 6, 7, 8");
>     VectorFloat out;
>     conn.computeInputs(out, in);

description:
The Connection class is used by the front-end to combine several inputs into a single feature stream. This is a very important operation since most speech recognition front ends combine different measurements (e.g., energy and spectrum) into a single feature vector.
This class is one of a number of classes that are mainly used by isip_transform to facilitate signal flow graph-based processing of signals. Programmers using the function-level interfaces in this class can perform similar operations using standard IFC operators and functions (such as the concatenate method in the Vector class). The table below summarizes the operations available in this class:
The input to this class can be one multichannel signal or multiple multichannel signals. In the case of one signal, the CHANNEL mode is provided to allow a means to convert the multichannel signal to a single channel. For multiple signals, this class provides a way to operate on individual channels of these signals.
dependencies:

- AlgorithmBase
- MemoryManager

public constants:

- define the class name:

      static const String CLASS_NAME = L"Connection";

- define the algorithm choices:

      enum ALGORITHM { CHANNEL = 0, STREAM, DEF_ALGORITHM = CHANNEL };

- define the implementation choices:

      enum IMPLEMENTATION { CONCATENATE = 0, INTERLEAVE, SELECT, DEF_IMPLEMENTATION = CONCATENATE };

- define the static NameMap objects

      static const NameMap ALGO_MAP(L"CHANNEL, STREAM");

      static const NameMap IMPL_MAP(L"CONCATENATE, INTERLEAVE, SELECT, SPLIT");

- define 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_CHANNEL = L"channel";

error codes:

- error code indicating Connection class general error:

      static const long ERR = 72100;

      static const long ERR_LENGTH = 72101;

protected data:

- algorithm name:

      ALGORITHM algorithm_d;

- implementation name

      IMPLEMENTATION implementation_d;

- the channel (for split)

      Long channel_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 method is inherited from base class

      boolean debug(const unichar* message) const;

- destructor/constructor(s):

      ~Connection();

      Connection(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION);

      Connection(const Connection& arg);

- assign methods:

      boolean assign(const Connection& arg);

- operator= methods:

      Connection& operator= (const Connection& 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 Connection& 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 setChannel(long chan);

      boolean set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION);

- get methods:

      ALGORITHM getAlgorithm() const;

      IMPLEMENTATION getImplementation() const;

      long getChannel() const;

      boolean get(ALGORITHM& algorithm, IMPLEMENTATION& implementation) const;

- AlgorithmBase interface contract methods:

      boolean assign(const AlgorithmBase& arg);

      boolean eq(const AlgorithmBase& arg) const;

      const String& className() const;

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

      boolean setParser(SofParser* parser);

private methods:

- algorithm-specific computation methods: operate on channels

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

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

- algorithm-specific computation methods: operate on streams

      boolean computeStreamConcatenate(AlgorithmData& output, const AlgorithmData& input);

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

examples:

- This example demonstrates how to use this class to combine one multichannel signal into one single channel signal:

      // declare variables
      //
      Vector< CircularBuffer<AlgorithmData> > input(1);
      Vector< AlgorithmData> output;
      AlgorithmData tmp;

      // create a signal with four channels
      //
      tmp.makeCombination().setLength(4);
      tmp.getCombination()(0).makeVectorFloat().assign(L"0, 1, 2, 3");
      tmp.getCombination()(1).makeVectorFloat().assign(L"4, 5, 6, 7");
      tmp.getCombination()(2).makeVectorFloat().assign(L"8, 9, 10, 11");
      tmp.getCombination()(3).makeVectorFloat().assign(L"12, 13, 14, 15");
      input(0).append(tmp);

      // initialize the connection block and process the data
      //
      Connection conn;
      conn.setAlgorithm(Connection::CHANNEL);
      conn.setImplementation(Connection::CONCATENATE);
      conn.apply(output, input);

  The corresponding output is shown in the first row in the table above.
- This example demonstrates how to combine two multichannel signals into one multichannel signal:

      // declare variables
      //
      Vector< CircularBuffer<AlgorithmData> > input(2);
      Vector<AlgorithmData> output;
      AlgorithmData tmp1;
      AlgorithmData tmp2;

      // create two signals with two channels each
      //
      tmp1.makeCombination().setLength(2);
      tmp1.getCombination()(0).makeVectorFloat().assign(L"0, 1, 0");
      tmp1.getCombination()(1).makeVectorFloat().assign(L"1, 0, 1");

      tmp2.makeCombination().setLength(2);
      tmp2.getCombination()(0).makeVectorFloat().assign(L"2, 3, 2");
      tmp2.getCombination()(1).makeVectorFloat().assign(L"3, 2, 3");

      input(0).append(tmp1);
      input(1).append(tmp2);

      // initialize the connection block and process the data
      //
      Connection conn;
      conn.setAlgorithm(Connection::STREAM);
      conn.setImplementation(Connection::CONCATENATE);
      conn.apply(output, input);

  The corresponding output is shown in the third row in the table above.

notes:

- none.