Traditional GeographicLib interface

As well as the Julia interface functions functions, GeographicLib.jl exposes an interface as similar as possible to that as implemeted in the Python version of the original library.

Note

For consistency with the original Python interface, coordinates are given in the order lat, lon to the ‘traditional’ interface. This is the opposite order to the Julia-style interface, which sticks with lon, lat in line with many other packages.

Types and constructors

Geodesics, GeodesicLines and Polygons are constructed as in the Julia-style interface, but with an additional method for GeodesicLine:

GeographicLib.GeodesicLines.GeodesicLine — Method.

GeodesicLine(geod::Geodesic, lat1, lon1, azi1; caps, salp1, calp1) -> line

Create a GeodesicLine with starting latitude lat1° and longitude lon1°, and azimuth azi1°.

Control the capabilities of the line with caps. Optionally specify the sine and cosine of the azimuth at point 1, respectively salp1 and calp1.

source

Output masks

As in the traditional interface, the exact output from a call to any of the functions is controlled by passing in an output mask. (See the Python documentation for details.)

This is a bitwise-or combination of flags from the module GeographicLib.GeodesicCapability.

To use these easily, import GeographicLib.GeodesicCapability and define a utility ‘alias’, for example:

julia> using GeographicLib

julia> const Mask = GeographicLib.GeodesicCapability
GeographicLib.GeodesicCapability

julia> mask = Mask.LATITUDE | Mask.LONGITUDE # Only compute longitude and latitude
392

julia> g = GeographicLib.WGS84;

julia> GeographicLib.Direct(g, 0, 0, 10, 10, mask)
GeographicLib.Result:
    lat1: 0.0
    lon1: 0.0
    lat2: 8.906300725867944e-5
    lon2: 1.5599081205783052e-5
     a12: 9.013372974228532e-5
     s12: NaN
    azi1: 10.0
    azi2: <>
     m12: <>
     M12: <>
     M21: <>
     S12: <>

Output

Calculations with Direct, ArcDirect, Position, ArcPosition and Inverse return a Result type which contains fields with values filled by the calculation. When these are not made (due to the flags set in output masks), fields are nothing.

GeographicLib.Result — Type.

Result

Type holding the result of a forward or inverse calculation using a geodesic.

If fields have not been calculated because of the presence/absence of any flags when performing the calculation, the field will be nothing.

Fields

These are user-accesible.

lat1: Latitude of starting point (°)
lon1: Longitude of starting point (°)
lat2: Latitude of end point (°)
lon2: Longitude of end point (°)
a12: Angular distace between start and end points (°)
s12: Distance between start and end points (°)
azi1: Forward azimuth from start point to end point (°)
azi2: Forward azimuth at end point from start point along great cricle
m12: Reduced length of the geodesic
M12: First geodesic scale
M21: Second geodesic scale
S12: Area between the path from the first to the second point, and the equator (m²)

source

Functions

GeographicLib.Direct — Function.

Direct(geodesic, lat1, lon1, azi1, s12, outmask=Geodesics.STANDARD) -> result::Geodesics.Result

Solve the direct geodesic problem and return a Geodesics.Result containing the parameters of interest

Input parameters: lat1: latitude of the first point in degrees lon1: longitude of the first point in degrees azi1: azimuth at the first point in degrees s12: the distance from the first point to the second in meters outmask: a mask setting which output values are computed (see note below)

Compute geodesic starting at (lat1, lon1) with azimuth azi1 and length s12. The default value of outmask is STANDARD, i.e., the lat1, lon1, azi1, lat2, lon2, azi2, s12, a12 entries are returned.

Output mask

May be any combination of: Geodesics.EMPTY, Geodesics.LATITUDE, Geodesics.LONGITUDE, Geodesics.AZIMUTH, Geodesics.DISTANCE, Geodesics.STANDARD, Geodesics.DISTANCE_IN, Geodesics.REDUCEDLENGTH, Geodesics.GEODESICSCALE, Geodesics.AREA, Geodesics.ALL or Geodesics.LONG_UNROLL. See the docstring for each for more information.

Flags are combined by bitwise or-ing values together, e.g. Geodesics.AZIMUTH | Geodesics.DISTANCE.

source

GeographicLib.ArcDirect — Function.

ArcDirect(geodesic, lat1, lon1, azi1, a12, outmask=Geodesics.STANDARD) -> result::Geodesics.Result

Solve the direct geodesic problem and return a Geodesics.Result containing the parameters of interest

Input parameters: lat1: latitude of the first point in degrees lon1: longitude of the first point in degrees azi1: azimuth at the first point in degrees a12: the angular distance from the first point to the second in ° outmask: a mask setting which output values are computed (see note below)

Compute geodesic starting at (lat1, lon1)° with azimuth azi1° and arc length a12°. The default value of outmask is STANDARD, i.e., the lat1, lon1, azi1, lat2, lon2, azi2, s12, a12 entries are returned.

Output mask

Flags are combined by bitwise or-ing values together, e.g. Geodesics.AZIMUTH | Geodesics.DISTANCE.

source

GeographicLib.Geodesics.Inverse — Function.

Inverse(geodesic, lat1, lon1, lat2, lon2, outmask=STANDARD) -> result::Result

Solve the inverse geodesic problem and return a Result containing the parameters of interest.

Input arguments:

lat1: latitude of the first point in degrees
lon1: longitude of the first point in degrees
lat2: latitude of the second point in degrees
lon2: longitude of the second point in degrees
outmask: a mask setting which output values are computed (see note below)

Compute geodesic between (lat1, lon1) and (lat2, lon2). The default value of outmask is Geodesics.STANDARD, i.e., the lat1, lon1, azi1, lat2, lon2, azi2, s12, a12 entries are returned.

Output mask

Flags are combined by bitwise or-ing values together, e.g. Geodesics.AZIMUTH | Geodesics.DISTANCE.

source

GeographicLib.GeodesicLines.Position — Function.

Position(line::GeodesicLine, s12, outmask=STANDARD) -> result::Result

Find the position on the line given s12, the distance from the first point to the second in metres.

The default value of outmask is STANDARD, i.e., the lat1, lon1, azi1, lat2, lon2, azi2, s12, a12 entries are returned. The GeodesicLine object must have been constructed with the DISTANCE_IN capability.

source

GeographicLib.GeodesicLines.SetDistance — Function.

SetDistance(line::GeodesicLine, s13) -> line′::GeodesicLine

Specify the position of point 3 in terms of distance from point 1 to point 3 in meters

Return a new GeodesicLine with s13 and a13 set.

source

GeographicLib.GeodesicLines.SetArc — Function.

SetArc(line::GeodesicLine, a13) -> line′::GeodesicLine

Specify the position of point 3 in terms of spherical arc length from point 1 to point 3 in degrees.

Return a new GeodesicLine with a13 and s13 set.

source

Note

Unlike the Python interface, the SetPosition and SetArc functions do not change the GeodesicLine struct, but return an updated copy. Make sure to use a pattern like line = SetArc(line, azi, angle) when using these functions.