Provided by: tcllib_1.21+dfsg-1_all bug

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 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 essentially 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 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 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.

       ::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 order) 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  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 coordinates 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