javax.microedition.location
Class Orientation

java.lang.Object
  javax.microedition.location.Orientation

public class Orientation
extends java.lang.Object

The Orientation class represents the physical orientation of the terminal. Orientation is described by azimuth to north (the horizontal pointing direction), pitch (the vertical elevation angle) and roll (the rotation of the terminal around its own longitudinal axis).

It is not expected that all terminals will support all of these parameters. If a terminal supports getting the Orientation, it must provide the compass azimuth information. Most commonly, this class will be used to obtain the current compass direction. Providing the pitch and roll is optional. Pitch and roll information are not meant to be used as an accelerometer data, but only to help in determining the accuracy of the azimuth value. Access to the accelerometer data should be done through other APIs, for example, through JSR 256 Sensor API.

It is up to the terminal to define its own axes, but it is generally recommended that the longitudinal axis is aligned with the bottom-to-top direction of the screen. This means that the pitch is positive when the top of the screen is up and the bottom of the screen down (when roll is zero). The roll is positive when the device is tilted clockwise looking from the direction of the bottom of the screen, i.e. when the left side of the screen is up and the right side of the screen is down (when pitch is zero).

The azimuth information may not be accurate if the terminal is not aligned vertically. If the API implementation takes the device orientation information into account when calculating the azimuth value, then getPitch and getRoll methods should return Float.NaN. No separate accuracy data is given for Orientation.

This class is only a container for the information. The constructor does not validate the parameters passed in but just retains the values. The get* methods return the values passed in the constructor. When the platform implementation returns Orientation objects, it must ensure that it only returns objects where the parameters have values set as described for their semantics in this class.

Constructor Summary

Orientation(float azimuth, boolean isMagnetic, float pitch, float roll)
Constructs a new Orientation object with the compass azimuth, pitch and roll parameters specified.

Method Summary

float	getCompassAzimuth() Returns the terminal's horizontal compass azimuth in degrees relative to either magnetic or true north.
static Orientation	getOrientation() Returns the terminal's current orientation.
float	getPitch() Returns the terminal's tilt in degrees defined as an angle in the vertical plane orthogonal to the ground, and through the longitudinal axis of the terminal.
float	getRoll() Returns the terminal's rotation in degrees around its own longitudinal axis.
boolean	isOrientationMagnetic() Returns a boolean value that indicates whether this Orientation is relative to the magnetic field of the Earth or relative to true north and gravity.

Methods inherited from class java.lang.Object

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

Constructor Detail

Orientation

public Orientation(float azimuth,
                   boolean isMagnetic,
                   float pitch,
                   float roll)

Constructs a new Orientation object with the compass azimuth, pitch and roll parameters specified.

The values are expressed in degrees using floating point values.

If the pitch or roll is undefined, the parameter shall be given as Float.NaN.

Parameters:

azimuth - The compass azimuth relative to true or magnetic north. Valid range: [0.0, 360.0). For example, value 0.0 indicates north, 90.0 east, 180.0 south and 270.0 west.

isMagnetic - a boolean stating whether the compass azimuth is given as relative to the magnetic field of the Earth (=true) or to true north and gravity (=false)

pitch - the pitch of the terminal in degrees, valid range: [-90.0, 90.0] or Float.NaN if the pitch is undefined

roll - the roll of the terminal in degrees, valid range: [-180.0, 180.0) or Float.NaN if the roll is undefined

Method Detail

getCompassAzimuth

public float getCompassAzimuth()

Returns the terminal's horizontal compass azimuth in degrees relative to either magnetic or true north. The value is always in the range [0.0, 360.0) degrees. The isOrientationMagnetic() method indicates whether the returned azimuth is relative to true north or magnetic north.

Returns:

the terminal's compass azimuth in degrees relative to true or magnetic north

See Also:

isOrientationMagnetic()

isOrientationMagnetic

public boolean isOrientationMagnetic()

Returns a boolean value that indicates whether this Orientation is relative to the magnetic field of the Earth or relative to true north and gravity. If this method returns true, the compass azimuth and pitch are relative to the magnetic field of the Earth. If this method returns false, the compass azimuth is relative to true north and pitch is relative to gravity.

Returns:

true if this Orientation is relative to the magnetic field of the Earth, false if this Orientation is relative to true north and gravity

See Also:

getCompassAzimuth()

getPitch

public float getPitch()

Returns the terminal's tilt in degrees defined as an angle in the vertical plane orthogonal to the ground, and through the longitudinal axis of the terminal. The value is always in the range [-90.0, 90.0] degrees. A negative value means that the top of the terminal screen is pointing towards the ground.

Returns:

the terminal's pitch in degrees or Float.NaN if not available

getRoll

public float getRoll()

Returns the terminal's rotation in degrees around its own longitudinal axis. The value is always in the range [-180.0, 180.0) degrees. A negative value means that the terminal is orientated anti-clockwise from its default orientation, looking from direction of the bottom of the screen.

Returns:

the terminal's roll in degrees or Float.NaN if not available

getOrientation

public static Orientation getOrientation()
                                  throws LocationException

Returns the terminal's current orientation.

Returns:

an Orientation object containing the terminal's current orientation or null if the orientation can not be currently determined

Throws:

java.lang.SecurityException - if the calling application does not have a permission to query the orientation

LocationException - if the implementation does not support orientation determination

See Also:

Orientation