Data.Geo.Jord.Geodetics

Geodetic calculations assuming a spherical earth model.

All functions are implemented using the vector-based approached described in Gade, K. (2010). A Non-singular Horizontal Position Representation

The GreatCircle type

data GreatCircle

A circle on the surface of the Earth which lies in a plane passing through the Earth's centre. Every two distinct and non-antipodal points on the surface of the Earth define a Great Circle.

It is internally represented as its normal vector - i.e. the normal vector to the plane containing the great circle.

See greatCircle, greatCircleE, greatCircleF or greatCircleBearing constructors.

Instances

Eq GreatCircle

Defined in Data.Geo.Jord.Geodetics

Methods

(==) :: GreatCircle -> GreatCircle -> Bool

(/=) :: GreatCircle -> GreatCircle -> Bool

Show GreatCircle

Defined in Data.Geo.Jord.Geodetics

Methods

showsPrec :: Int -> GreatCircle -> ShowS

show :: GreatCircle -> String

showList :: [GreatCircle] -> ShowS

class Show a => IsGreatCircle a where

 Class for data from which a GreatCircle can be computed.

Minimal complete definition

greatCircleE

Methods

greatCircle

Arguments

:: a

-> GreatCircle

GreatCircle from a, if greateCircleE returns a Left, this function errors.

greatCircleE

Arguments

:: a

-> Either String GreatCircle

GreatCircle from a, A Left indicates an error.

greatCircleF

Arguments

:: MonadFail m

=> a

-> m GreatCircle

GreatCircle from a, if greateCircleE returns a Left, this function fails.

Instances

(NTransform a, Show a) => IsGreatCircle (Track a)

GreatCircle from track.

Defined in Data.Geo.Jord.Kinematics

Methods

greatCircle :: Track a -> GreatCircle

greatCircleE :: Track a -> Either String GreatCircle

greatCircleF :: MonadFail m => Track a -> m GreatCircle

(NTransform a, Show a) => IsGreatCircle (a, Angle)

GreatCircle passing by the given position and heading on given bearing.

    greatCircle (readLatLong "283321N0290700W", decimalDegrees 33.0)

Defined in Data.Geo.Jord.Geodetics

Methods

greatCircle :: (a, Angle) -> GreatCircle

greatCircleE :: (a, Angle) -> Either String GreatCircle

greatCircleF :: MonadFail m => (a, Angle) -> m GreatCircle

(NTransform a, Show a) => IsGreatCircle (a, a)

GreatCircle passing by both given positions'. A Left indicates that given positions are equal or antipodal.

    let p1 = decimalLatLongHeight 45.0 (-143.5) (metres 1500)
    let p2 = decimalLatLongHeight 46.0 14.5 (metres 3000)
    greatCircle (p1, p2) -- heights are ignored, great circle are always at earth surface.

Defined in Data.Geo.Jord.Geodetics

Methods

greatCircle :: (a, a) -> GreatCircle

greatCircleE :: (a, a) -> Either String GreatCircle

greatCircleF :: MonadFail m => (a, a) -> m GreatCircle

Calculations

angularDistance :: NTransform a => a -> a -> Maybe a -> Angle

angularDistance p1 p2 n computes the angle between the horizontal positions p1 and p2. If n is Nothing, the angle is always in [0..180], otherwise it is in [-180, +180], signed + if p1 is clockwise looking along n, - in opposite direction.

antipode :: NTransform a => a -> a

antipode p computes the antipodal horizontal position of p: the horizontal position on the surface of the Earth which is diametrically opposite to p.

crossTrackDistance :: NTransform a => a -> GreatCircle -> Length -> Length

crossTrackDistance p gc computes the signed distance from horizontal position p to great circle gc. Returns a negative Length if position if left of great circle, positive Length if position if right of great circle; the orientation of the great circle is therefore important:

    let gc1 = greatCircle (decimalLatLong 51 0) (decimalLatLong 52 1)
    let gc2 = greatCircle (decimalLatLong 52 1) (decimalLatLong 51 0)
    crossTrackDistance p gc1 = (- crossTrackDistance p gc2)

    let p = decimalLatLong 53.2611 (-0.7972)
    let gc = greatCircleBearing (decimalLatLong 53.3206 (-1.7297)) (decimalDegrees 96.0)
    crossTrackDistance p gc r84 -- -305.663 metres

crossTrackDistance84 :: NTransform a => a -> GreatCircle -> Length

crossTrackDistance using the mean radius of the WGS84 reference ellipsoid.

destination :: NTransform a => a -> Angle -> Length -> Length -> a

destination p b d r computes the destination position from position p having travelled the distance d on the initial bearing (compass angle) b (bearing will normally vary before destination is reached) and using the earth radius r.

    let p0 = ecefToNVector (ecefMetres 3812864.094 (-115142.863) 5121515.161) s84
    let p1 = ecefMetres 3826406.4710518294 8900.536398998282 5112694.233184049
    let p = destination p0 (decimalDegrees 96.0217) (metres 124800) r84
    nvectorToEcef p s84 = p1

destination84 :: NTransform a => a -> Angle -> Length -> a

destination using the mean radius of the WGS84 reference ellipsoid.

finalBearing :: (Eq a, NTransform a) => a -> a -> Maybe Angle

finalBearing p1 p2 computes the final bearing arriving at p2 from p1 in compass angle.

Compass angles are clockwise angles from true north: 0 = north, 90 = east, 180 = south, 270 = west.

The final bearing will differ from the initialBearing by varying degrees according to distance and latitude.

Returns Nothing if both horizontal positions are equals.

initialBearing :: (Eq a, NTransform a) => a -> a -> Maybe Angle

initialBearing p1 p2 computes the initial bearing from p1 to p2 in compass angle.

Compass angles are clockwise angles from true north: 0 = north, 90 = east, 180 = south, 270 = west.

Returns Nothing if both horizontal positions are equals.

interpolate :: NTransform a => a -> a -> Double -> a

interpolate p0 p1 f# computes the horizontal position at fraction f between the p0 and p1@.

Special conditions:

    interpolate p0 p1 0.0 = p0
    interpolate p0 p1 1.0 = p1

errors if f || f 1

    let p1 = latLongHeight (readLatLong "53°28'46''N 2°14'43''W") (metres 10000)
    let p2 = latLongHeight (readLatLong "55°36'21''N 13°02'09''E") (metres 20000)
    interpolate p1 p2 0.5 = decimalLatLongHeight 54.7835574 5.1949856 (metres 15000)

intersections :: NTransform a => GreatCircle -> GreatCircle -> Maybe (a, a)

Computes the intersections between the two given GreatCircles. Two GreatCircles intersect exactly twice unless there are equal (regardless of orientation), in which case Nothing is returned.

    let gc1 = greatCircleBearing (decimalLatLong 51.885 0.235) (decimalDegrees 108.63)
    let gc2 = greatCircleBearing (decimalLatLong 49.008 2.549) (decimalDegrees 32.72)
    let (i1, i2) = fromJust (intersections gc1 gc2)
    i1 = decimalLatLong 50.9017226 4.4942782
    i2 = antipode i1

insideSurface :: (Eq a, NTransform a) => a -> [a] -> Bool

insideSurface p ps determines whether the p is inside the polygon defined by the list of positions ps. The polygon is closed if needed (i.e. if head ps /= last ps).

Uses the angle summation test: on a sphere, due to spherical excess, enclosed point angles will sum to less than 360°, and exterior point angles will be small but non-zero.

Always returns False if ps does not at least defines a triangle.

    let malmo = decimalLatLong 55.6050 13.0038
    let ystad = decimalLatLong 55.4295 13.82
    let lund = decimalLatLong 55.7047 13.1910
    let helsingborg = decimalLatLong 56.0465 12.6945
    let kristianstad = decimalLatLong 56.0294 14.1567
    let polygon = [malmo, ystad, kristianstad, helsingborg, lund]
    let hoor = decimalLatLong 55.9295 13.5297
    let hassleholm = decimalLatLong 56.1589 13.7668
    insideSurface hoor polygon = True
    insideSurface hassleholm polygon = False

mean :: NTransform a => [a] -> Maybe a

mean ps computes the mean geographic horitzontal position of ps, if it is defined.

The geographic mean is not defined for antipodals position (since they cancel each other).

Special conditions:

    mean [] = Nothing
    mean [p] = Just p
    mean [p1, p2, p3] = Just circumcentre
    mean [p1, .., antipode p1] = Nothing

surfaceDistance :: NTransform a => a -> a -> Length -> Length

surfaceDistance p1 p2 computes the surface distance (length of geodesic) between the positions p1 and p2.

surfaceDistance84 :: NTransform a => a -> a -> Length

surfaceDistance using the mean radius of the WGS84 reference ellipsoid.