Tizen Native API  3.0
Sensor Utility

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

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]RThe current rotation matrix
[in]prevRThe previous rotation matrix
[out]angleChangeAn 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_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid 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]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:
SENSOR_ERROR_NONE on success; otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid 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]IThe inclination matrix from sensor_util_get_rotation_matrix()
[out]inclinationThe geomagnetic inclination angle in radians
Returns:
SENSOR_ERROR_NONE on success; otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid 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:

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]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:
SENSOR_ERROR_NONE on success; otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid 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]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:
SENSOR_ERROR_NONE on success; Otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid 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]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:
SENSOR_ERROR_NONE on success; otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter