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.

The Utility API provides utility functions.

Required Header

#include <sensor.h>

Overview

Related Features

This API is related with the following features:

It is recommended to design feature related codes in your application for reliability.

You can check if a devrice supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature Element.

Enumeration Type Documentation

enum sensor_util_axis_e

Enumeration of the axis used in sensor_util_remap_coordinate_system.

Since :: 2.3

See also:: sensor_util_remap_coordinate_system

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

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:: 0 on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device

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

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:: 0 on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device

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

Parameters:

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

Returns:: 0 on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device

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

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:
0 on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE Successful

SENSOR_ERROR_INVALID_PARAMETER Invalid parameter

SENSOR_ERROR_NOT_SUPPORTED The sensor type is not supported in the current device

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

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:: 0 on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device

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

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:: 0 on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device

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

Remarks:: inR and outR can be the same array, but this is not recommended for performance reasons. This returns an error when X and Y define the same axis.

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:: 0 on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device

Functions

Required Header

Overview

Related Features

Enumeration Type Documentation

Function Documentation