Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

net.rim.device.api.system
Class MagnetometerData

java.lang.Object
  extended by net.rim.device.api.system.MagnetometerData

public final class MagnetometerData
extends Object

Encapsulates magnetometer sensor readings.

See Also:
MagnetometerChannelConfig
Since:
BlackBerry API 7.0.0

Field Summary
static int MAGNETOMETER_GET_DIRECTION_BACK
          Used in getDirection() to specify you want top direction.
static int MAGNETOMETER_GET_DIRECTION_BOTTOM
          Used in getDirection() to specify you want bottom direction.
static int MAGNETOMETER_GET_DIRECTION_FRONT
          Used in getDirection() to specify you want front direction.
static int MAGNETOMETER_GET_DIRECTION_LEFT
          Used in getDirection() to specify you want left direction.
static int MAGNETOMETER_GET_DIRECTION_RIGHT
          Used in getDirection() to specify you want right direction.
static int MAGNETOMETER_GET_DIRECTION_TOP
          Used in getDirection() to specify you want top direction.
static int MAGNETOMETER_HEADING_EAST
          Represents east heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_EAST_NORTH_EAST
          Represents east-northeast heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_EAST_SOUTH_EAST
          Represents east-southeast heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_NORTH
          Represents north heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_NORTH_EAST
          Represents northeast heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_NORTH_NORTH_EAST
          Represents north-northeast retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_NORTH_NORTH_WEST
          Represents north-northwest heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_NORTH_WEST
          Represents northwest heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_SOUTH
          Represents south heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_SOUTH_EAST
          Represents southeast heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_SOUTH_SOUTH_EAST
          Represents south-southeast heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_SOUTH_SOUTH_WEST
          Represents south-southwest heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_SOUTH_WEST
          Represents southwest heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_WEST
          Represents west heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_WEST_NORTH_WEST
          Represents west-northwest heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_HEADING_WEST_SOUTH_WEST
          Represents west-southwest heading retrieved by MagnetometerData.getHeading(float).
static int MAGNETOMETER_QUALITY_HIGH
          Represents high magnetometer quality, which is used by MagnetometerData.getCalibrationQuality().
static int MAGNETOMETER_QUALITY_LOW
          Represents low magnetometer quality, which is used by MagnetometerData.getCalibrationQuality().
static int MAGNETOMETER_QUALITY_MEDIUM
          Represents medium magnetometer quality, which is used by MagnetometerData.getCalibrationQuality().
static int MAGNETOMETER_QUALITY_UNRELIABLE
          Represents unreliable magnetometer quality, which is used by MagnetometerData.getCalibrationQuality().
 
Method Summary
 void getAccelerometerData(float[] xyz)
          Retrieves the accelerometer (Z) component from the rotation matrix.
 int getCalibrationQuality()
          Retrieves the calibration quality.
 float getDirection(int side)
          Retrieves the direction for the provided side.
 float getDirectionBack()
          Retrieves the clockwise-positive angle between magnetic north and the front of the device (negative z axis), in degrees.
 float getDirectionBottom()
          Retrieves the clockwise-positive angle between magnetic north and the bottom of the device (negative y axis), in degrees.
 float getDirectionFront()
          Retrieves the clockwise-positive angle between magnetic north and the front of the device (positive z axis), in degrees.
 float getDirectionLeft()
          Retrieves the clockwise-positive angle between magnetic north and the left of the device (negative x axis), in degrees.
 float getDirectionRight()
          Retrieves the clockwise-positive angle between magnetic north and the right of the device (positive x axis), in degrees.
 float getDirectionTop()
          Retrieves the clockwise-positive angle between magnetic north and the top of the device (positive y axis), in degrees.
 float getFieldStrength()
          Retrieves the local magnetic field strength, the magnitude of the geomagnetic vector.
static int getHeading(float angle)
          Retrieves a rough estimate of the heading, based on an angle value in the range [0, 360).
 float getInclination()
          Retrieves the angle between the x-y plane and the magnetic vector (dip angle).
 void getInclinationMatrix(float[] im)
          A matrix representing the inclination returned from getInclination.
 void getMagnetometerData(float[] xyz)
          Retrieves raw magnetometer data (in tesla).
 boolean getOrientation(float[] orientation)
          Retrieves the device orientation.
 boolean getRotationMatrix(float[] rm)
          Retrieves the rotation matrix.
 int getTimestamp()
          Retrieves a timestamp that specifies when this data was captured.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

MAGNETOMETER_QUALITY_UNRELIABLE

public static final int MAGNETOMETER_QUALITY_UNRELIABLE
Represents unreliable magnetometer quality, which is used by MagnetometerData.getCalibrationQuality().

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_QUALITY_LOW

public static final int MAGNETOMETER_QUALITY_LOW
Represents low magnetometer quality, which is used by MagnetometerData.getCalibrationQuality().

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_QUALITY_MEDIUM

public static final int MAGNETOMETER_QUALITY_MEDIUM
Represents medium magnetometer quality, which is used by MagnetometerData.getCalibrationQuality().

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_QUALITY_HIGH

public static final int MAGNETOMETER_QUALITY_HIGH
Represents high magnetometer quality, which is used by MagnetometerData.getCalibrationQuality().

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_NORTH

public static final int MAGNETOMETER_HEADING_NORTH
Represents north heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [348.75, 11.25).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_NORTH_NORTH_EAST

public static final int MAGNETOMETER_HEADING_NORTH_NORTH_EAST
Represents north-northeast retrieved by MagnetometerData.getHeading(float). This indicates a degree value [11.25, 33.75).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_NORTH_EAST

public static final int MAGNETOMETER_HEADING_NORTH_EAST
Represents northeast heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [33.75, 56.25).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_EAST_NORTH_EAST

public static final int MAGNETOMETER_HEADING_EAST_NORTH_EAST
Represents east-northeast heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [56.25, 78.75).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_EAST

public static final int MAGNETOMETER_HEADING_EAST
Represents east heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [78.75, 101.25).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_EAST_SOUTH_EAST

public static final int MAGNETOMETER_HEADING_EAST_SOUTH_EAST
Represents east-southeast heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [101.25, 123.75).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_SOUTH_EAST

public static final int MAGNETOMETER_HEADING_SOUTH_EAST
Represents southeast heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [123.75, 146.25).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_SOUTH_SOUTH_EAST

public static final int MAGNETOMETER_HEADING_SOUTH_SOUTH_EAST
Represents south-southeast heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [146.25, 168.75).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_SOUTH

public static final int MAGNETOMETER_HEADING_SOUTH
Represents south heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [168.75, 191.25).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_SOUTH_SOUTH_WEST

public static final int MAGNETOMETER_HEADING_SOUTH_SOUTH_WEST
Represents south-southwest heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [191.25, 213.75).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_SOUTH_WEST

public static final int MAGNETOMETER_HEADING_SOUTH_WEST
Represents southwest heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [213.75, 236.25).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_WEST_SOUTH_WEST

public static final int MAGNETOMETER_HEADING_WEST_SOUTH_WEST
Represents west-southwest heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [236.25, 258.75).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_WEST

public static final int MAGNETOMETER_HEADING_WEST
Represents west heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [258.75, 281.25).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_WEST_NORTH_WEST

public static final int MAGNETOMETER_HEADING_WEST_NORTH_WEST
Represents west-northwest heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [281.25, 303.75).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_NORTH_WEST

public static final int MAGNETOMETER_HEADING_NORTH_WEST
Represents northwest heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [303.75, 326.25).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_HEADING_NORTH_NORTH_WEST

public static final int MAGNETOMETER_HEADING_NORTH_NORTH_WEST
Represents north-northwest heading retrieved by MagnetometerData.getHeading(float). This indicates a degree value [326.25, 348.75).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_GET_DIRECTION_TOP

public static final int MAGNETOMETER_GET_DIRECTION_TOP
Used in getDirection() to specify you want top direction. Equivalent to getDirectionTop()

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_GET_DIRECTION_BOTTOM

public static final int MAGNETOMETER_GET_DIRECTION_BOTTOM
Used in getDirection() to specify you want bottom direction. Equivalent to getDirectionBottom()

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_GET_DIRECTION_LEFT

public static final int MAGNETOMETER_GET_DIRECTION_LEFT
Used in getDirection() to specify you want left direction. Equivalent to getDirectionLeft()

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_GET_DIRECTION_RIGHT

public static final int MAGNETOMETER_GET_DIRECTION_RIGHT
Used in getDirection() to specify you want right direction. Equivalent to getDirectionRight()

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_GET_DIRECTION_FRONT

public static final int MAGNETOMETER_GET_DIRECTION_FRONT
Used in getDirection() to specify you want front direction. Equivalent to getDirectionFront()

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

MAGNETOMETER_GET_DIRECTION_BACK

public static final int MAGNETOMETER_GET_DIRECTION_BACK
Used in getDirection() to specify you want top direction. Equivalent to getDirectionBack()

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0


Method Detail

getMagnetometerData

public void getMagnetometerData(float[] xyz)
Retrieves raw magnetometer data (in tesla).

Parameters:
xyz - The array to store magnetometer data in. xyz should be of length 3.
Since:
BlackBerry API 7.0.0

getAccelerometerData

public void getAccelerometerData(float[] xyz)
Retrieves the accelerometer (Z) component from the rotation matrix.

Parameters:
xyz - The array to store accelerometer data in. xyz should be of length 3.
See Also:
getRotationMatrix
Since:
BlackBerry API 7.0.0

getRotationMatrix

public boolean getRotationMatrix(float[] rm)
Retrieves the rotation matrix. The accelerometer and magnetometer data used in the construction of this rotation matrix has been filtered and corrected. If this is not desired (or not sufficient) then DeviceOrientationUtil#getRotationMatrix can be used directly.

Parameters:
rm - The rotation matrix, either length 9 or 16.
Returns:
true if the rotation matrix is returned, false otherwise.
See Also:
for more details about this method.
Since:
BlackBerry API 7.0.0

getOrientation

public boolean getOrientation(float[] orientation)
Retrieves the device orientation.

Parameters:
orientation - The device orientation.
Returns:
true if the device orientation is returned, false otherwise.
Throws:
IllegalArgumentException - if orientation is not length 3
See Also:
for more details about this method.
Since:
BlackBerry API 7.0.0

getFieldStrength

public float getFieldStrength()
Retrieves the local magnetic field strength, the magnitude of the geomagnetic vector.

Returns:
The strength of the local magnetic field.
Since:
BlackBerry API 7.0.0

getDirection

public float getDirection(int side)
Retrieves the direction for the provided side.

Parameters:
side - side to return the direction for.
Returns:
the direction
Throws:
IllegalArgumentException - if side is invalid
Since:
BlackBerry API 7.0.0

getDirectionTop

public float getDirectionTop()
Retrieves the clockwise-positive angle between magnetic north and the top of the device (positive y axis), in degrees.

Returns:
The direction (in degrees) where the value is in the range [0, 360).
Since:
BlackBerry API 7.0.0

getDirectionBottom

public float getDirectionBottom()
Retrieves the clockwise-positive angle between magnetic north and the bottom of the device (negative y axis), in degrees.

Returns:
The direction (in degrees) where the value is in the range [0, 360).
Since:
BlackBerry API 7.0.0

getDirectionRight

public float getDirectionRight()
Retrieves the clockwise-positive angle between magnetic north and the right of the device (positive x axis), in degrees.

Returns:
The direction (in degrees) where the value is in the range [0, 360).
Since:
BlackBerry API 7.0.0

getDirectionLeft

public float getDirectionLeft()
Retrieves the clockwise-positive angle between magnetic north and the left of the device (negative x axis), in degrees.

Returns:
The direction (in degrees) where the value is in the range [0, 360).
Since:
BlackBerry API 7.0.0

getDirectionFront

public float getDirectionFront()
Retrieves the clockwise-positive angle between magnetic north and the front of the device (positive z axis), in degrees.

Returns:
The direction (in degrees) where the value is in the range [0, 360).
Since:
BlackBerry API 7.0.0

getDirectionBack

public float getDirectionBack()
Retrieves the clockwise-positive angle between magnetic north and the front of the device (negative z axis), in degrees.

Returns:
The direction (in degrees) where the value is in the range [0, 360).
Since:
BlackBerry API 7.0.0

getInclination

public float getInclination()
Retrieves the angle between the x-y plane and the magnetic vector (dip angle). This is a simple rotation about the x-axis, negative values indicate the inclination vector points below the x-y plane, positive values indicate the inclination vector points above the x-y plane.

Returns:
The inclination (in degrees).
Since:
BlackBerry API 7.0.0

getInclinationMatrix

public void getInclinationMatrix(float[] im)
A matrix representing the inclination returned from getInclination. This is a simple rotation about the x-axis.
|10 0|
|0cos(inc) -sin(inc)|
|0sin(inc) cos(inc)|
or
|10 00|
|0cos(inc) -sin(inc)0|
|0sin(inc) cos(inc)0|
|00 01|

Parameters:
im - The inclination matrix, either length 9 or 16
Throws:
NullPointerException - if im is null.
Since:
BlackBerry API 7.0.0

getTimestamp

public int getTimestamp()
Retrieves a timestamp that specifies when this data was captured. This value should not be confused with epoch, and should be used to calculate the difference between two measurements (i.e. it's min value is device startup).

Returns:
The timestamp this data was captured.
Since:
BlackBerry API 7.0.0

getHeading

public static int getHeading(float angle)
Retrieves a rough estimate of the heading, based on an angle value in the range [0, 360). Boxes the provided angle value to a 16pt compass rose.

Parameters:
angle - The specified angle value, which can be in the range of [0, 360).
Returns:
The heading, which can be one of the MAGNETOMETER_HEADING_* constants.
Throws:
IllegalArgumentException - if the angle is less than 0.
Since:
BlackBerry API 7.0.0

getCalibrationQuality

public int getCalibrationQuality()
Retrieves the calibration quality.

Returns:
The calibration quality, which can be one of the following values:
Since:
BlackBerry API 7.0.0



Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

Copyright 1999-2011 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