GeographicLib API — geographiclib 2.1 documentation

# GeographicLib API

## geographiclib

geographiclib: geodesic routines from GeographicLib

geographiclib.__version_info__ = (2, 1, 0)

  GeographicLib version as a tuple

geographiclib.__version__ = '2.1'

  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)

  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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

  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)

    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)

    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)

    Specify the position of point 3 in terms of distance

    Parameters:

      s13 – distance from point 1 to point 3 in meters

  SetArc(a13)

    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)

  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()

    Reset to empty polygon.

  AddPoint(lat, lon)

    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)

    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)

    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)

    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)

    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

  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