net.rim.device.api.location
Class GeomagneticField

java.lang.Object
  net.rim.device.api.location.GeomagneticField

public class GeomagneticField
extends Object

Estimates the magnetic field at a given point on Earth, and calculates the magnetic declination from true north.

This class uses the current World Magnetic Model (WMM2010). For more information about the WMM, visit World Magnetic Model.

Since:

BlackBerry API 7.0.0

Constructor Summary

GeomagneticField(double lat, double lon, int alt)
Estimates the geomagnetic field for the location specified in World Geodetic System 1984 (WGS84) coordinates.

Method Summary
float	getDeclination() Retrieves the declination (the angle between magnetic north and true north) of the geomagnetic field.
float	getFieldStrength() Retrieves the total intensity of the geomagnetic field.
float	getHorizontalFieldStrength() Retrieves the total horizontal intensity of the geomagnetic field.
float	getInclination() Retrieves the inclination (the angle relative to the horizontal plane) of the geomagnetic field.
float	getX() Retrieves the north component of the geomagnetic field.
float	getY() Retrieves the east component of the geomagnetic field.
float	getZ() Retrieves the vertical component (downwards) of the geomagnetic field.

Methods inherited from class java.lang.Object

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

Constructor Detail

GeomagneticField

public GeomagneticField(double lat,
                        double lon,
                        int alt)

Estimates the geomagnetic field for the location specified in World Geodetic System 1984 (WGS84) coordinates. estimate is called on this object's construction.

Parameters:

lat - Represents latitude, -90 degrees (south) to approximately +90 degrees (north), centered at the equator.

lon - Represents longitude, -180 degrees (west) to +180 degrees (east), centered at the prime meridian.

alt - Represents altitude, measured in meters, above (positive) or below (negative).

Throws:

IllegalArgumentException - if lat < -90 or lat > 90

IllegalArgumentException - if lon < -180 or lon > 180

IllegalStateException - if MagnetometerSensor.isSupported() returns false

Since:

BlackBerry API 7.0.0

Method Detail

getDeclination

public float getDeclination()

Retrieves the declination (the angle between magnetic north and true north) of the geomagnetic field.

Declination is positive when magnetic north is east of true north. Declination is negative when magnetic north is west of true north.

Returns:

The declination of the geomagnetic field, in degrees.

Since:

BlackBerry API 7.0.0

getInclination

public float getInclination()

Retrieves the inclination (the angle relative to the horizontal plane) of the geomagnetic field. A positive inclination indicates that the magnetic field vector is pointing above the horizonal plane. A negative inclination indicates that the magnetic field vector is pointing below the horizonal plane.

Returns:

The inclination of the geomagnetic field, in degrees.

Since:

BlackBerry API 7.0.0

getFieldStrength

public float getFieldStrength()

Retrieves the total intensity of the geomagnetic field.

Returns:

The strength of the geomagnetic field.

Since:

BlackBerry API 7.0.0

getHorizontalFieldStrength

public float getHorizontalFieldStrength()

Retrieves the total horizontal intensity of the geomagnetic field.

Returns:

The horizontal strength of the geomagnetic field.

Since:

BlackBerry API 7.0.0

getX

public float getX()

Retrieves the north component of the geomagnetic field.

Returns:

The north component of the geomagnetic field.

Since:

BlackBerry API 7.0.0

getY

public float getY()

Retrieves the east component of the geomagnetic field.

Returns:

The east component of the geomagnetic field.

Since:

BlackBerry API 7.0.0

getZ

public float getZ()

Retrieves the vertical component (downwards) of the geomagnetic field.

Returns:

The vertical component of the geomagnetic field.

Since:

BlackBerry API 7.0.0