Data.Geo.Jord.GreatCircle

Types and functions for working with Great Circle.

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

This module assumes a spherical earth.

TODO:

• alongTrackDistance :: Position -> GreatArc -> Length
• intersection :: GreatArc -> GreatArc -> Maybe Position
• nearestPoint :: Position -> GreatArc -> Position
• area :: [Position] -> Surface
• closestApproach

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

Methods

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

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

Show GreatCircle

Methods

showsPrec :: Int -> GreatCircle -> ShowS

show :: GreatCircle -> String

showList :: [GreatCircle] -> ShowS

The Position type

class Position a where

The Position class defines 2 functions to convert a position to and from a NVector. All functions in this module first convert Position to NVector and any resulting NVector back to a Position. This allows the call site to pass either NVector or GeoPos and to get back the same class instance.

Minimal complete definition

fromNVector, toNVector

Methods

fromNVector :: NVector -> a

Converts a NVector into Position instance.

toNVector :: a -> NVector

Converts the Position instance into a NVector.

Instances

Position NVector

Identity.

Methods

fromNVector :: NVector -> NVector

toNVector :: NVector -> NVector

Position GeoPos

GeoPos to/from NVector.

Methods

fromNVector :: NVector -> GeoPos

toNVector :: GeoPos -> NVector

Smart constructors

greatCircle :: (Eq a, Position a, Show a) => a -> a -> GreatCircle

GreateCircle passing by both given Positions. errors if given positions are equal or antipodal.

greatCircleE :: (Eq a, Position a) => a -> a -> Either String GreatCircle

GreateCircle passing by both given Positions. A Left indicates that given positions are equal or antipodal.

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

GreateCircle passing by both given Positions. fails if given positions are equal or antipodal.

greatCircleBearing :: Position a => a -> Angle -> GreatCircle

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

Geodesic calculations

antipode :: Position a => a -> a

Returns the antipodal Position of the given Position - i.e. the position on the surface of the Earth which is diametrically opposite to the given position.

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

crossTrackDistance' assuming a radius of meanEarthRadius.

crossTrackDistance' :: Position a => a -> GreatCircle -> Length -> Length

Signed distance from given Position to given GreatCircle. 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 (latLongDecimal 51 0) (latLongDecimal 52 1)
    let gc2 = greatCircle (latLongDecimal 52 1) (latLongDecimal 51 0)
    crossTrackDistance p gc1 == (- crossTrackDistance p gc2)

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

destination' assuming a radius of meanEarthRadius.

destination' :: Position a => a -> Angle -> Length -> Length -> a

Computes the destination Position from the given Position having travelled the given distance on the given initial bearing (bearing will normally vary before destination is reached) and using the given earth radius.

This is known as the direct geodetic problem.

distance :: Position a => a -> a -> Length

distance' assuming a radius of meanEarthRadius.

distance' :: Position a => a -> a -> Length -> Length

Computes the surface distance (length of geodesic) in Meters assuming a spherical Earth between the two given Positions and using the given earth radius.

finalBearing :: Position a => a -> a -> Angle

Computes the final bearing arriving at given destination p2 Position from given Position p1. the final bearing will differ from the initialBearing by varying degrees according to distance and latitude. Returns 180 if both position are equals.

initialBearing :: Position a => a -> a -> Angle

Computes the initial bearing from given p1 Position to given p2 Position, in compass degrees. Returns 0 if both position are equals.

interpolate :: Position a => a -> a -> Double -> a

Computes the Position at given fraction f between the two given Positions p0 and p1.

Special conditions:

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

errors if f || f 1.0

intersections :: Position 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.

isInside :: (Eq a, Position a) => a -> [a] -> Bool

Determines whether the given Position is inside the polygon defined by the given list of Positions. 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 positions does not at least defines a triangle.

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

Computes the geographic mean Position of the given Positions if it is defined.

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

Special conditions:

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

Misc.

meanEarthRadius :: Length

a, b,c => a b, a, c, b, c | Mean Earth radius: 6,371,008.8 metres.

northPole :: Position a => a

Position of the North Pole.

southPole :: Position a => a

Position of the South Pole.