android.location.Location Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* Copyright (C) 2007 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.location;
import android.os.Bundle;
import android.os.Parcel;
import android.os.Parcelable;
import android.util.Printer;
import java.text.DecimalFormat;
import java.util.StringTokenizer;
/**
* A class representing a geographic location sensed at a particular
* time (a "fix"). A location consists of a latitude and longitude, a
* UTC timestamp. and optionally information on altitude, speed, and
* bearing.
*
* Information specific to a particular provider or class of
* providers may be communicated to the application using getExtras,
* which returns a Bundle of key/value pairs. Each provider will only
* provide those entries for which information is available.
*/
public class Location implements Parcelable {
/**
* Constant used to specify formatting of a latitude or longitude
* in the form "[+-]DDD.DDDDD where D indicates degrees.
*/
public static final int FORMAT_DEGREES = 0;
/**
* Constant used to specify formatting of a latitude or longitude
* in the form "[+-]DDD:MM.MMMMM" where D indicates degrees and
* M indicates minutes of arc (1 minute = 1/60th of a degree).
*/
public static final int FORMAT_MINUTES = 1;
/**
* Constant used to specify formatting of a latitude or longitude
* in the form "DDD:MM:SS.SSSSS" where D indicates degrees, M
* indicates minutes of arc, and S indicates seconds of arc (1
* minute = 1/60th of a degree, 1 second = 1/3600th of a degree).
*/
public static final int FORMAT_SECONDS = 2;
private String mProvider;
private long mTime = 0;
private double mLatitude = 0.0;
private double mLongitude = 0.0;
private boolean mHasAltitude = false;
private double mAltitude = 0.0f;
private boolean mHasSpeed = false;
private float mSpeed = 0.0f;
private boolean mHasBearing = false;
private float mBearing = 0.0f;
private boolean mHasAccuracy = false;
private float mAccuracy = 0.0f;
private Bundle mExtras = null;
// Cache the inputs and outputs of computeDistanceAndBearing
// so calls to distanceTo() and bearingTo() can share work
private double mLat1 = 0.0;
private double mLon1 = 0.0;
private double mLat2 = 0.0;
private double mLon2 = 0.0;
private float mDistance = 0.0f;
private float mInitialBearing = 0.0f;
// Scratchpad
private float[] mResults = new float[2];
public void dump(Printer pw, String prefix) {
pw.println(prefix + "mProvider=" + mProvider + " mTime=" + mTime);
pw.println(prefix + "mLatitude=" + mLatitude + " mLongitude=" + mLongitude);
pw.println(prefix + "mHasAltitude=" + mHasAltitude + " mAltitude=" + mAltitude);
pw.println(prefix + "mHasSpeed=" + mHasSpeed + " mSpeed=" + mSpeed);
pw.println(prefix + "mHasBearing=" + mHasBearing + " mBearing=" + mBearing);
pw.println(prefix + "mHasAccuracy=" + mHasAccuracy + " mAccuracy=" + mAccuracy);
pw.println(prefix + "mExtras=" + mExtras);
}
/**
* Constructs a new Location. By default, time, latitude,
* longitude, and numSatellites are 0; hasAltitude, hasSpeed, and
* hasBearing are false; and there is no extra information.
*
* @param provider the name of the location provider that generated this
* location fix.
*/
public Location(String provider) {
mProvider = provider;
}
/**
* Constructs a new Location object that is a copy of the given
* location.
*/
public Location(Location l) {
set(l);
}
/**
* Sets the contents of the location to the values from the given location.
*/
public void set(Location l) {
mProvider = l.mProvider;
mTime = l.mTime;
mLatitude = l.mLatitude;
mLongitude = l.mLongitude;
mHasAltitude = l.mHasAltitude;
mAltitude = l.mAltitude;
mHasSpeed = l.mHasSpeed;
mSpeed = l.mSpeed;
mHasBearing = l.mHasBearing;
mBearing = l.mBearing;
mHasAccuracy = l.mHasAccuracy;
mAccuracy = l.mAccuracy;
mExtras = (l.mExtras == null) ? null : new Bundle(l.mExtras);
}
/**
* Clears the contents of the location.
*/
public void reset() {
mProvider = null;
mTime = 0;
mLatitude = 0;
mLongitude = 0;
mHasAltitude = false;
mAltitude = 0;
mHasSpeed = false;
mSpeed = 0;
mHasBearing = false;
mBearing = 0;
mHasAccuracy = false;
mAccuracy = 0;
mExtras = null;
}
/**
* Converts a coordinate to a String representation. The outputType
* may be one of FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS.
* The coordinate must be a valid double between -180.0 and 180.0.
*
* @throws IllegalArgumentException if coordinate is less than
* -180.0, greater than 180.0, or is not a number.
* @throws IllegalArgumentException if outputType is not one of
* FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS.
*/
public static String convert(double coordinate, int outputType) {
if (coordinate < -180.0 || coordinate > 180.0 ||
Double.isNaN(coordinate)) {
throw new IllegalArgumentException("coordinate=" + coordinate);
}
if ((outputType != FORMAT_DEGREES) &&
(outputType != FORMAT_MINUTES) &&
(outputType != FORMAT_SECONDS)) {
throw new IllegalArgumentException("outputType=" + outputType);
}
StringBuilder sb = new StringBuilder();
// Handle negative values
if (coordinate < 0) {
sb.append('-');
coordinate = -coordinate;
}
DecimalFormat df = new DecimalFormat("###.#####");
if (outputType == FORMAT_MINUTES || outputType == FORMAT_SECONDS) {
int degrees = (int) Math.floor(coordinate);
sb.append(degrees);
sb.append(':');
coordinate -= degrees;
coordinate *= 60.0;
if (outputType == FORMAT_SECONDS) {
int minutes = (int) Math.floor(coordinate);
sb.append(minutes);
sb.append(':');
coordinate -= minutes;
coordinate *= 60.0;
}
}
sb.append(df.format(coordinate));
return sb.toString();
}
/**
* Converts a String in one of the formats described by
* FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS into a
* double.
*
* @throws NullPointerException if coordinate is null
* @throws IllegalArgumentException if the coordinate is not
* in one of the valid formats.
*/
public static double convert(String coordinate) {
// IllegalArgumentException if bad syntax
if (coordinate == null) {
throw new NullPointerException("coordinate");
}
boolean negative = false;
if (coordinate.charAt(0) == '-') {
coordinate = coordinate.substring(1);
negative = true;
}
StringTokenizer st = new StringTokenizer(coordinate, ":");
int tokens = st.countTokens();
if (tokens < 1) {
throw new IllegalArgumentException("coordinate=" + coordinate);
}
try {
String degrees = st.nextToken();
double val;
if (tokens == 1) {
val = Double.parseDouble(degrees);
return negative ? -val : val;
}
String minutes = st.nextToken();
int deg = Integer.parseInt(degrees);
double min;
double sec = 0.0;
if (st.hasMoreTokens()) {
min = Integer.parseInt(minutes);
String seconds = st.nextToken();
sec = Double.parseDouble(seconds);
} else {
min = Double.parseDouble(minutes);
}
boolean isNegative180 = negative && (deg == 180) &&
(min == 0) && (sec == 0);
// deg must be in [0, 179] except for the case of -180 degrees
if ((deg < 0.0) || (deg > 179 && !isNegative180)) {
throw new IllegalArgumentException("coordinate=" + coordinate);
}
if (min < 0 || min > 59) {
throw new IllegalArgumentException("coordinate=" +
coordinate);
}
if (sec < 0 || sec > 59) {
throw new IllegalArgumentException("coordinate=" +
coordinate);
}
val = deg*3600.0 + min*60.0 + sec;
val /= 3600.0;
return negative ? -val : val;
} catch (NumberFormatException nfe) {
throw new IllegalArgumentException("coordinate=" + coordinate);
}
}
private static void computeDistanceAndBearing(double lat1, double lon1,
double lat2, double lon2, float[] results) {
// Based on http://www.ngs.noaa.gov/PUBS_LIB/inverse.pdf
// using the "Inverse Formula" (section 4)
int MAXITERS = 20;
// Convert lat/long to radians
lat1 *= Math.PI / 180.0;
lat2 *= Math.PI / 180.0;
lon1 *= Math.PI / 180.0;
lon2 *= Math.PI / 180.0;
double a = 6378137.0; // WGS84 major axis
double b = 6356752.3142; // WGS84 semi-major axis
double f = (a - b) / a;
double aSqMinusBSqOverBSq = (a * a - b * b) / (b * b);
double L = lon2 - lon1;
double A = 0.0;
double U1 = Math.atan((1.0 - f) * Math.tan(lat1));
double U2 = Math.atan((1.0 - f) * Math.tan(lat2));
double cosU1 = Math.cos(U1);
double cosU2 = Math.cos(U2);
double sinU1 = Math.sin(U1);
double sinU2 = Math.sin(U2);
double cosU1cosU2 = cosU1 * cosU2;
double sinU1sinU2 = sinU1 * sinU2;
double sigma = 0.0;
double deltaSigma = 0.0;
double cosSqAlpha = 0.0;
double cos2SM = 0.0;
double cosSigma = 0.0;
double sinSigma = 0.0;
double cosLambda = 0.0;
double sinLambda = 0.0;
double lambda = L; // initial guess
for (int iter = 0; iter < MAXITERS; iter++) {
double lambdaOrig = lambda;
cosLambda = Math.cos(lambda);
sinLambda = Math.sin(lambda);
double t1 = cosU2 * sinLambda;
double t2 = cosU1 * sinU2 - sinU1 * cosU2 * cosLambda;
double sinSqSigma = t1 * t1 + t2 * t2; // (14)
sinSigma = Math.sqrt(sinSqSigma);
cosSigma = sinU1sinU2 + cosU1cosU2 * cosLambda; // (15)
sigma = Math.atan2(sinSigma, cosSigma); // (16)
double sinAlpha = (sinSigma == 0) ? 0.0 :
cosU1cosU2 * sinLambda / sinSigma; // (17)
cosSqAlpha = 1.0 - sinAlpha * sinAlpha;
cos2SM = (cosSqAlpha == 0) ? 0.0 :
cosSigma - 2.0 * sinU1sinU2 / cosSqAlpha; // (18)
double uSquared = cosSqAlpha * aSqMinusBSqOverBSq; // defn
A = 1 + (uSquared / 16384.0) * // (3)
(4096.0 + uSquared *
(-768 + uSquared * (320.0 - 175.0 * uSquared)));
double B = (uSquared / 1024.0) * // (4)
(256.0 + uSquared *
(-128.0 + uSquared * (74.0 - 47.0 * uSquared)));
double C = (f / 16.0) *
cosSqAlpha *
(4.0 + f * (4.0 - 3.0 * cosSqAlpha)); // (10)
double cos2SMSq = cos2SM * cos2SM;
deltaSigma = B * sinSigma * // (6)
(cos2SM + (B / 4.0) *
(cosSigma * (-1.0 + 2.0 * cos2SMSq) -
(B / 6.0) * cos2SM *
(-3.0 + 4.0 * sinSigma * sinSigma) *
(-3.0 + 4.0 * cos2SMSq)));
lambda = L +
(1.0 - C) * f * sinAlpha *
(sigma + C * sinSigma *
(cos2SM + C * cosSigma *
(-1.0 + 2.0 * cos2SM * cos2SM))); // (11)
double delta = (lambda - lambdaOrig) / lambda;
if (Math.abs(delta) < 1.0e-12) {
break;
}
}
float distance = (float) (b * A * (sigma - deltaSigma));
results[0] = distance;
if (results.length > 1) {
float initialBearing = (float) Math.atan2(cosU2 * sinLambda,
cosU1 * sinU2 - sinU1 * cosU2 * cosLambda);
initialBearing *= 180.0 / Math.PI;
results[1] = initialBearing;
if (results.length > 2) {
float finalBearing = (float) Math.atan2(cosU1 * sinLambda,
-sinU1 * cosU2 + cosU1 * sinU2 * cosLambda);
finalBearing *= 180.0 / Math.PI;
results[2] = finalBearing;
}
}
}
/**
* Computes the approximate distance in meters between two
* locations, and optionally the initial and final bearings of the
* shortest path between them. Distance and bearing are defined using the
* WGS84 ellipsoid.
*
*
The computed distance is stored in results[0]. If results has length
* 2 or greater, the initial bearing is stored in results[1]. If results has
* length 3 or greater, the final bearing is stored in results[2].
*
* @param startLatitude the starting latitude
* @param startLongitude the starting longitude
* @param endLatitude the ending latitude
* @param endLongitude the ending longitude
* @param results an array of floats to hold the results
*
* @throws IllegalArgumentException if results is null or has length < 1
*/
public static void distanceBetween(double startLatitude, double startLongitude,
double endLatitude, double endLongitude, float[] results) {
if (results == null || results.length < 1) {
throw new IllegalArgumentException("results is null or has length < 1");
}
computeDistanceAndBearing(startLatitude, startLongitude,
endLatitude, endLongitude, results);
}
/**
* Returns the approximate distance in meters between this
* location and the given location. Distance is defined using
* the WGS84 ellipsoid.
*
* @param dest the destination location
* @return the approximate distance in meters
*/
public float distanceTo(Location dest) {
// See if we already have the result
synchronized (mResults) {
if (mLatitude != mLat1 || mLongitude != mLon1 ||
dest.mLatitude != mLat2 || dest.mLongitude != mLon2) {
computeDistanceAndBearing(mLatitude, mLongitude,
dest.mLatitude, dest.mLongitude, mResults);
mLat1 = mLatitude;
mLon1 = mLongitude;
mLat2 = dest.mLatitude;
mLon2 = dest.mLongitude;
mDistance = mResults[0];
mInitialBearing = mResults[1];
}
return mDistance;
}
}
/**
* Returns the approximate initial bearing in degrees East of true
* North when traveling along the shortest path between this
* location and the given location. The shortest path is defined
* using the WGS84 ellipsoid. Locations that are (nearly)
* antipodal may produce meaningless results.
*
* @param dest the destination location
* @return the initial bearing in degrees
*/
public float bearingTo(Location dest) {
synchronized (mResults) {
// See if we already have the result
if (mLatitude != mLat1 || mLongitude != mLon1 ||
dest.mLatitude != mLat2 || dest.mLongitude != mLon2) {
computeDistanceAndBearing(mLatitude, mLongitude,
dest.mLatitude, dest.mLongitude, mResults);
mLat1 = mLatitude;
mLon1 = mLongitude;
mLat2 = dest.mLatitude;
mLon2 = dest.mLongitude;
mDistance = mResults[0];
mInitialBearing = mResults[1];
}
return mInitialBearing;
}
}
/**
* Returns the name of the provider that generated this fix,
* or null if it is not associated with a provider.
*/
public String getProvider() {
return mProvider;
}
/**
* Sets the name of the provider that generated this fix.
*/
public void setProvider(String provider) {
mProvider = provider;
}
/**
* Returns the UTC time of this fix, in milliseconds since January 1,
* 1970.
*/
public long getTime() {
return mTime;
}
/**
* Sets the UTC time of this fix, in milliseconds since January 1,
* 1970.
*/
public void setTime(long time) {
mTime = time;
}
/**
* Returns the latitude of this fix.
*/
public double getLatitude() {
return mLatitude;
}
/**
* Sets the latitude of this fix.
*/
public void setLatitude(double latitude) {
mLatitude = latitude;
}
/**
* Returns the longitude of this fix.
*/
public double getLongitude() {
return mLongitude;
}
/**
* Sets the longitude of this fix.
*/
public void setLongitude(double longitude) {
mLongitude = longitude;
}
/**
* Returns true if this fix contains altitude information, false
* otherwise.
*/
public boolean hasAltitude() {
return mHasAltitude;
}
/**
* Returns the altitude of this fix. If {@link #hasAltitude} is false,
* 0.0f is returned.
*/
public double getAltitude() {
return mAltitude;
}
/**
* Sets the altitude of this fix. Following this call,
* hasAltitude() will return true.
*/
public void setAltitude(double altitude) {
mAltitude = altitude;
mHasAltitude = true;
}
/**
* Clears the altitude of this fix. Following this call,
* hasAltitude() will return false.
*/
public void removeAltitude() {
mAltitude = 0.0f;
mHasAltitude = false;
}
/**
* Returns true if this fix contains speed information, false
* otherwise. The default implementation returns false.
*/
public boolean hasSpeed() {
return mHasSpeed;
}
/**
* Returns the speed of the device over ground in meters/second.
* If hasSpeed() is false, 0.0f is returned.
*/
public float getSpeed() {
return mSpeed;
}
/**
* Sets the speed of this fix, in meters/second. Following this
* call, hasSpeed() will return true.
*/
public void setSpeed(float speed) {
mSpeed = speed;
mHasSpeed = true;
}
/**
* Clears the speed of this fix. Following this call, hasSpeed()
* will return false.
*/
public void removeSpeed() {
mSpeed = 0.0f;
mHasSpeed = false;
}
/**
* Returns true if the provider is able to report bearing information,
* false otherwise. The default implementation returns false.
*/
public boolean hasBearing() {
return mHasBearing;
}
/**
* Returns the direction of travel in degrees East of true
* North. If hasBearing() is false, 0.0 is returned.
*/
public float getBearing() {
return mBearing;
}
/**
* Sets the bearing of this fix. Following this call, hasBearing()
* will return true.
*/
public void setBearing(float bearing) {
while (bearing < 0.0f) {
bearing += 360.0f;
}
while (bearing >= 360.0f) {
bearing -= 360.0f;
}
mBearing = bearing;
mHasBearing = true;
}
/**
* Clears the bearing of this fix. Following this call, hasBearing()
* will return false.
*/
public void removeBearing() {
mBearing = 0.0f;
mHasBearing = false;
}
/**
* Returns true if the provider is able to report accuracy information,
* false otherwise. The default implementation returns false.
*/
public boolean hasAccuracy() {
return mHasAccuracy;
}
/**
* Returns the accuracy of the fix in meters. If hasAccuracy() is false,
* 0.0 is returned.
*/
public float getAccuracy() {
return mAccuracy;
}
/**
* Sets the accuracy of this fix. Following this call, hasAccuracy()
* will return true.
*/
public void setAccuracy(float accuracy) {
mAccuracy = accuracy;
mHasAccuracy = true;
}
/**
* Clears the accuracy of this fix. Following this call, hasAccuracy()
* will return false.
*/
public void removeAccuracy() {
mAccuracy = 0.0f;
mHasAccuracy = false;
}
/**
* Returns additional provider-specific information about the
* location fix as a Bundle. The keys and values are determined
* by the provider. If no additional information is available,
* null is returned.
*
*
A number of common key/value pairs are listed
* below. Providers that use any of the keys on this list must
* provide the corresponding value as described below.
*
*
* - satellites - the number of satellites used to derive the fix
*
*/
public Bundle getExtras() {
return mExtras;
}
/**
* Sets the extra information associated with this fix to the
* given Bundle.
*/
public void setExtras(Bundle extras) {
mExtras = (extras == null) ? null : new Bundle(extras);
}
@Override public String toString() {
return "Location[mProvider=" + mProvider +
",mTime=" + mTime +
",mLatitude=" + mLatitude +
",mLongitude=" + mLongitude +
",mHasAltitude=" + mHasAltitude +
",mAltitude=" + mAltitude +
",mHasSpeed=" + mHasSpeed +
",mSpeed=" + mSpeed +
",mHasBearing=" + mHasBearing +
",mBearing=" + mBearing +
",mHasAccuracy=" + mHasAccuracy +
",mAccuracy=" + mAccuracy +
",mExtras=" + mExtras + "]";
}
public static final Parcelable.Creator CREATOR =
new Parcelable.Creator() {
public Location createFromParcel(Parcel in) {
String provider = in.readString();
Location l = new Location(provider);
l.mTime = in.readLong();
l.mLatitude = in.readDouble();
l.mLongitude = in.readDouble();
l.mHasAltitude = in.readInt() != 0;
l.mAltitude = in.readDouble();
l.mHasSpeed = in.readInt() != 0;
l.mSpeed = in.readFloat();
l.mHasBearing = in.readInt() != 0;
l.mBearing = in.readFloat();
l.mHasAccuracy = in.readInt() != 0;
l.mAccuracy = in.readFloat();
l.mExtras = in.readBundle();
return l;
}
public Location[] newArray(int size) {
return new Location[size];
}
};
public int describeContents() {
return 0;
}
public void writeToParcel(Parcel parcel, int flags) {
parcel.writeString(mProvider);
parcel.writeLong(mTime);
parcel.writeDouble(mLatitude);
parcel.writeDouble(mLongitude);
parcel.writeInt(mHasAltitude ? 1 : 0);
parcel.writeDouble(mAltitude);
parcel.writeInt(mHasSpeed ? 1 : 0);
parcel.writeFloat(mSpeed);
parcel.writeInt(mHasBearing ? 1 : 0);
parcel.writeFloat(mBearing);
parcel.writeInt(mHasAccuracy ? 1 : 0);
parcel.writeFloat(mAccuracy);
parcel.writeBundle(mExtras);
}
}