StlRecogniserWrapper Class Reference

#include <stlrecogniserwrapper.h>

Inheritance diagram for StlRecogniserWrapper:

AbstractRecogniser List of all members.

Public Member Functions

 StlRecogniserWrapper (StlRecogniserInterface *recogniser, JavaVM *jvm, DigestDbModel *digestDbModel, QObject *parent=0)
virtual ~StlRecogniserWrapper ()
virtual QByteArray key () const
virtual QString title () const
virtual QString description () const
QHash< QString, QVariant > defaultParams () const
StlRecogniserInterfacerecogniser () const

Protected Member Functions

virtual bool initTraining (const QList< QByteArray > &featureKeys, const QHash< QString, QVariant > &params)
virtual bool examineSample (const FeatureVec &featureVec, const QSet< int > &classes)
virtual bool finaliseTraining ()
virtual bool writeModelFile (const QString &fileName)
virtual bool readModelFile (const QString &fileName)
virtual Stroke flatten (const StrokeList &strokes)
virtual ClassProbabilities classify (const FeatureVec &featureVec)

Constructor & Destructor Documentation

StlRecogniserWrapper::StlRecogniserWrapper ( StlRecogniserInterface recogniser,
JavaVM *  jvm,
DigestDbModel digestDbModel,
QObject *  parent = 0 
)

Constructs a new C++ STL recogniser wrapper.

Note: The new object takes ownership of the recogniser and hence becomes responsible for the deletion of it.

Note: This asserts that the recogniser is non-null. This is also asserted by almost all of this class's methods.

StlRecogniserWrapper::~StlRecogniserWrapper (  )  [virtual]


Member Function Documentation

QByteArray StlRecogniserWrapper::key (  )  const [virtual]

Returns the recogniser's "key". This is used for identifying recognisers for purposes such as recording the type of a given trained recogniser and for use in "factories".

This string should only contain lower-case characters. All string matching performed with it will be case-insensitive.

Note: This does not return a (const) reference for the sake of "wrappers" (e.g. JavaRecogniserWrapper and StlRecogniserWrapper), which may have to convert the string from a different structure, usually with the use of a temporary variable. Qt's implicit sharing will help performance.

Implements AbstractRecogniser.

QString StlRecogniserWrapper::title (  )  const [virtual]

Returns the recogniser's "title". This is used in the application's user interface to label the recogniser in a human friendly / readable manner.

Note: This does not return a (const) reference for the sake of "wrappers" (e.g. JavaRecogniserWrapper and StlRecogniserWrapper), which may have to convert the string from a different structure, usually with the use of a temporary variable. Qt's implicit sharing will help performance.

Implements AbstractRecogniser.

QString StlRecogniserWrapper::description (  )  const [virtual]

Returns the recogniser's "description". This is used in the application's user interface to provide more information to the user about the recogniser.

A subset of HTML may be used, such as to make the text bold and change its colour, size and alignment. Please see the Qt documentation for more details on its HTML support.

Note: This does not return a (const) reference for the sake of "wrappers" (e.g. JavaRecogniserWrapper and StlRecogniserWrapper), which may have to convert the string from a different structure, usually with the use of a temporary variable. Qt's implicit sharing will help performance.

Implements AbstractRecogniser.

QHash< QString, QVariant > StlRecogniserWrapper::defaultParams (  )  const [virtual]

Implements AbstractRecogniser.

StlRecogniserInterface * StlRecogniserWrapper::recogniser (  )  const

bool StlRecogniserWrapper::initTraining ( const QList< QByteArray > &  featureKeys,
const QHash< QString, QVariant > &  params 
) [protected, virtual]

This is used primarily for ensuring that the trainer's state is ready for training, as train() can be called multiple times.

The featureKeys are provided here, as they may be required to initialise one or more data structures.

Implements AbstractRecogniser.

bool StlRecogniserWrapper::examineSample ( const FeatureVec featureVec,
const QSet< int > &  classes 
) [protected, virtual]

This is called every time a sample/example is to be processed (or logged, where processing could be delayed until finaliseTraining() is called).

The featureVec is the feature vector that has been extracted from the sample.

Note: The FeatureResultT typedef is currently a double.

The featureVec can be converted to an STL vector:

  vector<FeatureResultT> v = featureVec.toStdVector()

Note: If you wan't the stoke data for some reason, then store a copy of what you return from flatten().

Implements AbstractRecogniser.

bool StlRecogniserWrapper::finaliseTraining (  )  [protected, virtual]

This is used primarily for building the model if that wasn't (completely) done by examineSample().

This should also be used to free any allocated memory and to clear the state, remembering that train() may be called multiple times.

Implements AbstractRecogniser.

bool StlRecogniserWrapper::writeModelFile ( const QString &  fileName  )  [protected, virtual]

This must be implemented and must write a file to fileName. The fileName is the file name for the output model file, including the path (e.g. "/Users/bob/Library/Digest/linear_recog52.model"). If the model must be written as multiple files, then fileName should be the master/index/reference file (which will be passed to the corresponding AbstractRecogniser::readModelFile() method) and any support files should be placed along side it in the same path.

There are no restrictions on the file being binary or ascii, nor on its contents.

See also fileName()

Implements AbstractRecogniser.

bool StlRecogniserWrapper::readModelFile ( const QString &  fileName  )  [protected, virtual]

This method is called during initialisation, as to load in the recogniser specific model file that was created by the corresponding AbstractRecogniserTrainer::writeModelFile() method. Thus, this method will be called only once.

The fileName is the file name of the model file, including the path (e.g. "/Users/bob/Library/Digest/linear_recog52.model").

Because some recognisers may not require a training phase, or may not use a GestureLab managed model file for some other reason, this method could be implemented to just return true.

There are no restrictions on the file being binary or ascii, nor on its contents.

Implements AbstractRecogniser.

Stroke StlRecogniserWrapper::flatten ( const StrokeList strokes  )  [protected, virtual]

This is used to merge/join/flattern a (potentially) multi-stroke gesture before feature extraction is performed (and thus examination or classification).

If any filtering needs to be performed on the stroke(s), then it should be done by this method. This includes smoothing the stroke(s) or even reducing the number of points in them.

This default implementation simply joins all of the strokes together. It does not join strokes together based on the location of their start and end points.

Note: This is non-const, as the recogniser may need to examine the stroke's structure and record information about it, ready for use by either classify() or examineSample().

Reimplemented from AbstractRecogniser.

ClassProbabilities StlRecogniserWrapper::classify ( const FeatureVec featureVec  )  [protected, virtual]

This is called every time a given gesture is to be classified / recognised.

The featureVec is the feature vector that has been extracted from the gesture. Hence, the gesture parameter may not need to be used at all.

Note: The FeatureResultT typedef is currently a double.

The featureVec can be converted to an STL vector:

  vector<FeatureResultT> v = featureVec.toStdVector()

Note: If you wan't the stoke data for some reason, then store a copy of what you return from flatten().

The ClassProbabilities results to be returned is simply a hash-table that maps gesture classes to the recogniser's "confidence" that the given gesture belongs to the given class. The sum of the confidence values across all the classes (those known and trained-on) should be equal to 1.0. Thus, scaling may need to be performed before returning the results.

Note: The ClassProbabilities typedef is a QHash (hash-table - see the Qt doc), mapping the class ID ClassIndexT (currently an int) to the confidence ClassProbabilityT (currently a double).

It does not matter if there are fewer classes in the returned ClassProbabilities than there exists in the current database (new classes may be added to or removed from the database at any given time). Thus, a recogniser could simply return a hash that only has one item in it, which would have to have a confidence of 1.0.

Example - A recogniser has trained on three classes: X, Y and Z. If the recogniser has a confidence of 70% that the given gesture was an X, 20% that it was a Y and 10% that it was a Z, then the following would return the corresponding ClassProbabilities:

  ClassProbabilities results;
  results[X] = 0.7;
  results[Y] = 0.2;
  results[Z] = 0.1;
  return results;
Warning: The above is only an example of how the results are represented by ClassProbabilities. A real recogniser would obviously not be hard coded and would get the class IDs from its own model.

Implements AbstractRecogniser.


The documentation for this class was generated from the following files:
Generated on Mon Jul 30 09:46:53 2007 for Digest by  doxygen 1.5.2