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


-- | Database agnostic, spatially indexed type for geographic points.
--   
--   Defines type for storing geographic coordinates that can be spatially
--   indexed by any database which supports Word64. This inxeding is
--   implemented using a normal integer index on points repersented using a
--   Morton Z-Order curve. Geographic regions are transformed into a
--   covering set of tiles (contigious ranges) which can be used in a
--   single query.
@package persistent-spatial
@version 0.1.0.0


-- | Morton reperesentation of integer pairs (interleaved bits) used for
--   creating spatial indexes.
--   
--   Bit interleaving code is originally from the documentation of
--   Data.Sparse by Edward Kmett at
--   <a>https://www.schoolofhaskell.com/user/edwardk/revisiting-matrix-multiplication/part-1</a>
module Data.Morton

-- | Type implementing a Morton Z-Order Curve. Stores two <a>Word32</a>
--   values with bits interleaved. This allows for spatial indexing by
--   rectangular tiles which form contiguous intervals.
newtype Morton
Morton :: Word64 -> Morton

-- | Construct a Morton value from its two coordinates.
pattern MortonPair :: Word32 -> Word32 -> Morton

-- | Type for closed intervals. The second field should be greater than the
--   first.
data Interval a
Interval :: a -> a -> Interval a

-- | Returns intersection of two intervals, or Nothing if they do not
--   overlap.
intersectInterval :: Ord a => Interval a -> Interval a -> Maybe (Interval a)

-- | Tests whether an element is contained within a given Interval.
intervalElem :: Ord a => a -> Interval a -> Bool

-- | Returns the size of an integer interval.
intervalSize :: Integral a => Interval a -> Integer

-- | Returns the size of a Morton interval.
intervalSizeMorton :: Interval Morton -> Integer

-- | Type for retangles in Morton space reperesented by upper-left and
--   lower-right corners
data MortonRect
MortonRect :: {-# UNPACK #-} !Morton -> {-# UNPACK #-} !Morton -> MortonRect

-- | Construct/match rectangles by their sides.
pattern MortonRectSides :: Interval Word32 -> Interval Word32 -> MortonRect

-- | Returns x,y bounds of a rectangle
mortonRectBounds :: MortonRect -> (Interval Word32, Interval Word32)

-- | Rerurns intersection of two rectangles.
intersectMortonRect :: MortonRect -> MortonRect -> Maybe MortonRect

-- | Returns the area of a rectangle
mortonRectSize :: MortonRect -> Integer

-- | Type for a tile in Morton space, a special type of rectangle which is
--   the set of all points sharing a common binary prefex. Reperesented as
--   a point and mask length simillarly to a CIDR subnet.
data MortonTile
MortonTile :: {-# UNPACK #-} !Morton -> {-# UNPACK #-} !Int -> MortonTile

-- | Returns a tile as an <a>Interval</a>.
mortonTileBounds :: MortonTile -> Interval Morton

-- | Returns a tile as a <a>MortonRect</a>.
mortonTileRect :: MortonTile -> MortonRect

-- | Finds the smallest tile completely enclosing a rectangle. This can be
--   arbitrarily large if the rectangle crosses a seam.
enclosingMortonTile :: MortonRect -> MortonTile

-- | Splits a <a>MortonTile</a> in half. Does not split tiles containing a
--   single value.
splitMortonTile :: MortonTile -> [MortonTile]

-- | Trims a <tt>MortonTile</tt> to its subtile overlapping a given
--   rectangle. Returns <a>Nothing</a> if the rectabgle and tile do not
--   intersect.
trimMortonTile :: MortonRect -> MortonTile -> Maybe MortonTile

-- | Covers a rectangle using tiles within a range of sizes (specified by
--   their mask values).
mortonTileCoverSized :: Int -> Maybe Int -> MortonRect -> [MortonTile]

-- | Covers a rectangle with tiles no larger then the area to be covered
--   (no lower size limit). The total area coverd by these tiles bas a
--   trivial upper bound of 8 tiles the rectangle's area plus the area of
--   its enclosing square and the actual performance is usually
--   significantly better (possibly always, although I have not proven so).
mortonTileCover :: MortonRect -> [MortonTile]

-- | Version of <a>mortonTileCover</a> which allows the rectangle to wrap
--   around the maximum x/y coordinates (as if the space were a torus).
mortonTileCoverTorus :: Morton -> Morton -> [MortonTile]
instance GHC.Read.Read Data.Morton.MortonRect
instance GHC.Show.Show Data.Morton.MortonRect
instance GHC.Classes.Eq Data.Morton.MortonRect
instance GHC.Base.Functor Data.Morton.Interval
instance GHC.Read.Read a => GHC.Read.Read (Data.Morton.Interval a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Morton.Interval a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Morton.Interval a)
instance GHC.Enum.Enum Data.Morton.Morton
instance GHC.Classes.Ord Data.Morton.Morton
instance GHC.Classes.Eq Data.Morton.Morton
instance GHC.Show.Show Data.Morton.MortonTile
instance GHC.Read.Read Data.Morton.MortonTile
instance GHC.Classes.Eq Data.Morton.MortonTile
instance GHC.Classes.Ord Data.Morton.MortonTile
instance GHC.Show.Show Data.Morton.Morton
instance GHC.Read.Read Data.Morton.Morton


-- | Defines a type for georgraphic coordinates that can be spatially
--   indexed by any database supporting 64 bit integer values. This
--   indexing works by reperesenting points using a <a>Morton</a> Z-Order
--   curce, with each coordinate reperesented as a 32-bit fixed-point value
--   which then have their bits interleaved into a 64-bit integer to the
--   internal reperesentation.
--   
--   Taking binary prefixes of these values divides the globe into a
--   hierarchy of rectangular tiles (repereseteh here as <a>LatLongTile</a>
--   objects), each of which is a contiguous interval when points are
--   ordered according to their integer reperesentations. As any geographic
--   region can be covered by a small number of tiles of simillar size,
--   this provides an easy to loop up data for specific reguions. Instances
--   and a filter for persistent are provided for this purpose.
module Data.LatLong

-- | Type for storing geographic coordinates that can be spatially indexed
--   (<a>Morton</a> ordering). Each coordinate is reperesented as as 32-bit
--   fixed point value and is also accessible as a Double through a pattern
--   synonym. Order follows a Morton Z-order curve which can be used to
--   search a database by tiles. This works with any database capable of
--   storing and indexing <a>Word64</a> (although this type only uses those
--   values fitting in a 64 bit signed integer)
newtype LatLong

-- | Underlying reperesentation and source of ordering for indexing
LatLongZ :: Morton -> LatLong

-- | Pattern for accessing latitide and longitude coordinates as
--   <a>Double</a> values. This is not fully isomoprphic as latitude is
--   clipped to ±90, longitude is wrapped mod 360 ±180, and rounding error
--   exists due to the internal fixed-point reperesentation.
pattern LatLong :: Double -> Double -> LatLong

-- | Lens for latitude.
lat :: Lens' LatLong Double

-- | Lens for longitude.
long :: Lens' LatLong Double

-- | Earth's average radius in meters
earthRadius :: Double

-- | Calculate distance between two points using the Haversine formula (up
--   to 0.5% due to the assumption of a spherical Earth). Distance is
--   returned in meters.
geoDistance :: LatLong -> LatLong -> Double

-- | Calculates the corner coordinates of a square with a given center and
--   radius (in meters). Based on the Mercator projection thus has
--   distortion near the poles (within 5% for a radius at most 200km and
--   latitude within ±70).
geoSquare :: LatLong -> Double -> (LatLong, LatLong)

-- | Represents a LatLong tile, which is both a rectangle and a contoguous
--   interval in the ordering.
data LatLongTile

-- | Gets the corners of a tile, which are also the bounds of its interval
--   in sort order.
latLongTileInterval :: LatLongTile -> Interval LatLong

-- | Covers a rectangle (defined by its corners) tiles of at most its size.
latLongTileCover :: LatLong -> LatLong -> [LatLongTile]

-- | Covers a square (defined by its center and radius) by tiles.
latLongTileCoverSquare :: LatLong -> Double -> [LatLongTile]

-- | Tests whether a point is contasined in a tile set.
tileSetElem :: LatLong -> [LatLongTile] -> Bool

-- | Persistent filter producing the SQL equiveland ot <a>tileSetElem</a>.
withinTileSet :: EntityField row LatLong -> [LatLongTile] -> Filter row
instance GHC.Show.Show Data.LatLong.LatLongTile
instance GHC.Read.Read Data.LatLong.LatLongTile
instance GHC.Classes.Eq Data.LatLong.LatLongTile
instance GHC.Classes.Ord Data.LatLong.LatLong
instance GHC.Classes.Eq Data.LatLong.LatLong
instance Data.Aeson.Types.ToJSON.ToJSON Data.LatLong.LatLong
instance Data.Aeson.Types.FromJSON.FromJSON Data.LatLong.LatLong
instance Web.Internal.HttpApiData.FromHttpApiData Data.LatLong.LatLong
instance Web.Internal.HttpApiData.ToHttpApiData Data.LatLong.LatLong
instance GHC.Show.Show Data.LatLong.LatLong
instance Database.Persist.Class.PersistField.PersistField Data.LatLong.LatLong
instance Database.Persist.Sql.Class.PersistFieldSql Data.LatLong.LatLong