Tizen Native API
Utility

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

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]RThe current rotation matrix
[in]prevRThe previous rotation matrix
[out]angleChangeAn array of floats in which the angle change is stored
Returns:
0 on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_NOT_SUPPORTEDThe 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]latitudeThe latitude in geodetic coordinates
[in]longitudeThe longitude in geodetic coordinates
[in]altitudeThe altitude in geodetic coordinates
[out]declinationThe declination of the horizontal component of the magnetic field in degrees
Returns:
0 on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_NOT_SUPPORTEDThe 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]IThe inclination matrix from sensor_util_get_rotation_matrix()
[out]inclinationThe geomagnetic inclination angle in radians
Returns:
0 on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_NOT_SUPPORTEDThe 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:

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]GxThe X-axis gravity vector in the device's coordinate
[in]GyThe Y-axis gravity vector in the device's coordinate
[in]GzThe Z-axis gravity vector in the device's coordinate
[in]MxThe X-axis geomagnetic vector in the device's coordinate
[in]MyThe Y-axis geomagnetic vector in the device's coordinate
[in]MzThe Z-axis geomagnetic vector in the device's coordinate
[out]RThe array of 9 floats that represent the rotation matrix "R"
It can be null.
[out]IThe 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_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_NOT_SUPPORTEDThe 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]VxThe X-axis rotation vector
[in]VyThe Y-axis rotation vector
[in]VzThe Z-axis rotation vector
[out]RA 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_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_NOT_SUPPORTEDThe 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]inRThe rotation matrix (3x3) to be transformed
[in]xThe world axis and direction on which the X axis of the device is mapped
[in]yThe world axis and direction on which the Y axis of the device is mapped
[out]outRThe transformed rotation matrix (3x3)
Returns:
0 on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_NOT_SUPPORTEDThe sensor type is not supported in the current device