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.5?
::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
::map::slippy fit geobox canvdim geobox zmin zmax
______________________________________________________________________________
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 boolean value, true if the tile is valid, and false otherwise.
For the latter a message is left in the variable named by msg-
var, 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 es-
sentially 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 col-
umn) at that level. The tile identifier uses pure integer num-
bers 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 col-
umn) at that level. The tile identifier uses floating point num-
bers for the tile coordinates, representing not only the tile
the geographic coordinates map to, but also the fractional loca-
tion 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 contain-
ing zoom level, row, and column) to a geographical location
(list containing 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 con-
taining 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 contain-
ing zoom level, y, and x) to a geographical location (list con-
taining 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 con-
taining zoom level, y, and x, in this order) to a tile identi-
fier (list containing zoom level, row, and column) at that
level.
::map::slippy fit geobox canvdim geobox zmin zmax
Calculates the zoom level (whithin the bounds zmin and zmax)
such that geobox (a 4-element list containing the latitudes and
longitudes lat0, lat1, lon0 and lon1 of a geo box, in this or-
der) fits into a viewport given by canvdim, a 2-element list
containing the width and height of the viewport, in this order.
COORDINATE SYSTEMS
The commands of this package operate on three distinct coordinate sys-
tems, 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 de-
grees. Note that +180 and -180 longitude are the same meridian, oppo-
site to greenwich.
zero latitude the Equator, with positive values going north and nega-
tive 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 sig-
nal how far inside the tile the location in question is, with pure in-
teger coordinates (no fractional part) representing the upper left cor-
ner 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
tcllib 0.5 map::slippy(3tcl)