Index: doc/index.txt
===================================================================
--- doc/index.txt (revision 4501)
+++ doc/index.txt (working copy)
@@ -38,9 +38,9 @@
[/doc/pdf/style-manual.pdf '''Style Manual'''] [pdf]
This is the complete documentation of the style rules that determine how
-the OSM taged features are converted into the Garmin features.
+the OSM tagged features are converted into Garmin features.
-[/doc/typ-compiler '''TYP compiler manual''']
+[/doc/typ-compiler '''TYP Compiler Manual''']
This documents the language that is accepted by the TYP compiler that
is included within mkgmap.
@@ -48,5 +48,8 @@
Instructions on how to control messages that are logged and to where
they are written.
-For other documentation go to the Open Street Map wiki for documentation
-[http://wiki.openstreetmap.org/wiki/Mkgmap here]
+[/doc/logging '''Tuning''']
+Instructions on how to minimise execution time and avoid running out of memory.
+
+Further information can be found in the
+[http://wiki.openstreetmap.org/wiki/Mkgmap '''Open Street Map wiki''']
Index: doc/options.txt
===================================================================
--- doc/options.txt (revision 4501)
+++ doc/options.txt (working copy)
@@ -15,11 +15,10 @@
heap memory required increases proportionally with the number of CPU
cores being used. The default value may not be sufficient to allow
mkgmap to use all the available CPU cores, which will cause the run time
-to be longer than necessary. To allow mkgmap to run optimally, you may
+to be longer than necessary or can cause mkgmap to crash if it runs out
+of memory. To allow mkgmap to run optimally, you may
need to use this option to allow more memory to be allocated to the Java
-heap. Typically, mkgmap requires about 500MB per core, so an 8-core
-processor might need to specify -Xmx4g - note there is no space or
-equals sign in the option.
+heap. Note there is no space or equals sign in the option.
;-enableassertions
;-ea
@@ -113,7 +112,7 @@
Placing the mkgmap --description option after -c template.args ensures that the
value is applied to gmapsupp.img.
-Different GPS devices, MapSource, Basecamp and QLandkarte handle descriptions
+Different GPS devices, BaseCamp and QLandkarte handle descriptions
inconsistently. Some display the description when selecting maps or tiles,
others use the family name.
@@ -153,17 +152,8 @@
=== Address search options ===
;--index
-: Generate a global address search index. If the --gmapsupp option is
-also given, then the index is generated within the resulting
-gmapsupp.img file so that address search will work on a GPS
-device.
-
-If both the --gmapsupp and any of --tdbfile, --gmapi, or --nsis options
-are given alongside the --index option, then both indexes will be created.
-Note that this will require roughly twice as much memory.
-
-If the map is sent to the device by MapSource, it will enable
-find by name and address search on the GPS.
+: Generate an address index to allow searches by address.
+The default is to not create an address index.
: The address fields are assigned by special mkgmap address
tags using the style file:
@@ -422,7 +412,7 @@
: The version of the product. Default value is 100 which means version 1.00.
;--series-name=name
-: This name will be displayed in MapSource in the map selection
+: This name will be displayed in BaseCamp in the map selection
drop-down. The default is "OSM map".
;--area-name=name
@@ -491,11 +481,11 @@
=== Hill Shading (DEM) options ===
-: Hill Shading is rendered by PC programs (MapSource or BaseCamp) or GPS devices
+: Hill Shading is rendered by BaseCamp and GPS devices
when the map includes a Digital Elevation Model (DEM). Use the following options
to add a DEM to the map and control its characteristics. DEM creation requires
files containing height information for the area covered by the map, the so
-called hgt files, which typically cover 1 degree latitude * 1 degree longitude
+called hgt files, which typically cover 1 degree latitude by 1 degree longitude
and are named by the coordinates of their bottom left corner (e.g. N53E009). They
contain height information in a grid of points. Typical hgt files contain either
1 arc second or 3 arc second data. 3 arc second files have 1201 x 1201 points, which means
@@ -508,16 +498,15 @@
files containing *.hgt files. Directories are searched for *.hgt files
and also for *.hgt.zip and *.zip files.
: The list is searched in the given order, so if you want to use 1 arc second files
-make sure that they are found first. There are different sources for *.hgt
+make sure that they are found first. There are different sources for hgt
files, some have so called voids which are areas without data. Those should be
avoided.
;--dem-dists=number[,number...]
-: If given, the option specifies the resolution(s) or zoom level for the DEM
-data. If not given, mkgmap tries to determine a reasonable value based on the
-resolution found in the *.hgt files. For desktop programs like MapSource or
-Basecamp you only need one zoom level, for GPS devices you need one for each
-resolution given with the --levels option. The actual values are given as
+: If given, the option specifies the resolution(s) for the DEM data.
+If not given, mkgmap determines a single value based on the resolution of the hgt files.
+For BaseCamp you only need one value; for GPS devices you need one for each
+resolution given with the --levels option. The actual values are the
distance between two DEM points and should be a multiple or submultiple of the
distance between two points in the hgt file, that is 3314 for 1 arc second and 9942 for
3 arc second. Higher distances mean lower resolution and thus fewer bytes in the map.
@@ -558,9 +547,7 @@
in the CPU. If no value is specified, the limit is set to the number of CPU
cores. The default is for the limit to be automatically set to a reasonable
value based on the amount of memory allocated to the Java runtime and the
-amount used in processing the first tile. To optimise mkgmap to use all
-available CPU cores, you may need to use the Java -Xmx option to increase
-the amount of available heap storage.
+amount used in processing the first tile.
;--keep-going
: Don't quit whole application if an exception occurs while
@@ -777,7 +764,7 @@
blocker (default 20)
:;fbratio=NUM
:: only sea polygons with a higher ratio
-(highway points * 100000 / polygon size) are removed
+(highway points x 100000 / polygon size) are removed
(default 0.5)
:;fbdebug
:: switches on the debugging of the flood blocker
@@ -790,7 +777,9 @@
;--nsis
: Write a .nsi file that can be used with the Nullsoft Scriptable Install System
-(NSIS) to create a Windows Mapsource Installer.
+(NSIS) to create a Windows Installer for using the map in BaseCamp.
+It looks for an installer template and license file template in the resources and resources\installer folders.
+Note that it does not use the license file specified in --license-file.
;--make-opposite-cycleways
: Some one-way streets allow bicycle traffic in the reverse
@@ -859,14 +848,14 @@
: Ignore all tags for which the value matches the regular expression pattern "(?i)fix[ _]?+me".
;--tdbfile
-: Write files that are essential to running with MapSource, a .tdb file and
+: Write files that are essential to running with BaseCamp; a .tdb file and
an overview map. The options --nsis and --gmapi imply --tdbfile.
;--show-profiles=1
-: Sets a flag in tdb file. The meaning depends on the availability of DEM
+: Sets a flag in the tdb file. The meaning depends on the availability of DEM
data (see "Hill Shading (DEM) options").
-: Without DEM data the flag enables profile calculation in MapSource or
-Basecamp based on information from contour lines.
+: Without DEM data the flag enables profile calculation in BaseCamp based on
+information from contour lines.
: If DEM data is available the profile is calculated with that
information and the flag only changes the status line to show the height when
you hover over an area with valid DEM data.
Index: doc/tuning.txt
===================================================================
--- doc/tuning.txt (nonexistent)
+++ doc/tuning.txt (working copy)
@@ -0,0 +1,9 @@
+=== Tuning ===
+
+Building a map is a resource intensive process that may take several hours to complete. To minimise execution time and make sure the process does not run out of memory, it is necessary to tune the process using command line options.
+
+Mkgmap is designed to allow multi-threaded operation and, providing sufficient memory is available, will complete in the shortest time if the number of threads used is the same as the number of CPU cores available. Each input file is processed in a separate thread with a scheduler determining when a thread is available for use and which input file is next to be processed. You can specify the maximum number of threads to be used by mkgmap with the --max-jobs option. If you do not specify this option, mkgmap will attempt to determine how many threads it can handle simultaneously by dividing the available heap memory by the amount of memory used when processing the first input file on the command line. In this case, it is important to make sure that the first input file is representative of the other files. If one of your input files is a typ file and you do not specify –max-jobs in your command line, make sure that the typ file is not the first input file specified. As typ file compilation uses few resources this would be likely to lead mkgmap to believe it could run more simultaneous jobs than is realistic.
+
+If mkgmap crashes with a message that it is out of memory, or it does not use all the available cores, you may need to allow it to use more memory. Typically, mkgmap requires about 500MB of heap memory per thread, so an 8-core processor might need 4GB memory to be allocated to the Java heap. You can specify the maximum Java heap size using the –Xmx Java option. Note that this option needs to be specified before –jar mkgmap.jar, unlike the mkgmap options, which are specified after. The format is –Xmx[g|G|m|M|k|K] where g, m and k indicate gigabytes, megabytes and kilobytes respectively, so to specify 4GB use –Xmx4g. Note that there is no space or equals sign in this option.
+
+After processing all the input files, any required processes that operate on all tiles are undertaken. This includes generating a gmapsupp.img file if –gmapsupp is specified and creating indexes if –index is specified. If the --gmapsupp and –index options are both specified along with any of --tdbfile, --gmapi, or --nsis then two indexes will be created. This is likely to require roughly twice as much memory. If you run out of memory at this stage, rather than increasing the amount of memory you may find it beneficial to separate these into separate commands, with –gmapsupp and –index in one command and –index and --tdbfile, --gmapi, or –nsis in another.
Index: resources/help/en/options
===================================================================
--- resources/help/en/options (revision 4501)
+++ resources/help/en/options (working copy)
@@ -15,10 +15,10 @@
required increases proportionally with the number of CPU cores being used.
The default value may not be sufficient to allow mkgmap to use all the
available CPU cores, which will cause the run time to be longer than
- necessary. To allow mkgmap to run optimally, you may need to use this
- option to allow more memory to be allocated to the Java heap. Typically,
- mkgmap requires about 500MB per core, so an 8-core processor might need to
- specify -Xmx4g - note there is no space or equals sign in the option.
+ necessary or can cause mkgmap to crash if it runs out of memory. To allow
+ mkgmap to run optimally, you may need to use this option to allow more
+ memory to be allocated to the Java heap. Note there is no space or equals
+ sign in the option.
-enableassertions
-ea
@@ -111,9 +111,9 @@
from the mkgmap command line. Placing the mkgmap --description option after
-c template.args ensures that the value is applied to gmapsupp.img.
- Different GPS devices, MapSource, Basecamp and QLandkarte handle
- descriptions inconsistently. Some display the description when selecting
- maps or tiles, others use the family name.
+ Different GPS devices, BaseCamp and QLandkarte handle descriptions
+ inconsistently. Some display the description when selecting maps or tiles,
+ others use the family name.
--country-name=name
Set the map's country name. The default is "COUNTRY".
@@ -150,17 +150,9 @@
=== Address search options ===
--index
- Generate a global address search index. If the --gmapsupp option is also
- given, then the index is generated within the resulting gmapsupp.img file
- so that address search will work on a GPS device.
+ Generate an address index to allow searches by address. The default is to
+ not create an address index.
- If both the --gmapsupp and any of --tdbfile, --gmapi, or --nsis options
- are given alongside the --index option, then both indexes will be created.
- Note that this will require roughly twice as much memory.
-
- If the map is sent to the device by MapSource, it will enable find by name
- and address search on the GPS.
-
The address fields are assigned by special mkgmap address tags using the
style file:
mkgmap:country
@@ -410,8 +402,8 @@
The version of the product. Default value is 100 which means version 1.00.
--series-name=name
- This name will be displayed in MapSource in the map selection drop-down.
- The default is "OSM map".
+ This name will be displayed in BaseCamp in the map selection drop-down. The
+ default is "OSM map".
--area-name=name
Area name is displayed on Garmin units (or at least on eTrex) as the second
@@ -476,18 +468,18 @@
=== Hill Shading (DEM) options ===
- Hill Shading is rendered by PC programs (MapSource or BaseCamp) or GPS
- devices when the map includes a Digital Elevation Model (DEM). Use the
- following options to add a DEM to the map and control its characteristics.
- DEM creation requires files containing height information for the area
- covered by the map, the so called hgt files, which typically cover 1 degree
- latitude * 1 degree longitude and are named by the coordinates of their
- bottom left corner (e.g. N53E009). They contain height information in a
- grid of points. Typical hgt files contain either 1 arc second or 3 arc
- second data. 3 arc second files have 1201 x 1201 points, which means files
- contain 2 x 1201 x 1201 = 2,884,802 bytes. 1 arc second files have 3601 x
- 3601 points, with a file size of 25,934,402 bytes. Other files are
- supported as long as the formula sqrt(filesize/2) gives an integer value.
+ Hill Shading is rendered by BaseCamp and GPS devices when the map includes
+ a Digital Elevation Model (DEM). Use the following options to add a DEM to
+ the map and control its characteristics. DEM creation requires files
+ containing height information for the area covered by the map, the so
+ called hgt files, which typically cover 1 degree latitude by 1 degree
+ longitude and are named by the coordinates of their bottom left corner
+ (e.g. N53E009). They contain height information in a grid of points.
+ Typical hgt files contain either 1 arc second or 3 arc second data. 3 arc
+ second files have 1201 x 1201 points, which means files contain 2 x 1201 x
+ 1201 = 2,884,802 bytes. 1 arc second files have 3601 x 3601 points, with a
+ file size of 25,934,402 bytes. Other files are supported as long as the
+ formula sqrt(filesize/2) gives an integer value.
--dem=path[,path...]
The option expects a comma separated list of paths to directories or zip
@@ -495,23 +487,21 @@
also for *.hgt.zip and *.zip files.
The list is searched in the given order, so if you want to use 1 arc second
files make sure that they are found first. There are different sources for
- *.hgt files, some have so called voids which are areas without data. Those
+ hgt files, some have so called voids which are areas without data. Those
should be avoided.
--dem-dists=number[,number...]
- If given, the option specifies the resolution(s) or zoom level for the DEM
- data. If not given, mkgmap tries to determine a reasonable value based on
- the resolution found in the *.hgt files. For desktop programs like
- MapSource or Basecamp you only need one zoom level, for GPS devices you
- need one for each resolution given with the --levels option. The actual
- values are given as distance between two DEM points and should be a
- multiple or submultiple of the distance between two points in the hgt file,
- that is 3314 for 1 arc second and 9942 for 3 arc second. Higher distances
- mean lower resolution and thus fewer bytes in the map. Reasonable values
- for the highest resolution should not be much smaller than 50% hgt
- resolution, that is somewhere between 1648 and 5520 for 1 arc second hgt
- input files (3312 is often used), and 5520 to 9942 for 3 arc second hgt
- input files.
+ If given, the option specifies the resolution(s) for the DEM data. If not
+ given, mkgmap determines a single value based on the resolution of the hgt
+ files. For BaseCamp you only need one value; for GPS devices you need one
+ for each resolution given with the --levels option. The actual values are
+ the distance between two DEM points and should be a multiple or submultiple
+ of the distance between two points in the hgt file, that is 3314 for 1 arc
+ second and 9942 for 3 arc second. Higher distances mean lower resolution
+ and thus fewer bytes in the map. Reasonable values for the highest
+ resolution should not be much smaller than 50% hgt resolution, that is
+ somewhere between 1648 and 5520 for 1 arc second hgt input files (3312 is
+ often used), and 5520 to 9942 for 3 arc second hgt input files.
Example which should work with levels="0:24, 1:22, 2:20, 3:18":
--dem-dists=3312,13248,26512,53024
This was found in a Garmin Demo map for transalpin data created 2009.
@@ -546,9 +536,7 @@
in the CPU. If no value is specified, the limit is set to the number of CPU
cores. The default is for the limit to be automatically set to a reasonable
value based on the amount of memory allocated to the Java runtime and the
- amount used in processing the first tile. To optimise mkgmap to use all
- available CPU cores, you may need to use the Java -Xmx option to increase
- the amount of available heap storage.
+ amount used in processing the first tile.
--keep-going
Don't quit whole application if an exception occurs while processing a map
@@ -759,7 +747,7 @@
at least so many highway points must be contained in a sea polygon so
that it may be removed by the flood blocker (default 20)
fbratio=NUM
- only sea polygons with a higher ratio (highway points * 100000 /
+ only sea polygons with a higher ratio (highway points x 100000 /
polygon size) are removed (default 0.5)
fbdebug
switches on the debugging of the flood blocker generates GPX files for
@@ -771,7 +759,10 @@
--nsis
Write a .nsi file that can be used with the Nullsoft Scriptable Install
- System (NSIS) to create a Windows Mapsource Installer.
+ System (NSIS) to create a Windows Installer for using the map in BaseCamp.
+ It looks for an installer template and license file template in the
+ resources and resources\installer folders. Note that it does not use the
+ license file specified in --license-file.
--make-opposite-cycleways
Some one-way streets allow bicycle traffic in the reverse direction and
@@ -835,14 +826,14 @@
"(?i)fix[ _]?+me".
--tdbfile
- Write files that are essential to running with MapSource, a .tdb file and
- an overview map. The options --nsis and --gmapi imply --tdbfile.
+ Write files that are essential to running with BaseCamp; a .tdb file and an
+ overview map. The options --nsis and --gmapi imply --tdbfile.
--show-profiles=1
- Sets a flag in tdb file. The meaning depends on the availability of DEM
+ Sets a flag in the tdb file. The meaning depends on the availability of DEM
data (see "Hill Shading (DEM) options").
- Without DEM data the flag enables profile calculation in MapSource or
- Basecamp based on information from contour lines.
+ Without DEM data the flag enables profile calculation in BaseCamp based on
+ information from contour lines.
If DEM data is available the profile is calculated with that information
and the flag only changes the status line to show the height when you hover
over an area with valid DEM data.