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


-- | For manipulating GPS coordinates and trails.
--   
@package gps
@version 1.2

module Geo.Types
data Track
Track :: Maybe Text -> Maybe Text -> [Segment] -> Track
trkName :: Track -> Maybe Text
trkDescription :: Track -> Maybe Text
segments :: Track -> [Segment]

-- | A GPX segments is just a bundle of points.
data Segment
Segment :: [Point] -> Segment
points :: Segment -> [Point]
type Latitude = Double
type Longitude = Double

-- | Track point is a full-fledged representation of all the data available
--   in most GPS loggers. It is possible you don't want all this data and
--   can just made do with coordinates (via <tt>Pnt</tt>) or a custom
--   derivative.
data Point
Point :: Latitude -> Longitude -> Maybe Double -> Maybe UTCTime -> Point
pntLat :: Point -> Latitude
pntLon :: Point -> Longitude

-- | In meters
pntEle :: Point -> Maybe Double
pntTime :: Point -> Maybe UTCTime
pt :: Latitude -> Longitude -> Maybe Double -> Maybe UTCTime -> Point
zeroPoint :: Point
instance Eq Point
instance Ord Point
instance Show Point
instance Read Point
instance Eq Segment
instance Ord Segment
instance Show Segment
instance Read Segment
instance Eq Track
instance Ord Track
instance Show Track
instance Read Track


-- | 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
module Geo.Computations

-- | Distances are expressed in meters
type Distance = Double

-- | 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]

-- | Genearlly a circle indicates a known area in which we are searching
--   (so a center point and maximum possible distance from that point)
type Circle a = (a, Distance)

-- | An arc is represented as a circle, starting heading and ending heading
type Arc a = (Circle a, Heading, Heading)

-- | Track point is a full-fledged representation of all the data available
--   in most GPS loggers. It is possible you don't want all this data and
--   can just made do with coordinates (via <tt>Pnt</tt>) or a custom
--   derivative.
data Point
Point :: Latitude -> Longitude -> Maybe Double -> Maybe UTCTime -> Point
pntLat :: Point -> Latitude
pntLon :: Point -> Longitude

-- | In meters
pntEle :: Point -> Maybe Double
pntTime :: Point -> Maybe UTCTime
pt :: Latitude -> Longitude -> Maybe Double -> Maybe UTCTime -> Point

-- | North is 0 radians
north :: Heading

-- | South, being 180 degrees from North, is pi.
south :: Heading

-- | East is 270 degrees (3 pi / 2)
east :: Heading

-- | West is 90 degrees (pi/2)
west :: Heading

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

-- | Circumference of earth (meters)
circumferenceOfEarth :: Double

-- | Direction two points aim toward (0 = North, pi<i>2 = West, pi = South,
--   3pi</i>2 = East)
heading :: Point -> Point -> Heading
distance :: Point -> Point -> Distance

-- | Speed in meters per second, only if a <tt>Time</tt> was recorded for
--   each waypoint.
speed :: Point -> Point -> Maybe Speed
getVector :: Point -> Point -> Vector

-- | Given a vector and coordinate, computes a new coordinate. Within some
--   epsilon it should hold that if
--   
--   <pre>
--   dest = addVector (dist,heading) start
--   </pre>
--   
--   then
--   
--   <pre>
--   heading == heading start dest
--   </pre>
--   
--   <pre>
--   dist    == distance start dest
--   </pre>
addVector :: Vector -> Point -> Point

-- | <tt>interpolate c1 c2 w</tt> where <tt>0 &lt;= w &lt;= 1</tt> Gives a
--   point on the line between c1 and c2 equal to c1 when <tt>w == 0</tt>
--   (weighted linearly toward c2).
interpolate :: Point -> Point -> Double -> Point

-- | Compute the points at which two circles intersect (assumes a flat
--   plain). If the circles do not intersect or are identical then the
--   result is <tt>Nothing</tt>.
circleIntersectionPoints :: (Point, Distance) -> (Point, Distance) -> Maybe (Point, Point)

-- | Find the area in which all given circles intersect. The resulting area
--   is described in terms of the bounding arcs. All cirlces must intersect
--   at two points.
intersectionArcsOf :: [Circle Point] -> [Arc Point]
maximumDistanceOfArc :: Point -> Arc Point -> Distance
data AvgMethod c

-- | Obtain the <a>mean</a> of the considered points
AvgMean :: AvgMethod c

-- | Obtain the <a>harmonicMean</a>
AvgHarmonicMean :: AvgMethod c

-- | Obtain the <a>geometricMean</a>
AvgGeometricMean :: AvgMethod c

-- | Obtain the median of the considered points
AvgMedian :: AvgMethod c

-- | Compute the speed considering only the given endpoints
AvgEndPoints :: AvgMethod c

-- | Take the minimum of the speeds from the given methods
AvgMinOf :: [AvgMethod c] -> AvgMethod c
AvgWith :: ([c] -> Speed) -> AvgMethod c

-- | When grouping points, lists of points are either marked as
--   <a>Select</a> or <a>NotSelect</a>.
data Selected a
Select :: a -> Selected a
unSelect :: Selected a -> a
NotSelect :: a -> Selected a
unSelect :: Selected a -> a

-- | A PointGrouping is a function that selects segments of a trail.
--   
--   Grouping point _does not_ result in deleted points. It is always true
--   that:
--   
--   forall g :: PointGrouping c --&gt; concatMap unSelect (g ts) == ts
--   
--   The purpose of grouping is usually for later processing. Any desire to
--   drop points that didn't meet a particular grouping criteria can be
--   filled with a composition with <a>filter</a> (or directly via
--   <a>filterPoints</a>).
type PointGrouping c = Trail c -> [Selected (Trail c)]

-- | Given a selection of coordinates, transform the selected coordinates
--   in some way (while leaving the non-selected coordinates unaffected).
type TransformGrouping c = [Selected (Trail c)] -> [Selected (Trail c)]
isSelected :: Selected a -> Bool
isNotSelected :: Selected a -> Bool
onSelected :: (a -> b) -> (a -> b) -> Selected a -> b
selLength :: Selected [a] -> Int

-- | Find the total distance traveled
totalDistance :: [Point] -> Distance
totalTime :: Trail Point -> NominalDiffTime

-- | <tt>avgSpeeds n points</tt> Average speed using a window of up to
--   <tt>n</tt> seconds and averaging by taking the Median
--   (<a>AvgMedian</a>).
avgSpeeds :: NominalDiffTime -> Trail Point -> [(UTCTime, Speed)]

-- | <tt>slidingAverageSpeed m n</tt> Average speed using a moving window
--   of up to <tt>n</tt> seconds and an <a>AvgMethod</a> of <tt>m</tt>.
slidingAverageSpeed :: AvgMethod Point -> NominalDiffTime -> Trail Point -> [(UTCTime, Speed)]

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

-- | Uses Grahams scan to compute the convex hull of the given points. This
--   operation requires sorting of the points, so don't try it unless you
--   have notably more memory than the list of points will consume.
convexHull :: [Point] -> [Point]

-- | Construct a bezier curve using the provided trail. Construct a new
--   trail by sampling the given bezier curve at the given times. The
--   current implementation assumes the times of the input coordinates are
--   available and all equal (Ex: all points are 5 seconds apart), the
--   results will be poor if this is not the case!
bezierCurveAt :: [UTCTime] -> Trail Point -> Trail Point

-- | Interpolate selected points onto a bezier curve. Note this gets
--   exponentially more expensive with the length of the segement being
--   transformed - it is not advisable to perform this operation on trail
--   segements with more than ten points!
bezierCurve :: [Selected (Trail Point)] -> Trail Point

-- | Filters out any points that go backward in time (thus must not be
--   valid if this is a trail)
linearTime :: [Point] -> [Point]

-- | Remove all points that remain <a>NotSelect</a>ed by the given grouping
--   algorithm.
filterPoints :: PointGrouping a -> Trail a -> Trail a

-- | Groups trail segments into contiguous points within the speed and all
--   others outside of the speed. The "speed" from point p(i) to p(i+1) is
--   associated with p(i) (execpt for the first speed value, which is
--   associated with both the first and second point)
betweenSpeeds :: Double -> Double -> PointGrouping Point

-- | A "rest point" means the coordinates remain within a given distance
--   for at least a particular amount of time.
restLocations :: Distance -> NominalDiffTime -> PointGrouping Point

-- | chunking points into groups spanning at most the given time interval.
spansTime :: NominalDiffTime -> PointGrouping Point

-- | chunk the trail into groups of N points
everyNPoints :: Int -> PointGrouping a

-- | intersects the given groupings
intersectionOf :: [PointGrouping Point] -> PointGrouping Point

-- | Inverts the selected/nonselected segments
invertSelection :: TransformGrouping a

-- | <tt>firstGrouping f ps</tt> only the first segment remains
--   <a>Select</a>ed, and only if it was already selected by <tt>f</tt>.
firstGrouping :: TransformGrouping a

-- | Only the last segment, if any, is selected (note: the current
--   implementation is inefficient, using <a>reverse</a>)
lastGrouping :: TransformGrouping a

-- | Union all the groupings
unionOf :: [PointGrouping Point] -> PointGrouping Point

-- | For every selected group, refine the selection using the second
--   grouping method. This differs from <tt>IntersectionOf</tt> by
--   restarting the second grouping algorithm at the beginning each group
--   selected by the first algorithm.
refineGrouping :: PointGrouping a -> TransformGrouping a

-- | Intersection binary operator
(/\) :: [Selected (Trail a)] -> TransformGrouping a

-- | Union binary operator
(\/) :: [Selected (Trail a)] -> TransformGrouping a

-- | Smooth points with rest areas using a bezierCurve.
--   
--   Parameters: rest for 1 minute within 30 meters get smoothed in a
--   bezier curve over every 8 points.
smoothRests :: Trail Point -> Trail Point

-- | Smooth every 7 points using a bezier curve
smoothTrail :: Trail Point -> Trail Point
bezierPoint :: [Point] -> Double -> Point