@ircam/sc-motion

Simple motion processing utilities.

Install

npm install --save @ircam/sc-motion

Format

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.

API

Table of Contents

• format
  • Examples
  • dataXyz
  • dataAlphaBetaGamma
  • dataArray
  • dataMotion
  • degreeToRadian
  • radianToDegree
  • g
  • gToNewton
  • newtonToG
  • arrayNormaliseInPlace
  • xyzToArray
  • arrayToXyz
  • alphaBetaGammaToArray
  • arrayToAlphaBetaGamma
  • apiValidate
  • apiConvert
• Gravity
  • Parameters
  • Examples
  • outputApi
  • frequency
  • gyroscopeWeightLinear
  • reset
  • set
  • process

format

Format utilities for sensor data.

Examples

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 ]
// }

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 ],
// }

dataXyz

Data object with x, y, and z properties, for API 'v3'.

Type: Object

Properties

• x number The x-coordinate value.
• y number The y-coordinate value.
• z number The z-coordinate value.

dataAlphaBetaGamma

Data object with alpha, beta and gamma properties, for API 'v3'.

Type: Object

Properties

• alpha number The x-coordinate value.
• beta number The y-coordinate value.
• gamma number The z-coordinate value.

dataArray

Data array with three numerical values, for API 'v3'.

Type: Array<number>

Properties

• 0 number The first coordinate value.
• 1 number The second coordinate value.
• 2 number The third coordinate value.

dataMotion

Data sensor according to API version.

Type: (dataXyz | dataAlphaBetaGamma | dataArray)

degreeToRadian

Converts an angle from degrees to radians.

Parameters

• angle number The angle in degrees to be converted.

Returns number The angle in radians.

radianToDegree

Converts an angle from radians to degrees.

Parameters

• angle number The angle in radians to be converted.

Returns number The angle converted to degrees.

g

The standard acceleration due to gravity (g) in meters per second squared (m/s²).

Type: number

gToNewton

Converts a value from g-force (g) to Newtons (N).

Parameters

• force number The value in g-force to be converted.

Returns number The equivalent value in Newtons.

newtonToG

Converts a value from Newtons to G-force.

Parameters

• force number The value in Newtons to be converted.

Returns number The equivalent value in G-force.

arrayNormaliseInPlace

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 The original magnitude (Euclidean norm) of the vector.

xyzToArray

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 The x-coordinate value.
  • coordinates.y number The y-coordinate value.
  • coordinates.z number The z-coordinate value.

Returns Array<number> An array containing the x, y, and z values in order.

arrayToXyz

Converts an array of three numerical values into an object with x, y, and z 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, and z properties corresponding to the input array values.

alphaBetaGammaToArray

Converts an object containing alpha, beta, and gamma properties into an array.

Parameters

• angle dataAlphaBetaGamma The input object.

  • angle.alpha number The alpha value.
  • angle.beta number The beta value.
  • angle.gamma number The gamma value.

Returns dataArray An array containing the alpha, beta, and gamma values in order.

arrayToAlphaBetaGamma

Converts an array of three elements into an object with properties alpha, beta, and gamma.

Parameters

• $0 Array

  • $0.0
  • $0.1
  • $0.2

• angle dataArray An array containing three numeric elements [alpha, beta, gamma].

• angle number [0] - The alpha value.

• angle number [1] - The beta value.

• angle number [2] - The gamma value.

Returns dataAlphaBetaGamma An object with properties alpha, beta, and gamma.

apiValidate

Validates if the provided API is included in the list of valid APIs.

Parameters

• api string The API name to validate.

Returns boolean Returns true if the API is valid, otherwise false.

apiConvert

• See: apiValid

Copy and converts sensor data between different API formats.

Parameters

• options Object The format options.

  • options.api string? 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? The output API format.
  • options.magnetometer
  • options.thermometer
  • options.absoluteorientation
  • options.heading
  • options.battery
  • options.control
  • options.extra ...any

• Throws Error If the format between the specified input and output APIs is unsupported.

Returns Object The converted data. The output is a deep copy of the input data, even if the input and output APIs are the same.

Gravity

• See: https://w3c.github.io/accelerometer/#gravitysensor-interface

Gravity class for estimating gravity using accelerometer and gyroscope.

Parameters

• $0 Object (optional, default {})

  • $0.outputApi (optional, default 'v3')
  • $0.gyroscopeWeightLinear (optional, default 0.9)
  • $0.frequency (optional, default undefined)

• options Object Configuration options for the Gravity instance. (optional, default {})

Examples

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 }

outputApi

The API version for the input and output data. Current version is 'v3'.

Type: String

• Throws Error Throws an error if outputApi is invalid.

frequency

The sample rate for processing. Used if sampleTime is not provided when processing.

Type: (Number | undefined)

• Throws Error Throws an error if frequency is not a positive number.

gyroscopeWeightLinear

The linear weight for the gyroscope.

Type: Float

• Throws Error Throws an error if gyroscopeWeightLinear is not between 0 and 1.

reset

Resets the internal state of the Gravity instance. Clears the last recorded sample time and resets the accelerometer and gyroscope estimates to null.

set

Sets the attributes for the Gravity instance.

Parameters

• attributes Object The attributes to set. Same as constructor.

• Throws Error Same as constructor.

process

Processes accelerometer and gyroscope data to estimate gravity.

accelerometer, gyroscope and gravity conform to the api version.

Parameters

• params Object 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? The timestamp of the current sample in seconds.
  • params.api

• Throws Error Throws an error if API version is missing.
• Throws Error Throws an error if accelerometer data is missing.
• Throws Error Throws an error if gyroscope data is missing.
• Throws Error 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.

License

BSD-3-Clause