Tiles@home/Tileset as one file v2

Fileformat

v2 of the tileset format is a mostly backwards compatible extension of v1 (Tiles@home/Tileset_as_one_file).

The current implementation assumes a file format, in which all tiles of a tileset are clustered together in one file. It consists out of a header, an index, the image data, and an optional meta data part. Those four parts follow one after the other in the tileset file. The header and index start at offsets 0 and 8. The offsets for the data parts are determined by the contents of the header.

As a special case of a tileset file the index and data parts can be omitted if all tiles are empty. This case is indicated by the fourth byte of the header (see below).

The endianness is defined to be little-endian.

Header

The header part are the first 8 bytes of the tileset file. They have the following form:

Python's [struct module]: pack('<BBBBI', FILEVER, levels, size, emptyness, userid)

Perl pack("CCCCV, FILEVER, levels, size, emptyness, userid")

• FILEVER is currently always 2 and denotes the version of the tileset file structure
• levels is the number of zoom levels contained in the tileset file
• size is the number of tiles in the topmost zoom level (lowest number)
• emptiness indicates whether all tiles in the tileset are empty and if so whether the whole tileset is empty sea (=1), land (=2) or transparent (=3).
• userid is the numerical 32-bit ID of the t@h user that uploaded the file (which is server internal). This number will always be verified and set by the t@h server based on the uploader id.

Notes: The server only makes limited use of these values:

• It performs a sanity check on FILEVER
• It ignores levels and size, assuming 6 and 1 for all tileset files.
• It honors emptiness insofar as it will delete existing data and display an empty tile based on the servers oceantiles.dat file
• userid will be set to the uploader's user id if it is not already set correctly.

Index

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

Each index denotes an unsigned 32-bit integer and 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 (i.e. an offset value beyond the last index offset)

There is one more offset than tiles, the last one will always point to the start of the meta data part of the tileset file or to the end of the file if there is no meta data part, so it is guaranteed that there will be at least one valid offset by skipping ahead tile offsets.

The tiles are ordered by z, y, x. This is to say: lowzoom-to-highzoom, left-to-right, top-to-bottoom. 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.

The number of index entries is: ni = size^2 * (4^levels - 1) / 3

Therefore, the offset to the last index entry (which is pointing to the start of meta data) is: 8 + 4 * ni

Tile Data

The tile data section contains the raw png data one after the other with no separation. The start of the tile data part of a tileset file is at: 8 + 4 * (ni + 1)

PNGdata1PNGdata2PNGdata3....PNGdatani

Meta Data

The start of the meta data part - if present - of a tileset file is indicated by the last index entry. The meta data reaches to the end of the file. It consists of lines of plain text. Each line is of the form:

Key: Value

Key is all characters (case-independant) before the first colon (:) and Value is all characters (case-dependant) following the first colon up to the end of the line, excluding surrounding white space. All values are stored in their string representation using the 'C' locale. Strings are stored in UTF-8 encoding. Empty lines and lines only containing white space are ignored.

Currently, the following keys are defined:

• Layer is the name of the Tiles@home layer the tileset belongs to
• Zoom is the topmost zoom level (the zoom level of the first tile in the file)
• X is the x coordinate of the first tile in its zoom level
• Y is the y coordinate of the first tile in its zoom level
• Osm-Timestamp is the Unix timestamp from when the OSM data was downloaded by the client
• User-Id is the user ID of the uploading user, this is set by the server

--Matthiasj 19:08, 23 September 2008 (UTC)