Tiles@home/Tileset as one file

From OpenStreetMap Wiki
Jump to navigation Jump to search

This format has mostly been superseeded by v2: Tiles@home/Tileset_as_one_file_v2. The server is able to handle files uploaded in v1 and v2 though.


The current implementation assumes a file format, in which all 1365 tiles of a tileset are clustered together in one file. It consists out of a header, an index, and the image data. Those three parts follow one after the other in the tilesetfile, ie they start at offset 0, 8, and 5472 bytes respectively.

The layer, and base z,x,y values of the tileset file are currently not part of the file itself. That has to be determined by the location the file is stored under.

The endianness is defined to be little-endian.


pack('<BBBBI',FILEVER,0,0,0,userid) (as written by python's [struct module]). (the 3 zeros are not used yet). In perl this is pack("CxxxV")

  • FILEVER is currently always 1 and denotes the version of the OSM file structure
  • userid is the numerical 32-bit ID of the t@h user that uploaded the file. This number will always be set by the t@h server.


1366 times: pack('<I',offset) (perl: pack("V",offset))

Each index (pack('<I'...) denotes an unsigned 32-bit INT) either contains the blankness information of the tile in question (0=unknown, 1=sea, 2=land, 3=transparent), or the offset to the spot in the file where the PNG data of that tile starts. To calculate the length of the PNG file one needs to examine the following offset, it will point to the next PNG start (if it is not blank, if it is blank you will need to examine more offsets until you find a pointer to a real place in the file (ie an offset value > 5472)

There is one more offset (1366) than tiles (1365), the last one will always point to the end of the tilesetfile, so it is guaranteed that there will be at least one non-blank one by skipping ahead tile offsets.

The tiles are ordered by z, y, x. This is to say: left-to-right, top-to-bottoom, lowzoom-to-highzoom. Example:

  • Offset 0 = z12 (0,0)
  • Offset 1 = z13 (0,0), (1,0), (0,1), (1,1)
  • Offset 5 = z14 (0,0), (1,0), (2,0), ...

If the tileset is based at z12 then the location of tile (x,y,z) is: n=z-12; x + (2^n) * y + (4^n-1)/3. This can be adapted obviously to tilesets at other levels.



Please discuss in Talk:Tiles@home/Tileset_as_one_file for future enhancements.

Tileset file sizes

An analysis of tileset file sizes at zoom level 12 in Aug 2008 resulted in the following:

  • analyzed tilesets: 7,217,159 or which 6,993,894 were completly empty sets (ie file size 5472).
  • Summary stats of file sizes including empty tilesets:
|1st Qu.|Median|Mean |3rd Qu.|Max     |
|5472   |5472  |31916|5472   |31335930|
  • Summary stats of file sizes excluding empty tilesets:
|    Min|1st Qu.|Median|Mean  |3rd Qu.|Max     |
|   5575|178400 |506700|907700|1155000|31340000|
  •  # of tilesets bigger the n bytes:
|62912   |3465    |670      |156      |44       |10       |


See [1] and [2] for benchmarks performed by Florian. See [3] for benchmark performed by Jiri.

Update with mod_tah module benchmarks when ready.

Blank tiles

Single blank tiles are embedded in a tileset file as indicated above. Completely blank tilesets are currently stored in file. Empty tilesets at z12 will eventually be removed and their status will be looked up, using oceantiles.dat

How to serve tiles

There is a python and a apache module mod_tah to serve the tilesets.