Naqsha.Geometry

The geometric types and values exposed by naqsha.

Basics

A point on the globe is specified by giving its geo coordinates represented by the type Geo. It is essentially a pair of the Latitude and Longitude of the point.

Examples

kanpurLatitude  :: Latitude
kanpurLatitude  = lat $ degree 26.4477777
kanpurLongitude :: Longitude
kanpurLongitude = lon $ degree 80.3461111
kanpurGeo       :: Geo
kanpurGeo       = Geo kanpurLatitude kanpurLongitude

You can also specify the latitude and longitude in units of degree, minute and seconds.

kanpurLatitude  = lat $ degree 26 <> minute 26 <> second 52
kanpurLongitude = lon $ degree 80 <> minute 20 <> second 46

The show and read instance of the Latitude and Longitude types uses degrees for displaying and reading respectively. Show and Read instances can express these quantities up to Nano degree precision.

Convention on sign.

For latitudes, positive means north of the equator and negative means south. In the case of longitudes, positive means east of the longitude zero and negative means west. However, if you find these conventions confusing you can use the combinators north, south, east, and west when constructing latitudes or longitudes.

data Geo

The coordinates of a point on the earth's surface.

Constructors

Geo !Latitude !Longitude

Instances

Eq Geo

Defined in Naqsha.Geometry.Coordinate

Methods

(==) :: Geo -> Geo -> Bool

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

Show Geo

Defined in Naqsha.Geometry.Coordinate

Methods

showsPrec :: Int -> Geo -> ShowS

show :: Geo -> String

showList :: [Geo] -> ShowS

Vector Vector Geo

Defined in Naqsha.Geometry.Coordinate

Methods

basicUnsafeFreeze :: PrimMonad m => Mutable Vector (PrimState m) Geo -> m (Vector Geo)

basicUnsafeThaw :: PrimMonad m => Vector Geo -> m (Mutable Vector (PrimState m) Geo)

basicLength :: Vector Geo -> Int

basicUnsafeSlice :: Int -> Int -> Vector Geo -> Vector Geo

basicUnsafeIndexM :: Monad m => Vector Geo -> Int -> m Geo

basicUnsafeCopy :: PrimMonad m => Mutable Vector (PrimState m) Geo -> Vector Geo -> m ()

elemseq :: Vector Geo -> Geo -> b -> b

MVector MVector Geo

Defined in Naqsha.Geometry.Coordinate

Methods

basicLength :: MVector s Geo -> Int

basicUnsafeSlice :: Int -> Int -> MVector s Geo -> MVector s Geo

basicOverlaps :: MVector s Geo -> MVector s Geo -> Bool

basicUnsafeNew :: PrimMonad m => Int -> m (MVector (PrimState m) Geo)

basicInitialize :: PrimMonad m => MVector (PrimState m) Geo -> m ()

basicUnsafeReplicate :: PrimMonad m => Int -> Geo -> m (MVector (PrimState m) Geo)

basicUnsafeRead :: PrimMonad m => MVector (PrimState m) Geo -> Int -> m Geo

basicUnsafeWrite :: PrimMonad m => MVector (PrimState m) Geo -> Int -> Geo -> m ()

basicClear :: PrimMonad m => MVector (PrimState m) Geo -> m ()

basicSet :: PrimMonad m => MVector (PrimState m) Geo -> Geo -> m ()

basicUnsafeCopy :: PrimMonad m => MVector (PrimState m) Geo -> MVector (PrimState m) Geo -> m ()

basicUnsafeMove :: PrimMonad m => MVector (PrimState m) Geo -> MVector (PrimState m) Geo -> m ()

basicUnsafeGrow :: PrimMonad m => MVector (PrimState m) Geo -> Int -> m (MVector (PrimState m) Geo)

newtype Vector Geo

Defined in Naqsha.Geometry.Coordinate

newtype Vector Geo = GeoV (Vector (Angle, Angle))

newtype MVector s Geo

Defined in Naqsha.Geometry.Coordinate

newtype MVector s Geo = MGeoV (MVector s (Angle, Angle))

northPole :: Geo

The North pole

southPole :: Geo

The South pole

Latitudes

data Latitude

The latitude of a point. Positive denotes North of Equator where as negative South.

Instances

Bounded Latitude

Defined in Naqsha.Geometry.Internal

Methods

minBound :: Latitude

maxBound :: Latitude

Eq Latitude

Defined in Naqsha.Geometry.Internal

Methods

(==) :: Latitude -> Latitude -> Bool

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

Ord Latitude

Defined in Naqsha.Geometry.Internal

Methods

compare :: Latitude -> Latitude -> Ordering

(<) :: Latitude -> Latitude -> Bool

(<=) :: Latitude -> Latitude -> Bool

(>) :: Latitude -> Latitude -> Bool

(>=) :: Latitude -> Latitude -> Bool

max :: Latitude -> Latitude -> Latitude

min :: Latitude -> Latitude -> Latitude

Read Latitude

Defined in Naqsha.Geometry.Internal

Methods

readsPrec :: Int -> ReadS Latitude

readList :: ReadS [Latitude]

readPrec :: ReadPrec Latitude

readListPrec :: ReadPrec [Latitude]

Show Latitude

Defined in Naqsha.Geometry.Internal

Methods

showsPrec :: Int -> Latitude -> ShowS

show :: Latitude -> String

showList :: [Latitude] -> ShowS

Bits Latitude

Defined in Naqsha.Geometry.Internal

Methods

(.&.) :: Latitude -> Latitude -> Latitude

(.|.) :: Latitude -> Latitude -> Latitude

xor :: Latitude -> Latitude -> Latitude

complement :: Latitude -> Latitude

shift :: Latitude -> Int -> Latitude

rotate :: Latitude -> Int -> Latitude

zeroBits :: Latitude

bit :: Int -> Latitude

setBit :: Latitude -> Int -> Latitude

clearBit :: Latitude -> Int -> Latitude

complementBit :: Latitude -> Int -> Latitude

testBit :: Latitude -> Int -> Bool

bitSizeMaybe :: Latitude -> Maybe Int

bitSize :: Latitude -> Int

isSigned :: Latitude -> Bool

shiftL :: Latitude -> Int -> Latitude

unsafeShiftL :: Latitude -> Int -> Latitude

shiftR :: Latitude -> Int -> Latitude

unsafeShiftR :: Latitude -> Int -> Latitude

rotateL :: Latitude -> Int -> Latitude

rotateR :: Latitude -> Int -> Latitude

popCount :: Latitude -> Int

Angular Latitude

Defined in Naqsha.Geometry.Angle

Methods

toAngle :: Latitude -> Angle

Vector Vector Latitude

Defined in Naqsha.Geometry.Internal

Methods

basicUnsafeFreeze :: PrimMonad m => Mutable Vector (PrimState m) Latitude -> m (Vector Latitude)

basicUnsafeThaw :: PrimMonad m => Vector Latitude -> m (Mutable Vector (PrimState m) Latitude)

basicLength :: Vector Latitude -> Int

basicUnsafeSlice :: Int -> Int -> Vector Latitude -> Vector Latitude

basicUnsafeIndexM :: Monad m => Vector Latitude -> Int -> m Latitude

basicUnsafeCopy :: PrimMonad m => Mutable Vector (PrimState m) Latitude -> Vector Latitude -> m ()

elemseq :: Vector Latitude -> Latitude -> b -> b

MVector MVector Latitude

Defined in Naqsha.Geometry.Internal

Methods

basicLength :: MVector s Latitude -> Int

basicUnsafeSlice :: Int -> Int -> MVector s Latitude -> MVector s Latitude

basicOverlaps :: MVector s Latitude -> MVector s Latitude -> Bool

basicUnsafeNew :: PrimMonad m => Int -> m (MVector (PrimState m) Latitude)

basicInitialize :: PrimMonad m => MVector (PrimState m) Latitude -> m ()

basicUnsafeReplicate :: PrimMonad m => Int -> Latitude -> m (MVector (PrimState m) Latitude)

basicUnsafeRead :: PrimMonad m => MVector (PrimState m) Latitude -> Int -> m Latitude

basicUnsafeWrite :: PrimMonad m => MVector (PrimState m) Latitude -> Int -> Latitude -> m ()

basicClear :: PrimMonad m => MVector (PrimState m) Latitude -> m ()

basicSet :: PrimMonad m => MVector (PrimState m) Latitude -> Latitude -> m ()

basicUnsafeCopy :: PrimMonad m => MVector (PrimState m) Latitude -> MVector (PrimState m) Latitude -> m ()

basicUnsafeMove :: PrimMonad m => MVector (PrimState m) Latitude -> MVector (PrimState m) Latitude -> m ()

basicUnsafeGrow :: PrimMonad m => MVector (PrimState m) Latitude -> Int -> m (MVector (PrimState m) Latitude)

newtype Vector Latitude

Defined in Naqsha.Geometry.Internal

newtype Vector Latitude = LatV (Vector Angle)

newtype MVector s Latitude

Defined in Naqsha.Geometry.Internal

newtype MVector s Latitude = MLatV (MVector s Angle)

lat :: Angle -> Latitude

Construct latitude out of an angle.

north :: Angle -> Latitude

Convert an angle to a northern latitude

tropicOfCancer = north $ degree 23.5

south :: Angle -> Latitude

Convert an angle to a southern latitude.

 tropicOfCapricon = south $ degree 23.5

equator :: Latitude

The latitude of equator.

tropicOfCancer :: Latitude

The latitude corresponding to the Tropic of Cancer.

tropicOfCapricon :: Latitude

The latitude corresponding to the Tropic of Capricon

Longitudes.

data Longitude

The longitude of a point. Positive denotes East of the Greenwich meridian where as negative denotes West.

Instances

Bounded Longitude

Defined in Naqsha.Geometry.Internal

Methods

minBound :: Longitude

maxBound :: Longitude

Eq Longitude

Defined in Naqsha.Geometry.Internal

Methods

(==) :: Longitude -> Longitude -> Bool

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

Ord Longitude

Defined in Naqsha.Geometry.Internal

Methods

compare :: Longitude -> Longitude -> Ordering

(<) :: Longitude -> Longitude -> Bool

(<=) :: Longitude -> Longitude -> Bool

(>) :: Longitude -> Longitude -> Bool

(>=) :: Longitude -> Longitude -> Bool

max :: Longitude -> Longitude -> Longitude

min :: Longitude -> Longitude -> Longitude

Read Longitude

Defined in Naqsha.Geometry.Internal

Methods

readsPrec :: Int -> ReadS Longitude

readList :: ReadS [Longitude]

readPrec :: ReadPrec Longitude

readListPrec :: ReadPrec [Longitude]

Show Longitude

Defined in Naqsha.Geometry.Internal

Methods

showsPrec :: Int -> Longitude -> ShowS

show :: Longitude -> String

showList :: [Longitude] -> ShowS

Semigroup Longitude

Defined in Naqsha.Geometry.Internal

Methods

(<>) :: Longitude -> Longitude -> Longitude

sconcat :: NonEmpty Longitude -> Longitude

stimes :: Integral b => b -> Longitude -> Longitude

Monoid Longitude

Defined in Naqsha.Geometry.Internal

Methods

mempty :: Longitude

mappend :: Longitude -> Longitude -> Longitude

mconcat :: [Longitude] -> Longitude

Bits Longitude

Defined in Naqsha.Geometry.Internal

Methods

(.&.) :: Longitude -> Longitude -> Longitude

(.|.) :: Longitude -> Longitude -> Longitude

xor :: Longitude -> Longitude -> Longitude

complement :: Longitude -> Longitude

shift :: Longitude -> Int -> Longitude

rotate :: Longitude -> Int -> Longitude

zeroBits :: Longitude

bit :: Int -> Longitude

setBit :: Longitude -> Int -> Longitude

clearBit :: Longitude -> Int -> Longitude

complementBit :: Longitude -> Int -> Longitude

testBit :: Longitude -> Int -> Bool

bitSizeMaybe :: Longitude -> Maybe Int

bitSize :: Longitude -> Int

isSigned :: Longitude -> Bool

shiftL :: Longitude -> Int -> Longitude

unsafeShiftL :: Longitude -> Int -> Longitude

shiftR :: Longitude -> Int -> Longitude

unsafeShiftR :: Longitude -> Int -> Longitude

rotateL :: Longitude -> Int -> Longitude

rotateR :: Longitude -> Int -> Longitude

popCount :: Longitude -> Int

Group Longitude

Defined in Naqsha.Geometry.Internal

Methods

invert :: Longitude -> Longitude

pow :: Integral x => Longitude -> x -> Longitude

Angular Longitude

Defined in Naqsha.Geometry.Angle

Methods

toAngle :: Longitude -> Angle

Vector Vector Longitude

Defined in Naqsha.Geometry.Internal

Methods

basicUnsafeFreeze :: PrimMonad m => Mutable Vector (PrimState m) Longitude -> m (Vector Longitude)

basicUnsafeThaw :: PrimMonad m => Vector Longitude -> m (Mutable Vector (PrimState m) Longitude)

basicLength :: Vector Longitude -> Int

basicUnsafeSlice :: Int -> Int -> Vector Longitude -> Vector Longitude

basicUnsafeIndexM :: Monad m => Vector Longitude -> Int -> m Longitude

basicUnsafeCopy :: PrimMonad m => Mutable Vector (PrimState m) Longitude -> Vector Longitude -> m ()

elemseq :: Vector Longitude -> Longitude -> b -> b

MVector MVector Longitude

Defined in Naqsha.Geometry.Internal

Methods

basicLength :: MVector s Longitude -> Int

basicUnsafeSlice :: Int -> Int -> MVector s Longitude -> MVector s Longitude

basicOverlaps :: MVector s Longitude -> MVector s Longitude -> Bool

basicUnsafeNew :: PrimMonad m => Int -> m (MVector (PrimState m) Longitude)

basicInitialize :: PrimMonad m => MVector (PrimState m) Longitude -> m ()

basicUnsafeReplicate :: PrimMonad m => Int -> Longitude -> m (MVector (PrimState m) Longitude)

basicUnsafeRead :: PrimMonad m => MVector (PrimState m) Longitude -> Int -> m Longitude

basicUnsafeWrite :: PrimMonad m => MVector (PrimState m) Longitude -> Int -> Longitude -> m ()

basicClear :: PrimMonad m => MVector (PrimState m) Longitude -> m ()

basicSet :: PrimMonad m => MVector (PrimState m) Longitude -> Longitude -> m ()

basicUnsafeCopy :: PrimMonad m => MVector (PrimState m) Longitude -> MVector (PrimState m) Longitude -> m ()

basicUnsafeMove :: PrimMonad m => MVector (PrimState m) Longitude -> MVector (PrimState m) Longitude -> m ()

basicUnsafeGrow :: PrimMonad m => MVector (PrimState m) Longitude -> Int -> m (MVector (PrimState m) Longitude)

newtype Vector Longitude

Defined in Naqsha.Geometry.Internal

newtype Vector Longitude = LongV (Vector Angle)

newtype MVector s Longitude

Defined in Naqsha.Geometry.Internal

newtype MVector s Longitude = MLongV (MVector s Angle)

lon :: Angle -> Longitude

Convert angles to longitude.

east :: Angle -> Longitude

Convert angle to an eastern longitude.

kanpurLongitude = east $ degree 80.3461

west :: Angle -> Longitude

Convert angle to a western longitude

newyorkLongitude = west $ degree 74.0059

greenwich :: Longitude

The zero longitude.

Angles and angular quantities.

data Angle

An abstract angle. Internally, angles are represented as a 64-bit integer with each unit contribute 1/2^64 fraction of a complete circle. This means that angles are accurate up to a resolution of 2 π / 2^64 radians. Angles form a group under the angular addition and the fact that these are represented as integers means one can expect high speed accurate angle arithmetic.

When expressing angles one can use a more convenient notation:

myAngle   = degree 21.71167
yourAngle = degree 21 <> minute 42 <> second 42

Instances

Bounded Angle

Defined in Naqsha.Geometry.Internal

Methods

minBound :: Angle

maxBound :: Angle

Enum Angle

Defined in Naqsha.Geometry.Internal

Methods

succ :: Angle -> Angle

pred :: Angle -> Angle

toEnum :: Int -> Angle

fromEnum :: Angle -> Int

enumFrom :: Angle -> [Angle]

enumFromThen :: Angle -> Angle -> [Angle]

enumFromTo :: Angle -> Angle -> [Angle]

enumFromThenTo :: Angle -> Angle -> Angle -> [Angle]

Eq Angle

Defined in Naqsha.Geometry.Internal

Methods

(==) :: Angle -> Angle -> Bool

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

Ord Angle

Defined in Naqsha.Geometry.Internal

Methods

compare :: Angle -> Angle -> Ordering

(<) :: Angle -> Angle -> Bool

(<=) :: Angle -> Angle -> Bool

(>) :: Angle -> Angle -> Bool

(>=) :: Angle -> Angle -> Bool

max :: Angle -> Angle -> Angle

min :: Angle -> Angle -> Angle

Read Angle

Defined in Naqsha.Geometry.Internal

Methods

readsPrec :: Int -> ReadS Angle

readList :: ReadS [Angle]

readPrec :: ReadPrec Angle

readListPrec :: ReadPrec [Angle]

Show Angle

Defined in Naqsha.Geometry.Internal

Methods

showsPrec :: Int -> Angle -> ShowS

show :: Angle -> String

showList :: [Angle] -> ShowS

Semigroup Angle

Defined in Naqsha.Geometry.Internal

Methods

(<>) :: Angle -> Angle -> Angle

sconcat :: NonEmpty Angle -> Angle

stimes :: Integral b => b -> Angle -> Angle

Monoid Angle

Defined in Naqsha.Geometry.Internal

Methods

mempty :: Angle

mappend :: Angle -> Angle -> Angle

mconcat :: [Angle] -> Angle

Bits Angle

Defined in Naqsha.Geometry.Internal

Methods

(.&.) :: Angle -> Angle -> Angle

(.|.) :: Angle -> Angle -> Angle

xor :: Angle -> Angle -> Angle

complement :: Angle -> Angle

shift :: Angle -> Int -> Angle

rotate :: Angle -> Int -> Angle

zeroBits :: Angle

bit :: Int -> Angle

setBit :: Angle -> Int -> Angle

clearBit :: Angle -> Int -> Angle

complementBit :: Angle -> Int -> Angle

testBit :: Angle -> Int -> Bool

bitSizeMaybe :: Angle -> Maybe Int

bitSize :: Angle -> Int

isSigned :: Angle -> Bool

shiftL :: Angle -> Int -> Angle

unsafeShiftL :: Angle -> Int -> Angle

shiftR :: Angle -> Int -> Angle

unsafeShiftR :: Angle -> Int -> Angle

rotateL :: Angle -> Int -> Angle

rotateR :: Angle -> Int -> Angle

popCount :: Angle -> Int

Group Angle

Defined in Naqsha.Geometry.Internal

Methods

invert :: Angle -> Angle

pow :: Integral x => Angle -> x -> Angle

Unbox Angle

Defined in Naqsha.Geometry.Internal

Angular Angle

Defined in Naqsha.Geometry.Angle

Methods

toAngle :: Angle -> Angle

Vector Vector Angle

Defined in Naqsha.Geometry.Internal

Methods

basicUnsafeFreeze :: PrimMonad m => Mutable Vector (PrimState m) Angle -> m (Vector Angle)

basicUnsafeThaw :: PrimMonad m => Vector Angle -> m (Mutable Vector (PrimState m) Angle)

basicLength :: Vector Angle -> Int

basicUnsafeSlice :: Int -> Int -> Vector Angle -> Vector Angle

basicUnsafeIndexM :: Monad m => Vector Angle -> Int -> m Angle

basicUnsafeCopy :: PrimMonad m => Mutable Vector (PrimState m) Angle -> Vector Angle -> m ()

elemseq :: Vector Angle -> Angle -> b -> b

MVector MVector Angle

Defined in Naqsha.Geometry.Internal

Methods

basicLength :: MVector s Angle -> Int

basicUnsafeSlice :: Int -> Int -> MVector s Angle -> MVector s Angle

basicOverlaps :: MVector s Angle -> MVector s Angle -> Bool

basicUnsafeNew :: PrimMonad m => Int -> m (MVector (PrimState m) Angle)

basicInitialize :: PrimMonad m => MVector (PrimState m) Angle -> m ()

basicUnsafeReplicate :: PrimMonad m => Int -> Angle -> m (MVector (PrimState m) Angle)

basicUnsafeRead :: PrimMonad m => MVector (PrimState m) Angle -> Int -> m Angle

basicUnsafeWrite :: PrimMonad m => MVector (PrimState m) Angle -> Int -> Angle -> m ()

basicClear :: PrimMonad m => MVector (PrimState m) Angle -> m ()

basicSet :: PrimMonad m => MVector (PrimState m) Angle -> Angle -> m ()

basicUnsafeCopy :: PrimMonad m => MVector (PrimState m) Angle -> MVector (PrimState m) Angle -> m ()

basicUnsafeMove :: PrimMonad m => MVector (PrimState m) Angle -> MVector (PrimState m) Angle -> m ()

basicUnsafeGrow :: PrimMonad m => MVector (PrimState m) Angle -> Int -> m (MVector (PrimState m) Angle)

newtype Vector Angle

Defined in Naqsha.Geometry.Internal

newtype Vector Angle = AngV (Vector Int64)

newtype MVector s Angle

Defined in Naqsha.Geometry.Internal

newtype MVector s Angle = MAngV (MVector s Int64)

degree :: Rational -> Angle

Express angle in degrees.

minute :: Rational -> Angle

Express angle in minutes.

second :: Rational -> Angle

Express angle in seconds.

radian :: Double -> Angle

Express angle in radians

toDegree :: Fractional r => Angle -> r

Measure angle in degrees. This conversion may lead to loss of precision.

toRadian :: Angle -> Double

Measure angle in radians. This conversion may lead to loss of precision.

class Angular a where

Angular quantities.

Methods

toAngle :: a -> Angle

Instances

Angular Longitude

Defined in Naqsha.Geometry.Angle

Methods

toAngle :: Longitude -> Angle

Angular Latitude

Defined in Naqsha.Geometry.Angle

Methods

toAngle :: Latitude -> Angle

Angular Angle

Defined in Naqsha.Geometry.Angle

Methods

toAngle :: Angle -> Angle

Geometric hashing.

Geometric hashing is a technique of converting geometric coordinates into 1-dimension strings. Often these hashes ensures that string with large common prefix are close by (although not the converse). Hence, these hashes can be used to stored geo-cordinates in database and build into it a sense of location awareness. We support the following geometric hashing:

Naqsha.Geometry.Coordinate.GeoHash:

The geohash standard (https://en.wikipedia.org/wiki/Geohash).

None of these modules are imported by default the user may import the one that is most desirable.

Distance calculation.

Calculating quantities like distance, bearing etc depends on the model of the globe that we choose. Even in a given model we might have different algorithms to compute the distance depending on speed-accuracy trade-offs. Choosing the correct model and algorithms is application dependent and hence we do not expose any default ones. The following modules can be imported depending on the need

Naqsha.Geometry.Spherical:

Assume a spherical model of the globe. Distance is calculated using the haversine formula.

Internal details

The basic types like Latitude or Longitude are exposed as opaque types from this module. This gives a certain amount of type safety when working with these quantities. A user should, whenever possible, only use this module. For the rare case when some non-trivial operations need to be defined, we expose the internal module Naqsha.Geometry.Internal. However, use this interface with caution.