# calcGCdist: Calculate Great-Circle Distance In PBSmapping: Mapping Fisheries Data and Spatial Analysis Tools

## Description

Calculate the great-circle distance between geographic (LL) coordinates. Also calculate the initial bearing of the great-circle arc (at its starting point).

## Usage

 `1` ```calcGCdist(lon1, lat1, lon2, lat2, R=6371.2) ```

## Arguments

 `lon1` Longitude coordinate (degrees) of the start point. `lat1` Latitude coordinate(degrees) of the start point. `lon2` Longitude coordinate(degrees) of the end point. `lat2` Latitude coordinate(degrees) of the end point. `R` Mean radius (km) of the Earth.

## Details

The great-circle distance is calculated between two points along a spherical surface using the shortest distance and disregarding topography.

Method 1: Haversine Formula

a = sin^2((phi2-phi1)/2) + cos(phi1) cos(phi2) sin^2((lambda2-lambda1)/2)

c = 2 * atan2(sqrt(a), sqrt(1-a))

d = R * c

where
phi = latitude (in radians),
lambda = longitude (in radians),
R = radius (km) of the Earth,
a = square of half the chord length between the points,
c = angular distance in radians,
d = great-circle distance (km) between two points.

Method 2: Spherical Law of Cosines

d = acos(sin(phi1) sin(phi2) + cos(phi1) cos(phi2) cos(lambda2-lambda1)) * R

The initial bearing (aka forward azimuth) for the start point can be calculated using:

theta = atan2( sin(lambda2-lambda1) cos(phi2), cos(phi1) sin(phi2) - sin(phi1) cos(phi2) cos(lambda2-lambda1) )

## Value

A list obect containing:
`a` – Haversine a = square of half the chord length between the points,
`c` – Haversine c = angular distance in radians,
`d` – Haversine d = great-circle distance (km) between two points,
`d2` – Law of Cosines d = great-circle distance (km) between two points,
`theta` – Initial bearing theta (degrees) for the start point.

## Note

If one uses the north geomagnetic pole as an end point, theta crudely approximates the magnetic declination.

## Author(s)

Rowan Haigh, Program Head – Offshore Rockfish
Pacific Biological Station (PBS), Fisheries & Oceans Canada (DFO), Nanaimo BC
opus locus: Institute of Ocean Sciences (IOS), Sidney BC
Last modified `Rd: 2017-06-22`

## See Also

`addCompass`, `calcArea`, `calcCentroid`, `calcLength`

## Examples

 ```1 2 3 4``` ```local(envir=.PBSmapEnv,expr={ #-- Distance between southern BC waters and north geomagnetic pole print(calcGCdist(-126.5,48.6,-72.7,80.4)) }) ```

PBSmapping documentation built on Jan. 15, 2021, 3:41 p.m.