sl.gc.dist: Great-Circle Distance

In helgegoessling/spheRlab: Spherical Geometry, Analysis, and Plotting of Geoscientific Data on Arbitrary Grids

Great-Circle Distance

Description

Compute great-circle distances between two or more points on a sphere. If coordinates for more than two points are provided, either distances between consecutive points, between the first and all other points, between specific pairs of points, or between all pairs of points are computed.

Usage

sl.gc.dist(lon = NULL, lat = NULL, x = NULL, y = NULL, z = NULL, Rsphere = 1, sequential = TRUE, distmat = FALSE, byrot = FALSE)

Arguments

lon	a vector of length N >= 2 or an Mx2 matrix or data frame with the longitudes of the points. Not required if (x,y,z) are provided.
lat	a vector of length N >= 2 or an Mx2 matrix or data frame with the latitudes of the points. Not required if (x,y,z) are provided.
x	a vector of length N >= 2 or an Mx2 matrix or data frame with the x-coordinates of the points. Not required if (lon,lat) are provided. Note that sqrt(x^2+y^2+z^2)=1 must hold, that is, (x,y,z) must be located on a unit sphere (inpedendent of Rsphere which only affects the values of the returned distances).
y	a vector of length N >= 2 or an Mx2 matrix or data frame with the y-coordinates of the points. Not required if (lon,lat) are provided. Note that sqrt(x^2+y^2+z^2)=1 must hold, that is, (x,y,z) must be located on a unit sphere (inpedendent of Rsphere which only affects the returned distance).
z	a vector of length N >= 2 or an Mx2 matrix or data frame with the z-coordinates of the points. Not required if (lon,lat) are provided. Note that sqrt(x^2+y^2+z^2)=1 must hold, that is, (x,y,z) must be located on a unit sphere (inpedendent of Rsphere which only affects the returned distance).
Rsphere	a scalar value giving the radius of the sphere. Default is a unit sphere, that is, Rsphere=1.
sequential	a logical value specifying for the case that lon,lat or x,y,z are vectors and N > 2 whether distances are computed between consecutive pairs of points (default). If sequential=FALSE, distances from the first point to all other points are computed.
distmat	a logical value specifying whether distances are computed between all pairs of points. In this case, the built-in function dist is used (followed by a conversion to great-circle distance) and an NxN matrix is returned. Default is FALSE.
byrot	a logical value specifying whether distances are computed by rotation, which can be slow. Default is FALSE, meaning that distances are computed by the equation (2*Rsphere)*asin(sqrt(sum((xyz_2 - xyz_1)^2))/2).

Details

As detailed in the function argument description above, this function can handle different types of inputs (lon,lat versus x,y,z; vectors versus 2-column matrices), use different approaches for the computation (rotation versus cartesian distance versus built-in dist function), and compute distances between different sets of points (first against all others; subsequent pairs; all pairs).

Value

Either a vector of length N-1 or M (i.e., a scalar if N=2 or M=1) with the great-circle distances between the points, or an MxM matrix with all pairwise distances.

Author(s)

Helge Goessling

See Also

sl.cart.dist

Examples

sl.gc.dist(lon=c(0,30,90,0),lat=c(0,0,0,90))
## Should return:
## [1] 0.5235988 1.0471976 1.5707963

sl.gc.dist(lon=c(0,30,90,0),lat=c(0,0,0,90),sequential=FALSE)
## Should return:
## [1] 0.5235988 1.5707963 1.5707963

sl.gc.dist(lon=data.frame(lon1=c(10,25,30),lon2=c(20,35,0)),lat=data.frame(lat1=c(0,0,10),lon2=c(20,35,50)))
## Should return:
## [1] 0.3886629 0.6322375 0.8213473

sl.gc.dist(lon=c(0,30,90,0),lat=c(0,0,0,90),distmat=TRUE)
## Should return:
##           1         2        3        4
## 1 0.0000000 0.5235988 1.570796 1.570796
## 2 0.5235988 0.0000000 1.047198 1.570796
## 3 1.5707963 1.0471976 0.000000 1.570796
## 4 1.5707963 1.5707963 1.570796 0.000000

helgegoessling/spheRlab documentation built on April 8, 2024, 8:34 a.m.