GeographicLib API

geographiclib

geographiclib: geodesic routines from GeographicLib

geographiclib.__version_info__ = (1, 49, 0)

GeographicLib version as a tuple

geographiclib.__version__ = '1.49'

GeographicLib version as a string

geographiclib.geodesic

Define the Geodesic class

The ellipsoid parameters are defined by the constructor. The direct and inverse geodesic problems are solved by

  • Inverse() Solve the inverse geodesic problem
  • Direct() Solve the direct geodesic problem
  • ArcDirect() Solve the direct geodesic problem in terms of spherical arc length

GeodesicLine objects can be created with

PolygonArea objects can be created with

The public attributes for this class are

outmask and caps bit masks are

Example:
>>> from geographiclib.geodesic import Geodesic
>>> # The geodesic inverse problem
... Geodesic.WGS84.Inverse(-41.32, 174.81, 40.96, -5.50)
{'lat1': -41.32,
 'a12': 179.6197069334283,
 's12': 19959679.26735382,
 'lat2': 40.96,
 'azi2': 18.825195123248392,
 'azi1': 161.06766998615882,
 'lon1': 174.81,
 'lon2': -5.5}
Geodesic.WGS84 = Instantiation for the WGS84 ellipsoid
class geographiclib.geodesic.Geodesic(a, f)[source]

Solve geodesic problems

Construct a Geodesic object

Parameters:
  • a – the equatorial radius of the ellipsoid in meters
  • f – the flattening of the ellipsoid

An exception is thrown if a or the polar semi-axis b = a (1 - f) is not a finite positive quantity.

a = None

The equatorial radius in meters (readonly)

f = None

The flattening (readonly)

Inverse(lat1, lon1, lat2, lon2, outmask=1929)[source]

Solve the inverse geodesic problem

Parameters:
  • 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 – the output mask
Returns:

a Geodesic dictionary

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

Direct(lat1, lon1, azi1, s12, outmask=1929)[source]

Solve the direct geodesic problem

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 – the output mask
Returns:

a Geodesic dictionary

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.

ArcDirect(lat1, lon1, azi1, a12, outmask=1929)[source]

Solve the direct geodesic problem in terms of spherical arc length

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 – spherical arc length from the first point to the second in degrees
  • outmask – the output mask
Returns:

a Geodesic dictionary

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.

Line(lat1, lon1, azi1, caps=3979)[source]

Return a GeodesicLine object

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
  • caps – the capabilities
Returns:

a GeodesicLine

This allows points along a geodesic starting at (lat1, lon1), with azimuth azi1 to be found. The default value of caps is STANDARD | DISTANCE_IN, allowing direct geodesic problem to be solved.

DirectLine(lat1, lon1, azi1, s12, caps=3979)[source]

Define a GeodesicLine object in terms of the direct geodesic problem specified in terms of spherical arc length

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
  • caps – the capabilities
Returns:

a GeodesicLine

This function sets point 3 of the GeodesicLine to correspond to point 2 of the direct geodesic problem. The default value of caps is STANDARD | DISTANCE_IN, allowing direct geodesic problem to be solved.

ArcDirectLine(lat1, lon1, azi1, a12, caps=3979)[source]

Define a GeodesicLine object in terms of the direct geodesic problem specified in terms of spherical arc length

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 – spherical arc length from the first point to the second in degrees
  • caps – the capabilities
Returns:

a GeodesicLine

This function sets point 3 of the GeodesicLine to correspond to point 2 of the direct geodesic problem. The default value of caps is STANDARD | DISTANCE_IN, allowing direct geodesic problem to be solved.

InverseLine(lat1, lon1, lat2, lon2, caps=3979)[source]

Define a GeodesicLine object in terms of the invese geodesic problem

Parameters:
  • 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
  • caps – the capabilities
Returns:

a GeodesicLine

This function sets point 3 of the GeodesicLine to correspond to point 2 of the inverse geodesic problem. The default value of caps is STANDARD | DISTANCE_IN, allowing direct geodesic problem to be solved.

Polygon(polyline=False)[source]

Return a PolygonArea object

Parameters:polyline – if True then the object describes a polyline instead of a polygon
Returns:a PolygonArea
EMPTY = 0

No capabilities, no output.

LATITUDE = 128

Calculate latitude lat2.

LONGITUDE = 264

Calculate longitude lon2.

AZIMUTH = 512

Calculate azimuths azi1 and azi2.

DISTANCE = 1025

Calculate distance s12.

STANDARD = 1929

All of the above.

DISTANCE_IN = 2051

Allow distance s12 to be used as input in the direct geodesic problem.

REDUCEDLENGTH = 4101

Calculate reduced length m12.

GEODESICSCALE = 8197

Calculate geodesic scales M12 and M21.

AREA = 16400

Calculate area S12.

ALL = 32671

All of the above.

LONG_UNROLL = 32768

Unroll longitudes, rather than reducing them to the range [-180d,180d].

geographiclib.geodesicline

Define the GeodesicLine class

The constructor defines the starting point of the line. Points on the line are given by

A reference point 3 can be defined with

  • SetDistance() set position of 3 in terms of the distance from the starting point
  • SetArc() set position of 3 in terms of the spherical arc length from the starting point

The object can also be constructed by

The public attributes for this class are

class geographiclib.geodesicline.GeodesicLine(geod, lat1, lon1, azi1, caps=3979, salp1=nan, calp1=nan)[source]

Points on a geodesic path

Construct a GeodesicLine object

Parameters:
  • geod – a Geodesic object
  • lat1 – latitude of the first point in degrees
  • lon1 – longitude of the first point in degrees
  • azi1 – azimuth at the first point in degrees
  • caps – the capabilities

This creates an object allowing points along a geodesic starting at (lat1, lon1), with azimuth azi1 to be found. The default value of caps is STANDARD | DISTANCE_IN. The optional parameters salp1 and calp1 should not be supplied; they are part of the private interface.

a = None

The equatorial radius in meters (readonly)

f = None

The flattening (readonly)

caps = None

the capabilities (readonly)

lat1 = None

the latitude of the first point in degrees (readonly)

lon1 = None

the longitude of the first point in degrees (readonly)

azi1 = None

the azimuth at the first point in degrees (readonly)

salp1 = None

the sine of the azimuth at the first point (readonly)

calp1 = None

the cosine of the azimuth at the first point (readonly)

s13 = None

the distance between point 1 and point 3 in meters (readonly)

a13 = None

the arc length between point 1 and point 3 in degrees (readonly)

Position(s12, outmask=1929)[source]

Find the position on the line given s12

Parameters:
  • s12 – the distance from the first point to the second in meters
  • outmask – the output mask
Returns:

a Geodesic dictionary

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.

ArcPosition(a12, outmask=1929)[source]

Find the position on the line given a12

Parameters:
  • a12 – spherical arc length from the first point to the second in degrees
  • outmask – the output mask
Returns:

a Geodesic dictionary

The default value of outmask is STANDARD, i.e., the lat1, lon1, azi1, lat2, lon2, azi2, s12, a12 entries are returned.

SetDistance(s13)[source]

Specify the position of point 3 in terms of distance

Parameters:s13 – distance from point 1 to point 3 in meters
SetArc(a13)[source]

Specify the position of point 3 in terms of arc length

Parameters:a13 – spherical arc length from point 1 to point 3 in degrees

geographiclib.polygonarea

Define the PolygonArea class

The constructor initializes a empty polygon. The available methods are

  • Clear() reset the polygon
  • AddPoint() add a vertex to the polygon
  • AddEdge() add an edge to the polygon
  • Compute() compute the properties of the polygon
  • TestPoint() compute the properties of the polygon with a tentative additional vertex
  • TestEdge() compute the properties of the polygon with a tentative additional edge

The public attributes for this class are

class geographiclib.polygonarea.PolygonArea(earth, polyline=False)[source]

Area of a geodesic polygon

Construct a PolygonArea object

Parameters:
  • earth – a Geodesic object
  • polyline – if true, treat object as a polyline instead of a polygon

Initially the polygon has no vertices.

earth = None

The geodesic object (readonly)

polyline = None

Is this a polyline? (readonly)

area0 = None

The total area of the ellipsoid in meter^2 (readonly)

num = None

The current number of points in the polygon (readonly)

lat1 = None

The current latitude in degrees (readonly)

lon1 = None

The current longitude in degrees (readonly)

Clear()[source]

Reset to empty polygon.

AddPoint(lat, lon)[source]

Add the next vertex to the polygon

Parameters:
  • lat – the latitude of the point in degrees
  • lon – the longitude of the point in degrees

This adds an edge from the current vertex to the new vertex.

AddEdge(azi, s)[source]

Add the next edge to the polygon

Parameters:
  • azi – the azimuth at the current the point in degrees
  • s – the length of the edge in meters

This specifies the new vertex in terms of the edge from the current vertex.

Compute(reverse=False, sign=True)[source]

Compute the properties of the polygon

Parameters:
  • reverse – if true then clockwise (instead of counter-clockwise) traversal counts as a positive area
  • sign – if true then return a signed result for the area if the polygon is traversed in the “wrong” direction instead of returning the area for the rest of the earth
Returns:

a tuple of number, perimeter (meters), area (meters^2)

If the object is a polygon (and not a polygon), the perimeter includes the length of a final edge connecting the current point to the initial point. If the object is a polyline, then area is nan.

More points can be added to the polygon after this call.

TestPoint(lat, lon, reverse=False, sign=True)[source]

Compute the properties for a tentative additional vertex

Parameters:
  • lat – the latitude of the point in degrees
  • lon – the longitude of the point in degrees
  • reverse – if true then clockwise (instead of counter-clockwise) traversal counts as a positive area
  • sign – if true then return a signed result for the area if the polygon is traversed in the “wrong” direction instead of returning the area for the rest of the earth
Returns:

a tuple of number, perimeter (meters), area (meters^2)

TestEdge(azi, s, reverse=False, sign=True)[source]

Compute the properties for a tentative additional edge

Parameters:
  • azi – the azimuth at the current the point in degrees
  • s – the length of the edge in meters
  • reverse – if true then clockwise (instead of counter-clockwise) traversal counts as a positive area
  • sign – if true then return a signed result for the area if the polygon is traversed in the “wrong” direction instead of returning the area for the rest of the earth
Returns:

a tuple of number, perimeter (meters), area (meters^2)

geographiclib.constants

Define the WGS84 ellipsoid

class geographiclib.constants.Constants[source]

Constants describing the WGS84 ellipsoid

WGS84_a = 6378137.0

the equatorial radius in meters of the WGS84 ellipsoid in meters

WGS84_f = 0.0033528106647474805

the flattening of the WGS84 ellipsoid, 1/298.257223563