Classes | Macros | Enumerations | Functions
geodesic.h File Reference

API for the geodesic routines in C. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  geod_geodesic
 
struct  geod_geodesicline
 
struct  geod_polygon
 

Macros

#define GEODESIC_VERSION
 
#define GEODESIC_VERSION_MAJOR   1
 
#define GEODESIC_VERSION_MINOR   49
 
#define GEODESIC_VERSION_NUM(a, b, c)   ((((a) * 10000 + (b)) * 100) + (c))
 
#define GEODESIC_VERSION_PATCH   0
 

Enumerations

enum  geod_flags { GEOD_NOFLAGS = 0U, GEOD_ARCMODE = 1U<<0, GEOD_LONG_UNROLL = 1U<<15 }
 
enum  geod_mask {
  GEOD_NONE = 0U, GEOD_LATITUDE = 1U<<7 | 0U, GEOD_LONGITUDE = 1U<<8 | 1U<<3, GEOD_AZIMUTH = 1U<<9 | 0U,
  GEOD_DISTANCE = 1U<<10 | 1U<<0, GEOD_DISTANCE_IN = 1U<<11 | 1U<<0 | 1U<<1, GEOD_REDUCEDLENGTH = 1U<<12 | 1U<<0 | 1U<<2, GEOD_GEODESICSCALE = 1U<<13 | 1U<<0 | 1U<<2,
  GEOD_AREA = 1U<<14 | 1U<<4, GEOD_ALL = 0x7F80U| 0x1FU
}
 

Functions

void geod_direct (const struct geod_geodesic *g, double lat1, double lon1, double azi1, double s12, double *plat2, double *plon2, double *pazi2)
 
void geod_directline (struct geod_geodesicline *l, const struct geod_geodesic *g, double lat1, double lon1, double azi1, double s12, unsigned caps)
 
double geod_gendirect (const struct geod_geodesic *g, double lat1, double lon1, double azi1, unsigned flags, double s12_a12, double *plat2, double *plon2, double *pazi2, double *ps12, double *pm12, double *pM12, double *pM21, double *pS12)
 
void geod_gendirectline (struct geod_geodesicline *l, const struct geod_geodesic *g, double lat1, double lon1, double azi1, unsigned flags, double s12_a12, unsigned caps)
 
double geod_geninverse (const struct geod_geodesic *g, double lat1, double lon1, double lat2, double lon2, double *ps12, double *pazi1, double *pazi2, double *pm12, double *pM12, double *pM21, double *pS12)
 
double geod_genposition (const struct geod_geodesicline *l, unsigned flags, double s12_a12, double *plat2, double *plon2, double *pazi2, double *ps12, double *pm12, double *pM12, double *pM21, double *pS12)
 
void geod_gensetdistance (struct geod_geodesicline *l, unsigned flags, double s13_a13)
 
void geod_init (struct geod_geodesic *g, double a, double f)
 
void geod_inverse (const struct geod_geodesic *g, double lat1, double lon1, double lat2, double lon2, double *ps12, double *pazi1, double *pazi2)
 
void geod_inverseline (struct geod_geodesicline *l, const struct geod_geodesic *g, double lat1, double lon1, double lat2, double lon2, unsigned caps)
 
void geod_lineinit (struct geod_geodesicline *l, const struct geod_geodesic *g, double lat1, double lon1, double azi1, unsigned caps)
 
void geod_polygon_addedge (const struct geod_geodesic *g, struct geod_polygon *p, double azi, double s)
 
void geod_polygon_addpoint (const struct geod_geodesic *g, struct geod_polygon *p, double lat, double lon)
 
void geod_polygon_clear (struct geod_polygon *p)
 
unsigned geod_polygon_compute (const struct geod_geodesic *g, const struct geod_polygon *p, int reverse, int sign, double *pA, double *pP)
 
void geod_polygon_init (struct geod_polygon *p, int polylinep)
 
unsigned geod_polygon_testedge (const struct geod_geodesic *g, const struct geod_polygon *p, double azi, double s, int reverse, int sign, double *pA, double *pP)
 
unsigned geod_polygon_testpoint (const struct geod_geodesic *g, const struct geod_polygon *p, double lat, double lon, int reverse, int sign, double *pA, double *pP)
 
void geod_polygonarea (const struct geod_geodesic *g, double lats[], double lons[], int n, double *pA, double *pP)
 
void geod_position (const struct geod_geodesicline *l, double s12, double *plat2, double *plon2, double *pazi2)
 
void geod_setdistance (struct geod_geodesicline *l, double s13)
 

Detailed Description

API for the geodesic routines in C.

This an implementation in C of the geodesic algorithms described in

The principal advantages of these algorithms over previous ones (e.g., Vincenty, 1975) are

The shortest path between two points on the ellipsoid at (lat1, lon1) and (lat2, lon2) is called the geodesic. Its length is s12 and the geodesic from point 1 to point 2 has forward azimuths azi1 and azi2 at the two end points.

Traditionally two geodesic problems are considered:

The ellipsoid is specified by its equatorial radius a (typically in meters) and flattening f. The routines are accurate to round off with double precision arithmetic provided that |f| < 1/50; for the WGS84 ellipsoid, the errors are less than 15 nanometers. (Reasonably accurate results are obtained for |f| < 1/5.) For a prolate ellipsoid, specify f < 0.

The routines also calculate several other quantities of interest

If points 1, 2, and 3 lie on a single geodesic, then the following addition rules hold:

The shortest distance returned by the solution of the inverse problem is (obviously) uniquely defined. However, in a few special cases there are multiple azimuths which yield the same shortest distance. Here is a catalog of those cases:

These routines are a simple transcription of the corresponding C++ classes in GeographicLib. The "class data" is represented by the structs geod_geodesic, geod_geodesicline, geod_polygon and pointers to these objects are passed as initial arguments to the member functions. Most of the internal comments have been retained. However, in the process of transcription some documentation has been lost and the documentation for the C++ classes, GeographicLib::Geodesic, GeographicLib::GeodesicLine, and GeographicLib::PolygonAreaT, should be consulted. The C++ code remains the "reference implementation". Think twice about restructuring the internals of the C code since this may make porting fixes from the C++ code more difficult.

Copyright (c) Charles Karney (2012-2017) charl.nosp@m.es@k.nosp@m.arney.nosp@m..com and licensed under the MIT/X11 License. For more information, see https://geographiclib.sourceforge.io/

This library was distributed with GeographicLib 1.49.

Definition in file geodesic.h.

Macro Definition Documentation

◆ GEODESIC_VERSION

#define GEODESIC_VERSION
Value:
#define GEODESIC_VERSION_NUM(a, b, c)
Definition: geodesic.h:142
#define GEODESIC_VERSION_MAJOR
Definition: geodesic.h:125
#define GEODESIC_VERSION_PATCH
Definition: geodesic.h:135
#define GEODESIC_VERSION_MINOR
Definition: geodesic.h:130

The version of the geodesic library as a single integer, packed as MMmmmmpp where MM is the major version, mmmm is the minor version, and pp is the patch level. Users should not rely on this particular packing of the components of the version number. Instead they should use a test such as

#if GEODESIC_VERSION >= GEODESIC_VERSION_NUM(1,40,0)
...
#endif

Definition at line 155 of file geodesic.h.

◆ GEODESIC_VERSION_MAJOR

#define GEODESIC_VERSION_MAJOR   1

The major version of the geodesic library. (This tracks the version of GeographicLib.)

Definition at line 125 of file geodesic.h.

◆ GEODESIC_VERSION_MINOR

#define GEODESIC_VERSION_MINOR   49

The minor version of the geodesic library. (This tracks the version of GeographicLib.)

Definition at line 130 of file geodesic.h.

◆ GEODESIC_VERSION_NUM

#define GEODESIC_VERSION_NUM (   a,
  b,
  c 
)    ((((a) * 10000 + (b)) * 100) + (c))

Pack the version components into a single integer. Users should not rely on this particular packing of the components of the version number; see the documentation for GEODESIC_VERSION, below.

Definition at line 142 of file geodesic.h.

◆ GEODESIC_VERSION_PATCH

#define GEODESIC_VERSION_PATCH   0

The patch level of the geodesic library. (This tracks the version of GeographicLib.)

Definition at line 135 of file geodesic.h.

Enumeration Type Documentation

◆ geod_flags

enum geod_flags

flag values for the flags argument to geod_gendirect() and geod_genposition()

Enumerator
GEOD_NOFLAGS 

No flags

GEOD_ARCMODE 

Position given in terms of arc distance

GEOD_LONG_UNROLL 

Unroll the longitude

Definition at line 900 of file geodesic.h.

◆ geod_mask

enum geod_mask

mask values for the caps argument to geod_lineinit().

Enumerator
GEOD_NONE 

Calculate nothing

GEOD_LATITUDE 

Calculate latitude

GEOD_LONGITUDE 

Calculate longitude

GEOD_AZIMUTH 

Calculate azimuth

GEOD_DISTANCE 

Calculate distance

GEOD_DISTANCE_IN 

Allow distance as input

GEOD_REDUCEDLENGTH 

Calculate reduced length

GEOD_GEODESICSCALE 

Calculate geodesic scale

GEOD_AREA 

Calculate reduced length

GEOD_ALL 

Calculate everything

Definition at line 883 of file geodesic.h.

Function Documentation

◆ geod_direct()

void geod_direct ( const struct geod_geodesic g,
double  lat1,
double  lon1,
double  azi1,
double  s12,
double *  plat2,
double *  plon2,
double *  pazi2 
)

Solve the direct geodesic problem.

Parameters
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in]lat1latitude of point 1 (degrees).
[in]lon1longitude of point 1 (degrees).
[in]azi1azimuth at point 1 (degrees).
[in]s12distance from point 1 to point 2 (meters); it can be negative.
[out]plat2pointer to the latitude of point 2 (degrees).
[out]plon2pointer to the longitude of point 2 (degrees).
[out]pazi2pointer to the (forward) azimuth at point 2 (degrees).

g must have been initialized with a call to geod_init(). lat1 should be in the range [−90°, 90°]. The values of lon2 and azi2 returned are in the range [−180°, 180°]. Any of the "return" arguments plat2, etc., may be replaced by 0, if you do not need some quantities computed.

If either point is at a pole, the azimuth is defined by keeping the longitude fixed, writing lat = ±(90° − ε), and taking the limit ε → 0+. An arc length greater that 180° signifies a geodesic which is not a shortest path. (For a prolate ellipsoid, an additional condition is necessary for a shortest path: the longitudinal extent must not exceed of 180°.)

Example, determine the point 10000 km NE of JFK:

double lat, lon;
geod_init(&g, 6378137, 1/298.257223563);
geod_direct(&g, 40.64, -73.78, 45.0, 10e6, &lat, &lon, 0);
printf("%.5f %.5f\n", lat, lon);

◆ geod_directline()

void geod_directline ( struct geod_geodesicline l,
const struct geod_geodesic g,
double  lat1,
double  lon1,
double  azi1,
double  s12,
unsigned  caps 
)

Initialize a geod_geodesicline object in terms of the direct geodesic problem.

Parameters
[out]la pointer to the object to be initialized.
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in]lat1latitude of point 1 (degrees).
[in]lon1longitude of point 1 (degrees).
[in]azi1azimuth at point 1 (degrees).
[in]s12distance from point 1 to point 2 (meters); it can be negative.
[in]capsbitor'ed combination of geod_mask() values specifying the capabilities the geod_geodesicline object should possess, i.e., which quantities can be returned in calls to geod_position() and geod_genposition().

This function sets point 3 of the geod_geodesicline to correspond to point 2 of the direct geodesic problem. See geod_lineinit() for more information.

◆ geod_gendirect()

double geod_gendirect ( const struct geod_geodesic g,
double  lat1,
double  lon1,
double  azi1,
unsigned  flags,
double  s12_a12,
double *  plat2,
double *  plon2,
double *  pazi2,
double *  ps12,
double *  pm12,
double *  pM12,
double *  pM21,
double *  pS12 
)

The general direct geodesic problem.

Parameters
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in]lat1latitude of point 1 (degrees).
[in]lon1longitude of point 1 (degrees).
[in]azi1azimuth at point 1 (degrees).
[in]flagsbitor'ed combination of geod_flags(); flags & GEOD_ARCMODE determines the meaning of s12_a12 and flags & GEOD_LONG_UNROLL "unrolls" lon2.
[in]s12_a12if flags & GEOD_ARCMODE is 0, this is the distance from point 1 to point 2 (meters); otherwise it is the arc length from point 1 to point 2 (degrees); it can be negative.
[out]plat2pointer to the latitude of point 2 (degrees).
[out]plon2pointer to the longitude of point 2 (degrees).
[out]pazi2pointer to the (forward) azimuth at point 2 (degrees).
[out]ps12pointer to the distance from point 1 to point 2 (meters).
[out]pm12pointer to the reduced length of geodesic (meters).
[out]pM12pointer to the geodesic scale of point 2 relative to point 1 (dimensionless).
[out]pM21pointer to the geodesic scale of point 1 relative to point 2 (dimensionless).
[out]pS12pointer to the area under the geodesic (meters2).
Returns
a12 arc length from point 1 to point 2 (degrees).

g must have been initialized with a call to geod_init(). lat1 should be in the range [−90°, 90°]. The function value a12 equals s12_a12 if flags & GEOD_ARCMODE. Any of the "return" arguments, plat2, etc., may be replaced by 0, if you do not need some quantities computed.

With flags & GEOD_LONG_UNROLL bit set, the longitude is "unrolled" so that the quantity lon2lon1 indicates how many times and in what sense the geodesic encircles the ellipsoid.

◆ geod_gendirectline()

void geod_gendirectline ( struct geod_geodesicline l,
const struct geod_geodesic g,
double  lat1,
double  lon1,
double  azi1,
unsigned  flags,
double  s12_a12,
unsigned  caps 
)

Initialize a geod_geodesicline object in terms of the direct geodesic problem spacified in terms of either distance or arc length.

Parameters
[out]la pointer to the object to be initialized.
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in]lat1latitude of point 1 (degrees).
[in]lon1longitude of point 1 (degrees).
[in]azi1azimuth at point 1 (degrees).
[in]flagseither GEOD_NOFLAGS or GEOD_ARCMODE to determining the meaning of the s12_a12.
[in]s12_a12if flags = GEOD_NOFLAGS, this is the distance from point 1 to point 2 (meters); if flags = GEOD_ARCMODE, it is the arc length from point 1 to point 2 (degrees); it can be negative.
[in]capsbitor'ed combination of geod_mask() values specifying the capabilities the geod_geodesicline object should possess, i.e., which quantities can be returned in calls to geod_position() and geod_genposition().

This function sets point 3 of the geod_geodesicline to correspond to point 2 of the direct geodesic problem. See geod_lineinit() for more information.

◆ geod_geninverse()

double geod_geninverse ( const struct geod_geodesic g,
double  lat1,
double  lon1,
double  lat2,
double  lon2,
double *  ps12,
double *  pazi1,
double *  pazi2,
double *  pm12,
double *  pM12,
double *  pM21,
double *  pS12 
)

The general inverse geodesic calculation.

Parameters
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in]lat1latitude of point 1 (degrees).
[in]lon1longitude of point 1 (degrees).
[in]lat2latitude of point 2 (degrees).
[in]lon2longitude of point 2 (degrees).
[out]ps12pointer to the distance from point 1 to point 2 (meters).
[out]pazi1pointer to the azimuth at point 1 (degrees).
[out]pazi2pointer to the (forward) azimuth at point 2 (degrees).
[out]pm12pointer to the reduced length of geodesic (meters).
[out]pM12pointer to the geodesic scale of point 2 relative to point 1 (dimensionless).
[out]pM21pointer to the geodesic scale of point 1 relative to point 2 (dimensionless).
[out]pS12pointer to the area under the geodesic (meters2).
Returns
a12 arc length from point 1 to point 2 (degrees).

g must have been initialized with a call to geod_init(). lat1 and lat2 should be in the range [−90°, 90°]. Any of the "return" arguments ps12, etc., may be replaced by 0, if you do not need some quantities computed.

◆ geod_genposition()

double geod_genposition ( const struct geod_geodesicline l,
unsigned  flags,
double  s12_a12,
double *  plat2,
double *  plon2,
double *  pazi2,
double *  ps12,
double *  pm12,
double *  pM12,
double *  pM21,
double *  pS12 
)

The general position function.

Parameters
[in]la pointer to the geod_geodesicline object specifying the geodesic line.
[in]flagsbitor'ed combination of geod_flags(); flags & GEOD_ARCMODE determines the meaning of s12_a12 and flags & GEOD_LONG_UNROLL "unrolls" lon2; if flags & GEOD_ARCMODE is 0, then l must have been initialized with caps |= GEOD_DISTANCE_IN.
[in]s12_a12if flags & GEOD_ARCMODE is 0, this is the distance from point 1 to point 2 (meters); otherwise it is the arc length from point 1 to point 2 (degrees); it can be negative.
[out]plat2pointer to the latitude of point 2 (degrees).
[out]plon2pointer to the longitude of point 2 (degrees); requires that l was initialized with caps |= GEOD_LONGITUDE.
[out]pazi2pointer to the (forward) azimuth at point 2 (degrees).
[out]ps12pointer to the distance from point 1 to point 2 (meters); requires that l was initialized with caps |= GEOD_DISTANCE.
[out]pm12pointer to the reduced length of geodesic (meters); requires that l was initialized with caps |= GEOD_REDUCEDLENGTH.
[out]pM12pointer to the geodesic scale of point 2 relative to point 1 (dimensionless); requires that l was initialized with caps |= GEOD_GEODESICSCALE.
[out]pM21pointer to the geodesic scale of point 1 relative to point 2 (dimensionless); requires that l was initialized with caps |= GEOD_GEODESICSCALE.
[out]pS12pointer to the area under the geodesic (meters2); requires that l was initialized with caps |= GEOD_AREA.
Returns
a12 arc length from point 1 to point 2 (degrees).

l must have been initialized with a call to geod_lineinit() with caps |= GEOD_DISTANCE_IN. The value azi2 returned is in the range [−180°, 180°]. Any of the "return" arguments plat2, etc., may be replaced by 0, if you do not need some quantities computed. Requesting a value which l is not capable of computing is not an error; the corresponding argument will not be altered.

With flags & GEOD_LONG_UNROLL bit set, the longitude is "unrolled" so that the quantity lon2lon1 indicates how many times and in what sense the geodesic encircles the ellipsoid.

Example, compute way points between JFK and Singapore Changi Airport using geod_genposition(). In this example, the points are evenly space in arc length (and so only approximately equally spaced in distance). This is faster than using geod_position() and would be appropriate if drawing the path on a map.

double lat[101], lon[101];
int i;
geod_init(&g, 6378137, 1/298.257223563);
geod_inverseline(&l, &g, 40.64, -73.78, 1.36, 103.99,
for (i = 0; i <= 100; ++i) {
geod_genposition(&l, GEOD_ARCMODE, i * l.a13 * 0.01,
lat + i, lon + i, 0, 0, 0, 0, 0, 0);
printf("%.5f %.5f\n", lat[i], lon[i]);
}

◆ geod_gensetdistance()

void geod_gensetdistance ( struct geod_geodesicline l,
unsigned  flags,
double  s13_a13 
)

Specify position of point 3 in terms of either distance or arc length.

Parameters
[in,out]la pointer to the geod_geodesicline object.
[in]flagseither GEOD_NOFLAGS or GEOD_ARCMODE to determining the meaning of the s13_a13.
[in]s13_a13if flags = GEOD_NOFLAGS, this is the distance from point 1 to point 3 (meters); if flags = GEOD_ARCMODE, it is the arc length from point 1 to point 3 (degrees); it can be negative.

If flags = GEOD_NOFLAGS, this calls geod_setdistance(). If flags = GEOD_ARCMODE, the s13 is only set if the geod_geodesicline object has been constructed with caps |= GEOD_DISTANCE.

◆ geod_init()

void geod_init ( struct geod_geodesic g,
double  a,
double  f 
)

Initialize a geod_geodesic object.

Parameters
[out]ga pointer to the object to be initialized.
[in]athe equatorial radius (meters).
[in]fthe flattening.

◆ geod_inverse()

void geod_inverse ( const struct geod_geodesic g,
double  lat1,
double  lon1,
double  lat2,
double  lon2,
double *  ps12,
double *  pazi1,
double *  pazi2 
)

Solve the inverse geodesic problem.

Parameters
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in]lat1latitude of point 1 (degrees).
[in]lon1longitude of point 1 (degrees).
[in]lat2latitude of point 2 (degrees).
[in]lon2longitude of point 2 (degrees).
[out]ps12pointer to the distance from point 1 to point 2 (meters).
[out]pazi1pointer to the azimuth at point 1 (degrees).
[out]pazi2pointer to the (forward) azimuth at point 2 (degrees).

g must have been initialized with a call to geod_init(). lat1 and lat2 should be in the range [−90°, 90°]. The values of azi1 and azi2 returned are in the range [−180°, 180°]. Any of the "return" arguments, ps12, etc., may be replaced by 0, if you do not need some quantities computed.

If either point is at a pole, the azimuth is defined by keeping the longitude fixed, writing lat = ±(90° − ε), and taking the limit ε → 0+.

The solution to the inverse problem is found using Newton's method. If this fails to converge (this is very unlikely in geodetic applications but does occur for very eccentric ellipsoids), then the bisection method is used to refine the solution.

Example, determine the distance between JFK and Singapore Changi Airport:

double s12;
geod_init(&g, 6378137, 1/298.257223563);
geod_inverse(&g, 40.64, -73.78, 1.36, 103.99, &s12, 0, 0);
printf("%.3f\n", s12);

◆ geod_inverseline()

void geod_inverseline ( struct geod_geodesicline l,
const struct geod_geodesic g,
double  lat1,
double  lon1,
double  lat2,
double  lon2,
unsigned  caps 
)

Initialize a geod_geodesicline object in terms of the inverse geodesic problem.

Parameters
[out]la pointer to the object to be initialized.
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in]lat1latitude of point 1 (degrees).
[in]lon1longitude of point 1 (degrees).
[in]lat2latitude of point 2 (degrees).
[in]lon2longitude of point 2 (degrees).
[in]capsbitor'ed combination of geod_mask() values specifying the capabilities the geod_geodesicline object should possess, i.e., which quantities can be returned in calls to geod_position() and geod_genposition().

This function sets point 3 of the geod_geodesicline to correspond to point 2 of the inverse geodesic problem. See geod_lineinit() for more information.

◆ geod_lineinit()

void geod_lineinit ( struct geod_geodesicline l,
const struct geod_geodesic g,
double  lat1,
double  lon1,
double  azi1,
unsigned  caps 
)

Initialize a geod_geodesicline object.

Parameters
[out]la pointer to the object to be initialized.
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in]lat1latitude of point 1 (degrees).
[in]lon1longitude of point 1 (degrees).
[in]azi1azimuth at point 1 (degrees).
[in]capsbitor'ed combination of geod_mask() values specifying the capabilities the geod_geodesicline object should possess, i.e., which quantities can be returned in calls to geod_position() and geod_genposition().

g must have been initialized with a call to geod_init(). lat1 should be in the range [−90°, 90°].

The geod_mask values are [see geod_mask()]:

  • caps |= GEOD_LATITUDE for the latitude lat2; this is added automatically,
  • caps |= GEOD_LONGITUDE for the latitude lon2,
  • caps |= GEOD_AZIMUTH for the latitude azi2; this is added automatically,
  • caps |= GEOD_DISTANCE for the distance s12,
  • caps |= GEOD_REDUCEDLENGTH for the reduced length m12,
  • caps |= GEOD_GEODESICSCALE for the geodesic scales M12 and M21,
  • caps |= GEOD_AREA for the area S12,
  • caps |= GEOD_DISTANCE_IN permits the length of the geodesic to be given in terms of s12; without this capability the length can only be specified in terms of arc length.

A value of caps = 0 is treated as GEOD_LATITUDE | GEOD_LONGITUDE | GEOD_AZIMUTH | GEOD_DISTANCE_IN (to support the solution of the "standard" direct problem).

When initialized by this function, point 3 is undefined (l->s13 = l->a13 = NaN).

◆ geod_polygon_addedge()

void geod_polygon_addedge ( const struct geod_geodesic g,
struct geod_polygon p,
double  azi,
double  s 
)

Add an edge to the polygon or polyline.

Parameters
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in,out]pa pointer to the geod_polygon object specifying the polygon.
[in]aziazimuth at current point (degrees).
[in]sdistance from current point to next point (meters).

g and p must have been initialized with calls to geod_init() and geod_polygon_init(), respectively. The same g must be used for all the points and edges in a polygon. This does nothing if no points have been added yet. The lat and lon fields of p give the location of the new vertex.

◆ geod_polygon_addpoint()

void geod_polygon_addpoint ( const struct geod_geodesic g,
struct geod_polygon p,
double  lat,
double  lon 
)

Add a point to the polygon or polyline.

Parameters
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in,out]pa pointer to the geod_polygon object specifying the polygon.
[in]latthe latitude of the point (degrees).
[in]lonthe longitude of the point (degrees).

g and p must have been initialized with calls to geod_init() and geod_polygon_init(), respectively. The same g must be used for all the points and edges in a polygon. lat should be in the range [−90°, 90°].

An example of the use of this function is given in the documentation for geod_polygon_compute().

◆ geod_polygon_clear()

void geod_polygon_clear ( struct geod_polygon p)

Clear the polygon, allowing a new polygon to be started.

Parameters
[in,out]pa pointer to the object to be cleared.

◆ geod_polygon_compute()

unsigned geod_polygon_compute ( const struct geod_geodesic g,
const struct geod_polygon p,
int  reverse,
int  sign,
double *  pA,
double *  pP 
)

Return the results for a polygon.

Parameters
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in]pa pointer to the geod_polygon object specifying the polygon.
[in]reverseif non-zero then clockwise (instead of counter-clockwise) traversal counts as a positive area.
[in]signif non-zero 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.
[out]pApointer to the area of the polygon (meters2); only set if polyline is non-zero in the call to geod_polygon_init().
[out]pPpointer to the perimeter of the polygon or length of the polyline (meters).
Returns
the number of points.

The area and perimeter are accumulated at two times the standard floating point precision to guard against the loss of accuracy with many-sided polygons. Only simple polygons (which are not self-intersecting) are allowed. There's no need to "close" the polygon by repeating the first vertex. Set pA or pP to zero, if you do not want the corresponding quantity returned.

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

Example, compute the perimeter and area of the geodesic triangle with vertices (0°N,0°E), (0°N,90°E), (90°N,0°E).

double A, P;
int n;
struct geod_polygon p;
geod_init(&g, 6378137, 1/298.257223563);
n = geod_polygon_compute(&g, &p, 0, 1, &A, &P);
printf("%d %.8f %.3f\n", n, P, A);

◆ geod_polygon_init()

void geod_polygon_init ( struct geod_polygon p,
int  polylinep 
)

Initialize a geod_polygon object.

Parameters
[out]pa pointer to the object to be initialized.
[in]polylinepnon-zero if a polyline instead of a polygon.

If polylinep is zero, then the sequence of vertices and edges added by geod_polygon_addpoint() and geod_polygon_addedge() define a polygon and the perimeter and area are returned by geod_polygon_compute(). If polylinep is non-zero, then the vertices and edges define a polyline and only the perimeter is returned by geod_polygon_compute().

The area and perimeter are accumulated at two times the standard floating point precision to guard against the loss of accuracy with many-sided polygons. At any point you can ask for the perimeter and area so far.

An example of the use of this function is given in the documentation for geod_polygon_compute().

◆ geod_polygon_testedge()

unsigned geod_polygon_testedge ( const struct geod_geodesic g,
const struct geod_polygon p,
double  azi,
double  s,
int  reverse,
int  sign,
double *  pA,
double *  pP 
)

Return the results assuming a tentative final test point is added via an azimuth and distance; however, the data for the test point is not saved. This lets you report a running result for the perimeter and area as the user moves the mouse cursor. Ordinary floating point arithmetic is used to accumulate the data for the test point; thus the area and perimeter returned are less accurate than if geod_polygon_addedge() and geod_polygon_compute() are used.

Parameters
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in]pa pointer to the geod_polygon object specifying the polygon.
[in]aziazimuth at current point (degrees).
[in]sdistance from current point to final test point (meters).
[in]reverseif non-zero then clockwise (instead of counter-clockwise) traversal counts as a positive area.
[in]signif non-zero 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.
[out]pApointer to the area of the polygon (meters2); only set if polyline is non-zero in the call to geod_polygon_init().
[out]pPpointer to the perimeter of the polygon or length of the polyline (meters).
Returns
the number of points.

◆ geod_polygon_testpoint()

unsigned geod_polygon_testpoint ( const struct geod_geodesic g,
const struct geod_polygon p,
double  lat,
double  lon,
int  reverse,
int  sign,
double *  pA,
double *  pP 
)

Return the results assuming a tentative final test point is added; however, the data for the test point is not saved. This lets you report a running result for the perimeter and area as the user moves the mouse cursor. Ordinary floating point arithmetic is used to accumulate the data for the test point; thus the area and perimeter returned are less accurate than if geod_polygon_addpoint() and geod_polygon_compute() are used.

Parameters
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in]pa pointer to the geod_polygon object specifying the polygon.
[in]latthe latitude of the test point (degrees).
[in]lonthe longitude of the test point (degrees).
[in]reverseif non-zero then clockwise (instead of counter-clockwise) traversal counts as a positive area.
[in]signif non-zero 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.
[out]pApointer to the area of the polygon (meters2); only set if polyline is non-zero in the call to geod_polygon_init().
[out]pPpointer to the perimeter of the polygon or length of the polyline (meters).
Returns
the number of points.

lat should be in the range [−90°, 90°].

◆ geod_polygonarea()

void geod_polygonarea ( const struct geod_geodesic g,
double  lats[],
double  lons[],
int  n,
double *  pA,
double *  pP 
)

A simple interface for computing the area of a geodesic polygon.

Parameters
[in]ga pointer to the geod_geodesic object specifying the ellipsoid.
[in]latsan array of latitudes of the polygon vertices (degrees).
[in]lonsan array of longitudes of the polygon vertices (degrees).
[in]nthe number of vertices.
[out]pApointer to the area of the polygon (meters2).
[out]pPpointer to the perimeter of the polygon (meters).

lats should be in the range [−90°, 90°].

Only simple polygons (which are not self-intersecting) are allowed. There's no need to "close" the polygon by repeating the first vertex. The area returned is signed with counter-clockwise traversal being treated as positive.

Example, compute the area of Antarctica:

double
lats[] = {-72.9, -71.9, -74.9, -74.3, -77.5, -77.4, -71.7, -65.9, -65.7,
-66.6, -66.9, -69.8, -70.0, -71.0, -77.3, -77.9, -74.7},
lons[] = {-74, -102, -102, -131, -163, 163, 172, 140, 113,
88, 59, 25, -4, -14, -33, -46, -61};
double A, P;
geod_init(&g, 6378137, 1/298.257223563);
geod_polygonarea(&g, lats, lons, (sizeof lats) / (sizeof lats[0]), &A, &P);
printf("%.0f %.2f\n", A, P);

◆ geod_position()

void geod_position ( const struct geod_geodesicline l,
double  s12,
double *  plat2,
double *  plon2,
double *  pazi2 
)

Compute the position along a geod_geodesicline.

Parameters
[in]la pointer to the geod_geodesicline object specifying the geodesic line.
[in]s12distance from point 1 to point 2 (meters); it can be negative.
[out]plat2pointer to the latitude of point 2 (degrees).
[out]plon2pointer to the longitude of point 2 (degrees); requires that l was initialized with caps |= GEOD_LONGITUDE.
[out]pazi2pointer to the (forward) azimuth at point 2 (degrees).

l must have been initialized with a call, e.g., to geod_lineinit(), with caps |= GEOD_DISTANCE_IN. The values of lon2 and azi2 returned are in the range [−180°, 180°]. Any of the "return" arguments plat2, etc., may be replaced by 0, if you do not need some quantities computed.

Example, compute way points between JFK and Singapore Changi Airport the "obvious" way using geod_direct():

double s12, azi1, lat[101],lon[101];
int i;
geod_init(&g, 6378137, 1/298.257223563);
geod_inverse(&g, 40.64, -73.78, 1.36, 103.99, &s12, &azi1, 0);
for (i = 0; i < 101; ++i) {
geod_direct(&g, 40.64, -73.78, azi1, i * s12 * 0.01, lat + i, lon + i, 0);
printf("%.5f %.5f\n", lat[i], lon[i]);
}

A faster way using geod_position():

double lat[101],lon[101];
int i;
geod_init(&g, 6378137, 1/298.257223563);
geod_inverseline(&l, &g, 40.64, -73.78, 1.36, 103.99, 0);
for (i = 0; i <= 100; ++i) {
geod_position(&l, i * l.s13 * 0.01, lat + i, lon + i, 0);
printf("%.5f %.5f\n", lat[i], lon[i]);
}

◆ geod_setdistance()

void geod_setdistance ( struct geod_geodesicline l,
double  s13 
)

Specify position of point 3 in terms of distance.

Parameters
[in,out]la pointer to the geod_geodesicline object.
[in]s13the distance from point 1 to point 3 (meters); it can be negative.

This is only useful if the geod_geodesicline object has been constructed with caps |= GEOD_DISTANCE_IN.



gtsam
Author(s):
autogenerated on Tue Jul 4 2023 02:40:49