geodesic

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 20, 2023 License: MIT Imports: 7 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	// WGS84_a is the equatorial radius of the WGS84 ellipsoid (6378137 m)
	WGS84_a = 6378137.

	// WGS84_f is the flattening of the WGS84 ellipsoid (1/298.257223563)
	WGS84_f = 1 / 298.257223563
)

Variables

View Source 
var (
	// WGS84 is an instance of Geodesic which represents the Earth according to the
	// World Geodetic System. See also:
	// https://en.wikipedia.org/wiki/World_Geodetic_System
	WGS84, _ = NewGeodesic(WGS84_a, WGS84_f)
)

Functions

This section is empty.

Types

type Data 

type Data struct {

	// Lat1 is the latitude of point 1 in degrees
	Lat1 float64

	// Lon1 is the longitude of point 1 in degrees
	Lon1 float64

	// Azi1 is the azimuth at point 1 in degrees
	Azi1 float64

	// Lat2 is the latitude of point 2 in degrees
	Lat2 float64

	// Lon2 is the longitude of point 2 in degrees
	Lon2 float64

	// Azi2 is the azimuth at point 2 in degrees
	Azi2 float64

	// S12 is the distance between point 1 and point 2 in meters
	S12 float64

	// A12 is the arc length on the auxiliary sphere between point 1 and point 2 in
	// degrees
	A12 float64

	// M12Reduced is the reduced length of the geodesic in meters.
	//
	// Reduced length:
	//  If we fix the first point and increase azi1 by dazi1 (radians), the second
	//  point is displaced m12 dazi1 in the direction azi2 + 90 degrees. The quantity
	//  m12 is called the "reduced length" and is symmetric under interchange of the
	//  two points. On a curved surface the reduced length obeys a symmetry relation,
	//  m12 + m21 = 0. On a flat surface, we have m12 = s12. The ratio s12/m12 gives
	//  the azimuthal scale for an azimuthal equidistant projection.
	M12Reduced float64

	// M12 is the geodesic scale of point 2 relative to point 1 (dimensionless)
	//
	// Geodesic scale:
	//  Consider a reference geodesic and a second geodesic parallel to this one at
	//  point 1 and separated by a small distance dt. The separation of the two
	//  geodesics at point 2 is M12 dt where M12 is called the "geodesic scale". M21
	//  is defined similarly (with the geodesics being parallel at point 2). On a flat
	//  surface, we have M12 = M21 = 1. The quantity 1/M12 gives the scale of the
	//  Cassini-Soldner projection.
	M12 float64

	// M21 is the geodesic scale of point 1 relative to point 2 (dimensionless)
	//
	// Geodesic scale:
	//  Consider a reference geodesic and a second geodesic parallel to this one at
	//  point 1 and separated by a small distance dt. The separation of the two
	//  geodesics at point 2 is M12 dt where M12 is called the "geodesic scale". M21
	//  is defined similarly (with the geodesics being parallel at point 2). On a flat
	//  surface, we have M12 = M21 = 1. The quantity 1/M12 gives the scale of the
	//  Cassini-Soldner projection.
	M21 float64

	// S12Area is the area under the geodesic (meters²)
	//
	// Area:
	//  The area between the geodesic from point 1 to point 2 and the equation is
	//  represented by S12Area; it is the area, measured counter-clockwise, of the
	//  geodesic quadrilateral with corners (lat1,lon1), (0,lon1), (0,lon2), and
	//  (lat2,lon2). It can be used to compute the area of any geodesic polygon.
	S12Area float64
}

Data describes the characteristics of a geodesic between point 1 (Lat1, Lon1) and point 2 (Lat2, Lon2). Fields that have not been set will be filled by math.NaN. Data will always include the field A12.

type Geodesic 

type Geodesic struct {
	// contains filtered or unexported fields
}

Geodesic is a type representing geodesic calculations.

The shortest path between two points on a 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 azimuths azi1 and azi2 at the two end points. (The azimuth is the heading measured clockwise from north. azi2 is the "forward" azimuth, i.e., the heading that takes you beyond point 2 not back to point 1.)

Given lat1, lon1, azi1, and s12, we can determine lat2, lon2, and azi2. This is the direct geodesic problem and its solution is given by the function Direct. (If s12 is sufficiently large that the geodesic wraps more than halfway around the earth, there will be another geodesic between the points with a smaller s12.)

Given lat1, lon1, lat2, and lon2, we can determine azi1, azi2, and s12. This is the inverse geodesic problem, whose solution is given by Inverse. Usually, the solution to the inverse problem is unique. In cases where there are multiple solutions (all with the same s12, of course), all the solutions can be easily generated once a particular solution is provided.

The standard way of specifying the direct problem is to specify the distance s12 to the second point. However it is sometimes useful instead to specify the arc length a12 (in degrees) on the auxiliary sphere. This is a mathematical construct used in solving the geodesic problems. The solution of the direct problem in this form is provided by ArcDirect. An arc length in excess of 180° indicates that the geodesic is not a shortest path. In addition, the arc length between an equatorial crossing and the next extremum of latitude for a geodesic is 90°.

This type can also calculate several other quantities related to geodesics. These are:

Reduced length: 

If we fix the first point and increase azi1 by dazi1 (radians), the second point
is displaced m12 dazi1 in the direction azi2 + 90°. The quantity m12 is called
the "reduced length" and is symmetric under interchange of the two points. On a
curved surface the reduced length obeys a symmetry relation, m12 + m21 = 0. On a
flat surface, we have m12 = s12. The ratio s12/m12 gives the azimuthal scale for
an azimuthal equidistant projection.

Geodesic scale: 

Consider a reference geodesic and a second geodesic parallel to this one at
point 1 and separated by a small distance dt. The separation of the two
geodesics at point 2 is M12 dt where M12 is called the "geodesic scale". M21 is
defined similarly (with the geodesics being parallel at point 2). On a flat
surface, we have M12 = M21 = 1. The quantity 1/M12 gives the scale of the
Cassini-Soldner projection.

Area: 

The area between the geodesic from point 1 to point 2 and the equation is
represented by S12; it is the area, measured counter-clockwise, of the geodesic
quadrilateral with corners (lat1,lon1), (0,lon1), (0,lon2), and (lat2,lon2). It
can be used to compute the area of any geodesic polygon.

The quantities m12, M12, M21, which all specify the behavior of nearby geodesics, obey addition rules. If points 1, 2, and 3 all lie on a single geodesic, then the following rules hold: 

s13 = s12 + s23
a13 = a12 + a23
S13 = S12 + S23
m13 = m12 M23 + m23 M21
M13 = M12 M23 - (1 - M12 M21) m23 / m12
M31 = M32 M21 - (1 - M23 M32) m12 / m23

The results of the geodesic calculations are bundled up into a Data struct which includes the input parameters and all the computed results, i.e., lat1, lon1, azi1, lat2, lon2, azi2, s12, a12, m12 (as M12Reduced), M12, M21, S12 (as S12Area).

The functions DirectWithCapabilities, InverseWithCapabilities, and ArcDirectWithCapabilities include an optional final argument of type capabilities.Mask to allow you to specify which results should be computed and returned. The default functions Direct, Inverse, and ArcDirect are equivalent to calling DirectWithCapabilities, InverseWithCapabilities, and ArcDirectWithCapabilities with the capabilities.Standard argument, which will compute "standard" geodesic results (latitudes, longitudes, azimuths, and distance). A custom capabilities.Mask argument can be bitor'ed out of a combination of other capabilities.Mask values. For example, if you wish to only compute the distance between two points, you would call, e.g., 

geodesicData := WGS84.Inverse(lat1, lon1, lat2, lon2, capabilities.Distance)

Additional functionality is provided by the geodesic.Line type, which allows a sequence of points along a geodesic to be computed. An instance of geodesic.Line can be created by calling Geodesic.Line.

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: 

lat1 = -lat2 (with neither point at a pole). If azi1 = azi2, the geodesic is
unique. Otherwise there are two geodesics and the second one is obtained by
setting [azi1, azi2] → [azi2, azi1], [M12, M21] → [M21, M12], S12 → -S12. (This
occurs when the longitude difference is near ±180° for oblate ellipsoids.)

lon2 = lon1 ± 180° (with neither point at a pole). If azi1 = 0° or ±180°, the
geodesic is unique. Otherwise there are two geodesics and the second one is
obtained by setting [ azi1, azi2] → [-azi1, -azi2], S12 → - S12. (This occurs
when lat2 is near -lat1 for prolate ellipsoids.)

Points 1 and 2 at opposite poles. There are infinitely many geodesics which can
be generated by setting [azi1, azi2] → [azi1, azi2] + [d, -d], for arbitrary d.
(For spheres, this prescription applies when points 1 and 2 are antipodal.)

s12 = 0 (coincident points). There are infinitely many geodesics which can be
generated by setting [azi1, azi2] → [azi1, azi2] + [d, d], for arbitrary d.

The calculations are accurate to better than 15 nm (15 nanometers) for the WGS84 ellipsoid. See Sec. 9 of arXiv:1102.1215v1 (https://arxiv.org/abs/1102.1215v1) for details. The algorithms used by this type are based on series expansions using the flattening f as a small parameter. These are only accurate for |f| < 0.02; however, reasonably accurate results will be obtained for |f| < 0.2. Here is a table of the approximate maximum error (expressed as a distance) for an ellipsoid with the same equatorial radius as the WGS84 ellipsoid and different values of the flattening. 

|f|      error
0.01     25 nm
0.02     30 nm
0.05     10 um
0.1     1.5 mm
0.2     300 mm

The algorithms are described in 

C. F. F. Karney, Algorithms for geodesics, J. Geodesy 87, 43-55 (2013)
Link: https://doi.org/10.1007/s00190-012-0578-z
Addenda: https://geographiclib.sourceforge.io/geod-addenda.html

func NewGeodesic 

func NewGeodesic(a, f float64) (*Geodesic, error)

NewGeodesic creates a new instance of Geodesic with the given equatorial radius a (in meters) and flattening of the ellipsoid f. Setting f = 0 gives a sphere; negative f gives a prolate ellipsoid.

This function will return an error if either a or (1-f) is not positive.

func (*Geodesic) ArcDirect 

func (g *Geodesic) ArcDirect(lat1, lon1, azi1, a12 float64) Data

ArcDirect solves the direct geodesic problem where the length of the geodesic is specified in terms of arc length. 

lat1: latitude of point 1 (degrees). Should be in the range [-90°, 90°].
lon1: longitude of point 1 (degrees).
azi1: azimuth at point 1 (degrees).
a12: arc length between point 1 and point 2 (meters); can be negative.

The returned values Data.Lon2 and Data.Azi2 are in the range [-180°, 180°].

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°.)

This function is equivalent to calling ArcDirectWithCapabilities with capabilities.Standard.

func (*Geodesic) ArcDirectLine 

func (g *Geodesic) ArcDirectLine(lat1, lon1, azi1, a12 float64) *Line

ArcDirectLine returns an instance of geodesic.Line defined in terms of the direct geodesic problem and specified in terms of arc length. The function sets point 3 of the returned geodesic.Line to correspond to point 2 of the direct geodesic problem. 

lat1: latitude of point 1 (degrees). Should be in the range [-90°, 90°].
lon1: longitude of point 1 (degrees).
azi1: azimuth at point 1 (degrees).
a12: arc length between point 1 and point 2 (degrees); it can be negative.

This function is equivalent to calling ArcDirectLineWithCapabilities with capabilities.All.

func (*Geodesic) ArcDirectLineWithCapabilities 

func (g *Geodesic) ArcDirectLineWithCapabilities(lat1, lon1, azi1, a12 float64, caps capabilities.Mask) *Line

ArcDirectLineWithCapabilities returns an instance of geodesic.Line defined in terms of the direct geodesic problem and specified in terms of arc length. The function sets point 3 of the returned geodesic.Line to correspond to point 2 of the direct geodesic problem. It also allows you to specify which results should be computed and returned via the capabilities.Mask argument.

See ArcDirectLine for more details.

func (*Geodesic) ArcDirectWithCapabilities 

func (g *Geodesic) ArcDirectWithCapabilities(lat1, lon1, azi1, a12 float64, caps capabilities.Mask) Data

ArcDirectWithCapabilities solves the direct geodesic problem where the length of the geodesic is specified in terms of arc length. It also allows you to specify which results should be computed and returned via the capabilities.Mask argument.

See ArcDirect for more details.

func (*Geodesic) Direct 

func (g *Geodesic) Direct(lat1, lon1, azi1, s12 float64) Data

Direct solves the direct geodesic problem where the length of the geodesic is specified in terms of distance. 

lat1: latitude of point 1 (degrees). Should be in the range [-90°, 90°].
lon1: longitude of point 1 (degrees).
azi1: azimuth at point 1 (degrees).
s12: distance between point 1 and point 2 (meters); can be negative.

The returned values Data.Lon2 and Data.Azi2 are in the range [-180°, 180°].

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°.)

This function is equivalent to calling DirectWithCapabilities with capabilities.Standard.

func (*Geodesic) DirectLine 

func (g *Geodesic) DirectLine(lat1, lon1, azi1, s12 float64) *Line

DirectLine returns an instance of geodesic.Line defined in terms of the direct geodesic problem and specified in terms of distance. The function sets point 3 of the returned geodesic.Line to correspond to point 2 of the direct geodesic problem. 

lat1: latitude of point 1 (degrees). Should be in the range [-90°, 90°].
lon1: longitude of point 1 (degrees).
azi1: azimuth at point 1 (degrees).
s12: distance between point 1 and point 2 (meters); it can be negative.

This function is equivalent to calling DirectLineWithCapabilities with capabilities.All.

func (*Geodesic) DirectLineWithCapabilities 

func (g *Geodesic) DirectLineWithCapabilities(lat1, lon1, azi1, s12 float64, caps capabilities.Mask) *Line

DirectLineWithCapabilities returns an instance of geodesic.Line defined in terms of the direct geodesic problem and specified in terms of distance. The function sets point 3 of the returned geodesic.Line to correspond to point 2 of the direct geodesic problem. It also allows you to specify which results should be computed and returned via the capabilities.Mask argument.

See DirectLine for more details.

func (*Geodesic) DirectWithCapabilities 

func (g *Geodesic) DirectWithCapabilities(lat1, lon1, azi1, s12 float64, caps capabilities.Mask) Data

DirectWithCapabilities solves the direct geodesic problem where the length of the geodesic is specified in terms of distance. It also allows you to specify which results should be computed and returned via the capabilities.Mask argument.

See Direct for more details.

func (*Geodesic) EllipsoidArea 

func (g *Geodesic) EllipsoidArea() float64

EllipsoidArea returns the total area of the ellipsoid in meters². The area of a polygon encircling a pole can be found by adding EllipsoidArea()/2 to the sum of S12Area for each side of the polygon.

func (*Geodesic) EquatorialRadius 

func (g *Geodesic) EquatorialRadius() float64

EquatorialRadius returns the equatorial radius of the ellipsoid in meters. This is the value used to create the Geodesic instance.

func (*Geodesic) Flattening 

func (g *Geodesic) Flattening() float64

Flattening returns the flattening of the ellipsoid. This is the value used to create the Geodesic instance.

func (*Geodesic) Inverse 

func (g *Geodesic) Inverse(lat1, lon1, lat2, lon2 float64) Data

Inverse solves the inverse geodesic problem. 

lat1: latitude of point 1 (degrees). Should be in the range [-90°, 90°].
lon1: longitude of point 1 (degrees).
lat2: latitude of point 2 (degrees). Should be in the range [-90°, 90°].
lon2: longitude of point 2 (degrees).

The returned values Data.Azi1 and Data.Azi2 are in the range [-180°, 180°].

If either point is at a pole, the azimuth is defined by keeping the longitude fixed, writing lat = ±(90° - ε), 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.

This function is equivalent to calling InverseWithCapabilities with capabilities.Standard.

func (*Geodesic) InverseLine 

func (g *Geodesic) InverseLine(lat1, lon1, lat2, lon2 float64) *Line

InverseLine an instance of geodesic.Line defined in terms of the inverse geodesic problem. This function sets point 3 of the GeodesicLine to correspond to point 2 of the inverse geodesic problem. 

lat1: latitude of point 1 (degrees). Should be in the range [-90°, 90°].
lon1: longitude of point 1 (degrees).
lat2: latitude of point 2 (degrees). Should be in the range [-90°, 90°].
lon2: longitude of point 2 (degrees).

This function is equivalent to calling InverseLineWithCapabilities with capabilities.All.

func (*Geodesic) InverseLineWithCapabilities 

func (g *Geodesic) InverseLineWithCapabilities(lat1, lon1, lat2, lon2 float64, caps capabilities.Mask) *Line

InverseLineWithCapabilities an instance of geodesic.Line defined in terms of the inverse geodesic problem. This function sets point 3 of the GeodesicLine to correspond to point 2 of the inverse geodesic problem. It also allows you to specify which results should be computed and returned via the capabilities.Mask argument.

See InverseLineWithCapabilities for more details.

func (*Geodesic) InverseWithCapabilities 

func (g *Geodesic) InverseWithCapabilities(lat1, lon1, lat2, lon2 float64, caps capabilities.Mask) Data

InverseWithCapabilities solves the inverse geodesic problem. It also allows you to specify which results should be computed and returned via the capabilities.Mask argument.

See Inverse for more details.

func (*Geodesic) Line 

func (g *Geodesic) Line(lat1, lon1, azi1 float64) *Line

Line returns an instance of geodesic.Line to allow computation of several points on a single geodesic. 

lat1: latitude of point 1 (degrees).
lon1: longitude of point 1 (degrees).
azi1: azimuth at point 1 (degrees).

If the point is at a pole, the azimuth is defined by keeping lon1 fixed, writing lat1 = ±(90 - ε), and taking the limit ε → 0+.

This function is equivalent to calling LineWithCapabilities with capabilities.All.

func (*Geodesic) LineWithCapabilities 

func (g *Geodesic) LineWithCapabilities(lat1, lon1, azi1 float64, caps capabilities.Mask) *Line

LineWithCapabilities returns an instance of geodesic.Line to allow computation of several points on a single geodesic. It also allows you to specify which results should be computed and returned via the capabilities.Mask argument.

See Line for more details.

type Gnomonic added in v1.1.0 

type Gnomonic struct {
	Earth *Geodesic
}

Gnomonic is a type representing calculations for gnomonic projections centered at an arbitrary position C on the ellipsoid. This projection is derived in Section 8 of C. F. F. Karney, Algorithms for geodesics, J. Geodesy 87, 43–55 (2013); DOI: 10.1007/s00190-012-0578-z; addenda: https://geographiclib.sourceforge.io/geod-addenda.html.

The gnomonic projection of a point P on the ellipsoid is defined as follows: compute the geodesic line from C to P; compute the reduced length m12, geodesic scale M12, and ρ = m12/M12; finally, this gives the coordinates x and y of P in gnomonic projection with x = ρ sin azi1; y = ρ cos azi1, where azi1 is the azimuth of the geodesic at C. The method Forward(double, double, double, double) performs the forward projection and Reverse(double, double, double, double) is the inverse of the projection. The methods also return the azimuth azi of the geodesic at P and reciprocal scale rk in the azimuthal direction. The scale in the radial direction is 1/(rk^2).

For a sphere, ρ reduces to a tan(s12/a), where s12 is the length of the geodesic from C to P, and the gnomonic projection has the property that all geodesics appear as straight lines. For an ellipsoid, this property holds only for geodesics intersecting the centers. However geodesic segments close to the center are approximately straight.

Consider a geodesic segment of length l. Let T be the point on the geodesic (extended if necessary) closest to C, the center of the projection, and t, be the distance CT. To lowest order, the maximum deviation (as a true distance) of the corresponding gnomonic line segment (i.e., with the same end points) from the geodesic is: 

K(T) − K(C)) l^2 t / 32.

where K is the Gaussian curvature.

This result applies for any surface. For an ellipsoid of revolution, consider all geodesics whose end points are within a distance r of C. For a given r, the deviation is maximum when the latitude of C is 45°, when endpoints are a distance r away, and when their azimuths from the center are ± 45° or ± 135°. To lowest order in r and the flattening f, the deviation is f (r/2a)^3 r.

CAUTION: The definition of this projection for a sphere is standard. However, there is no standard for how it should be extended to an ellipsoid. The choices are:

  • Declare that the projection is undefined for an ellipsoid.
  • Project to a tangent plane from the center of the ellipsoid. This causes great ellipses to appear as straight lines in the projection; i.e., it generalizes the spherical great circle to a great ellipse. This was proposed by independently by Bowring and Williams in 1997.
  • Project to the conformal sphere with the constant of integration chosen so that the values of the latitude match for the center point and perform a central projection onto the plane tangent to the conformal sphere at the center point. This causes normal sections through the center point to appear as straight lines in the projection; i.e., it generalizes the spherical great circle to a normal section. This was proposed by I. G. Letoval'tsev, Generalization of the gnomonic projection for a spheroid and the principal geodetic problems involved in the alignment of surface routes, Geodesy and Aerophotography (5), 271–274 (1963).
  • The projection given here. This causes geodesics close to the center point to appear as straight lines in the projection; i.e., it generalizes the spherical great circle to a geodesic.

The algorithms are described in 

C. F. F. Karney, Algorithms for geodesics, J. Geodesy 87, 43-55 (2013)
Link: https://doi.org/10.1007/s00190-012-0578-z
Addenda: https://geographiclib.sourceforge.io/geod-addenda.html

func (*Gnomonic) Forward added in v1.1.0 

func (g *Gnomonic) Forward(lat0, lon0, lat, lon float64) GnomonicData

Forward performs the forward projection from geographic to gnomonic. 

lat0: latitude of center point of projection (degrees). Should be in the range [-90°, 90°].
lon0: longitude of center point of projection (degrees). Should be in the range [−540°, 540°).
lat - latitude of point (degrees). Should be in the range [-90°, 90°].
lon - longitude of point (degrees). Should be in the range [−540°, 540°).

The scale of the projection is 1/rk2 in the "radial" direction, azi clockwise from true north, and is 1/rk in the direction perpendicular to this. If the point lies "over the horizon", i.e., if rk ≤ 0, then NaNs are returned for x and y (the correct values are returned for azi and rk). A call to Forward followed by a call to Reverse will return the original (lat, lon) (to within roundoff) provided the point is not over the horizon.

func (*Gnomonic) Reverse added in v1.1.0 

func (g *Gnomonic) Reverse(lat0, lon0, x, y float64) GnomonicData

Reverse performs the reverse projection from gnomonic to geographic. 

lat0: latitude of center point of projection (degrees). Should be in the range [-90°, 90°].
lon0: longitude of center point of projection (degrees). Should be in the range [−540°, 540°).
x: easting of point (meters).
y: northing of point (meters).

The returned values GnomonicData.Lat and GnomonicData.Lon are in the range [-180°, 180°].

The scale of the projection is 1/rk2 in the "radial" direction, azi clockwise from true north, and is 1/rk in the direction perpendicular to this. Even though all inputs should return a valid lat and lon, it's possible that the procedure fails to converge for very large x or y; in this case NaNs are returned for all the output arguments. A call to Reverse followed by a call to Forward will return the original (x, y) (to roundoff).

type GnomonicData added in v1.1.0 

type GnomonicData struct {
	Lat0 float64
	Lon0 float64
	Lat  float64
	Lon  float64
	X    float64
	Y    float64
	Azi  float64
	Rk   float64
}

GnomonicData describes the results of gnomonic projection. This is used to return the results for a gnomonic projection of a point (lat, lon) given a center point of projection (lat0, lon0). The returned GnomonicData structs always include the parameters provided to Gnomonic.Forward and Gnomonic.Reverse and it always includes the fields x, y, azi. and rk.

type Line 

type Line struct {
	// contains filtered or unexported fields
}

Line represents a geodesic line and facilitates the determination of a series of points on a single geodesic. The Geodesic.Line function should be used to create an instance of Line.

Position returns the location of point 2 a distance s12 along the geodesic. Alternatively, ArcPosition gives the position of point 2 an arc length a12 along the geodesic. The additional functions PositionWithCapabilities and ArcPositionWithCapabilities include an optional final argument of type capabilities.Mask to allow you to specify which results should be computed and returned.

You can register the position of a reference point 3 a distance (arc length), s13 (a13) along the geodesic with the SetDistance (SetArc) functions. Points a fractional distance along the line can be found by providing, for example, 0.5 * Distance as an argument to Position. The Geodesic.InverseLine or Geodesic.DirectLine functions return Line instances with point 3 set to the point 2 of the corresponding geodesic problem. Line instances created Geodesic.Line have s13 and a13 set to math.NaN.

The calculations are accurate to better than 15 nm (15 nanometers). See Sec. 9 of arXiv:1102.1215v1 (https://arxiv.org/abs/1102.1215v1) for details. The algorithms used by this class are based on series expansions using the flattening f as a small parameter. These are only accurate for |f| < 0.02; however reasonably accurate results will be obtained for |f| < 0.2.

The algorithms are described in 

C. F. F. Karney, Algorithms for geodesics, J. Geodesy 87, 43-55 (2013)
Link: https://doi.org/10.1007/s00190-012-0578-z
Addenda: https://geographiclib.sourceforge.io/geod-addenda.html

func (*Line) Arc 

func (l *Line) Arc() float64

Arc returns a13, the arc length to point 3 (degrees).

func (*Line) ArcPosition 

func (l *Line) ArcPosition(a12 float64) Data

ArcPosition computes the position of point 2 which is an arc length a12 (degrees) from point 1. The values of lon2 and azi2 returned are in the range [-180°, 180°]. 

a12: arc length from point 1 to point 2 (degrees); can be negative.

This function is equivalent to calling ArcPositionWithCapabilities with capabilities.Standard.

func (*Line) ArcPositionWithCapabilities 

func (l *Line) ArcPositionWithCapabilities(a12 float64, caps capabilities.Mask) Data

ArcPositionWithCapabilities computes the position of point 2 which is an arc length a12 (degrees) from point 1. It also allows you to specify which results should be computed and returned via the capabilities.Mask argument. Note that the Line instance must have been created with caps |= capabilities.DistanceIn; otherwise, no parameters are set.

See ArcPosition for more details.

func (*Line) Distance 

func (l *Line) Distance() float64

Distance returns s13, the distance to point 3 (meters).

func (*Line) Position 

func (l *Line) Position(s12 float64) Data

Position computes the position of point 2 which is a distance s12 (meters) from point 1. The values of lon2 and azi2 returned are in the range [-180°, 180°]. 

s12: distance from point 1 to point 2 (meters); can be negative.

This function is equivalent to calling PositionWithCapabilities with capabilities.Standard.

func (*Line) PositionWithCapabilities 

func (l *Line) PositionWithCapabilities(s12 float64, caps capabilities.Mask) Data

PositionWithCapabilities computes the position of point 2 which is a distance s12 (meters) from point 1. It also allows you to specify which results should be computed and returned via the capabilities.Mask argument. Note that the Line instance must have been created with caps |= capabilities.DistanceIn; otherwise, no parameters are set.

See Position for more details.

func (*Line) SetArc 

func (l *Line) SetArc(a13 float64)

SetArc specifies the position of point 3 on the geodesic in terms of arc length (degrees). This is only useful if the Line instance was created with capabilities.Distance.

func (*Line) SetDistance 

func (l *Line) SetDistance(s13 float64)

SetDistance specifies the position of point 3 on the geodesic in terms of distance (meters). This is only useful if the Line instance was created with capabilities.DistanceIn.

type PolygonArea 

type PolygonArea struct {
	// contains filtered or unexported fields
}

PolygonArea is a type representing geodesic polygon area and perimeter calculations on an ellipsoid. The area of a geodesic polygon is calculated using the method given in Section 6 of: 

C. F. F. Karney, Algorithms for geodesics, J. Geodesy 87, 43-55 (2013)
Link: https://doi.org/10.1007/s00190-012-0578-z
Addenda: https://geographiclib.sourceforge.io/geod-addenda.html

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.

This type lets you add vertices one at a time to the polygon. 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. There's also an option to treat the points as defining a polyline instead of a polygon; in that case, only the perimeter is computed.

func NewPolygonArea 

func NewPolygonArea(g *Geodesic, polyline bool) *PolygonArea

NewPolygonArea creates a new instance of PolygonArea with the given Geodesic. If polyline is set to true, added points will be interpreted as defining a polyline instead of a polygon.

func (*PolygonArea) AddEdge 

func (p *PolygonArea) AddEdge(azi, s float64)

AddEdge adds an edge to the polygon or polyline represented by the PolygonArea instance. 

azi: azimuth at current point (degrees).
s: distance from current point to next point (meters).

This function does nothing if no points have been added yet. Use CurrentPoint to determine the position of the newest vertex.

func (*PolygonArea) AddPoint 

func (p *PolygonArea) AddPoint(lat, lon float64)

AddPoint adds a point to the polygon or polyline represented by the PolygonArea instance. Note that lat should be in the range [-90°, 90°].

func (*PolygonArea) Clear 

func (p *PolygonArea) Clear()

Clear resets the PolygonArea instance, allowing a new polygon to be started.

func (*PolygonArea) Compute 

func (p *PolygonArea) Compute(reverse, sign bool) PolygonResult

Compute returns the results of the polygon area/perimeter calculation so far. 

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.

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

func (*PolygonArea) CurrentPoint 

func (p *PolygonArea) CurrentPoint() (float64, float64)

CurrentPoint reports the previous (lat, lon) vertex added to the polygon or polyline. If no points have been added, math.NaN is returned instead.

func (*PolygonArea) TestEdge 

func (p *PolygonArea) TestEdge(azi, s float64, reverse, sign bool) PolygonResult

TestEdge returns the polygon perimeter/area 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 AddPoint and Compute are used. 

azi: azimuth at current point (degrees).
s: distance from current point to final test point (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.

func (*PolygonArea) TestPoint 

func (p *PolygonArea) TestPoint(lat, lon float64, reverse, sign bool) PolygonResult

TestPoint returns the polygon perimeter/area 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 AddPoint and Compute are used. 

lat: the latitude of the test point (degrees). Should be in the range [-90°, 90°].
lon: the longitude of the test point (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.

type PolygonResult 

type PolygonResult struct {
	// Num is the number of vertices in the polygon or polyline
	Num int

	// Perimeter is the perimeter of the polygon or the length of the polyline (meters)
	Perimeter float64

	// Area is the area of the polygon (meters²)
	Area float64
}

PolygonResult is a container struct for results from geodesic polygon perimeter/area calculations.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.