map::slippy(3tcl)						 Mapping utilities						 map::slippy(3tcl)

__________________________________________________________________________________________________________________________________________________

NAME

       map::slippy - Common code for slippy based map packages

SYNOPSIS

       package require Tcl  8.4

       package require Tk  8.4

       package require map::slippy  ?0.4?

       ::map::slippy length level

       ::map::slippy tiles level

       ::map::slippy tile size

       ::map::slippy tile valid tile levels ?msgvar?

       ::map::slippy geo 2tile geo

       ::map::slippy geo 2tile.float geo

       ::map::slippy geo 2point geo

       ::map::slippy tile 2geo tile

       ::map::slippy tile 2point tile

       ::map::slippy point 2geo point

       ::map::slippy point 2tile point

_________________________________________________________________

DESCRIPTION

       This package provides a number of methods doing things needed by all types of slippy-based map packages.

API

       ::map::slippy length level
	      This  method  returns the width/height of a slippy-based map at the specified zoom level, in pixels. This is, in essence, the result
	      of

		expr { [tiles $level] * [tile size] }

       ::map::slippy tiles level
	      This method returns the width/height of a slippy-based map at the specified zoom level, in tiles.

       ::map::slippy tile size
	      This method returns the width/height of a tile in a slippy-based map, in pixels.

       ::map::slippy tile valid tile levels ?msgvar?
	      This method checks whether tile described a valid tile in a slippy-based map containing that many zoom levels. The result is a bool-
	      ean  value, true if the tile is valid, and false otherwise. For the latter a message is left in the variable named by msgvar, should
	      it be specified.

	      A tile identifier as stored in tile is a list containing zoom level, tile row, and tile column, in this order.  The  command  essen-
	      tially checks this, i.e. the syntax, that the zoom level is between 0 and "levels-1", and that the row/col information is within the
	      boundaries for the zoom level, i.e. 0 ...  "[tiles $zoom]-1".

       ::map::slippy geo 2tile geo
	      Converts a geographical location at a zoom level (geo, a list containing zoom level, latitude, and longitude, in this  order)  to  a
	      tile  identifier	(list containing zoom level, row, and column) at that level. The tile identifier uses pure integer numbers for the
	      tile coordinates, for all geographic coordinates mapping to that tile.

       ::map::slippy geo 2tile.float geo
	      Converts a geographical location at a zoom level (geo, a list containing zoom level, latitude, and longitude, in this  order)  to  a
	      tile identifier (list containing zoom level, row, and column) at that level. The tile identifier uses floating point numbers for the
	      tile coordinates, representing not only the tile the geographic coordinates map to, but also the fractional location inside of  that
	      tile.

       ::map::slippy geo 2point geo
	      Converts	a  geographical  location at a zoom level (geo, a list containing zoom level, latitude, and longitude, in this order) to a
	      pixel position (list containing zoom level, y, and x) at that level.

       ::map::slippy tile 2geo tile
	      Converts a tile identifier at a zoom level (tile, list containing zoom level, row, and column) to a geographical location (list con-
	      taining zoom level, latitude, and longitude, in this order) at that level.

       ::map::slippy tile 2point tile
	      Converts	a tile identifier at a zoom level (tile, a list containing zoom level, row, and column, in this order) to a pixel position
	      (list containing zoom level, y, and x) at that level.

       ::map::slippy point 2geo point
	      Converts a pixel position at a zoom level (point, list containing zoom level, y, and x) to a geographical location (list	containing
	      zoom level, latitude, and longitude, in this order) at that level.

       ::map::slippy point 2tile point
	      Converts	a pixel position at a zoom level (point, a list containing zoom level, y, and x, in this order) to a tile identifier (list
	      containing zoom level, row, and column) at that level.

COORDINATE SYSTEMS

       The commands of this package operate on three distinct coordinate systems, which are explained below.

   GEOGRAPHIC
       Geographical coordinates are represented by Latitude and Longitude, each of which is measured in degrees, as they are essentially angles.

       Zero longitude is the Greenwich meridian, with positive values going east, and negative values going west, for a total  range  of  +/-  180
       degrees. Note that +180 and -180 longitude are the same meridian, opposite to greenwich.

       zero  latitude  the  Equator,  with positive values going north and negative values going south. While the true range is +/- 90 degrees the
       projection used by the package requires us to cap the range at +/- 85.05112877983284 degrees. This means that north and south pole are  not
       representable and not part of any map.

   TILES
       While Geographical coordinates of the previous section are independent of zoom level the tile coordinates are not.

       Generally  the  integer	part  of tile coordinates represent the row and column number of the tile in question, wheras the fractional parts
       signal how far inside the tile the location in question is, with pure integer coordinates (no fractional part) representing the upper  left
       corner of the tile.

       The  zero  point  of  the  map  is  at the upper left corner, regardless of zoom level, with larger coordinates going right (east) and down
       (south), and smaller coordinates going left (west) and up (north). Again regardless of zxoom level.

       Negative tile coordinates are not allowed.

       At zoom level 0 the whole map is represented by a single, putting the geographic zero at 1/2, 1/2 of tile coordinates,  and  the  range	of
       tile coordinates as [0...1].

       To  go  from a zoom level N to the next deeper level N+1 each tile of level N is split into its four quadrants, which then are the tiles of
       level N+1.

       This means that at zoom level N the map is sliced (horizontally and vertically) into 2^N stripes, for a total of 4^N tiles, with tile coor-
       dinates ranging from 0 to 2^N+1.

   PIXELS/POINTS
       pixel  coordinates, also called point coordinates are in essence tile coordinates scaled by the size of the image representing a tile. This
       tile size currently has a fixed value, 256.

REFERENCES

       [1]    http://wiki.openstreetmap.org/wiki/Main_Page

KEYWORDS

       geodesy, geography, latitute, location, longitude, map, slippy, zoom

map									0.4							 map::slippy(3tcl)