Run.GPS Atlas Format

What is it?

Run.GPS Atlas Format is a high performance archive format that is mainly intended for storing map tiles but can be used to store any data you like.

Main goals:

• extremely fast access to hierarchical data (data stored in folders)
• ability to maintain very large archives (10 GB or more)
• high extensibility - ability to attach any type of binary data or meta information
• cross platform compatibility

Run.GPS Atlas files have suffix .ratlas

Using Mobile Atlas Creator to create Run.GPS Atlas files

Mobile Atlas Creator (MOBAC) is a great tool to download maps from various sources (OpenStreetMap, Google Maps, Yahoo Maps and many others) and convert them to different output formats needed for different software or devices. MOBAC supports the Run.GPS Atlas format.

Download: http://mobac.sourceforge.net/

The usage of this program is described in the manual, see downloads section. Mobile Atlas Creator is published under the terms of the GNU General Public License.

Hint: How to start Mobile Atlas Creator on a Mac

Mobile Atlas Creator comes as a ZIP archive containing an EXE file for Windows and a .sh shell file for Unix. You can start MOBAC by double-clicking the JAR file but then it won't start with the correct memory settings. You can also use the "start.sh" script but you need to use the Terminal for this.

Do this to start MOBAC from Finder or Dock on a Mac:

1. copy the "start.sh" script to "start_MOBAC.command"
2. change it's access rights and make it executable (from Terminal): chmod 755 start_MOBAC.command
3. edit start_MOBAC.command with a text editor and add a "cd" (change directory) to the MOBAC dir:

cd "/Applications/Mobile Atlas Creator 1.9/" 
java -Xms64m -Xmx512M -jar Mobile_Atlas_Creator.jar

Now you can start MOBAC from Finder or the Dock by double-clicking the .command file.

Using the Run.GPSAtlasCreator command line tool to create Run.GPS Atlas files

RunGPSAtlasCreator is a simple command line tool that creates a Run.GPS atlas file from a directory containing map tiles.

Download:

• RunGPSAtlasCreator.jar
• RunGPSAtlasFile.java (full source code)

Usage:

First cd to the directoy containing the zoom level folders (10, 11, 12, ...), then start the RunGPSAtlasCreator:

java -jar RunGPSAtlasCreator <atlas-name> <map-source-name> 

e.g.

java -jar RunGPSAtlasCreator MunichMap OpenStreetMap 

How do I use a Run.GPS Atlas file?

You need Run.GPS Trainer UV version 2.3.8 or higher (or another compatible application). Simply copy the file to your "map_images" directory (e.g. "/sdcard/My Documents/Run.GPS/map_images/" (Win Mobile) or "/sdcard/Run.GPS/map_images" (Android)) and restart the application. The map will then appear in the online map layers in the "Items on Map" dialog.

Why not use one of the common archive file formats?

ZIP archives do use a directory structure, but its corresponding data structure is not hierarchical. You need to read in the whole directory structure to access a single file. This is much too slow for very large archives with 100000 entries or more.

TAR archives can store files in hierarchical data structures, but the directory structure is spread across the entire file, which makes it also too slow to use for fast access to single files.

How are entries accessed in a Run.GPS Atlas file?

A hierarchical numeric structure is used (for reasons of performance).

Example:

You can store a file on /0/0/0/1 or on /76/8665/676/7676.

If you want to store map tiles, the scheme /zoom/x-coordinate/y-coordinate is used.

There's a set of standard keys:

Key	Content	Example
/0/0/0	file format version number	3L
/0/0/1	file type as a string	"Run.GPS Atlas File"
/0/0/2	name of the atlas	"Bavaria"
/0/0/3	map source name	"OpenStreetMap Mapnik"
/0/0/4	created by	"Atlas Creator"
/0/1/1	min zoom	8L
/0/1/2	max zoom	16L

What can be stored in a Run.GPS Atlas file?

You can store any kind of binary data, for example PNG files. In addition to that, single LONG values can be stored (these are stored directly in the index for fast access). STRINGS can also be stored.

What is the file format?

The structure of a Run.GPS Atlas is as follows:

BASIC STRUCTURE
HEADER
INDEX
DATA

The HEADER is 128 bytes of length of which currently only 16 bytes are used. Structure:

Type	Name	Value	Description
long	FILETYPE_KEY	= 8723487877262773L	constant value to help recognize the file format
int	FILE_VERSION	= 3	file format version number, 3 is the current version
int	index size	4444 (example)	contains the total size (in bytes) of the index

The INDEX contains all elements of the directory structure starting with a root entry. All entries have the same data structure:

Type	Name	Description
int	key	the name of the directory entry, e.g. "10" in /10/234/873
long	value	this can be a pointer to the data section, or a file size, or any LONG value
int	next	pointer to the next entry on the same hierarchical level or -1 if that's the last one
int	child	pointer to the first child entry or -1 if that entry has no children

The DATA section simply contains all the concatenated files in the archive.

How large can it be?

The file size of a Run.GPS Atlas Format file is almost unlimited. All pointers and indexes are LONG data types (64 bit). The file size is limited by operating system and file system, however.

Google Android:

The maximum file size is 2 GB. If you have files larger than this, the RandomAccessFile.seek() operation will throw an exception (" value too large for defined data type").