Skip to content

Ircam-RnD/xmm-node

Repository files navigation

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

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.