-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | For manipulating GPS coordinates and trails.
--   
--   Useful for manipulating GPS coordinages (in various forms), building
--   paths, and performing basic computations
@package gps
@version 0.3.0


-- | Author: Thomas DuBuisson Copyright: Thomas DuBuisson License: BSD3
--   
--   A basic GPS library with calculations for distance and speed along
--   with helper functions for filtering/smoothing trails. All distances
--   are in meters and time is in seconds. Speed is thus meters/second
--   
--   The current intent of this library is to 1) Provide a standard type
--   class interface for coordinates 2) Include fleshed out support for
--   relevant libraries, a task too often neglected in modern Hackage
--   packages.
--   
--   Integration includes KML support via the xml package, pretty printing,
--   anb binary.
module Data.GPS

-- | A coordinate is a place on earths surface. While twoDMS and fromDMS
--   are the only required functions, coordinate systems may provide more
--   accurate calculations of heading, distance, and vectors without the
--   intermediate translation.
class Coordinate a
toDMS :: (Coordinate a) => a -> DMSCoordinate
fromDMS :: (Coordinate a) => DMSCoordinate -> a
distance :: (Coordinate a) => a -> a -> Distance
heading :: (Coordinate a) => a -> a -> Heading
getVector :: (Coordinate a) => a -> a -> Vector

-- | A location is a coordinate at a specific time
class (Coordinate coord) => Location loc coord time | loc -> coord, loc -> time
getCoordinate :: (Location loc coord time) => loc -> coord
getTime :: (Location loc coord time) => loc -> time
getUTC :: (Location loc coord time) => loc -> UTCTime
speed :: (Location loc coord time) => loc -> loc -> Speed

-- | DMSCoordinate is the typical degree minute second for
--   latitude/longitude used by most civilian GPS devices.
data DMSCoordinate
DMSCoord :: DMS Latitude -> DMS Longitude -> DMSCoordinate
latitude :: DMSCoordinate -> DMS Latitude
longitude :: DMSCoordinate -> DMS Longitude

-- | DMS is the degrees, minutes, seconds used for both latitude and
--   longitude
data DMS a
DMS :: Double -> Double -> Double -> DMS a
degrees :: DMS a -> Double
minutes :: DMS a -> Double
seconds :: DMS a -> Double

-- | Empty declaration for phantom type
data Latitude

-- | Empty declaration for phantom type
data Longitude

-- | Angles are expressed in radians from North. 0 == North pi/2 == West pi
--   == South (3<i>2)pi == East == - (pi </i> 2)
type Heading = Double

-- | Speed is hard coded as meters per second
type Speed = Double
type Vector = (Distance, Heading)
type Trail a = [a]
north :: Integer
south :: Double
east :: Double
west :: Double

-- | radius of the earth in meters
radiusOfEarth :: Double

-- | 'smoothTrails speed trail' should separate points that would mandate a
--   speed in excess of the given rate into separate Trails. No point are
--   deleted; if there is only one <tt>correct</tt> trail expected then the
--   largest resulting trail will likely be the one your looking for.
smoothTrails :: (Location a b c) => Speed -> Trail a -> [Trail a]

-- | longestSmoothTrail is ust <a>smoothTrails</a> returning only the
--   longest smooth trail.
longestSmoothTrail :: (Location a b c) => Speed -> Trail a -> Trail a
restLocations :: (Location a b c) => Distance -> NominalDiffTime -> Trail a -> [Trail a]

-- | Returns the closest distance between two trails (or Nothing if a trail
--   is empty) O( (n * m) * log (n * m) )
closestDistance :: (Coordinate a) => Trail a -> Trail a -> Maybe Distance

-- | Typically useful for printing, normalizes degrees<i>minutes</i>seconds
--   into just degrees and decimal minutes: DMSCoord (DMS 45 36.938455 0)
--   (DMS ...)
normalizeDMS :: DMSCoordinate -> DMSCoordinate

-- | Provides a lat/lon pair of doubles in degrees
dmsToDegreePair :: DMSCoordinate -> (Double, Double)

-- | Provides a lat/lon pair of doubles in radians
dmsToRadianPair :: DMSCoordinate -> (Double, Double)
degreePairToDMS :: (Double, Double) -> DMSCoordinate

-- | Given a vector and coordinate, computes a new DMS coordinate. within
--   some epsilon it should hold that if dest = addVector (dist,heading)
--   start then heading == dmsHeading start dest dist == distance start
--   dest
addVector :: Vector -> DMSCoordinate -> DMSCoordinate
instance Eq (DMS a)
instance Ord (DMS a)
instance Show (DMS a)
instance Read (DMS a)
instance Eq DMSCoordinate
instance Ord DMSCoordinate
instance Show DMSCoordinate
instance Read DMSCoordinate
instance Binary UTCTime
instance Binary DMSCoordinate
instance Pretty DMSCoordinate
instance (Coordinate c) => Coordinate (c, UTCTime)
instance (Coordinate c) => Location (c, UTCTime) c UTCTime
instance Coordinate DMSCoordinate


-- | Author: Thomas DuBuisson Copyright: Thomas DuBuisson License: BSD3
module Data.GPS.KML

-- | The KML type and operations might be moved into a Data.KML module in
--   the future
type KML = Element

-- | converts a given set of coordinates to a trail in KML format. Useful
--   for saving as a file.
trailToKML :: (Coordinate a) => String -> Trail a -> KML

-- | converts a given set of coordinates to points in KML format. Useful
--   for saving as a file.
pointsToKML :: (Coordinate a) => String -> [a] -> [String] -> KML

-- | Converts the KML elements to a string and prepends the proper XML
--   header, thus making it the correct format for saving as a file and
--   opening it with other programs such as GoogleEarth.
kmlToString :: KML -> String