Processing tools for motion
npm install @ircam/sc-motionSimple motion processing utilities.
``sh
npm install --save @ircam/sc-motion
`
Our goal is to provide unified axis and units across the different platforms. For this reason, we choose to follow the W3C specifications.
Please see FORMAT.md for OSC and WebSocket messages format.
In particular, we support the R-IoT hardware device and the CoMote phone app.
| |
| - |
| ⚠️ Please note that the messages format changed between version 2 and version 3. The old format for CoMote v2 is documented here. |
| |
* [format][1]
* [Examples][2]
* [dataXyz][3]
* [dataAlphaBetaGamma][4]
* [dataArray][5]
* [dataMotion][6]
* [degreeToRadian][7]
* [radianToDegree][8]
* [g][9]
* [gToNewton][10]
* [newtonToG][11]
* [arrayNormaliseInPlace][12]
* [xyzToArray][13]
* [arrayToXyz][14]
* [alphaBetaGammaToArray][15]
* [arrayToAlphaBetaGamma][16]
* [apiValidate][17]
* [apiConvert][18]
* [Gravity][19]
* [Parameters][20]
* [Examples][21]
* [outputApi][22]
* [frequency][23]
* [gyroscopeWeightLinear][24]
* [reset][25]
* [set][26]
* [process][27]
Format utilities for sensor data.
`javascript
import { xyzToArray } from '@ircam/sc-motion/format.js';
const accelerometer = { x: 9.81, y: 0, z: 0 };
const accelerometerArray = xyzToArray(accelerometer);
console.log({ accelerometer, accelerometerArray });
// {
// accelerometer: { x: 9.81, y: 0, z: 0 },
// accelerometerArray: [ 9.81, 0, 0 ]
// }
`
`javascript
import { apiConvert } from '@ircam/sc-motion/format.js';
const sensorData = {
api: 'v3',
accelerometer: { x: 9.81, y: 0, z: 0 },
gyroscope: { x: 0, y: 0, z: 0 },
};
const sensorDataConverted = apiConvert({
...sensorData,
outputApi: 'riot-v2-array',
});
console.log(sensorDataConverted);
// {
// api: 'riot-v2-array',
// accelerometer: [ 0, 9.81, 0 ],
// gyroscope: [ 0, 0, 0 ],
// }
`
Data object with x, y, and z properties, for API 'v3'.
Type: [Object][28]
#### Properties
* x [number][29] The x-coordinate value.y
* [number][29] The y-coordinate value.z
* [number][29] The z-coordinate value.
Data object with alpha, beta and gamma properties, for API 'v3'.
Type: [Object][28]
#### Properties
* alpha [number][29] The x-coordinate value.beta
* [number][29] The y-coordinate value.gamma
* [number][29] The z-coordinate value.
Data array with three numerical values, for API 'v3'.
Type: [Array][30]<[number][29]>
#### Properties
* 0 [number][29] The first coordinate value.1
* [number][29] The second coordinate value.2
* [number][29] The third coordinate value.
Data sensor according to API version.
Type: (dataXyz | dataAlphaBetaGamma | dataArray)
Converts an angle from degrees to radians.
#### Parameters
* angle [number][29] The angle in degrees to be converted.
Returns [number][29] The angle in radians.
Converts an angle from radians to degrees.
#### Parameters
* angle [number][29] The angle in radians to be converted.
Returns [number][29] The angle converted to degrees.
The standard acceleration due to gravity (g) in meters per second squared (m/s²).
Type: [number][29]
Converts a value from g-force (g) to Newtons (N).
#### Parameters
* force [number][29] The value in g-force to be converted.
Returns [number][29] The equivalent value in Newtons.
Converts a value from Newtons to G-force.
#### Parameters
* force [number][29] The value in Newtons to be converted.
Returns [number][29] The equivalent value in G-force.
Normalises a 3D vector in place and returns its original magnitude.
This function modifies the input array array directly by dividing each of its
components by the vector's magnitude (Euclidean norm). If the magnitude is
zero, the vector remains unchanged.
#### Parameters
* array dataArray A 3-element array representing the 3D vector to normalise.
Returns [number][29] The original magnitude (Euclidean norm) of the vector.
Converts an object with x, y, and z properties into an array.
#### Parameters
* coordinates dataXyz The object containing x, y, and z properties.
* coordinates.x [number][29] The x-coordinate value.coordinates.y
* [number][29] The y-coordinate value.coordinates.z
* [number][29] The z-coordinate value.
Returns [Array][30]<[number][29]> An array containing the x, y, and z values in order.
Converts an array of three numerical values into an object with x, y,z
and properties.
#### Parameters
* coordinates dataArray An array containing three numbers \[x, y, z].
* coordinates.0 coordinates.1
* coordinates.2
*
Returns dataXyz An object with x, y,z
and properties corresponding to the input array values.
Converts an object containing alpha, beta, and gamma properties into an array.
#### Parameters
* angle dataAlphaBetaGamma The input object.
* angle.alpha [number][29] The alpha value.angle.beta
* [number][29] The beta value.angle.gamma
* [number][29] The gamma value.
Returns dataArray An array containing the alpha, beta, and gamma values in order.
Converts an array of three elements into an object with properties alpha, beta, and gamma.
#### Parameters
* $0 [Array][30]
* $0.0 $0.1
* $0.2
* angle
* dataArray An array containing three numeric elements \[alpha, beta, gamma].angle
* [number][29] \[0] - The alpha value.angle
* [number][29] \[1] - The beta value.angle
* [number][29] \[2] - The gamma value.
Returns dataAlphaBetaGamma An object with properties alpha, beta, and gamma.
Validates if the provided API is included in the list of valid APIs.
#### Parameters
* api [string][31] The API name to validate.
Returns [boolean][32] Returns true if the API is valid, otherwise false.
* See: apiValid
Copy and converts sensor data between different API formats.
#### Parameters
* options [Object][28] The format options.
* options.api [string][31]? The input API format.options.accelerometer
* dataMotion? The accelerometer data to convert.options.gyroscope
* dataMotion? The gyroscope data to convert.options.gravity
* dataMotion? The gravity data to convert.options.outputApi
* [string][31]? The output API format.options.magnetometer
* options.thermometer
* options.absoluteorientation
* options.heading
* options.battery
* options.control
* options.extra
* ...any
* Throws [Error][33] If the format between the specified input and output APIs is unsupported.
Returns [Object][28] The converted data. The output is a deep copy of the input
data, even if the input and output APIs are the same.
* See: [https://w3c.github.io/accelerometer/#gravitysensor-interface][34]
Gravity class for estimating gravity using accelerometer and gyroscope.
* $0 [Object][28] (optional, default {})
* $0.outputApi (optional, default 'v3')$0.gyroscopeWeightLinear
* (optional, default 0.9)$0.frequency
* (optional, default undefined)options
* [Object][28] Configuration options for the Gravity instance. (optional, default {})
`javascript
import { Gravity } from '@ircam/sc-motion';
const gravityProcessor = new Gravity({ outputApi: 'v3'});
let motionSensor;
let gravity;
motionSensor = {
api: 'v3',
accelerometer: { x: 9.81, y: 0, z: 0 },
gyroscope: { x: 0, y: 0, z: 0 },
sampleTime: 0,
};
gravity = gravityProcessor.process(motionSensor);
console.log(gravity);
// { x: 9.80665, y: 0, z: 0 }
motionSensor = {
api: 'v3',
accelerometer: { x: 4.40, y: 4.40, z: 0 },
gyroscope: { x: -0.001, y: -0.001, z: 0 },
sampleTime: 0.01,
};
gravity = gravityProcessor.process(motionSensor);
console.log(gravity);
// { x: 6.934348715723057, y: 6.934348715723057, z: 0 }
`
The API version for the input and output data. Current version is 'v3'.
Type: [String][31]
* Throws [Error][33] Throws an error if outputApi is invalid.
The sample rate for processing. Used if sampleTime is not provided when processing.
Type: ([Number][29] | [undefined][35])
* Throws [Error][33] Throws an error if frequency is not a positive number.
The linear weight for the gyroscope.
Type: Float
* Throws [Error][33] Throws an error if gyroscopeWeightLinear is not between 0 and 1.
Resets the internal state of the Gravity instance.
Clears the last recorded sample time and resets the
accelerometer and gyroscope estimates to null.
Sets the attributes for the Gravity instance.
#### Parameters
* attributes [Object][28] The attributes to set. Same as constructor.
* Throws [Error][33] Same as constructor.
Processes accelerometer and gyroscope data to estimate gravity.
accelerometer, gyroscope and gravity conform to the api version.
#### Parameters
* params [Object][28] The input parameters. (optional, default {})
* params.accelerometer dataMotion The accelerometer data, conforming to the API version.params.gyroscope
* dataMotion The gyroscope data, conforming to the API version.params.timestamp
* [number][29]? The timestamp of the current sample in seconds.params.api`
*
* Throws [Error][33] Throws an error if API version is missing.
* Throws [Error][33] Throws an error if accelerometer data is missing.
* Throws [Error][33] Throws an error if gyroscope data is missing.
* Throws [Error][33] Throws an error if both sample interval and sample rate are missing (sample rate
comes from the constructor or the set method).
Returns dataMotion An object containing the estimated gravity vector. The gravity vector
is normalised and conforms to the output API version specified in the constructor.
[1]: #format
[2]: #examples
[3]: #dataxyz
[4]: #dataalphabetagamma
[5]: #dataarray
[6]: #datamotion
[7]: #degreetoradian
[8]: #radiantodegree
[9]: #g
[10]: #gtonewton
[11]: #newtontog
[12]: #arraynormaliseinplace
[13]: #xyztoarray
[14]: #arraytoxyz
[15]: #alphabetagammatoarray
[16]: #arraytoalphabetagamma
[17]: #apivalidate
[18]: #apiconvert
[19]: #gravity
[20]: #parameters-11
[21]: #examples-1
[22]: #outputapi
[23]: #frequency
[24]: #gyroscopeweightlinear
[25]: #reset
[26]: #set
[27]: #process
[28]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[29]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
[30]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
[31]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[32]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
[33]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error
[34]: https://w3c.github.io/accelerometer/#gravitysensor-interface
[35]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined