map::slippy(n)

📦

version 2.0 · 2 versions

2.0 · fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
1.21 · alpine 3.24, epel 9, opensuse-leap 16.0

, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

✨ map::slippy(n) ✨ — Mapping utilities

okay so bestie, this is the manual for map::slippy(n) from the Mapping utilities collection. It's part 1, and it's lowkey iconic. Let's get into it. 🫶

🌸 NAME 🌸

map::slippy — Common code for slippy based map packages. That's the whole name vibe. 💖

✨ SYNOPSIS ✨

First, the package requirements and the full command list, no cap:

package require Tcl 8.6 9

package require map::slippy ?0.10?

::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

🦋 DESCRIPTION 🦋

This package provides a number of methods doing things needed by all types of slippy-based map packages. It's the friend that has your back for all your slippy map needs. 💅

⚠️ BEWARE, Attention Version 0.9 is NOT backward compatible with version 0.7 and earlier. The entire API was heavily revised and changed. So if you're coming from 0.7, it's not me, it's the API. 😭

📝 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. iykyk.

🌈 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. Two totally different vibes, bestie. 🌍🖥️

🌍 GEOGRAPHIC 🌍

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. Yes, angles. Math is mathing. 📐

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. So like, same same but different. 🔄

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. Sorry polar bears, no map for you. 🐻‍❄️😭

A geographical location is represented by a list containing two values, the latitude, and longitude of the location, in this order. Lat first, then long. Don't mix it up. 💅

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. Min lat, min long, max lat, max long. Got it. 📦

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. Zoom zoom. 🔍

📍 POINTS 📍

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. Pixels go brrr. 🖥️✨

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. Yes, squares. 🟦

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. 256, the magic number. 🔢

A point is represented by a list containing the x- and y-coordinates of the location, in this order. x first, y second. Don't @ me. 📍

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. Min x, min y, max x, max y. 📦

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. So like, tile coords are the special guest star. 🌟

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

Generally the integer part of the tile coordinates represent the row and column number of a tile of the map, whereas 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. So up-left is zero, down-right is more. 🧭

Negative coordinates are not allowed. Periodt. 🚫

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]. One tile to rule them all. 👑

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. Quadrants, quadrants, quadrants. 🔲🔳

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. Math! 🤓

🛠️ API 🛠️

Now the commands, bestie. Each one is a little gift. 🎁

`::map slippy geo box 2point zoom geobox`

The command converts the geographical box geobox to a point box in the canvas, for the specified zoom level, and returns that box. Glow-up from geo to point. ✨

`::map slippy geo box center geobox`

The command returns the center of the geographical box geobox. Dead center, like your aesthetic. 🎯

`::map slippy geo box corners geobox`

This command returns a list containing the four corner locations implied by the geographical box geobox. The four points are top-left, bottom-left, top-right, and bottom-right, in that order. Four corners, four vibes. 🔲

`::map slippy geo box diameter geobox`

The command returns the diameter of the geographical box geobox, in meters. Meters, bestie. 📏

`::map slippy geo box dimensions geobox`

The command returns the dimensions of the geographical box geobox, width and height, in this order. Width first, height second. Don't @ me. 📐

`::map slippy geo box fit geobox canvdim zmax ?zmin?`

This command calculates the zoom level such that the geobox will fit into a viewport given by canvdim (a 2-element list containing the width and height of said viewport) and returns it. Fit check! 📸

The zoom level will be made to fit within the range zmin...zmax. When zmin is not specified it will default to 0. Default is zero, no cap. 0️⃣

`::map slippy geo box inside geobox geo`

The command tests if the geographical location geo is contained in the geographical box geobox or not. It returns true if so, and false else. In or out? True or false? 💅

`::map slippy geo box limit geobox`

This command limits the geographical box to at most 6 decimals and returns the result. Six decimals, that's the limit. ✋

For geographical coordinates 6 decimals is roughly equivalent to a grid of 11.1 cm. 11.1 cm, that's precise. 📏

`::map slippy geo box opposites geobox`

This command returns a list containing the two principal corner locations implied by the geographical box geobox. The two points are top-left, and bottom-right, in that order. Opposites attract. 🧲

`::map slippy geo box perimeter geobox`

The command returns the perimeter of the geographical box geobox, in meters. Walk the perimeter. 🚶‍♀️

`::map slippy geo box valid geobox`

This commands tests if the specified geographical box contains only valid latitudes and longitudes. It returns true if the box is valid, and false else. Valid check. ✅

`::map slippy geo box valid-list geoboxes`

This commands tests if the list of geographical boxes contains only valid latitudes and longitudes. It returns true if all the boxes are valid, and false else. All of them? Valid list energy. 📋

`::map slippy geo distance geo1 geo2`

This command computes the great-circle distance between the two geographical locations in meters and returns that value. Great-circle, like the shortest path on a sphere. 🌐

The code is based on https://wiki.tcl-lang.org/page/geodesy take on the haversine formula [https://en.wikipedia.org/wiki/Haversine_formula]. Haversine formula, iconic. 📐

`::map slippy geo distance* closed geo...`

An extension of map slippy geo distance this command computes the cumulative distance along the path specified by the ordered set of geographical locations in meters, and returns it. Cumulative distance, so it adds it all up. 🔗

Okay so real quick, finishing the thought from the last one — if the path is marked as closed (i.e. a polygon/loop) the result contains the distance between last and first element of the path as well, making the result the length of the perimeter of the area described by the locations. 🦋

::map slippy geo distance-list closed geo-list — literally the same energy as map slippy geo distance*, except it takes the path you're measuring as one single list of geographical locations instead of a whole varying number of arguments. Same math, tidier hands. 💅
::map slippy geo limit geo — this one caps your geographical location at at most 6 decimals and hands back the result. And for geographical coordinates, 6 decimals is roughly equivalent to a grid of 11.1 cm. That's the vibe. 📏
::map slippy geo bbox geo... and ::map slippy geo bbox-list geo-list — these two compute the bounding box for the set of geographical locations you give them and return a geographical box. When no geographical locations are specified the box is "0 0 0 0". And the locations come in as either a varying number of arguments, or as a single list — dealer's choice bestie. ✨
::map slippy geo center geo... and ::map slippy geo center-list geo-list — these two compute the center of the bounding box for the specified set of geographical locations. When no geographical locations are specified the center is "0 0". Again, locations are either a varying number of arguments, or a single list. 🎯
::map slippy geo diameter geo... and ::map slippy geo diameter-list geo-list — these two compute the diameter for the specified set of geographical locations, in meters. The diameter is the maximum of the pair-wise distances between all locations. When less than two geographical locations are specified the diameter is "0". And yup — varying number of arguments, or a single list. 🌀
::map slippy geo 2point zoom geo — converts the geographical location geo into a point in the canvas for the zoom level you specify, and returns that point. 🗺️
::map slippy geo 2point* zoom geo... and ::map slippy geo 2point-list zoom geo-list — these two are extensions of map slippy geo 2point that take a whole series of geographical locations (as either a varying number of arguments or a single list), convert them all to points per the specified zoom level, and return a list of the results. Glow up. 👑
::map slippy geo valid geo — tests if the specified geographical location contains only valid latitudes and longitudes. Returns true if the location is valid, and false else. ✅
::map slippy geo valid-list geos — same test, but for a whole list of geographical locations. Returns true if all the locations are valid, and false else. 🫶
::map slippy length level — returns the width/height of a slippy-based map at the specified zoom level, in pixels. In essence, this is the result of:

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

::map slippy limit2 x, ::map slippy limit3 x, and ::map slippy limit6 x — these cap the value at at most 2, 3, or 6 decimals respectively, and return the result. And for geographical coordinates, 6 decimals is roughly equivalent to a grid of 11.1 cm. 🎀
::map slippy point box 2geo zoom pointbox — converts the point box pointbox into a geographical box in the canvas, per the specified zoom level, and returns that box. 🦋
::map slippy point box center pointbox — returns the center of the pointbox. Simple. Iconic. 💅
::map slippy point box corners pointbox — returns a list of the four corner locations implied by the point box pointbox. The four points are top-left, bottom-left, top-right, and bottom-right, in that order. Don't shuffle them bestie, order matters. 🌸
::map slippy point box diameter pointbox — returns the diameter of the pointbox, in pixels. 📐
::map slippy point box dimensions pointbox — returns the dimensions of the pointbox — width and height, in this order. 📦
::map slippy point box inside pointbox point — tests if the point is contained in the pointbox or not. Returns true if so, and false else. 🔍
::map slippy point box opposites pointbox — returns a list of the two principal corner locations implied by the point box pointbox. The two points are top-left, and bottom-right, in that order. 💖
::map slippy point box perimeter pointbox — returns the perimeter of the pointbox, in pixels. Walk it around the block. 🚶‍♀️
::map slippy point distance point1 point2 — computes the euclidean distance between the two points in pixels and returns that value. 🧮
::map slippy point distance* closed point... — an extension of map slippy point distance, it computes the cumulative distance along the path specified by the ordered set of points, and returns it. And if the path is marked as closed (i.e. a polygon/loop) the result contains the distance between last and first element of the path as well, making the result the length of the perimeter of the area described by the locations. Round and round we go. 🔄
::map slippy point distance-list closed point-list — as a variant of map slippy point distance*, this one takes the path you're measuring as a single list of points instead of a varying number of arguments. ✨
::map slippy point bbox point... and ::map slippy point bbox-list point-list — these two compute the bounding box for the specified set of points and return a point box. When no points are specified the box is "0 0 0 0". And the locations are given as either a varying number of arguments, or as a single list. 🎁
::map slippy point center point... and ::map slippy point center-list point-list — these two compute the center of the bounding box for the specified set of points. When no points are specified the center is "0 0". Same deal — varying number of arguments, or a single list. 🎯
::map slippy point diameter point... and ::map slippy point diameter-list point-list — these two compute the diameter for the specified set of points, in pixels. The diameter is the maximum of the pair-wise distances between all locations. When less than two points are specified the diameter is "0". And yup, varying arguments or a single list. 🌀
::map slippy point 2geo zoom point — converts the point in the canvas, for the specified zoom level, into a geographical location, and returns that location. 🗺️
::map slippy point 2geo* zoom point... and ::map slippy point 2geo-list zoom point-list — these two are extensions of map slippy point 2geo that take a series of points as either a varying number of arguments or a single list, convert them all to geographical locations per the specified zoom level, and return a list of the results. 👑
::map slippy point simplify radial threshold point-list — takes a path of points (as a single list), simplifies it using the Radial Distance algorithm, and returns the simplified path as a list of points. In essence the algorithm keeps only the first of adjacent points nearer to that first point than the threshold, and drops the others. Declutter, but make it geometry. 🧹
::map slippy point simplify rdp point-list — takes a patch of points (as a single list), simplifies it using the non-parametric Ramer-Douglas-Peucker algorithm, and returns the simplified path as a list of points. Fancy name, clean results. ✨
::map slippy pretty-distance x — formats the distance x (in meters) for display and returns the resulting string (including the chosen unit). Sub-kilometer distances are limited to 2 decimals, i.e. centimeters, whereas Kilometers are limited to 3 decimals, i.e. meters. It's giving presentable. 💅
::map slippy tiles level — returns the width/height of a slippy-based map at the specified zoom level, in tiles. 🧱
::map slippy tile size — returns the width/height of a tile in a slippy-based map, in pixels. One lil square, measured. 🟦
::map slippy tile valid zoom row column levels ?msgvar? — checks if the tile described by zoom, row, and column is valid for a slippy-based map having that many zoom levels, or not. The result is a boolean value — true if the tile is valid, and false otherwise. In the latter case a message is left in the variable named by msgvar, should it be specified. 🔍
::map slippy valid latitude x — tests if the argument x is a valid latitude value, and returns the boolean result of that test. I.e. true if the value is valid, and false else. 🌐
::map slippy valid longitude x — tests if the argument x is a valid longitude value, and returns the boolean result of that test. I.e. true if the value is valid, and false else. 🌍

🌈 REFERENCES 🌈

[1] http://wiki.openstreetmap.org/wiki/Main_Page — the source of truth, go read it bestie 📚

🎀 KEYWORDS 🎀

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

And that's a wrap on map::slippy(n), brought to you by tcllib, version 0.10 — courtesy of the tcllib crew, no cap. Go map something gorgeous. 💖✨🌸

📦 where this page comes from

fedora 43: tcllib 2.0-3.fc43 · TCL
fedora 44: tcllib 2.0-4.fc44 · TCL
nixos 26.05: tcllib 2.0
nixpkgs unstable: tcllib 2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms