From TrekBuddy Wiki

Jump to: navigation, search

Keep in mind that several tutorials in various languages are linked on the Main Page and may cover similar topics in more detail, for beginners or experts etc.

For a complete guide when creating, visit fundamental HOWTO Maps and Atlases on forums.



For basic information, check out:

Below, you can find more advanced, technical information on maps.

Raster maps

Trekbuddy has support for raster maps. Such a map consists of a raster picture file and a GPS metrics file, known as a calibration file. Map picture format can be any popular graphics format like png, bmp, jpg, tiff etc. More information about digital maps can be found in Wikipedia GIS. Raster maps are prepared with different resolutions in DPI (dot per inch). For mobile phone usage map resolution should be similar to device screen resolution, which is usually 150-200 DPI. Calibration file should be OziExplorer .map format file or Map Calibrator .gmi file. Due to the lack of some data, the second one is only suggested for WGS84 maps mainly. Both programs can be used to produce calibration files for free. Calibrated raster map should be adopted for Trekbuddy usage. Fortunately, easy-to-use Tools like TB Cutter exist to do it. Maps can be included in atlas and grouped as layers, ie road, topo, street plan etc. Atlases and maps can be saved to tar format to reduce number of files.

Map datums and projections

Trekbuddy has some built-in datums and projections to support different maps. Hardcoded datums are WGS84, AGD66, CH-1903, NAD27 (CONUS), OSGB36, Ireland 1965, RT90, S-42(Russia). For other datums custom definitions can be used, with 3-point Molodensky transformation to WGS84 datum. The list of tested custom datums is available in the forum. Similar to datums, Trekbuddy includes a few basic projections, like Mercator, Transverse Mercator (TM) and Universal Transverse Mercator (UTM). Transverse Mercator projection is implemented as definable, so a lot of country specific TM grids can be used. Some other country specific grids are predefined too, like BNG, IG, etc. Information about map datum and projection is taken from a calibration file. If parameters are unknown, TB defaults to the datum selected in settings, default grid is UTM.


The map image maximum size is 1048575 x 1048575 (2^20-1 x 2^20-1 precisely from version 0.9.88; before it was 32512 x 32512).

On Android 2, there is also a 2 GB file size limit, handled by the system. On Android 3 and 4, the file size limit was increased to 4 GB.

Map Calibration

Calibration file should be OziExplorer .map format file or Map Calibrator .gmi file. Due to lack of some data, second one is suggested for WGS84 maps mainly. Both programs can be used to produce calibration files for free.

.map file format

This is the format primarly used by OziExplorer software (shareware). Preferred format for use with Trekbuddy. Format description here.

Sample MAP file:

OziExplorer Map Data File Version 2.2
1 ,Map Code,
WGS 84,WGS 84,   0.0000,   0.0000,WGS 84
Reserved 1
Reserved 2
Magnetic Variation,,,E
Map Projection,Latitude/Longitude,PolyCal,No,AutoCalOnly,No,BSBUseWPX,No
Point01,xy,   25, 1051,in, deg,  66,       0,N,  25,       0,W, grid,   ,           ,           ,N
Point02,xy, 8136, 3426,in, deg,  65,       0,N,  16,       0,W, grid,   ,           ,           ,N
Point03,xy, 5363, 1304,in, deg,  66,       0,N,  19,       0,W, grid,   ,           ,           ,N
Point30,xy, 8235, 5610,in, deg,  64,       0,N,  16,       0,W, grid,   ,           ,           ,N
Projection Setup,,,,,,,,,,
Map Feature = MF ; Map Comment = MC     These follow if they exist
Track File = TF      These follow if they exist
Moving Map Parameters = MM?    These follow if they exist
MMPLL,1, -25.027740,  66.442526
MMPLL,2, -13.090618,  66.442526
MMPLL,3, -13.090618,  63.405895
MMPLL,4, -25.027740,  63.405895
MOP,Map Open Position,0,0
IWH,Map Image Width/Height,10758,7212

Trekbuddy especially relies on these features:

 * 5th line (map datum)
 * Map Projection
 * several PointXY *
 * Map Projection 
 * MMPXY * (can be omitted if several PointXY)
 * MMPLL * (can be omitted if several PointXY)
 * IWH

TODO: informations are to be confirmed.

When TrekBuddy processes OziExplorer calibration file, MMPXY/MMPLL points are preffered because they are easier for precalculations that TrekBuddy does - they are 4 and exactly at map corners. But they are not needed, Point01/2/... are also good. TrekBuddy needs the first few lines with projection info etc., then either at least two Points or MMPXY/MMPLL and IWH. If TrekBuddy finds MMPXY/MMPLL when it parses .map file, it throws Points info away (however, Point lines need to be there; otherwise it throws an exception).

The precision of MMPLL relies on precision of Ozi calculations. Usually a map is calibrated using 2 to 32 distinctive points which may not be exactly at the corners (eg. older Czech hiking maps are such maps where corners are not very suitable for calibration). Great points for calibration are map grid lines.

.gmi file format

This is the format generated by Map Calibrator freeware. Support by Trekbuddy is limited, and .map file should be preferred when possible. sample GMI file:

Map Calibration data file v3.0
Border and Scale


What is an atlas and why use it?

An atlas is a set of maps organized in different layers. One layer may contain many maps. A layer may represent a zoom / detail level, a map type (topo / vector /satellite photo) or any other grouping criteria.

When TrekBuddy displays an arbitrary position or has no connection, you have to select layer and map manually - just like you do select directory and map when loading a map. The big improvement in convenience over maps is when TrekBuddy displays the current position reported from GPS receiver: You only have to select the layer (e.g. zoom level or map type) and TB automatically selects a fitting map out of all maps of the selected layer - you've no longer to be a map jockey when reaching the border of a map, no directory browsing needed any more, and much less scrolling.

Using atlases

In TrekBuddy, you can open atlases with MenuKey->OpenAtlas. In map mode switch layers of current atlas with 7, maps of current layer with 9 key.

Obtaining & Managing atlases

You may download readymade atlases or create it in one of the many possible ways, all belonging to one of the two types:

  • You may use tools like TBMapper (create an atlas out of existing maps or atlases) or like Mobile Atlas Creator or Googleak.NET (create an atlas using sources on the Internet). This three tools - and some more - can be found on Tools page.
  • Alternatively, you may create or maintain an atlas manually as described in this forum post. In short, an atlas is just a file and folder structure like this: You have a directory containing one .tba file (content: Atlas 1.0) and one or many directories (these are the layers). Inside a layer directory, you have one or many directories (these are the map names). In a map directory named <mapname>, you have a normal map consisting of a <mapname>.map and a <mapname>.set file and a directory set containing the image files named like <mapname>_2048_1024.<image_extension>.

Important: Your map doesn't necessarily need to be complete. You can leave out some image files (tiles) that don't contain useful information, like the blue sea. However, TrekBuddy needs at least one file to detect correct tile size, which is the smallest nonzero width and height, so make sure you leave this file.

Important: To avoid getting error messages saying Uri is invalid, be sure to have exactly 4 directory levels (1 = atlas, 2 = layer, 3 = map, 4 = map tiles) and surely Java compatible paths, so not containing spaces.

Hint: When using big atlases or atlases containing JPEG tiles (most suitable for satellite photos), it is very reasonable to manually edit an atlas - it's quick & easy. Reason for this hint: Big atlases usually take a long time to load. For atlases with JPEG tiles, most tools re-encode the JPEGs on each save operation, so you're constantly losing image quality, ultimately resulting in tiles where you'll have difficulties to recognize house borders etc.

GPX File format

Most geo applications allow to read and write files in GPX format, so you can create/modify waypoint collections easily using your own PC. Some information about the format (details at mixed with TrekBuddy-related hints:

  • lat and lon are in decimal degrees, WGS84 datum.
  • Altitude <ele> is in meters
  • Time is UTC, not local time, and spelled in ISO 8601 format. In some applications, e.g. Google Earth, you have to set the visible time interval accordingly (GE: upper area in map) in order to see the wayypoint / track.
  • Snapshots (pictures for waypoints) are stored as links, e.g. <link href="images-2008-07-07-11-47-57/pic-1.jpg" />
  • Further waypoint elements defined in GPX standard are ignored by TrekBuddy, e.g. description <dsc> or waypoint specification <type>. If they appear in the file, TrekBuddy will read the file but not use the additional information.
  • TrekBuddy requires a minimal correctness of XML, so close all tags correctly and use named entities for special characters: &amp; for & and &gt; / &lt; for > / < are mandatory, whereas &apos; for &apos; and &quot; for " are optional. Although xml encoding is set to 'UTF-8', a waypoint file may be stored in ANSI instead of UTF-8 format and still, TrekBuddy will accept it happily.
  • For <name> and comment <cmt> either use only a-z A-Z 0-9 ,.-_ or be absolutely sure your GPX file is encoded correctly in UTF8 (Notepad++: Menu - Format - Encode in UTF-8 without BOM). If file is not in UTF8, a single waypoint with Umlauts or the like will cause TrekBuddy to reject the whole waypoint file and to issue the message No waypoints found in <filename> (up to v0.9.80) or to process waypoint file with "strange" restrictions (since v0.9.81).
  • In tracklogs, TrekBuddy may write <fix> indicating 2d (no elevation information available) or 3d (ele available) navigation and <sat> indicating the number of used, visible satellites.


TrekBuddy 0.9.82b creates and reads GPX waypoint files like this:

<?xml version='1.0' encoding='UTF-8' ?> <gpx version="1.1" creator="TrekBuddy 0.9.79" xmlns="" xmlns:rmc="urn:net:trekbuddy:1.0:nmea:rmc" xmlns:gsm="urn:net:trekbuddy:1.0:gsm"> <wpt lat="47.044470906" lon="8.314939141"> <ele>452.0</ele> <time>2008-06-26T20:39:34Z</time> <name>Luzern, CH</name> <cmt>A nice city in Switzerland next to a big lake</cmt> <link href="images-2008-06-26-20-39-34/pic-1.jpg" /> </wpt> <wpt lat="47.062317960" lon="8.304618467"> <ele>491.0</ele> <time>2008-06-26T22:14:15Z</time> <name>2nd waypoint - Libellenstr</name> </wpt> </gpx>

TrekBuddy 0.9.82b cria e lê arquivos GPX waypoint como este:

  versão <gpx = "1.1" <xml version = '1 'encoding =' 0,0 UTF-8 '?> criador = "TrekBuddy 0.9.79" xmlns = "" xmlns: RMC = "urn: trekbuddy: NET 1.0: NMEA: rmc" xmlns: GSM = "urn : trekbuddy: NET 1.0: GSM "> lat="47.044470906" <wpt lon="8.314939141"> <ele> 452,0 </> elemento <hora> 2008-06-26T20: 39:34 Z </ hora> <name> Luzern, CH </ name> <cmt> Uma cidade agradável, na Suíça ao lado de um grande lago </ cmt> link href <= "images-2008-06-26-20-39-34/pic-1.jpg" / > </ wpt lat="47.062317960" <wpt> lon="8.304618467"> <ele> 491,0 </> elemento <hora> 2008-06-26T22: 14:15 Z </ tempo> <name> segundo waypoint - Libellenstr < / name> </ wpt> </ gpx> </ nowiki> </ pre>

=== Tracklogs ===
TrekBuddy 0.9.81 creates GPX tracklog files like this:

<pre><nowiki><?xml version='1.0' encoding='UTF-8' ?>
<gpx version="1.1" creator="TrekBuddy 0.9.81" xmlns="" 
 xmlns:rmc="urn:net:trekbuddy:1.0:nmea:rmc" xmlns:gsm="urn:net:trekbuddy:1.0:gsm">
      <trkpt lat="47.525141666" lon="7.690080000">
Personal tools