Tcl Library Source Code


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]


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

Table Of Contents


package require Tcl 8.6 9
package require map::slippy ?0.8?

::map slippy geo box 2point zoom geobox
::map slippy geo box center geobox
::map slippy geo box corners geobox
::map slippy geo box diameter geobox
::map slippy geo box dimensions geobox
::map slippy geo box fit geobox canvdim zmax ?zmin?
::map slippy geo box inside geobox geo
::map slippy geo box limit geobox
::map slippy geo box opposites geobox
::map slippy geo box perimeter geobox
::map slippy geo box valid geobox
::map slippy geo box valid-list geoboxes
::map slippy geo distance geo1 geo2
::map slippy geo distance* closed geo...
::map slippy geo distance-list closed geo-list
::map slippy geo limit geo
::map slippy geo bbox geo...
::map slippy geo bbox-list geo-list
::map slippy geo center geo...
::map slippy geo center-list geo-list
::map slippy geo diameter geo...
::map slippy geo diameter-list geo-list
::map slippy geo 2point zoom geo
::map slippy geo 2point* zoom geo...
::map slippy geo 2point-list zoom geo-list
::map slippy geo valid geo
::map slippy geo valid-list geos
::map slippy length level
::map slippy limit2 x
::map slippy limit3 x
::map slippy limit6 x
::map slippy point box 2geo zoom pointbox
::map slippy point box center pointbox
::map slippy point box corners pointbox
::map slippy point box diameter pointbox
::map slippy point box dimensions pointbox
::map slippy point box inside pointbox point
::map slippy point box opposites pointbox
::map slippy point box perimeter pointbox
::map slippy point distance point1 point2
::map slippy point distance* closed point...
::map slippy point distance-list closed point-list
::map slippy point bbox point...
::map slippy point bbox-list point-list
::map slippy point center point...
::map slippy point center-list point-list
::map slippy point diameter point...
::map slippy point diameter-list point-list
::map slippy point 2geo zoom point
::map slippy point 2geo* zoom point...
::map slippy point 2geo-list zoom point-list
::map slippy point simplify radial threshold point-list
::map slippy point simplify rdp point-list
::map slippy pretty-distance x
::map slippy tiles level
::map slippy tile size
::map slippy tile valid zoom row column levels ?msgvar?
::map slippy valid latitude x
::map slippy valid longitude x


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

BEWARE, Attention Version 0.8 is NOT backward compatible with version 0.7 and earlier. The entire API was heavily revised and changed.

Note: For the representation of locations in the various coordinate systems used by the commands of this package please read section Coordinate systems. The command descriptions will not repeat them, and assume that they are understood already.

Coordinate systems

The commands of this package operate in two distinct coordinate systems, geographical locations, and points. The former represents coordinates for locations on Earth, while the latter is for use on Tk canvas widgets.


Geographical locations (short: geo) are represented by a pair of Latitude and Longitude values, each of which is measured in degrees, as they are essentially angles.

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

The zero latitude is 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 roughly +/- 85.05112877983284 degrees. This means that the North and South poles are not representable and not part of any map.

A geographical location is represented by a list containing two values, the latitude, and longitude of the location, in this order.

A geographical bounding box is represented by a list containing four values, the minimal latitude and longitude of the box, and the maximal latitude and longitude of the box, in this order.

Geographical locations and boxes can be converted to points and their boxes by means of an additional parameter, the zoom level. This parameter indicates the size of the map in the canvas the coordinates are to be projected into.


Points (short: point) are represented by a pair of x and y values, each of which is measured in pixels. They reference a location in a Tk canvas widget. As a map can be shown at different degrees of magnification, the exact pixel coordinates for a geographical location depend on this zoom level.

For the following explanation to make sense it should be noted that a map shown in a Tk canvas widget is split into equal-sized quadratic tiles.

Point coordinates are tile coordinates scaled by the size of these tiles. This package uses tiles of size 256, which is the standard size used by many online servers providing map tiles of some kind or other.

A point is represented by a list containing the x- and y-coordinates of the lcoation, in this in this order.

A point bounding box is represented by a list containing four values, the minimal x and y of the box, and the maximal x and y of the box, in this order.

Point locations and boxes can be converted to geographical locations and their boxes by means of an additional parameter, the zoom level. This parameter indicates the size of the map in the canvas the coordinates are projected from.

Tile coordinates appear only in one place of the API, in the signature of command map slippy tile valid. Everything else uses Point coordinates.

Using tile coordinates in the following however makes the structure of the map at the various zoom levels (maginification factors) easier to explain.

Generally the integer part of the tile coordinates represent the row and column number of a tile of the map, wheras the fractional parts signal how far inside that tile the location in question is, with pure integer coordinates (no fractional part) representing the upper left corner of a 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 zoom level.

Negative coordinates are not allowed.

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

When going from zoom level N to the next deeper (magnified) 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 rows and columns, for a total of 4^N tiles, with the tile coordinates ranging from 0 to 2^N+1.





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