GeoUtils (JHPropertiesTyped

java.lang.Object
- dk.heick.properties.types.utils.GeoUtils

```
public class GeoUtils
extends Object
```
Java conversion of Geodesy representation conversion functions (c) Chris Veness 2002-2014
- www.movable-type.co.uk/scripts/latlong.html.
. This page presents a variety of calculations for latitude/longitude points, with the formula and code fragments for implementing them.
All these formula are for calculations on the basis of a spherical earth (ignoring ellipsoidal effects) – which is accurate enough* for most purposes…
[In fact, the earth is very slightly ellipsoidal; using a spherical model gives errors typically up to 0.3% – see notes for further details].
Use under MIT Licence - http://en.wikipedia.org/wiki/MIT_License.

Notes:
- Accuracy: since the earth is not quite a sphere, there are small errors in using spherical geometry; the earth is actually roughly ellipsoidal (or more precisely, oblate spheroidal) with a radius varying between about 6,378km (equatorial) and 6,357km (polar), and local radius of curvature varying from 6,336km (equatorial meridian) to 6,399km (polar). 6,371 km is the generally accepted value for the earth’s mean radius. This means that errors from assuming spherical geometry might be up to 0.55% crossing the equator, though generally below 0.3%, depending on latitude and direction of travel. An accuracy of better than 3m in 1km is mostly good enough for me, but if you want greater accuracy, you could use the Vincenty formula for calculating geodesic distances on ellipsoids, which gives results accurate to within 1mm. (Out of sheer perversity – I’ve never needed such accuracy – I looked up this formula and discovered the JavaScript implementation was simpler than I expected).
- Trig functions take arguments in radians, so latitude, longitude, and bearings in degrees (either decimal or degrees/minutes/seconds) need to be converted to radians, rad = π.deg/180. When converting radians back to degrees (deg = 180.rad/π), West is negative if using signed decimal degrees. For bearings, values in the range -π to +π [-180° to +180°] need to be converted to 0 to +2π [0°–360°]; this can be done by (brng+2.π)%2.π [or brng+360)%360] where % is the (floating point) modulo operator.
- The atan2() function widely used here takes two arguments, atan2(y, x), and computes the arc tangent of the ratio y/x. It is more flexible than atan(y/x), since it handles x=0, and it also returns values in all 4 quadrants -π to +π (the atan function returns values in the range -π/2 to +π/2).
- All bearings are with respect to true north, 0°=N, 90°=E, etc; if you are working from a compass, magnetic north varies from true north in a complex way around the earth, and the difference has to be compensated for by variances indicated on local maps.
- If you implement any formula involving atan2 in Microsoft Excel, you will need to reverse the arguments, as Excel has them the opposite way around from JavaScript – conventional order is atan2(y, x), but Excel uses atan2(x, y). To use atan2 in a (VBA) macro, you can use WorksheetFunction.Atan2().
- If you are using Google Maps, several of these functions are now provided in the Google Maps API V3 ‘spherical’ library (computeDistanceBetween(), computeHeading(), computeOffset(), interpolate(), etc; note they use a default Earth radius of 6,378,137 meters).
- If you use Ordnance Survey Grid References, I have implemented a script for converting between Lat/Long & OS Grid References.
- I learned a lot from the US Census Bureau GIS FAQ which is no longer available, so I’ve made a copy.
- Thanks to Ed Williams’ Aviation Formulary for many of the formula.
- For miles, divide km by 1.609344
- For nautical miles, divide km by 1.852 *
Since:

1.9

Author:

Frederik Heick

Field Summary

Fields
Modifier and Type	Field and Description
`static char[]`	`COMPASS_DIRECTIONS`
`static char`	`COMPASS_EAST`
`static char`	`COMPASS_NORTH`
`static char`	`COMPASS_SOUTH`
`static char`	`COMPASS_WEST`
`static char`	`DMS_SEPERATOR`
`static char`	`LAT_LNG_SEPERATOR`
`static double`	`LATITUDE_DEGREES_RANGE`
`static double`	`LONGITUDE_DEGREES_RANGE`
`static char`	`SYMBOL_DEGREES`
`static char`	`SYMBOL_MINUTES`
`static char`	`SYMBOL_SECONDS`
`static char[]`	`SYMBOLS`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static double`	`getBearingTo(LatLng fromPoint, LatLng toPoint)` Returns the (initial) bearing from pointFrom and toPoint.
`static LatLng`	`getDestinationPoint(LatLng fromPoint, double bearing, double distance)` Returns the destination point from 'this' point having travelled the given distance on the given initial bearing (bearing normally varies around path followed).
`static double`	`getDistanceBetweenPoints(LatLng pointFrom, LatLng pointTo)` Calculate the distance from pointFrom to destination point (using haversine formula).
`static double`	`getFinalBearingTo(LatLng fromPoint, LatLng toPoint)` Returns final bearing arriving at toPoint and fromPoint; the final bearing will differ from the initial bearing by varying degrees according to distance and latitude.
`static LatLng`	`getIntersection(LatLng firstPoint, double firstIntialBearing, LatLng secondPoint, double secondIntialBearing)` Returns the point of intersection of two paths defined by point and bearing.
`static LatLng`	`getMidPointTo(LatLng fromPoint, LatLng toPoint)` Returns the midpoint between fromPoint and toPoint.
`static double`	`getRHumbBearingTo(LatLng fromPoint, LatLng toPoint)` Returns the bearing from source point to destination point along a rhumb line.
`static LatLng`	`getRHumbDestinationPoint(LatLng fromPoint, double bearing, double distance)` Returns the destination point having travelled along a rhumb line from 'this' point the given distance on the given bearing.
`static double`	`getRHumbDistanceTo(LatLng fromPoint, LatLng toPoint)` Returns the distance travelling from source point to destination point along a rhumb line.
`static LatLng`	`getRHumbMidpointTo(LatLng fromPoint, LatLng toPoint)` Returns the loxodromic midpoint (along a rhumb line) between fromPoint and toPoint.
`static double`	`normalizeLatitudeDegrees(double latitudeDegrees)` Normalizes the latitude to inside a valid range.
`static double`	`normalizeLongitudeDegrees(double longitudeDegrees)` Normalizes the longitude to inside a valid range.
`static double`	`normalizeRange(double degrees, double range)` This function normalizes the a value according to a range.
`static Double`	`parseDMS(String dms)` Parses string representing degrees/minutes/seconds into numeric degrees.
`static LatLng`	`parseLatLng(String latlngStr)` Parses a string to LatLng instance, it can parse many formats.
`static String`	`toBearing(Double degress, LatLngFormat format)` Converts numeric degrees to deg/min/sec as a bearing (0°..360°), using format decimals.
`static String`	`toBearing(Double degress, LatLngFormat format, Integer dp)` Converts numeric degrees to deg/min/sec as a bearing (0°..360°)
`static String`	`toDMS(Double degrees, LatLngFormat format)` Converts decimal degrees to deg/min/sec format.
`static String`	`toDMS(Double degrees, LatLngFormat format, Integer dp)` Converts decimal degrees to deg/min/sec format - degree, prime, double-prime symbols are added, but sign is discarded, though no compass direction is added.
`static String`	`toLatitude(Double degress, LatLngFormat format)` Converts numeric latitude degrees to deg/min/sec latitude (3-digit degrees, suffixed with N/S).
`static String`	`toLatitude(Double degress, LatLngFormat format, Integer dp)` Converts numeric latitude degrees to deg/min/sec latitude (3-digit degrees, suffixed with N/S).
`static String`	`toLongitude(Double degress, LatLngFormat format)` Converts numeric longitude degrees to deg/min/sec latitude (3-digit degrees, suffixed with E/W).
`static String`	`toLongitude(Double degress, LatLngFormat format, Integer dp)` Converts numeric longitude degrees to deg/min/sec latitude (3-digit degrees, suffixed with E/W).
`static String`	`toString(LatLng point)` Returns a string representation of point, formatted as degrees+minutes+seconds.
`static String`	`toString(LatLng point, LatLngFormat format)` Returns a string representation of point, formatted as degrees, degrees+minutes, or degrees+minutes+seconds.
`static String`	`toString(LatLng point, LatLngFormat format, Integer dp)` Returns a string representation of point, formatted as degrees, degrees+minutes, or degrees+minutes+seconds.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - SYMBOL_DEGREES
```
public static final char SYMBOL_DEGREES
```
    See Also:
    
    Constant Field Values
  - SYMBOL_MINUTES
```
public static final char SYMBOL_MINUTES
```
    See Also:
    
    Constant Field Values
  - SYMBOL_SECONDS
```
public static final char SYMBOL_SECONDS
```
    See Also:
    
    Constant Field Values
  - COMPASS_NORTH
```
public static final char COMPASS_NORTH
```
    See Also:
    
    Constant Field Values
  - COMPASS_SOUTH
```
public static final char COMPASS_SOUTH
```
    See Also:
    
    Constant Field Values
  - COMPASS_EAST
```
public static final char COMPASS_EAST
```
    See Also:
    
    Constant Field Values
  - COMPASS_WEST
```
public static final char COMPASS_WEST
```
    See Also:
    
    Constant Field Values
  - DMS_SEPERATOR
```
public static final char DMS_SEPERATOR
```
    See Also:
    
    Constant Field Values
  - LAT_LNG_SEPERATOR
```
public static final char LAT_LNG_SEPERATOR
```
    See Also:
    
    Constant Field Values
  - SYMBOLS
```
public static final char[] SYMBOLS
```
  - COMPASS_DIRECTIONS
```
public static final char[] COMPASS_DIRECTIONS
```
  - LATITUDE_DEGREES_RANGE
```
public static final double LATITUDE_DEGREES_RANGE
```
    See Also:
    
    Constant Field Values
  - LONGITUDE_DEGREES_RANGE
```
public static final double LONGITUDE_DEGREES_RANGE
```
    See Also:
    
    Constant Field Values
- Method Detail
  - getDistanceBetweenPoints
```
public static double getDistanceBetweenPoints(LatLng pointFrom,
                                              LatLng pointTo)
```
    Calculate the distance from pointFrom to destination point (using haversine formula).
    
    Parameters:
    
    pointFrom - - Latitude/longitude of source point.
    
    pointTo - - Latitude/longitude of destination point.
    
    Returns:
    
    the distance between this point and destination point, in km (on sphere of 'this' radius).
  - getBearingTo
```
public static double getBearingTo(LatLng fromPoint,
                                  LatLng toPoint)
```
    Returns the (initial) bearing from pointFrom and toPoint.
    
    Parameters:
    
    fromPoint - - Latitude/longitude of source point.
    
    toPoint - - Latitude/longitude of destination point.
    
    Returns:
    
    The initial bearing in degrees from north.
  - getFinalBearingTo
```
public static double getFinalBearingTo(LatLng fromPoint,
                                       LatLng toPoint)
```
    Returns final bearing arriving at toPoint and fromPoint; the final bearing will differ from the initial bearing by varying degrees according to distance and latitude.
    
    Parameters:
    
    fromPoint - - Latitude/longitude of source point.
    
    toPoint - - Latitude/longitude of destination point.
    
    Returns:
    
    the final bearing in degrees from north.
  - getMidPointTo
```
public static LatLng getMidPointTo(LatLng fromPoint,
                                   LatLng toPoint)
```
    Returns the midpoint between fromPoint and toPoint.
    
    Parameters:
    
    fromPoint - - Latitude/longitude of source point.
    
    toPoint - - Latitude/longitude of destination point.
    
    Returns:
    
    the mid point between this point and the supplied point.
  - getDestinationPoint
```
public static LatLng getDestinationPoint(LatLng fromPoint,
                                         double bearing,
                                         double distance)
```
    Returns the destination point from 'this' point having travelled the given distance on the given initial bearing (bearing normally varies around path followed).
    
    Parameters:
    
    fromPoint - the source point.
    
    bearing - Initial bearing in degrees.
    
    distance - Distance in km (on sphere of 'this' radius).
    
    Returns:
    
    Destination point.
  - getIntersection
```
public static LatLng getIntersection(LatLng firstPoint,
                                     double firstIntialBearing,
                                     LatLng secondPoint,
                                     double secondIntialBearing)
```
    Returns the point of intersection of two paths defined by point and bearing.
    
    Parameters:
    
    firstPoint - - First point.
    
    firstIntialBearing - - Initial bearing from first point.
    
    secondPoint - - Second point.
    
    secondIntialBearing - - Initial bearing from second point.
    
    Returns:
    
    The destination point (null if no unique intersection defined).
  - getRHumbDistanceTo
```
public static double getRHumbDistanceTo(LatLng fromPoint,
                                        LatLng toPoint)
```
    Returns the distance travelling from source point to destination point along a rhumb line.
    
    Parameters:
    
    fromPoint - Latitude/longitude of source point.
    
    toPoint - Latitude/longitude of destination point.
    
    Returns:
    
    the distance in km between this point and destination point (on sphere of 'this' radius).
  - getRHumbBearingTo
```
public static double getRHumbBearingTo(LatLng fromPoint,
                                       LatLng toPoint)
```
    Returns the bearing from source point to destination point along a rhumb line.
    
    Parameters:
    
    fromPoint - - Latitude/longitude of source point.
    
    toPoint - - Latitude/longitude of destination point.
    
    Returns:
    
    The bearing in degrees from north.
  - getRHumbDestinationPoint
```
public static LatLng getRHumbDestinationPoint(LatLng fromPoint,
                                              double bearing,
                                              double distance)
```
    Returns the destination point having travelled along a rhumb line from 'this' point the given distance on the given bearing.
    
    Parameters:
    
    fromPoint - - Latitude/longitude of source point.
    
    bearing - - Bearing in degrees from north.
    
    distance - - Distance in km (on sphere of 'this' radius).
    
    Returns:
    
    The Destination point.
  - getRHumbMidpointTo
```
public static LatLng getRHumbMidpointTo(LatLng fromPoint,
                                        LatLng toPoint)
```
    Returns the loxodromic midpoint (along a rhumb line) between fromPoint and toPoint.
    
    Parameters:
    
    fromPoint - - Latitude/longitude of source point.
    
    toPoint - - Latitude/longitude of second point.
    
    Returns:
    
    midpoint between this point and second point.
  - toString
```
public static String toString(LatLng point,
                              LatLngFormat format,
                              Integer dp)
```
    Returns a string representation of point, formatted as degrees, degrees+minutes, or degrees+minutes+seconds.
    
    Parameters:
    
    point - the LatLng point
    
    format - the LatLngFormat
    
    dp - number of decimals.
    
    Returns:
    
    Comma-separated latitude/longitude.
  - toString
```
public static String toString(LatLng point,
                              LatLngFormat format)
```
    Returns a string representation of point, formatted as degrees, degrees+minutes, or degrees+minutes+seconds. Using the format default decimals.
    
    Parameters:
    
    point - the LatLng point
    
    format - the LatLngFormat
    
    Returns:
    
    Comma-separated latitude/longitude.
  - toString
```
public static String toString(LatLng point)
```
    Returns a string representation of point, formatted as degrees+minutes+seconds. Using the format default decimals.
    
    Parameters:
    
    point - the LatLng point
    
    Returns:
    
    Comma-separated latitude/longitude.
  - toLatitude
```
public static String toLatitude(Double degress,
                                LatLngFormat format,
                                Integer dp)
```
    Converts numeric latitude degrees to deg/min/sec latitude (3-digit degrees, suffixed with N/S).
    
    Parameters:
    
    degress - - Degrees to be formatted as specified.
    
    format - the LatLngFormat
    
    dp - - Number of decimal places to use – default 0 for dms, 3 for dm, 6 for d.
    
    Returns:
    
    Degrees formatted as deg/min/secs according to specified format.
  - toLatitude
```
public static String toLatitude(Double degress,
                                LatLngFormat format)
```
    Converts numeric latitude degrees to deg/min/sec latitude (3-digit degrees, suffixed with N/S). Using default decimals.
    
    Parameters:
    
    degress - - Degrees to be formatted as specified.
    
    format - the LatLngFormat
    
    Returns:
    
    degrees formatted as deg/min/secs according to specified format.
  - toLongitude
```
public static String toLongitude(Double degress,
                                 LatLngFormat format,
                                 Integer dp)
```
    Converts numeric longitude degrees to deg/min/sec latitude (3-digit degrees, suffixed with E/W).
    
    Parameters:
    
    degress - - Degrees to be formatted as specified.
    
    format - the LatLngFormat
    
    dp - - Number of decimal places to use – default 0 for dms, 3 for dm, 6 for d.
    
    Returns:
    
    degrees formatted as deg/min/secs according to specified format.
  - toLongitude
```
public static String toLongitude(Double degress,
                                 LatLngFormat format)
```
    Converts numeric longitude degrees to deg/min/sec latitude (3-digit degrees, suffixed with E/W). Using default decimals.
    
    Parameters:
    
    degress - - Degrees to be formatted as specified.
    
    format - the LatLngFormat
    
    Returns:
    
    degrees formatted as deg/min/secs according to specified format.
  - toDMS
```
public static String toDMS(Double degrees,
                           LatLngFormat format,
                           Integer dp)
```
    Converts decimal degrees to deg/min/sec format
    - degree, prime, double-prime symbols are added, but sign is discarded, though no compass direction is added.
    
    Parameters:
    
    degrees - - Degrees to be formatted as specified.
    
    format - the LatLngFormat
    
    dp - - Number of decimal places to use – default 0 for dms, 3 for dm, 6 for d.
    
    Returns:
    
    degrees formatted as deg/min/secs according to specified format.
  - toDMS
```
public static String toDMS(Double degrees,
                           LatLngFormat format)
```
    Converts decimal degrees to deg/min/sec format. Using format decimals.
    - degree, prime, double-prime symbols are added, but sign is discarded, though no compass direction is added.
    
    Parameters:
    
    degrees - - Degrees to be formatted as specified.
    
    format - the LatLngFormat
    
    Returns:
    
    degrees formatted as deg/min/secs according to specified format.
  - toBearing
```
public static String toBearing(Double degress,
                               LatLngFormat format,
                               Integer dp)
```
    Converts numeric degrees to deg/min/sec as a bearing (0°..360°)
    
    Parameters:
    
    degress - Degrees to be formatted as specified.
    
    format - the LatLngFormat
    
    dp - - Number of decimal places to use – default 0 for dms, 3 for dm, 6 for d.
    
    Returns:
    
    Degrees formatted as deg/min/secs according to specified format.
  - toBearing
```
public static String toBearing(Double degress,
                               LatLngFormat format)
```
    Converts numeric degrees to deg/min/sec as a bearing (0°..360°), using format decimals.
    
    Parameters:
    
    degress - Degrees to be formatted as specified.
    
    format - the LatLngFormat
    
    Returns:
    
    Degrees formatted as deg/min/secs according to specified format.
  - parseDMS
```
public static Double parseDMS(String dms)
                       throws ParseException
```
    Parses string representing degrees/minutes/seconds into numeric degrees. This is very flexible on formats, allowing signed decimal degrees, or deg-min-sec optionally suffixed by compass direction (NSEW). A variety of separators are accepted (eg 3° 37' 09"W). Seconds and minutes may be omitted.
    
    Parameters:
    
    dms - - Degrees or deg/min/sec in variety of formats.
    
    Returns:
    
    degrees as decimal number.
    
    Throws:
    
    ParseException
  - parseLatLng
```
public static LatLng parseLatLng(String latlngStr)
                          throws ParseException
```
    Parses a string to LatLng instance, it can parse many formats. But it has to be to DMS numbers seperated by comma
    
    Parameters:
    
    latlngStr - the latLng String.
    
    Returns:
    
    a LatLng instance.
    
    Throws:
    
    ParseException - if failed to parse String.
    
    See Also:
    
    parseDMS(String), LAT_LNG_SEPERATOR
  - normalizeLatitudeDegrees
```
public static final double normalizeLatitudeDegrees(double latitudeDegrees)
```
    Normalizes the latitude to inside a valid range.
    
    Parameters:
    
    latitudeDegrees - the latitude degrees.
    
    Returns:
    
    a latitude degree, between -LATITUDE_DEGREES_RANGE and LATITUDE_DEGREES_RANGE. (-90 to 90).
  - normalizeLongitudeDegrees
```
public static final double normalizeLongitudeDegrees(double longitudeDegrees)
```
    Normalizes the longitude to inside a valid range.
    
    Parameters:
    
    longitudeDegrees - the latitude degrees.
    
    Returns:
    
    a longitude degree, between -LONGITUDE_DEGREES_RANGE and LONGITUDE_DEGREES_RANGE. (-180 to 180).
  - normalizeRange
```
public static final double normalizeRange(double degrees,
                                          double range)
```
    This function normalizes the a value according to a range. This is not simple modulo (as I thought when I started), but requires some special handling. For positive numbers we subtract 2*range from the number so that end up between -/+ range. For negative numbers we add this value. For example, if the value is 270 and the range is +/- 180. Then sign=1 so the (int) factor becomes 270+180/360 = 1. This means that 270-360=-90 is the result. (degrees are only used to make it easier to understand, this function is agnostic for radians/degrees). The result will be in [range,range> The algorithm is not very fast, but it handling the [> ranges made it very messy using integer arithmetic, and this is very readable. Note that it is highly unlikely that this method is called in normal situations. Normally input values to position are already normalized because they come from a GPS. And this is much more readable.
    
    Parameters:
    
    degrees - The value that needs adjusting
    
    range - -range = < value < range
    
    Returns:
    
    the degrees value normalize to inside range.

Class GeoUtils

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SYMBOL_DEGREES

SYMBOL_MINUTES

SYMBOL_SECONDS

COMPASS_NORTH

COMPASS_SOUTH

COMPASS_EAST

COMPASS_WEST

DMS_SEPERATOR

LAT_LNG_SEPERATOR

SYMBOLS

COMPASS_DIRECTIONS

LATITUDE_DEGREES_RANGE

LONGITUDE_DEGREES_RANGE

Method Detail

getDistanceBetweenPoints

getBearingTo

getFinalBearingTo

getMidPointTo

getDestinationPoint

getIntersection

getRHumbDistanceTo

getRHumbBearingTo

getRHumbDestinationPoint

getRHumbMidpointTo

toString

toString

toString

toLatitude

toLatitude

toLongitude

toLongitude

toDMS

toDMS

toBearing

toBearing

parseDMS

parseLatLng

normalizeLatitudeDegrees

normalizeLongitudeDegrees

normalizeRange