The Sensor Utility API provides utility functions.

Required Header

#include <sensor.h>

Overview

This Sensor API provides utility functions.

Functions
int	sensor_util_get_rotation_matrix (float Gx, float Gy, float Gz, float Mx, float My, float Mz, float R[], float I[])
	Gets the inclination matrix "I" and rotation matrix "R" transforming a vector from the device coordinate to the world's coordinate.
int	sensor_util_get_rotation_matrix_from_vector (float Vx, float Vy, float Vz, float R[])
	Converts a rotation vector to a rotation matrix.
int	sensor_util_remap_coordinate_system (float inR[], sensor_util_axis_e x, sensor_util_axis_e y, float outR[])
	Rotates the supplied rotation matrix so that it is expressed in a different coordinate system.
int	sensor_util_get_inclination (float I[], float *inclination)
	Computes the geomagnetic inclination angle in radians from the inclination matrix I returned by sensor_util_get_rotation_matrix().
int	sensor_util_get_orientation (float R[], float values[])
	Computes the device's orientation based on the rotation matrix.
int	sensor_util_get_angle_change (float R[], float prevR[], float angleChange[])
	Computes the angle change between two rotation matrices.
int	sensor_util_get_declination (float latitude, float longitude, float altitude, float *declination)
	Gets the declination of the horizontal component of the magnetic field from true north, in degrees.

Enumeration Type Documentation

enum sensor_util_axis_e

Enumeration of the axis used in sensor_util_remap_coordinate_system().

Since :: 2.3.1

Enumerator:

SENSOR_UTIL_AXIS_MINUS_X	-X
SENSOR_UTIL_AXIS_MINUS_Y	-Y
SENSOR_UTIL_AXIS_MINUS_Z	-Z
SENSOR_UTIL_AXIS_X	+X
SENSOR_UTIL_AXIS_Y	+Y
SENSOR_UTIL_AXIS_Z	+Z

Function Documentation

int sensor_util_get_angle_change	(	float	R[],
		float	prevR[],
		float	angleChange[]
	)

Computes the angle change between two rotation matrices.

Given a current rotation matrix (R) and a previous rotation matrix (prevR), it computes the rotation around the x,y, and z axes which transforms prevR to R. It outputs a 3 element vector containing the x,y, and z angle change at indexes 0, 1, and 2 respectively.

Since :: 2.3.1

Remarks:

Each input matrix is a 3x3 matrix like this form:

          { R[0], R[1], R[2],
            R[3], R[4], R[5],
            R[6], R[7], R[6] }

Parameters:

[in]	R	The current rotation matrix
[in]	prevR	The previous rotation matrix
[out]	angleChange	An array of floats in which the angle change is stored

Returns:: SENSOR_ERROR_NONE on success; otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter

int sensor_util_get_declination	(	float	latitude,
		float	longitude,
		float	altitude,
		float *	declination
	)

Gets the declination of the horizontal component of the magnetic field from true north, in degrees.

Since :: 2.3.1

Parameters:

[in]	latitude	The latitude in geodetic coordinates
[in]	longitude	The longitude in geodetic coordinates
[in]	altitude	The altitude in geodetic coordinates
[out]	declination	The declination of the horizontal component of the magnetic field in degrees

Returns:: SENSOR_ERROR_NONE on success; otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter

int sensor_util_get_inclination	(	float	I[],
		float *	inclination
	)

Computes the geomagnetic inclination angle in radians from the inclination matrix I returned by sensor_util_get_rotation_matrix().

Since :: 2.3.1

Parameters:

[in]	I	The inclination matrix from sensor_util_get_rotation_matrix()
[out]	inclination	The geomagnetic inclination angle in radians

Returns:: SENSOR_ERROR_NONE on success; otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: sensor_util_get_rotation_matrix()

int sensor_util_get_orientation	(	float	R[],
		float	values[]
	)

Computes the device's orientation based on the rotation matrix.

When it returns, the array values are filled with the result:

values[0]: azimuth, rotation around the Z axis.
values[1]: pitch, rotation around the X axis.
values[2]: roll, rotation around the Y axis.
Since :
2.3.1

Remarks:
Parameter R must be an array of 9 floats from sensor_util_get_rotation_matrix()
Returned values are always arrays of 3 floats.

Parameters:

[in] R A 9 element rotation matrix in the array

[out] values An array of 3 floats to hold the result

Returns:
SENSOR_ERROR_NONE on success; otherwise a negative error value

Return values:

SENSOR_ERROR_NONE Successful

SENSOR_ERROR_INVALID_PARAMETER Invalid parameter

See also:
sensor_util_get_rotation_matrix()

int sensor_util_get_rotation_matrix	(	float	Gx,
		float	Gy,
		float	Gz,
		float	Mx,
		float	My,
		float	Mz,
		float	R[],
		float	I[]
	)

Gets the inclination matrix "I" and rotation matrix "R" transforming a vector from the device coordinate to the world's coordinate.

[0 0 g] = R * gravity (g = magnitude of gravity)
[0 m 0] = I * R * geomagnetic (m = magnitude of the geomagnetic field)
R is the identity matrix when the device is aligned with the world's coordinate system, that is, when the device's X axis points towards the East, the Y axis points to the North Pole and the device is facing the sky.
I is a rotation matrix transforming the geomagnetic vector into the same coordinate space as gravity (the world's coordinate space). I is a simple rotation around the X axis.

Since :: 2.3.1

Remarks:

Parameters Gx, Gy, and Gz can be obtained from the values returned by SENSOR_GRAVITY.
Parameters Mx, My, and Mz can be obtained from the values returned by SENSOR_MAGNETIC.
Output parameter R and I are always returned as a 3x3 matrix array of 9 floats like this form:

          { R[0], R[1], R[2],
            R[3], R[4], R[5],
            R[6], R[7], R[6] }

Parameters:

[in]	Gx	The X-axis gravity vector in the device's coordinate
[in]	Gy	The Y-axis gravity vector in the device's coordinate
[in]	Gz	The Z-axis gravity vector in the device's coordinate
[in]	Mx	The X-axis geomagnetic vector in the device's coordinate
[in]	My	The Y-axis geomagnetic vector in the device's coordinate
[in]	Mz	The Z-axis geomagnetic vector in the device's coordinate
[out]	R	The array of 9 floats that represent the rotation matrix "R" It can be null.
[out]	I	The array of 9 floats that represent the inclination matrix "I" It can be null.

Returns:: SENSOR_ERROR_NONE on success; otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter

int sensor_util_get_rotation_matrix_from_vector	(	float	Vx,
		float	Vy,
		float	Vz,
		float	R[]
	)

Converts a rotation vector to a rotation matrix.

Rotation vectors (Vx, Vy, Vz) can be obtained from SENSOR_ROTATION_VECTOR. It returns a 9 element rotation matrix in the array R. R must have length as 9.

Since :: 2.3.1

Parameters:

[in]	Vx	The X-axis rotation vector
[in]	Vy	The Y-axis rotation vector
[in]	Vz	The Z-axis rotation vector
[out]	R	A 9 element rotation matrix in the array R that must have length as 9

Returns:: SENSOR_ERROR_NONE on success; Otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter

int sensor_util_remap_coordinate_system	(	float	inR[],
		sensor_util_axis_e	x,
		sensor_util_axis_e	y,
		float	outR[]
	)

Rotates the supplied rotation matrix so that it is expressed in a different coordinate system.

This is typically used when an application needs to compute the three orientation angles of the device in a different coordinate system.

Since :: 2.3.1

Remarks:: inR and outR can be the same array, but this is not recommended for performance reasons.
x and y should be perpendicular to each other. Otherwise, this function returns an error.

Parameters:

[in]	inR	The rotation matrix (3x3) to be transformed
[in]	x	The world axis and direction on which the X axis of the device is mapped
[in]	y	The world axis and direction on which the Y axis of the device is mapped
[out]	outR	The transformed rotation matrix (3x3)

Returns:: SENSOR_ERROR_NONE on success; otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter

Required Header

Overview

Functions

Enumeration Type Documentation

Function Documentation