GroundTruth Manual
This page contains the manual for the GroundTruth mapmaking tool. It describes the information relevant to a latest version of GroundTruth, so if you encounter any problems, please make sure you're running the latest version before submitting any bug reports.
Introduction
Basic Usage
Installing In MapSource
If you have MapSource, you can run the *.reg file which is one of the files generated by GroundTruth to install the generated maps. Then you can upload the map to your GPS unit using the MapSource.
WARNING: as always with registry files, be careful when running them. The author of GroundTruth is not responsible for any damages you may incur to your operating system by running incorrect registry files. If you want to be on the safe side, first make a backup of your registry using some free tool.
Before running the .reg file, you have to update it in a text editor to reflect the location where you unzipped the map ZIP file (otherwise MapSource may fail to start):
REGEDIT4 [HKEY_LOCAL_MACHINE\SOFTWARE\Garmin\MapSource\Families\Slovenia OSM Hiking Map] "ID"=hex:65,1 "TYP"="D:\\Programs\\Gps\\GroundTruth\\Slovenia\\Hiking\\455.TYP" [HKEY_LOCAL_MACHINE\SOFTWARE\Garmin\MapSource\Families\Slovenia OSM Hiking Map\455] "LOC"="D:\\Programs\\Gps\\GroundTruth\\Slovenia\\Hiking" "BMAP"="D:\\Programs\\Gps\\GroundTruth\\Slovenia\\Hiking\\455.img" "TDB"="D:\\Programs\\Gps\\GroundTruth\\Slovenia\\Hiking\\455.tdb"
You have to replace D:\\Programs\\Gps\\GroundTruth\\Slovenia\\Hiking\\ with your own path (make sure you use double backslash (\\) in the path.
NOTE: if you have problems running the MapSource after installing maps, you can use the free MapSetToolkit tool (http://cypherman1.googlepages.com/) to uninstall the individual maps (select the mapset and click on the Uninstall button).
Command Line Interface
getdata Command
Used for fetching OSM data from the OSMXAPI server. You have to specify the extents of the map area to be downloaded by choosing one of the 3 bounds options.
Example:
groundtruth getdata -bu="https://www.openstreetmap.org/?lat=46.4951&lon=15.5395&zoom=12&layers=B000FTF"
bounds Option
Specifies map boundaries in the following order: <minlat>,<minlong>,<maxlat>,<maxlong>.
Example:
-b=10,20.3,15,22.33
boundsbox Option
Specifies map boundaries as a box: <lat>,<long>,<box size in km's>.
boundsurl Option
Specifies map boundaries by using OSM map URL (please put the URL inside double quotes).
Example:
-bu="https://www.openstreetmap.org/?lat=46.4951&lon=15.5395&zoom=12&layers=B000FTF"
outputfile Option
Specifies the name (path) of the output OSM file. The default is output.osm in the current directory.
osmxapiurl Option
Specifies the URL of the OSXMAPI server to use for downloading. The default is http://osmxapi.hypercube.telascience.org/api/0.6/*
NOTE: this option is available from version 1.4.* onwards.
makemap Command
cgp Option
Specifies the directory (not the exe itself!) where cgpsmapper executables are stored. The default is the current directory.
NOTE: when running in Windows mode, GroundTruth uses both cgpsmapper.exe (for generating IMG files) and cpreview.exe (for generating MapSource preview files). In non-Windows mode only the cgpsmapper executable is used.
chartable Option
Specifies the #Character Conversion Tables to use when converting from "national" characters (not supported by most Garmin units) to those that are supported. You can use the table stored locally in a file or from Internet. The default rules used are the ones that come in the ZIP package (Rules/CharacterConversionTable.txt).
Examples:
-chartable="https://wiki.openstreetmap.org/wiki/GroundTruth_Characters_Conversion_Table"
With this GroundTruth will download the latest character conversion table from the dedicated Wiki page. Use this option if your language mappings have not yet been included in the latest GroundTruth ZIP package.
contourrules
The contours rendering rules to use (either a local file path or an OSM wiki rules URL). Examples:
-contourrules=Rules/ContoursRules.txt -contourrules=https://wiki.openstreetmap.org/wiki/GroundTruth_Contours_Rules_(Metric)
If this option is not specified, the default rules that come in the GroundTruth package (Rules/ContoursRules.txt) will be used.
ele Option
Specifies elevation {unit} to use in generated maps (m for meters, f for feet; default is meters).
extimeout Option
Specifies the timeout in minutes for external programs (like cgpsmapper) to execute. The default is 60 minutes, after which the application aborts. If you work on large maps, this default period will probably not be long enough for cgpsmapper to finish its work, so try setting a longer period.
familycode Option
familyname Option
ibffile Option
Specifies that relief contours should be generated using the specified IBF file (which contains contour data). If you want to specify more than one IBF file, repeat this option.
mapid Option
mapname Option
Sets the Garmin map {name} prefix used for all IMG files (each file gets an additional (incremental) suffix ID).
nocpg Option
If this option is set to true, GroundTruth will only produce Polish map and type files, without invoking cgpsmapper to produce the actual Garmin map files. This option is useful for manually tweaking the polish files (which are text files) before converting them to binary IMG and TDB files.
nosea Option
(new in v1.6) Specifies that no coastline processing will be done (i.e. the sea areas will not be rendered and filled as blue polygons). Use this option if you have problems with sea 'flooding' (this typically happens if the OSM coastlines are not complete). Enabling this option basically means GroundTruth will behave in a pre-1.6 fashion.
nonwin Option
Turns on the non-Windows mode (expects a different cgpsmapper executable name; does not generate MapSource-related files). This option should be used on Linux and Mac computers.
optionsfile Option
Allows you to specify command line options in a text file. Each option should be placed in its own line. Here's an example of the file:
-cgp=..\..\..\..\lib\cgpsmapper -upload -sendmapexe=..\..\..\..\lib\sendmap\sendmap20.exe
osmfile Option
A path to the OSM files to generate the map from. Example:
-osmfile=Gondor.osm
You can specify both plain text OSM files or compressed ones (.osm.bz2).
You can use more than one OSM file - each file will get its own corresponding .IMG file. If you specify more than one OSM file, you also need to specify a corresponding unique Garmin map name (using -mapname option) after each OSM file. Example:
-osmfile=Gondor.osm "-mapname=Gondor Garmin Map" -osmfile=Mordor.osm "-mapname=Mordor Garmin Map"
NOTE: since v1.2 the old -osmfiles option has been replaced with -osmfile.
outputpath Option
The directory path where all map output files (IMG, TYP...) will be stored (default is the Maps directory).
param Option
Specifies an additional cgpsmapper parameter for the map. For a complete list of parameters, please consult the cgpsmapper manual. Some examples:
-param=PreProcess:P
specifies a preprocessing mode which does a "full generalization + intersection detection for polylines and polygons", while:
-param=TreSize:4000
specifies "maximum allowed region size" to 4000 (don't ask me, I'm not an cgpsmapper expert :) ).
productcode Option
productname Option
rules Option
The rendering rules to use (either a local file path or an OSM wiki rules URL). If this option is not specified, the default rules that come in the GroundTruth package (Rules/DefaultRules.txt) will be used.
sendmapexe Option
simplifylevel Option
Specifies cgpsmapper's SimplifyLevel value. Has to be a value between 0.1 (fully simplified) and 10 (no simplification). Default value depends on the type of the map. See cGPSmapper's manual for more information about this setting.
transparent Option
Specifies a map transparency mode:
- Y=fully transparent
- S=semi transparent
- N=not transparent).
tresize Option
Specifies cgpsmapper's TreSize value. Has to be an integer. Default value depends on the type of the map. See cGPSmapper's manual for more information about this setting.
Default mode is N. Contour maps are always semi-transparent, regardless of this setting.
typetable Option
upload Option
Instructs GroundTruth to upload maps to the GPS unit after making them. Make sure you have the SendMap program somewhere on your disk (see #sendmapexe Option).
NOTES:
- The existing maps on the unit will be automatically deleted.
- The upload is done in two steps. In the first step a dummy map is uploaded and only then the real maps are sent to the unit. This is done in order to avoid "memory effect" that's sometimes occurs on the unit (the unit sometimes ignores the new TYP file if there has been a previous version of the map has been present on the unit prior to uploading).
contours Command
Generates contour lines from SRTM data. You have to specify the extents of geographical area to be covered by choosing one of the 3 bounds options. You can also specify the elevation interval between two adjacent contours and elevation units to use.
Example:
groundtruth contours -bu="https://www.openstreetmap.org/?lat=46.4951&lon=15.5395&zoom=12&layers=B000FTF"
bounds Option
Specifies map boundaries in the following order: <minlat>,<minlong>,<maxlat>,<maxlong>.
Example:
-b=10,20.3,15,22.33
boundsbox Option
Specifies map boundaries as a box: <lat>,<long>,<box size in km's>.
boundsurl Option
Specifies map boundaries by using OSM map URL (please put the URL inside double quotes).
Example:
-bu="https://www.openstreetmap.org/?lat=46.4951&lon=15.5395&zoom=12&layers=B000FTF"
feet Option
Specifies that feet should be used as elevation units when generating contours. Otherwise (if this option is not specified), meters will be used.
interval Option
Specifies the elevation difference (a real value, in elevation units) between two adjacent contours. The default interval is 20.
Example:
-interval=150 -feet
will make GroundTruth generate contours with 150 feet interval.
outputfile Option
Specifies the name (path) of the output IBF file. The default is output.ibf in the current directory.
ibf2osm Command
Generates OSM contours files from the previously generated contours Isohypse Binary File (IBF). OSM files contain contours (isohypses) represented as OSM ways. Each way is tagged with ele=* tag (and possibly some other tags, depending on the options you use).
Since the IBF file splits contours into rectangular tiled areas, the same splitting is then translated into OSM files too. To put it simply: by default, OSM files which are produced cover 0.25 x 0.25 degrees area (but this can be changed using the gridlat and gridlon parameters for the contours command. One of the benefits of this splitting is that you will no longer suffer with the very long contour ways.
NOTE: ibf2osm is a new (v1.5) command, which is intended to replace the old Srtm2Osm tool (which I (User:Breki) won't be supporting any longer). The contours generation algorithm for GroundTruth has been completely rewritten, certain bugs which were detected in Srtm2Osm have been fixed in GroundTruth, so I suggest switching to this new functionality.
Example:
groundtruth contours "-bu=https://www.openstreetmap.org/?lat=46.4951&lon=15.5395&zoom=12&layers=B000FTF"
cat Option
Adds the contour_ext=* to contour OSM ways. The value of the tag will represent the category of the contour (either elevation_major, elevation_medium or elevation_minor). The category of the contour is determined by defining elevation multiples, example:
-cat=1000,250
...defines that all multiples of 1000 will represent the major category, all (other) multiples of 250 will represent the medium category, and all the rest will belong to the minor category.
The elevation is in units which were specified when the IBF file was generated.
ibf Option
Specifies the IBF file to use to generate contours from (the default is output.ibf).
outputdir Option
Specifies the output directory path where all generated OSM files will be stored (the default is the Output directory).
outputfileformat Option
Specifies the file format of output files. The default is Contours{0}.osm where '{0}' will be replaced with the ID of the file, so for example, you could get the following files: Contours1.osm, Contours2.osm and so on. The ID of the file is generated incrementally, starting from 1.
startid Option
The starting ID to use when generating OSM ways and nodes (the default is 1000000000). The ID is incremented by 1 for each new node/way.
tagce Option
Adds the contour=elevation to contour OSM ways.
Rendering Rules
Where To Store
GroundTruth rendering rules are written as wikitext. You have several options on where to store the rules:
- On your local disk (in text files)
- On OSM Wiki (as Wiki pages) (see Category:GroundTruth Rules)
- Somewhere else (Web server, FTP server...)
GroundTruth command line interface supports loading rules specified as either a file path or an URL.
How To Write
The rules are grouped into 3 groups:
- Rules for areas
- Rules for lines
- Rules for points.
Each of these groups has its own Wiki section, containing a table which lists all rules for this group. Each rule is stored in a separate (single) table row. Each rule has several properties, each of which is stored in its own column.
From version 1.6 onwards there are also some ruleset options you can configure. These options typically act on the whole map and not a particular rule.
Ruleset Options
Ruleset options are stored in a table under Options subsection. They have been introduced in the GroundTruth version 1.6. These options typically act on the whole map and not a particular rule.
The following table is taken directly from rules definitions and contains explanation of each of the option:
| Option | Value | Comment |
|---|---|---|
| RulesVersion | 1.6 | Minimal version of GroundTruth needed to use these rules. GroundTruth will abort if it detects the rules version is newer than your GroundTruth application version. |
| LandBackgroundColor | #FFEFBF | Color of the map background. If not set, the default unit color will be used. If set, a rectangle will be drawn as a background for the map using the color you specified here. |
| SeaColor | #7EC9FF | Color of the sea polygons. |
| ForceBackgroundColor | true | Forces showing of custom the map background color. If you don't want to have a custom map color, set this value to default false. If, however, your map contains coastlines (and you haven't switched off coastline processing with the -nosea command line option), the custom background color will have to be rendered anyway. This is due to how the coastline processor renders sea and land polygons. |
Common Rule Properties
The following properties are common for all types of rules (areas, lines, points...):
| Column Name | Description |
|---|---|
| Rule Name | A unique name of the rule. This can be any text, as long as it's not repeated in other rules. |
| Selector | An expression which is used to tell GroundTruth which OSM elements are to be covered by the rule. Example: {{tag|place|city}} will apply to all OSM elements which are tagged as cities. You can combine several tags using and and or logical operators. You can also negate the expression using the not operator. You can use brackets for grouping.If you want to target relation's tags, you have to add a relation: prefix to a tag selector. Example: relation:{{tag|type|route}} and relation:{{tag|route|bicycle}} and relation:{{tag|network|ncn}} will target all national cycle routes. Depending on the type of the rule (line, point, area), the rule will then be applied to all of relation's ways/nodes/areas.You can mix relation's and non-relation's selectors in a single expression: relation:{{tag|route|bicycle}} or {{tag|cycleway|track}} will select both bicycle route relations and cycleway=track's.
NOTE: an individual OSM element (way, node) can appear in multiple rules. You can, for example, have one rule for drawing hiking trails and the other rule for emphasizing hiking trails which are blazed (marked). See GroundTruth Hiking Map for example on how to do this. |
| Min Level | A minimum zoom level the elements covered by this rule will appear on. If the Garmin unit is zoomed out even more, elements will not be shown (depending on the Detail Level set on your GPS unit). See #Zoom Levels for more info. If this value is not set, the minimum possible zoom level will apply. |
| Max Level | A maximum zoom level the elements covered by this rule will appear on. If the Garmin unit is zoomed in even more, elements will not be shown (depending on the Detail Level set on your GPS unit). See #Zoom Levels for more info. If this value is not set, the maximum possible zoom level will apply. |
| Type Name | If this value is set, it should map to a Garmin type in the Standard Garmin Types table. This enables you to map certain OSM feature into a Garmin type which is most related to it.
If the value is not set, GroundTruth will create a new Garmin type and automatically map this OSM feature to it. Note however that certain Garmin types have a hardcoded behavior which can not be replicated by other types (one example is mountain peak POI type). |
| Label | Specifies the text label that will be associated with map elements covered by the rendering rule. See #Labels for more information. |
Zoom Levels
NOTE: When specifying (and testing) zoom levels for map elements, be sure to have the GPS unit map detail set to Normal. This also applies to viewing maps in MapSource.
Zoom levels used by Garmin GPS are from 24 (meaning a highest zoom level, which will be indicated on the unit as 120 meters or below) to 12 (500 km to 800 km) [1].
Labels
The label consists of one or more parts separated by the ++ character. Example:
name ++ ele
- this is a two part label. The first part of the label will use the value of name=* followed by ele=* (elevation). So the resulting text label will like London 24 or Dead Sea -420, depending on the tag values of each corresponding OSM element. You can use relation's tags by prefixing the tag name with relation:. Example:
relation:name
will use relation's name=* in the label.
Literals
You can also use literals:
"peak" ++ name ++ ele
will result in labels such as peak Everest 8848
Conditionals
Sometimes you only want to display certain literals in combination with a tag value. But what if a map element does not have that tag? Here the conditionals come to the rescue:
name ++ ele "m"
The second part of the label (ele "m") will be displayed only if the element actually has the ele=* tag. Otherwise only the name=* will be shown. Example:
- Element: name=Everest,ele=8848 will be labeled as: Everest 8848 m
- Element: name=Unknown Peak will be labeled as: Unknown Peak
Special Symbols
You can add special symbols to labels. The table bellow describes these symbols:
| Symbol | Description |
|---|---|
| $value | Displays the value of the accompanying tag |
| $elevation | Uses the numerical value of the accompanying tag as an elevation in meters and converts it to the elevation unit specified by the command line option -elevation. This is useful for adding elevation to labels in the units of your choice.
Example: name ++ ele "$elevation" will use ele=* for elevation. So if you set meters as elevation units, the label will be displayed something like Everest 8848 or Everest 29029 for feet. |
| $uppercase | Converts the text value of the corresponding OSM tag into uppercase |
| $01 | Interstate symbol |
| $02 | US Highway - shield
NOTE: this symbol can only be used at the beginning of the label. Everything before the symbol will be ignored by the GPS unit. |
| $03 | US Highway - round symbol
NOTE: this symbol can only be used at the beginning of the label. Everything before the symbol will be ignored by the GPS unit. |
| $04 |  NOTE: this symbol can only be used at the beginning of the label. Everything before the symbol will be ignored by the GPS unit. Example: ref "$04$uppercase" will show ref=* in a box (see sample image on the right). |
| $05 | Main road - middle symbol
NOTE: this symbol can only be used at the beginning of the label. Everything before the symbol will be ignored by the GPS unit. |
| $06 | Main road - small symbol
NOTE: this symbol can only be used at the beginning of the label. Everything before the symbol will be ignored by the GPS unit. |
| $1c | From the cgpsmapper manual: Separation: on the map visible only the first section (when over 1km), with the mouse sees displayed one the word completely, not separated |
| $1e | From the cgpsmapper manual: Separation: on the map visible only the second section (when over 1km), with the mouse sees displayed one the word completely, by blank separated |
| $1f | A delimiter which tells Garmin that the text following this symbol is an elevation. If you use this symbol with a Summit POI type, the unit will only show the elevation part of the label if the user moves the cursor over the icon. Otherwise just the left part of the label will be shown.
Example: name ++ ele "$1f$elevation" |
Rules For Areas
Rules which work on areas (meaning: OSM ways which are closed) are stored in a table under Areas subsection. The order of these rules determines the order of displaying them on your GPS unit: areas targeted by the first rule will be rendered in front of those for subsequent rules. Likewise, areas targeted by the last rule will be displayed in the back.
| Rendering POI icons for areas | |
|
The area rules have the following specialized properties:
| Column Name | Description |
|---|---|
| Colors | A list of colors used to render the area. You can specify up to 4 colors: the first two are used for daytime pattern and the second two for nightime. If you specify only two colors, the daytime and nighttime patters will be the same. If you specify only one color, GroundTruth uses transparency for the color 0 (this is useful if you also specify the pattern for the area).
A color should be specified using the GroundTruthAreaColor Wiki template, example: {{GroundTruthAreaColor|#92CE67}}
NOTE: you should only use hexadecimal #RRGGBB format when specifying colors and not color names (like Red, LightGray etc). |
| Pattern | A bitmap pattern to use for rendering the area. The pattern should consist of several lines of characters. Each character represents a single pixel, the character number indicating which of the specified colors to use on a pixel.
Some rules when specifying area patterns:
1010 0101 |
Rules For Lines
Rules which work on lines (meaning: OSM ways which are not closed) are stored in a table under the Lines subsection. Line rules have the following specialized properties:
| Column Name | Description |
|---|---|
| Colors | A list of colors used to render the line. You can specify up to 4 colors: the first two are used for daytime pattern and the second two for the nightime. If you specify only two colors, the daytime and nighttime patterns will be the same. If you specify only one color, GroundTruth uses transparency for the color 0 (this is useful if you also specify the line pattern).
A color should be specified using the GroundTruthLineColor Wiki template, example: {{GroundTruthLineColor|#92CE67}}
NOTE: you should only use hexadecimal #RRGGBB format when specifying colors and not color names (like Red, LightGray etc). |
| Width | The width of the line (in pixels). If not specified, the line will be 1 pixel wide.
NOTE: this setting is ignored if you also specified the line pattern, since the pattern's height will also determine the width of the line. |
| Border Width | The border width of the line (in pixels). If not specified, the line will not have a border.
NOTE: this setting is ignored if you also specified the line pattern, since the pattern's height will also determine the width of the line. |
| Pattern | A bitmap pattern to use for drawing the line. The pattern should consist of several lines of characters. Each character represents a single pixel, the character number indicating which of the specified colors to use on a pixel.
Some rules when specifying area patterns:
1111001100111100 1111001100111100 |
Rules For Points
Rules which work on points (meaning: OSM nodes) are stored in a table under Points subsection. It should be noted that "Points" rules also work on areas by using a area's center point as a "kind-of-a" OSM node (see #Rules For Areas for more information).
Icon Definitions For Points
The point rules have the specialized property called Icon. It is a link/reference to the definition of the icon. If not set, a standard Garmin icon will be used (but only if the rule points to a standard Garmin type, see Type Names for more information).
In the current GroundTruth version you can only point to an icon which is on the same page, example:
[[#IconPeak]]
Also note that all icon definitions have to be stored under the Patterns section:
== Patterns ==
... and each pattern definition has to be in its own subsection (obviously, since the link has to point to it):
=== IconPeak ===
The icon definition consists of:
- a table of colors used by the icon
- a set of line patterns which define the icon.
A table of colors can have up to 255 colors. Each color is specified in its own table row and it has to have its unique ID (a single character) and the corresponding color (specified using the GroundTruthAreaColor template. Example of a color table row:
| 1 || {{GroundTruthAreaColor|#720065}}
And here's how the table looks like:
| Color ID | Color |
|---|---|
| 1 |
|
| 2 |
|
Once you have the colors specified, you can use them to define the actual icon bitmap:
222202222<br/> 211202112<br/> 211121112<br/> 221111122<br/> 022111220<br/> 221111122<br/> 211121112<br/> 211202112<br/> 222202222<br/>
The maximum width of the icon is 24 pixels/characters. The maximum height of the icon is also 24 pixels/characters. Note also that the '0' character represents a transparent color (which you do not specify in the color table, it's added automatically). So do not use the '0' for your own colors!
Character Conversion Tables
See also: GroundTruth Characters Conversion Table
Standard Garmin Types Tables
see GroundTruth Standard Garmin Types
See also
Links
- IMG File Format - written by John Mechalas
- TDB File Format - written by John Mechalas
- cGPSmapper Manual
- Mapdekode User's Manual