com.AndrewGray.geoutils
Class GreatCircle

java.lang.Object
  |
  +--com.AndrewGray.geoutils.GreatCircle

public class GreatCircle

extends java.lang.Object

implements various mathematical methods related to Great Circle calculations.

Great Circles are the shortest paths between locations. As such they represent the ideal course for such applications as aircraft and ocean navigation. On a typical Great Circle track the bearing varies constantly. Constant true courses are Rhumb lines

Note: All methods in this class assume the Earth is a perfect sphere of 6371km radius. In fact the equatorial radius is about 30Km greater than the polar.

Disclaimer & Warranty

The software is supplied as-is. No warranty, or statement of fitness of purpose is given.

All emphasis is on the user to verify values. In particular, this software should not be used for safety critical applications such as navigation, aeronautics, etc.

In obtaining this software you agree that liability of the copyright holder for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the software be limited to the purchase cost thereof. This includes but is not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the software to operate with any other software, even if such holder or other party has been advised of the possibility of such damages.

Copyright © 2004 by Andrew Gray

Author:

Andrew Gray

See Also:

RhumbLine

Inner Class Summary

class

GreatCircle.DistanceTooLargeException thrown by applyBearingAndDistance and getTrack if the specified distance is larger than Math.PI/4 (~5000km)

Constructor Summary

GreatCircle()
Creates a new Great Circle object

Method Summary

LatLong	applyBearingAndDistance(LatLong origin, double bearing, double km) compute destination LatLong given origin, bearing and distance.
double	getBearing(LatLong origin, LatLong destination) Calculate the initial bearing between two points on a great circle.
int	getDatelineTraversalID() Returns the id of point last computed by getTrack() which crosses Longitude 180 degrees.
double	getDistance(LatLong origin, LatLong destination) Method to compute Great Circle distance between two points.
double	getEarthRadius() Get the current radius of the Earth used in calculation
LatLong	getIntersection(LatLong ll1, double bearing1, LatLong ll2, double bearing2) Computes the LatLong of the intersection of two great circles given both origin LatLongs and initial bearings.
LatLong[]	getTrack(LatLong origin, LatLong destination, double kmIncTarget) Computes a track between two points given KM distance between waypoints.
void	setEarthRadius(double radius) Set the radius of the Earth for calculations that involve it.

Methods inherited from class java.lang.Object

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

Constructor Detail

GreatCircle

public GreatCircle()

Creates a new Great Circle object

Method Detail

getDistance

public double getDistance(LatLong origin,
                          LatLong destination)

Method to compute Great Circle distance between two points.

Parameters:

origin - LatLong representing start point of this GreatCircle

destination - LatLong representing end point of this GreatCircle

Returns:

The distance in Kilometres

getBearing

public double getBearing(LatLong origin,
                         LatLong destination)

Calculate the initial bearing between two points on a great circle.

This is the initial bearing which should be taken from origin to begin the Great Circle track. On most Great Circles the bearing varies continuously thoughout the track.

This is not the Direction between locations in the truest sense of the world.For the constant true bearing use the corresponding RhumbLine routine.

Parameters:

origin - LatLong representing start point of this GreatCircle

destination - LatLong representing end point of this GreatCircle

Returns:

the bearing in radians.

See Also:

RhumbLine, RhumbLine.getBearing(LatLong,LatLong)

applyBearingAndDistance

public LatLong applyBearingAndDistance(LatLong origin,
                                       double bearing,
                                       double km)
                                throws GreatCircle.DistanceTooLargeException

compute destination LatLong given origin, bearing and distance.

Parameters:

origin - LatLong representing start point of this GreatCircle

bearing - Course taken from origin - in radians

distance - Distance to travel along given bearing - km.

Returns:

LatLong representing destination on GreatCircle

Throws:

DistanceTooLarge - if the supplied distance is greater that PI/4 (~5000km)

getTrack

public LatLong[] getTrack(LatLong origin,
                          LatLong destination,
                          double kmIncTarget)
                   throws GreatCircle.DistanceTooLargeException

Computes a track between two points given KM distance between waypoints.

In the demonstration applet this method is used for the map plot of the Great Circle course between the two selected points.

On a Great Circle route the course normally constantly changes throughout the journey. Traditionally ocean navigators recalculated their course every 12 hours whilst the auto-pilots on modern aircraft do so continously.

This method uses the parameter kmIncTarget as the target distance between course recomputations. This is only a target distance as the concept of way points inherently increases the overall total distance travelled beyond that of an perfect Great Circle course..

The demonstration applet uses a kmIncTarget value of 200 which has been found to add less than 2% to most great circle routes.

Parameters:

origin - Start point on the Great Circle

destination - End point on the Great Circle

kmIncTarget - Target distance in KM between waypoints.

Returns:

array of LatLong

See Also:

getDatelineTraversalID()

getDatelineTraversalID

public int getDatelineTraversalID()

Returns the id of point last computed by getTrack() which crosses Longitude 180 degrees.

Returns:

-1 if track does not cross 180 long or if getTrack() has not been called.

setEarthRadius

public void setEarthRadius(double radius)

Set the radius of the Earth for calculations that involve it. Currently only getDistance..

Parameters:

radius - the new earth radius in KM

getEarthRadius

public double getEarthRadius()

Get the current radius of the Earth used in calculation

Returns:

the current earth radius in KM

getIntersection

public LatLong getIntersection(LatLong ll1,
                               double bearing1,
                               LatLong ll2,
                               double bearing2)

Computes the LatLong of the intersection of two great circles given both origin LatLongs and initial bearings.

Parameters:

ll1 - LatLong representing the origin of the first Great Circle

bearing1 - the initial bearing in radians of the first Great Circle

ll2 - LatLong representing the origin of the second Great Circle

bearing2 - the initial bearing in radians of the second Great Circle

Returns:

LatLong of the point of intersection or null if the Great Circles do not intersect.