proposed README organization
I've been trying to use mkgmap and having a bit of a hard time. I'm a little compulsive about having all the lore be in the source tree, and it seems the README is a bit behind the code. I have a bit of time here and there but not enough to really dig into the code. So I'll be trying to send patches to improve the state of the in-tree documenation after receiving some off-list encouragement to do so. Here's a patch which adds a README.INDEX that describes multiple readme files. If people think this is sane, I will start adjusting the docs to follow this plan and fill in some of the missing pieces, asking for help about the content on the list. I have saved a number of list postings that should be of great help - I am assuming that people do not mind their emails being cut/pasted/edited into READMEs. Besides what I listed below, I think we need a README that explains to a newbie: if you want to make an img from osm data to use, what options should you use and why. Plus probably ones that explain how to get maps into MapSource and RoadTrip. Comments welcome. Index: README.INDEX =================================================================== --- README.INDEX (revision 0) +++ README.INDEX (revision 0) @@ -0,0 +1,49 @@ +$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. + +* 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.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.java + +This file describes how to deal with java, CLASSPATH, which versions +work, etc. + +* README.building + +This file describes how to build mkgmap from source, producing a .jar. Property changes on: README.INDEX ___________________________________________________________________ Added: svn:keywords + Id
receiving some off-list encouragement to do so. Here's a patch which adds a README.INDEX that describes multiple readme files. If people
Besides what I listed below, I think we need a README that explains to a newbie: if you want to make an img from osm data to use, what options should you use and why. Plus probably ones that explain how to get maps into MapSource and RoadTrip.
Comments welcome.
Looks good to me. Thanks ..Steve
Greg Troxel wrote:
I've been trying to use mkgmap and having a bit of a hard time. I'm a little compulsive about having all the lore be in the source tree, and it seems the README is a bit behind the code. I have a bit of time here and there but not enough to really dig into the code. So I'll be trying to send patches to improve the state of the in-tree documenation after receiving some off-list encouragement to do so. Here's a patch which adds a README.INDEX that describes multiple readme files. If people think this is sane, I will start adjusting the docs to follow this plan and fill in some of the missing pieces, asking for help about the content on the list. I have saved a number of list postings that should be of great help - I am assuming that people do not mind their emails being cut/pasted/edited into READMEs.
Besides what I listed below, I think we need a README that explains to a newbie: if you want to make an img from osm data to use, what options should you use and why. Plus probably ones that explain how to get maps into MapSource and RoadTrip.
Comments welcome.
As a new user I also think the documentation needs improvement, and look froward to your contributions. For a utility like this, I agree that having it in the source is most useful. Garvan
As another new user, I would be happy to help out with the documentation as I've had to create a fair bit of my own recently just to get started. Garvan & maew wrote:
Greg Troxel wrote:
I've been trying to use mkgmap and having a bit of a hard time. I'm a little compulsive about having all the lore be in the source tree, and it seems the README is a bit behind the code. I have a bit of time here and there but not enough to really dig into the code. So I'll be trying to send patches to improve the state of the in-tree documenation after receiving some off-list encouragement to do so. Here's a patch which adds a README.INDEX that describes multiple readme files. If people think this is sane, I will start adjusting the docs to follow this plan and fill in some of the missing pieces, asking for help about the content on the list. I have saved a number of list postings that should be of great help - I am assuming that people do not mind their emails being cut/pasted/edited into READMEs.
Besides what I listed below, I think we need a README that explains to a newbie: if you want to make an img from osm data to use, what options should you use and why. Plus probably ones that explain how to get maps into MapSource and RoadTrip.
Comments welcome.
As a new user I also think the documentation needs improvement, and look froward to your contributions. For a utility like this, I agree that having it in the source is most useful.
Garvan
_______________________________________________ mkgmap-dev mailing list mkgmap-dev@lists.mkgmap.org.uk http://www.mkgmap.org.uk/mailman/listinfo/mkgmap-dev
Comments welcome.
I'll add a shout to this - I've spent the last week or so compiling a map of Scotland on Linux with a combination of Groundtruth (for contours - couldn't get mkgmap to work fsr), Mkgmap (for compiling) and QlandKarteGT for selecting and uploading to my Garmin. If any of that is useful info, I can post my work so far, hacky scripts and all. In fact, I may do so anyway, just to get opinions on what I may be doing in-efficiently (almost all of it I suspect :D) Greg
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
I've done some more README work. I am finding a lot of information on
Thanks for this, I'll look through it and let you have my thoughts. One thing that is worthy of note since I see it a lot, is that there is no need for a --net if you also have --route as the route option also creates the net section. Regards, ..Steve
participants (5)
-
Charlie Ferrero -
Garvan & maew -
Greg Sutcliffe -
Greg Troxel -
Steve Ratcliffe