Network.OSM

Basic Types

newtype TileID

A TileID, along with a zoom level, uniquely identifies a single OSM map tile. The standard size is 256x256 pixels for such a tile.

Constructors

TID

Fields

unTID :: (Int, Int)

Instances

Eq TileID

Data TileID

Ord TileID

Read TileID

Show TileID

Typeable TileID

PersistField TileID

data TileCoords

The coordinates associated with any particular GPS location can be computed using determineTileCoords and converted into tile ids using selectedTiles before final download with downloadTiles.

Constructors

TileCoords

Fields

minX :: Int

maxX :: Int

minY :: Int

maxY :: Int

Instances

Eq TileCoords

Ord TileCoords

Show TileCoords

type Zoom = Int

Types for tile cacheing

data OSMConfig

The cacheing operations run in their own monad that describe the location of the cache, the tile server URL, and the worker threads the retrieve tiles.

Constructors

OSMCfg

Fields

baseUrl :: String

cache :: Text

Path of the tile cache

noCacheAction :: Maybe (TileID -> Zoom -> IO (Either Status ByteString))

Action to take if the tile is not cached. Return Just val for a default value. Return Nothing to wait for a tile server.

nrQueuedDownloads :: Int

Max download queue size

nrConcurrentDownloads :: Int

Number of threads the tile downloading can concurrently run in. Tileserver admins request this be no more than 2.

networkEnabled :: Bool

True if we should use the network to download Tiles

data OSMState

The OSM operations maintain a list of tiles needing refreshed (for local caching), the state of the local cache, and initial configuration options.

Instances

MonadState OSMState OSM

data OSM a

A Monad transformer allowing you acquire OSM maps

Instances

Monad OSM

MonadIO OSM

MonadState OSMState OSM

High-level (cacheing) Operations

evalOSM :: OSM a -> OSMConfig -> IO a

evalOSM allows you to query an OSM server and the local cache. Take note - the OSMConfig thread limit is enforced per-evalOSM. Running many evalOSM processes can result in a violation of the limit and incur admin wrath.

getBestFitTiles :: Coordinate a => [a] -> OSM [[Either Status ByteString]]

Like downloadBestFitTiles but uses the cached copies when available.

getTiles :: [[TileID]] -> Zoom -> OSM [[Either Status ByteString]]

Like downloadTiles but uses the cached copies when available

getTile :: TileID -> Zoom -> OSM (Either Status ByteString)

Like downloadTile but uses a cached copy when available. Downloaded copies are added to the cache.

When the cached copy is out of date it will still be returned but a new copy will be downloaded and added to the cache concurrently.

defaultOSMConfig :: IO OSMConfig

A default configuration using the main OSM server as a tile server and a cabal-generated directory for the cache directory

Network Operations

downloadBestFitTiles :: Coordinate a => String -> [a] -> IO [[Either Status ByteString]]

Takes the tile server base URL, the set of coordinates that must appear within the map boundaries, and users the downloadTiles function to acquire all the necessary tiles.

The returned files should all be in an approriate grid for row/column display. See the test files of Main.hs and Main2.hs for examples of Repa stiching tiles into a single image or side by side display of individual tiles.

downloadTiles :: String -> Zoom -> [[TileID]] -> IO [[Either Status ByteString]]

Takes the boundaries of the OSM tiles and downloads the tiles, keeping them in proper grid patterns for latter stiching or side-by-side display.

downloadTile :: String -> Zoom -> TileID -> IO (Either Status ByteString)

Download a single tile form a given OSM server URL.

osmTileURL :: String

The official OSM tile server.

Frame-oriented operations

data Frame a

Constructors

Frame

Fields

width :: Int

height :: Int

center :: a

frameZoom :: Zoom

Instances

Eq a => Eq (Frame a)

Ord a => Ord (Frame a)

Read a => Read (Frame a)

Show a => Show (Frame a)

selectTilesForFrame :: Coordinate a => Frame a -> [[TileID]]

Given a width, height and center, compute the tiles needed to fill the display.

THIS ASSUMES tiles are 256x256 pixels!

tileCoordsForFrame :: Coordinate a => Frame a -> TileCoords

pixelPositionForFrame :: Coordinate a => Frame a -> a -> (Int, Int)

Helper Functions

pixelPosForCoord :: (Coordinate a, Integral t) => a -> TileCoords -> Zoom -> (t, t)

Takes a coordinate, the OSM tile boundaries, and a zoom level then generates (x,y) points to be placed on the Image. The origin is in the upper left of the picture.

determineTileCoords :: Coordinate a => [a] -> Zoom -> Maybe TileCoords

Computes the rectangular map region to download based on GPS points and a zoom level

selectedTiles :: TileCoords -> [[TileID]]

Takes the boundaries of the OSM tiles, and generates a list of the encompassed OSM tiles.

Legal

osmCopyrightText :: String

The suggested copyright text in accordance with http://wiki.openstreetmap.org/wiki/Legal_FAQ