net.rim.device.api.system
Class DeviceOrientationUtil

java.lang.Object
  net.rim.device.api.system.DeviceOrientationUtil

public final class DeviceOrientationUtil
extends Object

Provides utility methods to determine the BlackBerry device's orientation using inputs from the device's MagnetometerSensor and AccelerometerSensor.

Since:

BlackBerry API 7.0.0

Field Summary
static int	AXIS_NEGATIVE_X Represents a negative X axis that is used for DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int).
static int	AXIS_NEGATIVE_Y Represents a negative Y axis that is used for DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int).
static int	AXIS_NEGATIVE_Z Represents a negative Z axis that is used for DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int).
static int	AXIS_X Represents a positive X axis that is used for DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int).
static int	AXIS_Y Represents a positive Y axis that is used for DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int).
static int	AXIS_Z Represents a positive Z axis that is used for DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int).

Method Summary
static boolean	changeCoordinateSystem(float[] rm, float[] rmNew, int x, int y, int z) Performs a simple rotation of the specified rotation matrix that was calculated by getRotationMatrix().
static boolean	getOrientation(float[] rm, float[] orientation) Calculates the device's orientation from the specified rotation matrix.
static boolean	getRotationMatrix(float[] rm, float[] geomagnetic, float[] gravity) Calculates the rotation matrix (rm) for the device.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AXIS_X

public static final int AXIS_X

Represents a positive X axis that is used for DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int).

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

AXIS_Y

public static final int AXIS_Y

Represents a positive Y axis that is used for DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int).

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

AXIS_Z

public static final int AXIS_Z

Represents a positive Z axis that is used for DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int).

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

AXIS_NEGATIVE_X

public static final int AXIS_NEGATIVE_X

Represents a negative X axis that is used for DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int).

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

AXIS_NEGATIVE_Y

public static final int AXIS_NEGATIVE_Y

Represents a negative Y axis that is used for DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int).

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

AXIS_NEGATIVE_Z

public static final int AXIS_NEGATIVE_Z

Represents a negative Z axis that is used for DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int).

See Also:

Constant Field Values

Since:

BlackBerry API 7.0.0

Method Detail

getRotationMatrix

public static boolean getRotationMatrix(float[] rm,
                                        float[] geomagnetic,
                                        float[] gravity)

Calculates the rotation matrix (rm) for the device. The vectors from the device's coordinate system are transformed to the world coordinate system, which is an orthogonal normal basis, where:

• X is the vector product Y.Z (it is tangential to the ground at the device's current location and points approximately East)
• Y is tangental to the ground at the device's current location and points towards the north magnetic pole
• Z points towards the sky and it is perpendicular to the ground

• X is denoted by R below.
• Y is denoted by U below.
• Z is denoted by B below.

The inverse of the rotation matrix can be computed by taking its transpose.

The rotation matrix is only useful if the device is not free-falling and if the device is not close to a strong magnetic field. Results may be inaccurate if the device is accelerating rapidly or if the device is placed near a strong magnetic field.

 rm[0]  rm[1]  rm[2]  rm[3]
 rm[4]  rm[5]  rm[6]  rm[7]
 rm[8]  rm[9]  rm[10] rm[11]
 rm[12] rm[13] rm[14] rm[15] 

If rm is length 16, the resulting rotation matrix will have the following:

 Rx Ry Rz 0
 Ux Uy Uz 0
 Bz By Bz 0
 0  0  0  1 

If rm is length 9, the resulting rotation matrix will have the following:

 Rx Ry Rz 
 Ux Uy Uz 
 Bz By Bz  

Rm is the identity matrix when the device is aligned with the world's coordinate system. This matrix is ready to be used by OpenGL ES's glLoadMatrixf(float[], int). Note that because OpenGL matrices are column-major matrices, you must transpose the matrix before using it. However, since the matrix is a rotation matrix, its transpose is also its inverse, conveniently, it is often the inverse of the rotation that is needed for rendering; it can therefore be used with OpenGL ES directly.

Parameters:

rm - The resulting rotation matrix, which must be length of 9 or 16.

geomagnetic - The geomagnetic vector (x,y,z), which must be length 3.

gravity - The gravitational vector (x,y,z), which must be length 3.

Returns:

true if the rotation matrix is calculated, false otherwise.

Throws:

NullPointerException - if rm, geomagnetic, or gravity is null

IllegalArgumentException - if rm is not length 9 or 16, or if geomagnetic is not length 3, or if gravity is not length 3.

Since:

BlackBerry API 7.0.0

getOrientation

public static boolean getOrientation(float[] rm,
                                     float[] orientation)

Calculates the device's orientation from the specified rotation matrix. Note that the coordinate system is different than the world-coordinate system described for the rotation matrix.

Parameters:

rm - The rotation matrix that is calculated by DeviceOrientationUtil.getRotationMatrix(float[], float[], float[]). The length of the array must be 9 or 16.

orientation - The resulting orientation of the device. You can convert from radians to degrees using Math.toDegrees(double).

• orientation[0] is azimuth, or the rotation about the Z axis. Z is perpendicular to the ground and points towards its center. The range is (-pi, pi).
• orientation[1] is pitch, or the rotation about the X axis. X is the vector product Y.Z (it is tangential to the ground and points approximately West). The range is (-pi/2, pi/2).
• orientation[2] is roll, or the rotation about the Y axis. Y is tangential to the ground at the device's current location and points towards magnetic north. The range is (-pi, pi).

Returns:

true if the orientation is calculated, false otherwise.

Throws:

IllegalArgumentException - if orientation is not length 3

NullPointerException - if rm or orientation is null

Since:

BlackBerry API 7.0.0

changeCoordinateSystem

public static boolean changeCoordinateSystem(float[] rm,
                                             float[] rmNew,
                                             int x,
                                             int y,
                                             int z)

Performs a simple rotation of the specified rotation matrix that was calculated by getRotationMatrix().

You can use this method to compute the three orientation angles of the device DeviceOrientationUtil.getOrientation(float[], float[])) in a different coordinate system.

The given rotation matrix supplied by x, y, z is not validated. The values for x, y, z should be one of the following values: DeviceOrientationUtil.AXIS_X, DeviceOrientationUtil.AXIS_Y, DeviceOrientationUtil.AXIS_Z, DeviceOrientationUtil.AXIS_NEGATIVE_X, DeviceOrientationUtil.AXIS_NEGATIVE_Y, DeviceOrientationUtil.AXIS_NEGATIVE_Z.

Examples:

To rotate the rotation matrix by 90 degrees on the Z axis, use changeCoordinateSystem(rm, newRm, AXIS_Y, AXIS_NEGATIVE_X, AXIS_Z). This points the top of the device west.

To rotate the rotation matrix -90 degrees on the X axis, use changeCoordinateSystem(rm, newRm, AXIS_X, AXIS_Z, AXIS_NEGATIVE_Y). This points the back of the device north. This rotation is often used in augmented reality applications.

For example, when you specify changeCoordinateSystem(rm, newRm, AXIS_X, AXIS_Z, AXIS_NEGATIVE_Y) you are defining a rotation matrix that's defined as the following:

  1   0   0  (AXIS_X)
  0   0   1  (AXIS_Z)
  0  -1   0  (AXIS_NEGATIVE_Y)
  

These rotations are simple, because they define a matrix where each row and column only contains one non-zero value, which is either +1 or -1. Thus, this method exists only to compute simple 90 degree rotations. For other rotations, you must define the rotation matrix and perform the matrix multiplication.

Parameters:

rm - The rotation matrix that is calculated in DeviceOrientationUtil.getRotationMatrix(float[], float[], float[]).

rmNew - The rotation matrix after rotation is performed. This matrix must be the same size as rm, but it cannot be equal to rm.

x - The world axis that the X axis of the device is aligned to.

y - The world axis that the Y axis of the device is aligned to.

z - The world axis that the Z axis of the device is aligned to.

Returns:

true if the supplied rotation matrix (rm) has been processed into a new coordinate system (rmNew), false otherwise.

Throws:

IllegalArgumentException - if rm == rmNew

IllegalArgumentException - if rm.length != rmNew.length

IllegalArgumentException - if rm.length != 16 and rm.length != 9

NullPointerException - if rm or rmNew are null

Since:

BlackBerry API 7.0.0