GestureRecognitionToolkit  Version: 0.1.0
The Gesture Recognition Toolkit (GRT) is a cross-platform, open-source, c++ machine learning library for real-time gesture recognition.
DTW Class Reference
Inheritance diagram for DTW:
Classifier MLBase GRTBase Observer< TrainingResult > Observer< TestInstanceResult >

Public Types

enum  DistanceMethods { ABSOLUTE_DIST =0, EUCLIDEAN_DIST, NORM_ABSOLUTE_DIST }
 
enum  RejectionModes { TEMPLATE_THRESHOLDS =0, CLASS_LIKELIHOODS, THRESHOLDS_AND_LIKELIHOODS }
 
- Public Types inherited from Classifier
typedef std::map< std::string, Classifier *(*)() > StringClassifierMap
 
- Public Types inherited from MLBase
enum  BaseTypes { BASE_TYPE_NOT_SET =0, CLASSIFIER, REGRESSIFIER, CLUSTERER }
 

Public Member Functions

 DTW (bool useScaling=false, bool useNullRejection=false, Float nullRejectionCoeff=3.0, UINT rejectionMode=DTW::TEMPLATE_THRESHOLDS, bool dtwConstrain=true, Float radius=0.2, bool offsetUsingFirstSample=false, bool useSmoothing=false, UINT smoothingFactor=5, Float nullRejectionLikelihoodThreshold=0.99)
 
 DTW (const DTW &rhs)
 
virtual ~DTW (void)
 
DTWoperator= (const DTW &rhs)
 
virtual bool deepCopyFrom (const Classifier *classifier)
 
virtual bool train_ (TimeSeriesClassificationData &trainingData)
 
virtual bool predict_ (VectorFloat &inputVector)
 
virtual bool predict_ (MatrixFloat &timeSeries)
 
virtual bool reset ()
 
virtual bool clear ()
 
virtual bool saveModelToFile (std::fstream &file) const
 
virtual bool loadModelFromFile (std::fstream &file)
 
virtual bool recomputeNullRejectionThresholds ()
 
UINT getNumTemplates ()
 
bool setRejectionMode (UINT rejectionMode)
 
bool setNullRejectionThreshold (Float nullRejectionLikelihoodThreshold)
 
bool setOffsetTimeseriesUsingFirstSample (bool offsetUsingFirstSample)
 
bool setContrainWarpingPath (bool constrain)
 
bool setWarpingRadius (Float radius)
 
UINT getRejectionMode () const
 
bool enableZNormalization (bool useZNormalization, bool constrainZNorm=true)
 
bool enableTrimTrainingData (bool trimTrainingData, Float trimThreshold, Float maximumTrimPercentage)
 
Vector< DTWTemplategetModels ()
 
bool setModels (Vector< DTWTemplate > newTemplates)
 
Vector< VectorFloatgetInputDataBuffer () const
 
const Vector< MatrixFloat > & getDistanceMatrices () const
 
const Vector< Vector< IndexDist > > & getWarpingPaths () const
 
- Public Member Functions inherited from Classifier
 Classifier (void)
 
virtual ~Classifier (void)
 
bool copyBaseVariables (const Classifier *classifier)
 
std::string getClassifierType () const
 
bool getSupportsNullRejection () const
 
bool getNullRejectionEnabled () const
 
Float getNullRejectionCoeff () const
 
Float getMaximumLikelihood () const
 
Float getBestDistance () const
 
Float getPhase () const
 
virtual UINT getNumClasses () const
 
UINT getClassLabelIndexValue (UINT classLabel) const
 
UINT getPredictedClassLabel () const
 
VectorFloat getClassLikelihoods () const
 
VectorFloat getClassDistances () const
 
VectorFloat getNullRejectionThresholds () const
 
Vector< UINT > getClassLabels () const
 
Vector< MinMaxgetRanges () const
 
bool enableNullRejection (bool useNullRejection)
 
virtual bool setNullRejectionCoeff (Float nullRejectionCoeff)
 
virtual bool setNullRejectionThresholds (VectorFloat newRejectionThresholds)
 
bool getTimeseriesCompatible () const
 
ClassifiercreateNewInstance () const
 
ClassifierdeepCopy () const
 
const ClassifiergetClassifierPointer () const
 
const ClassifiergetBaseClassifier () const
 
- Public Member Functions inherited from MLBase
 MLBase (void)
 
virtual ~MLBase (void)
 
bool copyMLBaseVariables (const MLBase *mlBase)
 
virtual bool train (ClassificationData trainingData)
 
virtual bool train_ (ClassificationData &trainingData)
 
virtual bool train (RegressionData trainingData)
 
virtual bool train_ (RegressionData &trainingData)
 
virtual bool train (TimeSeriesClassificationData trainingData)
 
virtual bool train (ClassificationDataStream trainingData)
 
virtual bool train_ (ClassificationDataStream &trainingData)
 
virtual bool train (UnlabelledData trainingData)
 
virtual bool train_ (UnlabelledData &trainingData)
 
virtual bool train (MatrixFloat data)
 
virtual bool train_ (MatrixFloat &data)
 
virtual bool predict (VectorFloat inputVector)
 
virtual bool predict (MatrixFloat inputMatrix)
 
virtual bool map (VectorFloat inputVector)
 
virtual bool map_ (VectorFloat &inputVector)
 
virtual bool print () const
 
virtual bool save (const std::string filename) const
 
virtual bool load (const std::string filename)
 
virtual bool saveModelToFile (std::string filename) const
 
virtual bool loadModelFromFile (std::string filename)
 
virtual bool getModel (std::ostream &stream) const
 
Float scale (const Float &x, const Float &minSource, const Float &maxSource, const Float &minTarget, const Float &maxTarget, const bool constrain=false)
 
virtual std::string getModelAsString () const
 
DataType getInputType () const
 
DataType getOutputType () const
 
UINT getBaseType () const
 
UINT getNumInputFeatures () const
 
UINT getNumInputDimensions () const
 
UINT getNumOutputDimensions () const
 
UINT getMinNumEpochs () const
 
UINT getMaxNumEpochs () const
 
UINT getValidationSetSize () const
 
UINT getNumTrainingIterationsToConverge () const
 
Float getMinChange () const
 
Float getLearningRate () const
 
Float getRootMeanSquaredTrainingError () const
 
Float getTotalSquaredTrainingError () const
 
Float getValidationSetAccuracy () const
 
VectorFloat getValidationSetPrecision () const
 
VectorFloat getValidationSetRecall () const
 
bool getUseValidationSet () const
 
bool getRandomiseTrainingOrder () const
 
bool getTrained () const
 
bool getModelTrained () const
 
bool getScalingEnabled () const
 
bool getIsBaseTypeClassifier () const
 
bool getIsBaseTypeRegressifier () const
 
bool getIsBaseTypeClusterer () const
 
bool enableScaling (const bool useScaling)
 
bool setMaxNumEpochs (const UINT maxNumEpochs)
 
bool setMinNumEpochs (const UINT minNumEpochs)
 
bool setMinChange (const Float minChange)
 
bool setLearningRate (const Float learningRate)
 
bool setUseValidationSet (const bool useValidationSet)
 
bool setValidationSetSize (const UINT validationSetSize)
 
bool setRandomiseTrainingOrder (const bool randomiseTrainingOrder)
 
bool setTrainingLoggingEnabled (const bool loggingEnabled)
 
bool registerTrainingResultsObserver (Observer< TrainingResult > &observer)
 
bool registerTestResultsObserver (Observer< TestInstanceResult > &observer)
 
bool removeTrainingResultsObserver (const Observer< TrainingResult > &observer)
 
bool removeTestResultsObserver (const Observer< TestInstanceResult > &observer)
 
bool removeAllTrainingObservers ()
 
bool removeAllTestObservers ()
 
bool notifyTrainingResultsObservers (const TrainingResult &data)
 
bool notifyTestResultsObservers (const TestInstanceResult &data)
 
MLBasegetMLBasePointer ()
 
const MLBasegetMLBasePointer () const
 
Vector< TrainingResult > getTrainingResults () const
 
- Public Member Functions inherited from GRTBase
 GRTBase (void)
 
virtual ~GRTBase (void)
 
bool copyGRTBaseVariables (const GRTBase *GRTBase)
 
std::string getClassType () const
 
std::string getLastWarningMessage () const
 
std::string getLastErrorMessage () const
 
std::string getLastInfoMessage () const
 
bool setInfoLoggingEnabled (const bool loggingEnabled)
 
bool setWarningLoggingEnabled (const bool loggingEnabled)
 
bool setErrorLoggingEnabled (const bool loggingEnabled)
 
GRTBasegetGRTBasePointer ()
 
const GRTBasegetGRTBasePointer () const
 
- Public Member Functions inherited from Observer< TrainingResult >
virtual void notify (const TrainingResult &data)
 
- Public Member Functions inherited from Observer< TestInstanceResult >
virtual void notify (const TestInstanceResult &data)
 

Protected Member Functions

bool loadLegacyModelFromFile (std::fstream &file)
 
- Protected Member Functions inherited from Classifier
bool saveBaseSettingsToFile (std::fstream &file) const
 
bool loadBaseSettingsFromFile (std::fstream &file)
 
- Protected Member Functions inherited from MLBase
bool saveBaseSettingsToFile (std::fstream &file) const
 
bool loadBaseSettingsFromFile (std::fstream &file)
 
- Protected Member Functions inherited from GRTBase
Float SQR (const Float &x) const
 

Protected Attributes

Vector< DTWTemplatetemplatesBuffer
 
Vector< MatrixFloatdistanceMatrices
 
Vector< Vector< IndexDist > > warpPaths
 
CircularBuffer< VectorFloatcontinuousInputDataBuffer
 
UINT numTemplates
 
UINT rejectionMode
 
bool useSmoothing
 
bool useZNormalisation
 
bool offsetUsingFirstSample
 
bool constrainZNorm
 
bool constrainWarpingPath
 
bool trimTrainingData
 
Float zNormConstrainThreshold
 
Float radius
 
Float trimThreshold
 
Float maximumTrimPercentage
 
Float nullRejectionLikelihoodThreshold
 
UINT smoothingFactor
 
UINT distanceMethod
 
UINT averageTemplateLength
 
- Protected Attributes inherited from Classifier
std::string classifierType
 
bool supportsNullRejection
 
bool useNullRejection
 
UINT numClasses
 
UINT predictedClassLabel
 
UINT classifierMode
 
Float nullRejectionCoeff
 
Float maxLikelihood
 
Float bestDistance
 
Float phase
 
VectorFloat classLikelihoods
 
VectorFloat classDistances
 
VectorFloat nullRejectionThresholds
 
Vector< UINT > classLabels
 
Vector< MinMaxranges
 
- Protected Attributes inherited from MLBase
bool trained
 
bool useScaling
 
DataType inputType
 
DataType outputType
 
UINT baseType
 
UINT numInputDimensions
 
UINT numOutputDimensions
 
UINT numTrainingIterationsToConverge
 
UINT minNumEpochs
 
UINT maxNumEpochs
 
UINT validationSetSize
 
Float learningRate
 
Float minChange
 
Float rootMeanSquaredTrainingError
 
Float totalSquaredTrainingError
 
Float validationSetAccuracy
 
bool useValidationSet
 
bool randomiseTrainingOrder
 
VectorFloat validationSetPrecision
 
VectorFloat validationSetRecall
 
Random random
 
std::vector< TrainingResult > trainingResults
 
TrainingResultsObserverManager trainingResultsObserverManager
 
TestResultsObserverManager testResultsObserverManager
 
- Protected Attributes inherited from GRTBase
std::string classType
 
DebugLog debugLog
 
ErrorLog errorLog
 
InfoLog infoLog
 
TrainingLog trainingLog
 
TestingLog testingLog
 
WarningLog warningLog
 

Additional Inherited Members

- Static Public Member Functions inherited from Classifier
static ClassifiercreateInstanceFromString (std::string const &classifierType)
 
static Vector< std::string > getRegisteredClassifiers ()
 
- Static Public Member Functions inherited from GRTBase
static std::string getGRTVersion (bool returnRevision=true)
 
static std::string getGRTRevison ()
 
- Protected Types inherited from Classifier
enum  ClassifierModes { STANDARD_CLASSIFIER_MODE =0, TIMESERIES_CLASSIFIER_MODE }
 
- Static Protected Member Functions inherited from Classifier
static StringClassifierMapgetMap ()
 

Detailed Description

Definition at line 91 of file DTW.h.

Constructor & Destructor Documentation

DTW::DTW ( bool  useScaling = false,
bool  useNullRejection = false,
Float  nullRejectionCoeff = 3.0,
UINT  rejectionMode = DTW::TEMPLATE_THRESHOLDS,
bool  dtwConstrain = true,
Float  radius = 0.2,
bool  offsetUsingFirstSample = false,
bool  useSmoothing = false,
UINT  smoothingFactor = 5,
Float  nullRejectionLikelihoodThreshold = 0.99 
)

Default Constructor

Parameters
useScalingsets if the training and prediction data should be scaled to a specific range. Default value is useScaling = false
useNullRejectionsets if null rejection will be used for the realtime prediction. If useNullRejection is set to true then the predictedClassLabel will be set to 0 (which is the default null label) if the distance between the inputVector and the closest template is greater than the null rejection threshold for the top predicted class. The null rejection threshold is computed for each class during the training phase. Default value is useNullRejection = false
nullRejectionCoeffsets the null rejection coefficient, this is a multipler controlling the null rejection threshold for each class. This will only be used if the useNullRejection parameter is set to true. Default value is nullRejectionCoeff = 3.0
rejectionModesets the method used for null rejection. The options are TEMPLATE_THRESHOLDS, CLASS_LIKELIHOODS or THRESHOLDS_AND_LIKELIHOODS. Default = TEMPLATE_THRESHOLDS
dtwConstrainsets if the DTW warping path should be constrained within a specific distance from the main radius of the cost matrix. Default value = true
radiuscontrols the radius of the warping path, which is used if the dtwConstrain is set to true. Should be a value between [0 1]. Default value = 0.2
offsetUsingFirstSamplesets if each timeseries should be offset by the first sample in the timeseries. Default value = false
useSmoothingsets if the input timeseries should be smoothed (i.e. averaged and downsampled). Default value = false
smoothingFactorcontrols the amount of downsampling if the useSmoothing parameter is set to true. Default value = 5
nullRejectionLikelihoodThresholdset the null rejection threshold for likelihoods when CLASS_LIKELIHOODS or THRESHOLDS_AND_LIKELIHOODS modes are used for rejectionMode. Default value = 0.99

Definition at line 28 of file DTW.cpp.

DTW::DTW ( const DTW rhs)

Default copy constructor

Defines how the data from the rhs DTW should be copied to this DTW

Parameters
rhsanother instance of a DTW

Definition at line 65 of file DTW.cpp.

DTW::~DTW ( void  )
virtual

Default Destructor

Definition at line 69 of file DTW.cpp.

Member Function Documentation

bool DTW::clear ( )
virtual

This overrides the clear function in the Classifier base class. It will completely clear the ML module, removing any trained model and setting all the base variables to their default values.

Returns
returns true if the module was cleared succesfully, false otherwise

Reimplemented from Classifier.

Definition at line 522 of file DTW.cpp.

bool DTW::deepCopyFrom ( const Classifier classifier)
virtual

This is required for the Gesture Recognition Pipeline for when the pipeline.setClassifier(...) method is called. It clones the data from the Base Class Classifier pointer (which should be pointing to an DTW instance) into this instance

Parameters
classifiera pointer to the Classifier Base Class, this should be pointing to another DTW instance
Returns
returns true if the clone was successfull, false otherwise

Reimplemented from Classifier.

Definition at line 104 of file DTW.cpp.

bool DTW::enableTrimTrainingData ( bool  trimTrainingData,
Float  trimThreshold,
Float  maximumTrimPercentage 
)

Sets if the training data should be trimmed before training the DTW templates. If set to true then any training samples that have very little movement at the start or end of a file will be trimmed so as to remove the none movement at the start or end of the file. This can be useful if some of your examples have a section were the user paused before performing a gesture, or were the recording continued for a few seconds after the gesture ended. The trimThreshold and maximumTrimPrecentage parameters control how extreme the trimming can be. The trimThreshold should be in a range of [0 1] and the maximumTrimPrecentage should be in a range of [0 100]. If the amount of energy in the timeseries is below the trimThreshold then it will be trimmed.

Note that if the trimming mode is enabled, and a time series sample exceeds the maximumTrimPercentage, then that sample will not be added to the modified (trimmed) training dataset. If any sample exceeds the maximumTrimPercentage then a warning message will be displayed via the DTW trainingLog (unless the trainingLog's logging has been disabled).

Parameters
trimTrainingDataif true, then the training examples will be trimmed prior to training the DTW templates
trimThresholdthe trimThreshold sets the threshold at which the data should be trimmed. This should be in a range of [0 1]
maximumTrimPercentagethis sets the maximum amount of data that can be trimmed for one example. This should be in the range of [0 100]
Returns
returns true if the trimTrainingData parameters were updated successfully, false otherwise

Definition at line 1263 of file DTW.cpp.

bool DTW::enableZNormalization ( bool  useZNormalization,
bool  constrainZNorm = true 
)

Sets if z-normalization should be used for both training and realtime prediction. This should be called before training the templates.

Parameters
useZNormalizationif true then the data will be z-normalized before both training and prediction
constrainZNormif true then the data will only be z-normalized if the std-dev of the data is below a specific threshold
Returns
returns true if z-normalization was updated successfully, false otherwise

Definition at line 1257 of file DTW.cpp.

const Vector< MatrixFloat >& DTW::getDistanceMatrices ( ) const
inline

Gets the distances matrices from the last prediction. Each element in the vector represents the distance matrices for each corresponding class.

Returns
returns a vector of MatrixFloat containing the distance matrices from the last prediction, or an empty vector if no prediction has been made

Definition at line 320 of file DTW.h.

Vector< VectorFloat > DTW::getInputDataBuffer ( ) const
inline

Gets the current data in the DTW circular buffer.

Returns
returns a vector of VectorFloats containing the current data in the DTW circular buffer

Definition at line 313 of file DTW.h.

Vector< DTWTemplate > DTW::getModels ( )
inline

Gets the DTW models.

Returns
returns a vector of DTW templates, or an empty vector if no model has been trained.

Definition at line 299 of file DTW.h.

UINT DTW::getNumTemplates ( )
inline

This returns the number of templates in the current model.

Returns
returns an unsigned integer representing the number of templates in the current model.

Definition at line 216 of file DTW.h.

UINT DTW::getRejectionMode ( ) const
inline

Gets the rejection mode used for null rejection. The rejection mode will be one of the RejectionModes enums.

Returns
returns an unsigned integer representing the current rejection mode

Definition at line 265 of file DTW.h.

const Vector< Vector< IndexDist > >& DTW::getWarpingPaths ( ) const
inline

Gets the warping paths from the last prediction. Each element in the vector represents the warping path for each corresponding class.

Returns
returns a vector of vectors containing the warping paths from the last prediction, or an empty vector if no prediction has been made

Definition at line 327 of file DTW.h.

bool DTW::loadModelFromFile ( std::fstream &  file)
virtual

This loads a trained DTW model from a file. This overrides the loadModelFromFile function in the Classifier base class.

Parameters
filea reference to the file the DTW model will be loaded from
Returns
returns true if the model was loaded successfully, false otherwise

Reimplemented from MLBase.

Definition at line 1003 of file DTW.cpp.

DTW & DTW::operator= ( const DTW rhs)

Defines how the data from the rhs DTW should be copied to this DTW

Parameters
rhsanother instance of a DTW
Returns
returns a pointer to this instance of the DTW

Definition at line 73 of file DTW.cpp.

bool DTW::predict_ ( VectorFloat inputVector)
virtual

This predicts the class of the inputVector. This overrides the predict function in the Classifier base class.

Parameters
inputVectorthe input vector to classify
Returns
returns true if the prediction was performed, false otherwise

Reimplemented from MLBase.

Definition at line 474 of file DTW.cpp.

bool DTW::predict_ ( MatrixFloat timeSeries)
virtual

This predicts the class of the timeseries. This overrides the predict function in the Classifier base class.

Parameters
timeSeriesthe input timeseries to classify
Returns
returns true if the prediction was performed, false otherwise

Reimplemented from MLBase.

Definition at line 354 of file DTW.cpp.

bool DTW::recomputeNullRejectionThresholds ( )
virtual

This recomputes the null rejection thresholds for each of the classes in the DTW model. This will be called automatically if the setGamma(Float gamma) function is called. The DTW model needs to be trained first before this function can be called.

Returns
returns true if the null rejection thresholds were updated successfully, false otherwise

Reimplemented from Classifier.

Definition at line 536 of file DTW.cpp.

bool DTW::reset ( )
virtual

This resets the DTW classifier.

Returns
returns true if the DTW model was successfully reset, false otherwise.

Reimplemented from Classifier.

Definition at line 513 of file DTW.cpp.

bool DTW::saveModelToFile ( std::fstream &  file) const
virtual

This saves the trained DTW model to a file. This overrides the saveModelToFile function in the Classifier base class.

Parameters
filea reference to the file the DTW model will be saved to
Returns
returns true if the model was saved successfully, false otherwise

Reimplemented from MLBase.

Definition at line 942 of file DTW.cpp.

bool DTW::setContrainWarpingPath ( bool  constrain)

Sets if the warping path should be constrained to within a specific radius from the main diagonal of the cost matrix.

Parameters
constrainif true then the warping path should be constrained
Returns
returns true if the constrain parameter was updated successfully, false otherwise

Definition at line 1247 of file DTW.cpp.

bool DTW::setModels ( Vector< DTWTemplate newTemplates)

Sets the DTW models, overwriting any previous models. The size of the new templates vector must match the size of the old templates buffer.

Returns
returns true if the templates were updated, false otherwise

Definition at line 551 of file DTW.cpp.

bool DTW::setNullRejectionThreshold ( Float  nullRejectionLikelihoodThreshold)

Sets the rejection threshold for rejections based on class likelihood.

Returns
returns true if the rejection threshold was updated successfully, false otherwise

Definition at line 1236 of file DTW.cpp.

bool DTW::setOffsetTimeseriesUsingFirstSample ( bool  offsetUsingFirstSample)

Sets if each timeseries should be offset by the first sample in the timeseries. This can help the DTW algorithm be more invariant to the position a gesture is performed without having to normalize the data. You shoud call this function before training the algorithm.

Parameters
offsetUsingFirstSamplesets if each timeseries should be offset by the first sample in the timeseries
Returns
returns true if the offsetUsingFirstSample parameter was updated successfully, false otherwise

Definition at line 1242 of file DTW.cpp.

bool DTW::setRejectionMode ( UINT  rejectionMode)

Sets the rejection mode used for null rejection. The rejection mode should be one of the RejectionModes enums.

Returns
returns true if the rejection mode was updated successfully, false otherwise

Definition at line 1228 of file DTW.cpp.

bool DTW::setWarpingRadius ( Float  radius)

Sets the warping radius, this is used to constrain the warping path within a specific radius from the main diagonal of the cost matrix. This is only used if the #constrainWarpingPath parameter is set to true. The radius should be a value between [0 1].

Parameters
radiusthe new warping radius (should be between [0 1]
Returns
returns true if the warping radius parameter was updated successfully, false otherwise

Definition at line 1252 of file DTW.cpp.

bool DTW::train_ ( TimeSeriesClassificationData trainingData)
virtual

This trains the DTW model, using the labelled timeseries classification data. This overrides the train function in the Classifier base class.

Parameters
trainingDataa reference to the training data
Returns
returns true if the DTW model was trained, false otherwise

Reimplemented from MLBase.

Definition at line 139 of file DTW.cpp.


The documentation for this class was generated from the following files: