xmm-node

XMM native addon for Node.js

Wraps the XMM gesture recognition library into a NodeJS module. Can be used together with the client-side model decoders library xmm-client.

developers :

install :

• install latest NodeJS version
• clone xmm-node : git clone --recursive https://github.com/ircam-rnd/xmm-node.git
• install dependencies listed in package.json : npm install

build : node-pre-gyp rebuild

test : npm run test

publish : use node-pre-gyp-github

users :

npm install [--save] ircam-rnd/xmm-node

example :

// es6 :
import xmm from 'xmm-node';
// or older es versions :
var xmm = require('xmm-node');

// then :
var hhmm = new xmm('hhmm', {
	gaussians: 3,
	states: 12,
	relativeRegularization: 0.1,
	absoluteRegularization: 0.1
});

// valid xmm phrase created with xmm-client/PhraseMaker
var phrase = someFunctionReturningAPhrase();

hhmm.addPhrase(phrase);

hhmm.train(function(err, res) {
	if (err === null) {
		// res is a trained model : pass it to xmm-client/HhmmDecoder
		// or use hhmm.filter(someObservationVector) to do the decoding server-side.
	}
});

credits :

This library is developed by the ISMM team at IRCAM, within the context of the RAPID-MIX project, funded by the European Union’s Horizon 2020 research and innovation programme.
Original XMM code authored by Jules Françoise, ported to NodeJS by Joseph Larralde.
See github.com/Ircam-RnD/xmm for detailed XMM credits.

---

API documentation :

xmm

Kind: global class

• xmm
  • new xmm([modelType], [modelConfig])
  • .getConfig([configParam]) ⇒ xmmModelConfig | Number | String | Boolean
  • .setConfig(config)
  • .addPhrase(phrase)
  • .getPhrase(index) ⇒ Object
  • .getPhrasesOfLabel(label) ⇒ Object
  • .removePhrase(index)
  • .removePhrasesOfLabel(label)
  • .getTrainingSetSize() ⇒ Number
  • .getTrainingSetLabels() ⇒ Array.String
  • .getTrainingSet() ⇒ Object
  • .setTrainingSet(trainingSet)
  • .addTrainingSet(trainingSet)
  • .clearTrainingSet()
  • .train(callback)
  • .cancelTraining()
  • .getModel() ⇒ Object
  • .setModel(model)
  • .getModelType() ⇒ 'gmm' | 'hhmm'
  • .reset()
  • .filter(observation) ⇒ Object

new xmm([modelType], [modelConfig])

The main xmm class.

Param	Type	Default	Description
[modelType]	'gmm|hhmm'	'gmm'	The type of model.
[modelConfig]	xmmModelConfig		Configuration parameters for the model.

xmm.getConfig([configParam]) ⇒ xmmModelConfig | Number | String | Boolean

Get the actual model configuration parameters or one of them.

Kind: instance method of xmm
Returns: xmmModelConfig | Number | String | Boolean - Depends on the parameter.

If called without any argument, returns :

an object of type xmmModelConfig containing all the actual model configuration parameters

Otherwise, the returned value type depends on the requested configuration parameter :

'gaussians' : the number of gaussians

'relativeRegularization' : the relative regularization foat value

'absoluteRegularization' : the absolute regularization float value

'covarianceMode' : the actual covariance mode ('full' or 'diagonal')

'hierarchical' : if the model type is not 'hhmm', undefined, otherwise true if the model is hierarchical and false if it is not

'states' : if the model type is not 'hhmm', undefined, otherwise the number of states of the hmms

'transitionMode' : if the model type is not 'hhmm', undefined, otherwise the actual transition mode value ('ergodic' or 'leftright')

'regressionEstimator' : if the model type is not 'hhmm', undefined, otherwise the actual regression estimator used with hmms ('full', 'windowed' or 'likeliest')

'multiClassRegressionEstimator' : how to compute the regression : based on the likeliest class, or based on the whole set of classes,

Param	Type	Description
[configParam]	'gaussians|relativeRegularization|absoluteRegularization| covarianceMode|hierarchical|states|transitionMode| regressionEstimator|multiClassRegressionEstimator'	The name of a configuration parameter.

xmm.setConfig(config)

Set the actual model configuration parameters.

Kind: instance method of xmm

Param	Type	Description
config	xmmModelConfig	A config object as returned by getConfig when called without arguments (missing parameters won't be changed internally and invalid ones will be ignored).

xmm.addPhrase(phrase)

Add a phrase to the internal training set.

Kind: instance method of xmm

Param	Type	Description
phrase	Object	An object containing a valid XMM phrase.

xmm.getPhrase(index) ⇒ Object

Get phrase of a certain index from the internal training set.

Kind: instance method of xmm
Returns: Object - A valid XMM phrase from the internal training set.

Param	Type	Description
index	Number	The index of a phrase in the training set.

xmm.getPhrasesOfLabel(label) ⇒ Object

Get phrases of a certain label from the internal training set.

Kind: instance method of xmm
Returns: Object - A valid XMM training set containing all the requested phrases.

Param	Type	Description
label	String	The label of which we want to get the phrases.

xmm.removePhrase(index)

Remove phrase of a certain index from the internal training set.

Kind: instance method of xmm

Param	Type	Description
index	Number	The index of a phrase in the training set.

xmm.removePhrasesOfLabel(label)

Remove phrases of a certain label from the internal training set.

Kind: instance method of xmm

Param	Type	Description
label	String	The label of which we want to remove the phrases.

xmm.getTrainingSetSize() ⇒ Number

Get the number of phrases in the training set.

Kind: instance method of xmm
Returns: Number - The number of phrases in the training set.

xmm.getTrainingSetLabels() ⇒ Array.String

Get the array of all the labels in the training set.

Kind: instance method of xmm
Returns: Array.String - An array containing all the training set's labels.

xmm.getTrainingSet() ⇒ Object

Get the actual training set as an object.

Kind: instance method of xmm
Returns: Object - An object containing a valid XMM training set.

xmm.setTrainingSet(trainingSet)

Sets the actual training set.

Kind: instance method of xmm

Param	Type	Description
trainingSet	Object	An object containing a valid XMM training set.

xmm.addTrainingSet(trainingSet)

Adds a training set to the actual training set.

Kind: instance method of xmm

Param	Type	Description
trainingSet	Object	An object containing a valid XMM training set.

xmm.clearTrainingSet()

Clears the training set.

Kind: instance method of xmm

xmm.train(callback)

Trains the model with the current training set.

Kind: instance method of xmm

Param	Type	Description
callback	trainCallback	The callback handling the trained model.

xmm.cancelTraining()

Cancel the current training process.
WARNING This feature is experimental and may cause crashes

Kind: instance method of xmm

xmm.getModel() ⇒ Object

Returns the trained model (the same object as in trainCallback).

Kind: instance method of xmm
Returns: Object - An object containing the trained model.

xmm.setModel(model)

Sets the actual model from another already trained model.

Kind: instance method of xmm

Param	Type	Description
model	Object	A valid XMM model of the instance's actual type.

xmm.getModelType() ⇒ 'gmm' | 'hhmm'

Returns the type of the actual model.

Kind: instance method of xmm
Returns: 'gmm' | 'hhmm' - The type of model as String.

xmm.reset()

Resets the internal variables used for filtering.

Kind: instance method of xmm

xmm.filter(observation) ⇒ Object

Estimates an input array of floats.

Kind: instance method of xmm
Returns: Object - filteringResults - An object containing the estimation results.

Param	Type	Description
observation	Array.Number	The observation we want an estimation of.

---

xmmModelConfig

Kind: global typedef
Properties

Name	Type	Default	Description
[gaussians]	Number	1	the number of gaussians used for encoding a state.
[relativeRegularization]	Number	0.01	the relative regularization (see XMM documentation).
[absoluteRegularization]	Number	0.01	the absolute regularization (see XMM documentation).
[covarianceMode]	'diagonal|full'	'full'	the type of covariance matrix used in the model.
[hierarchical]	Boolean	true	if model is 'hhmm', turns hierarchical mode on/off.
[states]	Number	1	if model is 'hhmm', defines the number of states used to generate each individual hmm.
[transitionMode]	'ergodic|leftright'	'leftright'	if model is 'hhmm', sets the transition mode between the states of the individual hmm models.
[regressionEstimator]	'full|windowed|likeliest'	'full'	if model is 'hhmm', the type of estimator used for regression with hmms.
[multiClassRegressionEstimator]	'likeliest|mixture'	'likeliest'	how to compute the regression : based on the likeliest class, or based on the whole set of classes.

---

trainCallback : function

Callback handling the trained model.

Kind: global typedef

Param	Type	Description
err	String	Description of a potential error.
res	Object	An object containing the trained model.

---