GeographicLib API¶

geographiclib¶

geographiclib: geodesic routines from GeographicLib

geographiclib.__version_info__ = (2, 0, 0)¶: GeographicLib version as a tuple

geographiclib.__version__ = '2.0'¶: 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

Line()

DirectLine()

ArcDirectLine()

InverseLine()

PolygonArea objects can be created with

Polygon()

The public attributes for this class are

a f

outmask and caps bit masks are

EMPTY

LATITUDE

LONGITUDE

AZIMUTH

DISTANCE

STANDARD

DISTANCE_IN

REDUCEDLENGTH

GEODESICSCALE

AREA

ALL

LONG_UNROLL

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¶: The equatorial radius in meters (readonly)

f¶: 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

Position() position given in terms of distance

ArcPosition() position given in terms of spherical arc length

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

Geodesic.Line

Geodesic.DirectLine

Geodesic.ArcDirectLine

Geodesic.InverseLine

The public attributes for this class are

a f caps lat1 lon1 azi1 salp1 calp1 s13 a13

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¶: The equatorial radius in meters (readonly)

f¶: The flattening (readonly)

caps¶: the capabilities (readonly)

lat1¶: the latitude of the first point in degrees (readonly)

lon1¶: the longitude of the first point in degrees (readonly)

azi1¶: the azimuth at the first point in degrees (readonly)

salp1¶: the sine of the azimuth at the first point (readonly)

calp1¶: the cosine of the azimuth at the first point (readonly)

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

a13¶: 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

earth polyline area0 num lat1 lon1

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¶: The geodesic object (readonly)

polyline¶: Is this a polyline? (readonly)

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

num¶: The current number of points in the polygon (readonly)

lat1¶: The current latitude in degrees (readonly)

lon1¶: 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)

Arbitrarily complex polygons are allowed. In the case of self-intersecting polygons the area is accumulated “algebraically”, e.g., the areas of the 2 loops in a figure-8 polygon will partially cancel.

If the object is a polygon (and not a polyline), 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

GeographicLib API¶

geographiclib¶

geographiclib.geodesic¶

geographiclib.geodesicline¶

geographiclib.polygonarea¶

geographiclib.constants¶

Table of Contents

Previous topic

Next topic

This Page