Provided by: tcllib_1.19-dfsg-2_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