[mkgmap-dev] proposed README organization

Sat Jul 25 01:52:11 BST 2009

I've done some more README work.  I am finding a lot of information on
wikis, including talk pages, and have tried to link to it rather than
duplicating it, at least for now.

This patch creates all the files, even if some of them have little
content.  I did include an example of making gmapi-format maps for use
with RoadTrip.

I think this is an incremental improvement and that it would be
reasonable to commit this patch.  I intend to keep working on READMEs as
I have time.

    Greg

Index: README.styles
===================================================================

--- README.styles	(revision 0)
+++ README.styles	(revision 0)
@@ -0,0 +1,28 @@
+$Id$
+
+README.styles for mkgmap
+
+mkgmap uses style files to control the transformation from OSM tags to
+Garmin points, polylines, and polygons.  See
+resources/styles/default/*.
+
+* default style
+
+This style is intended to be useful.  If OSM were complete, both in
+features and coverage, and if mkgmap were also complete, then maps
+produced with this style should be able to be used in place of
+proprietary maps.
+
+* noname style
+
+This style is intended to highlight things on the map that need fixing.
+
+TODO: explain the high-level plan for this style.  Or perhaps put that
+as comments in the style file.  Explain how we get red? 
+
+
+* TYP files
+
+Garmin format supports TYP files to control rendering.  TODO: explain
+whether/how mkgmap supports TYP files.
+

Property changes on: README.styles
___________________________________________________________________
Added: svn:keywords
   + Id

Index: README.invoking
===================================================================
--- README.invoking	(revision 0)
+++ README.invoking	(revision 0)
@@ -0,0 +1,7 @@
+$Id$
+
+README.invoking for mkgmap
+
+[TODO: This file should either get the relevant parts of README, and
+then be spiffed up, or point to resources/help/en/options.]
+

Property changes on: README.invoking
___________________________________________________________________
Added: svn:keywords
   + Id

Index: README.sizes
===================================================================
--- README.sizes	(revision 0)
+++ README.sizes	(revision 0)
@@ -0,0 +1,29 @@
+$Id$
+
+README.sizes for mkgmap
+
+* Size constraints
+
+There are two important size constraints for mkgmap.  One is how big
+an osm input file (or each area in it) can be, affecting how much
+memory is required for mkgmap to run.  The other is the size of the
+resulting img tiles.
+
+See README.splitter for information about how to break input files
+into manageable sizes.
+
+* Input sizes
+
+With only 2GB of RAM, processing a 2.4G file (massachusetts.osm) as
+one tile resulted in lots of paging and finally a heap exceeded.
+
+* img sizes
+
+TO BE WRITTEN: what are the limits on img file size?
+
+* Measuring sizes
+
+TO BE WRITTEN: Explain how to take an osm file and see how much
+resources it takes up, both in RAM and in the .img file.  (Perhaps we
+need diagnostic output at the end of mkgamp runs.)
+

Property changes on: README.sizes
___________________________________________________________________
Added: svn:keywords
   + Id

Index: README.installing
===================================================================
--- README.installing	(revision 0)
+++ README.installing	(revision 0)
@@ -0,0 +1,44 @@
+$Id$
+
+README.installing for mkgmap
+
+* Approaches
+
+There are basically three approaches for taking the output of mkgmap
+and installing it on a GPS receiver.  One is to directly use the .img
+file, and the other two are to import tha map data to Garmin's
+proprietary programs for Windows (MapSource) and Mac (RoadTrip).
+
+With the direct .img approach, the receiver will have a single map,
+generated by mkgmap, and no way to switch back and forth.  With
+MapSource and RoadTrip, the OSM map can be installed along with other
+maps, and one can then use the UI on the GPS receiver to switch maps.
+Also, one can view the maps on a computer.
+
+* Direct .img
+
+mkgmap will normally produce a file called "gmapsupp.img".  Place this
+file on the filesystem in the GPS receiver as /Garmin/gmapsupp.img.
+(There is no way to switch among multiple img files from the GPS
+receiver UI.)
+
+* MapSource
+
+[TO BE WRITTEN: This needs some registry voodoo.]
+
+* RoadTrip
+
+TO BE FINISHED:
+
+Garmin provides RoadTrip, a program to view maps, as a no-cost
+download.  RoadTrip is bundled with MapInstaller and MapManager.
+
+  http://www8.garmin.com/support/download_details.jsp?id=4332
+
+ Create an overview map with --tdb and -overviewmap.
+
+ Get http://wiki.openstreetmap.org/wiki/Gmapibuilder and run it.
+
+ open the resulting .gmapi.  In MapManager, install the map.  Then, in
+ RoadTrip the map should be selectable.  In MapInstaller, you should
+ be able to choose tiles from the OSM map.

Property changes on: README.installing
___________________________________________________________________
Added: svn:keywords
   + Id

Index: README.overview
===================================================================
--- README.overview	(revision 0)
+++ README.overview	(revision 0)
@@ -0,0 +1,5 @@
+$Id$
+
+README.overview for mkgmap
+
+WRITEME

Property changes on: README.overview
___________________________________________________________________
Added: svn:keywords
   + Id

Index: README.splitter
===================================================================
--- README.splitter	(revision 0)
+++ README.splitter	(revision 0)
@@ -0,0 +1,23 @@
+$Id$
+
+README.splitter for mkgmap
+
+* Why split?
+
+As one tries to make maps of larger areas, the input files get so
+large that mkgmap's memory usage becomes larger than available memory.
+Additionally, very large .img files become problematic.  See
+README.sizes for details.
+
+* Splitter operation
+
+A program "splitter" is available from
+http://www.mkgmap.org.uk/page/tile-splitter
+
+That page contains documentation about the splitter.
+
+* Suggested paramaters
+
+TO BE WRITTEN: Are the default paramaters what people should be
+using?
+

Property changes on: README.splitter
___________________________________________________________________
Added: svn:keywords
   + Id

Index: README.INDEX
===================================================================
--- README.INDEX	(revision 0)
+++ README.INDEX	(revision 0)
@@ -0,0 +1,61 @@
+$Id$
+
+README.INDEX for mkgmap
+
+This file describes the various README files for mkgmap.  Each file is
+named README.name (where name is lower case) and covers a different
+area of mkgmap usage.
+
+The intent is that everything known about mkgmap will be contained in
+the various README files.  Currently, README.INDEX describes a
+proposed organization.  Files are listed in an order intended to be
+helpful to new users.
+
+* wiki, web pages
+
+http://wiki.openstreetmap.org/wiki/Mkgmap
+http://www.mkgmap.org.uk/page/main
+
+* README.overview
+
+This file describes the purpose of the program and contains
+acknowledgements.
+
+* README.invoking
+
+This file describes every command-line option for mkgmap.  It assumes
+that a .jar already exists and that there are no java issues.
+
+* README.splitter
+
+This file describes how to use the splitter with mkgmap.
+
+* README.examples
+
+This file describes typical ways to run mkgmap.  It is intended to
+cover various normal use cases.
+
+* README.styles
+
+This file describes how the style files work.
+
+* README.sizes
+
+This file contains information about how much memory is needed to
+perform various operations.
+
+* README.img
+
+This files contains pointers to descriptions of the garmin formats.
+It contains links to other related programs and documents.
+
+* README.installing
+
+This file explains how to get maps from mkgmap into GPS receivers via
+USB Mass Storage, via MapSource (Windows) and RoadTrip (Mac).
+
+* README.java
+
+This file describes how to deal with java, CLASSPATH, which versions
+work, etc.  It describes how to build mkgmap from source.
+

Property changes on: README.INDEX
___________________________________________________________________
Added: svn:keywords
   + Id

Index: README.img
===================================================================
--- README.img	(revision 0)
+++ README.img	(revision 0)
@@ -0,0 +1,63 @@
+$Id$
+
+README.img for mkgmap
+
+WRITEME
+
+* Format descriptions
+
+See
+
+  http://sourceforge.net/projects/garmin-img
+
+This site also has a program 'imgdecode' which reads a .img file and
+produces a textual representation of it.
+
+** Codepoints
+
+Besides the structure of files, mkgmap needs to know the codepoints to
+represent different kinds of roads and different POIs.  Information
+about these values is stored in the file:
+
+  resources/garmin_feature_list.csv
+
+The files
+
+  resources/map-features.csv
+  resources/osm_garmin_map.csv
+
+are obsolete and used to be used to convert OSM tags to garmin
+codepoints.  Now, style files are used - see README.styles.  They have
+not been modified in a long time and should perhaps be deleted.
+
+mkgmap has support for generating test maps with lines and points of
+possible codepoints.  Instead of using an OSM file as input, use the
+special input name "test-map:all-elements":
+  java -jar mkgmap.jar test-map:all-elements
+
+Set BASE_LAT and BASE_LON in the environment to control the location
+of the test elements.  See
+http://wiki.openstreetmap.org/wiki/Talk:Mkgmap/dev for more
+information.
+
+* TYP files
+
+TODO: links to TYP editors, and explanations of what TYP files are.
+
+* mapid and familyid values
+
+The .img format has an ID for tiles.  The splitter recommends
+63240001.img as the name of the first tile.
+
+Maps also have a family id code (set with --family-id) that denotes a
+map family.  TODO: Explain whether two maps have to differ in
+family-id or just tile numbers to easily coexist within MapSource and
+RoadTrip.
+
+If one would like to have multiple versions of OSM data installed at
+once, the compiled maps must appear distinct to MapSource and
+RoadTrip.
+
+TODO: Is there a registry of these values?  Is there any way for
+different people who want to produce and distribute Garmin-format maps
+to avoid colliding with each other?

Property changes on: README.img
___________________________________________________________________
Added: svn:keywords
   + Id

Index: README.examples
===================================================================
--- README.examples	(revision 0)
+++ README.examples	(revision 0)
@@ -0,0 +1,41 @@
+$Id$
+
+README.examples for mkgmap
+
+This file contains a number of examples of how to run mkgmap.  It does
+not attempt to label any way correct, but rather to give a number of
+situations and goals and show ways that people think are useful for
+that situation.  It is formatted to enable reasonably easy cut and paste.
+
+* OSM maps for use on garmin
+
+This example is for the goal of producing a maximally usable OSM map
+for Garmin, intended for use rather than to assist with mapping.
+
+# Split the Massachusetts osm file (from cloudmade).
+java -Xmx2000m -jar splitter.jar massachusetts.osm > OUT.01.splitter 2>&1
+
+# Create the map.  Family-id is arbitrary.  Use the areas created by
+# the splitter.  Create an overview map and a tdb file.
+java -enableassertions \
+  -Xmx2048m \
+  -jar mkgmap.jar \
+  --tdbfile \
+  --gmapsupp \
+  --family-id=632 \
+  --overview-mapname=40000001 \
+  --country-abbr="US" \
+  --country-name="United States" \
+  --region-abbr="MA" \
+  --region-name="Massachusetts" \
+  --description="OSM gdt" \
+  --ignore-osm-bounds \
+  --net \
+  --route \
+  --add-pois-to-areas \
+  --remove-short-arcs \
+  -c template.args > OUT.02.mkgmap 2>&1
+
+# Create a gmapi format map given the above map, overview map, and tdb.
+mkdir -p GMAPI
+gmapi-builder.py -o GMAPI -t 40000001.tdb -b 40000001.img -v gmapsupp.img > OUT.03.gmapi 2>&1 

Property changes on: README.examples
___________________________________________________________________
Added: svn:keywords
   + Id

Index: README.java
===================================================================
--- README.java	(revision 0)
+++ README.java	(revision 0)
@@ -0,0 +1,20 @@
+$Id$
+
+README.java for mkgmap
+
+* java versions
+
+The main version of java for which mkgmap is tested is 1.6.
+Java 1.5 should also work.
+
+TODO: Openjdk 1.7 may work.
+
+* building
+
+To build, you must have a JDK and apache ant installed.
+Then, just run "ant", which will produce dist/mkgmap.jar.
+
+* running
+
+To run, you must have a JRE installed.  See README.invoking and
+README.examples.

Property changes on: README.java
___________________________________________________________________
Added: svn:mime-type
   + text/plain
Added: svn:keywords
   + Id
Added: svn:eol-style
   + native


-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 193 bytes
Desc: not available
Url : http://lists.mkgmap.org.uk/pipermail/mkgmap-dev/attachments/20090724/ebdbef14/attachment.bin 
