

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object net.rim.device.api.system.DeviceOrientationUtil
public final class DeviceOrientationUtil
Provides utility methods to determine the BlackBerry device's orientation using
inputs from the device's MagnetometerSensor
and AccelerometerSensor
.
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 

public static final int AXIS_X
DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int)
.
public static final int AXIS_Y
DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int)
.
public static final int AXIS_Z
DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int)
.
public static final int AXIS_NEGATIVE_X
DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int)
.
public static final int AXIS_NEGATIVE_Y
DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int)
.
public static final int AXIS_NEGATIVE_Z
DeviceOrientationUtil.changeCoordinateSystem(float[], float[], int, int, int)
.
Method Detail 

public static boolean getRotationMatrix(float[] rm, float[] geomagnetic, float[] gravity)
The inverse of the rotation matrix can be computed by taking its transpose.
The rotation matrix is only useful if the device is not freefalling 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 1If rm is length 9, the resulting rotation matrix will have the following:
Rx Ry Rz Ux Uy Uz Bz By BzRm 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 columnmajor 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.
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.
true
if the rotation matrix is calculated, false
otherwise.
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.public static boolean getOrientation(float[] rm, float[] orientation)
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). true
if the orientation is calculated, false
otherwise.
IllegalArgumentException
 if orientation is not length 3
NullPointerException
 if rm or orientation is nullpublic static boolean changeCoordinateSystem(float[] rm, float[] rmNew, int x, int y, int z)
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 nonzero 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.
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.
true
if the supplied rotation matrix (rm) has been processed into
a new coordinate system (rmNew), false
otherwise.
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


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
Copyright 19992011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal