TMJ Raster Tile File Format Specification(*.tmj)

This *.tmj file format is used for storing Raster maps for use in TMJ-Mobile and is the output format of the TMJ-MapOrganiser. It is a very basic format allowing a large raster map image to be split into smaller tiles that are more easily handled on a limited-memory mobile phone.

Source Map

This can be a raster map of almost unlimited size, with certain restrictions:

• The map should be in a simple Equirectangular Projection, with Longitude along the x-axis and Latitude along the y-axis. TMJ-Mobile solely supports this projection in order to vastly simplify the calculations necessary for plotting lat/lng coordinates on top of the map (it is much more efficient to pre-process a map into this projection once via a PC, rather than have the phone do it).
  Note that if the map only covers a *small* area (perhaps a few km along each axis), then a Mercator projection might be satisfactory (as over small distances Mercators Latitude scaling is fairly constant), but the positional error along the y/latitude axis will increase as the map gets larger.

• The Map should be 'edge-aligned', without any border.

• The Minimum and Maximum Latitude and Longitudes must be known.

Map Tiling

To reduce the data that the phone has to load at any single time, the map needs to be pre-split into tiles. An appropriate tile size should be chosen, depending on several factors:

• The phone loads four tiles at a time, therefore the tile size needs to be chosen to at least match the pixel-size of the intended phone screen.

• Using larger tiles will reduce the number of times the phone needs to reload new tiles from the tmj file, but will require more memory on the phone.

• Note that for phones that run TMJ in both landscape or portrait format, the larger of the two pixel dimensions should be used for both the x- and y-tilesize, in order that the tiles will display correctly in both orientations

• The tile size must be a perfect denominator of the original map size, so that the map is split into equal sized-tiles.

• The tiles should be ordered by row (see diagram below), and the exact filesize of each tile must be known.

• The file format of each tile is not limited (and can theoretically change between tiles), but must be supported by the phone (it must be an 'intelligent' format, whereby the phone can easily determine the format from the image byte data, as the file extension is stripped from the file). It is recommended to use 8-bit PNG for standard line-based maps, or 24-bit JPEG tiles for aerial or contour-shaded maps.

Map 'Layers'

The TMJ file format can handled multiple separate maps within a single file. These 'layers' are treated totally independantly by TMJ-Mobile, but can be selected via the [*]/[#] keys. If each layer contains a different scale/zoom of the same map, then this can give the effect of zooming into/out of the map. (TMJ-Mobile is otherwise unable to apply any scaling factor when displaying the map).

File Format

The file has a plain-text ASCII header, terminated by a CR character, followed by raw binary raster data of each tile, placed end-to-end with no padding. The filesizes of each tile are stored in the header and are used to calculate the exact location in the file of each tile, which can then be loaded on demand.

File Header

This is a comma-separated list, with no trailing comma after the last item, and is terminated by a Carriage-Return character (ASCII: 13, Hex: 0x0d). Note that there should be no whitespace between each item.

• TOTAL_NUMBER_OF_LAYERS - the total number of layers in the file (at least 1)

• TOTAL_NUMBER_OF_TILES - the tile count of all tiles (in all layers)

• TILES - the plain ascii text 'TILES'. (Originally reserved for future formats)

• LAYER1_NAME - a name for Layer 1 (plain ascii only, no quotes

or commas), eg 'Map of UK 1:250000'

• LAYER1_TILE_COLUMNS - number of tiles along the x-axis

• LAYER1_TILE_ROWS - number of tiles along the y-axis

• LAYER1_TILE_PIXEL_SIZE_X - horizontal pixel width of each tile

• LAYER1_TILE_PIXEL_SIZE_Y - vertical pixel height of each tile

• LAYER1_MIN_LATITUDE - bounds of the original map

• LAYER1_MIN_LONGITUDE - bounds of the original map

• LAYER1_MAX_LATITUDE - bounds of the original map

• LAYER1_MAX_LONGITUDE - bounds of the original map

• LAYER1_TILES_BYTESIZE_LIST - list of the bytesize of each tile in Layer1

• LAYER2_DATA - if there are further layers (specified by TOTAL_NUMBER_OF_LAYERS) then the next Layer continues (starting at the 'TILES' command above)

• {CR} - Carriage-return character

Binary Tile Data

Following the header and CR character is the raw binary image data of each tile (whether in PNG/JPEG/GIF etc format), in layer, row, then column order (ie L1R1C1, L1R1C2, L1R1C3... L1R2C1, L1R2C2, L1R2C3... L1R3C1, L1R3C2, L1R3C3..., L2R1C1... etc).

Blank Tiles

In order to save space in the file, if there are any tiles that are filled entirely with a single colour (eg areas of ocean, or unmapped/low-detail regions), then these may be omitted from the binary data. They still need to have an entry in the TILES_BYTESIZE_LIST, which should be given as a negative number. The absolute value of the number is then used as a 24-bit 0xRRGGBB colour to fill the space of the tile.

Example File

The World (Simple) file has the following header:

The file has 2 layers, with 10 tiles in total. The first layer (called 'Maps') has 4 columns and 2 rows (8 tiles in total), with a tile size of 320x320 pixels covering an area from 90°S-90°N and 180°W-180°E (ie the entire globe). The 8 tiles in the first layer have 7297, 9506, 8610, 10050, 2021, 4548, 3575 and 5592 bytes respectively.
The 2nd layer (also called 'Maps') has 2 columns and 1 row, with the same tilesize and bounds as the first layer, and its tiles have sizes of 7835 and 9312 bytes.
Afer the Header and CR character the file then has 7297+9506+8610+10050+2021+4548+3575+5592+7835+9312=68346 bytes of image data