MapTileCacherIMP.perl
version 0.52 (25. Dec. 2009)
Author: tv-arnd (http://www.naviboard.de, http://forum.compegps.com)
License: GPL (Gnu Public License)

This perl programme is based on original MapTileCacher.perl version 1.37 (http://www.mgmaps.com/cache/).
You may check the German Aventura-Wiki for more info on multi-level zoom raster maps (http://wiki.aventura.cx).


What it does
============
After asking several map parameters, the programme downloads plenty of tile-files (256x256-bitmaps as png).
Per zoom-level, these tile-files are combined into (a) png-file(s).
 According to the "Map tiles per file"-setting, the 256x256-tile-files are assembled into larger square png's (can also be called tiles) but also rectangular png's at the right/bottom side (quite smart).
 One CompeGPS imp-file (single zoom-level) is created. This has to be imported into CompeGPS Land software (it referenced one larger png-file).
If multiple zoom-levels have been chosen, additionally one CompeGPS imp-file (multi zoom-level) is created.
This multi zoom-level *.imp-file (references multiple *.rtmap-files and) can be imported into CompeGPS Land software or Aventura hand-held GPS-device!


Prerequisites
=============
Linux: install "ImageMagick"-package and check/set correct path to "montage"-command in "MapTileCacherIMP.perl" (e.g. \usr\bin\montage")
       "MapTileCacherIMP.perl" uses "wget" (should be available on Linux systems)
       Set executable for "MapTileCacherIMP.perl" (chmod +x MapTileCacherIMP.perl)
       Run from directory, where "MapTileCacherIMP.perl" is located (./MapTileCacherIMP.perl)

MacOS X: instructions coming soon

MS Win: later


Quick Instructions
==================
0.  Run the programme.
1.  When asked for "Map tiles per file", enter a reasonable number, for testing e.g. 16.
    (Later you can try 256 or 512, remember to delete the file Cache.conf)
2.  Just press enter all the time, then programme runs with defaults.
3.  Check sub-directory "MGMapsCache/OpenStreetMap_15/" for the map-files created.
    Check that all larger *.png-files (not the individual 256x256-tile-files) contain all tiles and look ok.
    (Later, if you have set more than 1 zoom level, check sub-directory "MGMapsCache/" for the multi-level (ML) IMP-file.)
4.  Copy all *.imp and larger *.png files from the individual directories into ONE directory accessible by CompeGPS Land software (MS Win).
    (Remember: All files into the same dircetory.)
5.  Within CompeGPS Land software, do Menu->Maps->Batch Convert raster maps, select all *.imp files (except the multi-level (ML) zoom imp-file).
6.  Choose "RMAP" in the upcoming dialogue.
7.  CompeGPS Land software now creates as many *.rmap-files (CompeGPS RasterMAP) as you have selected *.imp-files.
    (Now the single-level imp-files and all png-files can be deleted. Do not delete the multi-level (ML) zoom imp-file.)
8.  Rename all the *.rmap-files to the extension .RTMAP, i.e. CompeGPS RasterTileMAP.
    (You might check each individual *.rtmap-file for completeness and readability by loading each file into CompeGPS Land software.)
9.  Within CompeGPS Land software, load the multi-level (ML) IMP-file (only the one ML file)
10. Within CompeGPS Land software use mouse to move around map, use mouse-wheel to zoom in/out (and explore more details when zooming-in). You may have to zoom-in quite far to see the map (esp. if you see a red frame only).
11. Copy the multi-level (ML) IMP-file and the *.rtmap-files to one sub-directory in Aventura's memory-card. (Remember: All files into the same dircetory.)
    On Aventura, open *.imp-file by Menu->Data->Open->"select the directory"->"select *.imp-file".



Known Issues
============
Not tested yet under MS Win. Sould work under MacOS X.

Skipping tiles-download for already downloaded tiles may not be perfect (based on original MapTileCacher.perl concept).
 Delete *.mgm-files in a certain directory to force re-download of tiles and/or delete "Cache.conf".
Not sure, if downloading tiles works reliable for large number of tiles (to handle connection problems, server problems, ...). This will lead to a hick-up (missing tiles disturbe the sequence) in the assemble process (montage should complain, if a tile-file to be assembled is missing).

"Map tiles per file" ($tiles_per_file) is only requested to enter once. Then this is saved in "Cache.conf".
 Delete "cache.conf", if you want the set a different "Map tiles per file".

"Map tiles per file" limits not tested, seems to work ok for 512
 (info: all 256x256-tile-names are passed on to ImageMagick's "montage"-command as command-line parameters, not sure if there's a limit.)

*.mgm-files are still created (does not hurt).
programme still contains several subroutines not essentially required for the purpose of creating *.imp-files (does not hurt).

Works for OpenStreetMap, Osmarender, OpenCycleMap, others (?)


Vison and Open Issues
=====================
MapTileCacherIMP.perl asks for a lower-level zoom and then a number of further zoom-levels (higher levels = zoom-in). It is easy to calculate the next zoom-level and download/arrange the calibration-files (imp). Unfortunately this loads all tiles for all zoom-levels (not too bad), but may this wastes a lot of memory and bandwidth and produces maps-details you may never be interested in.
Nice would be to select an area, one is interested in (a kind of focus/center at a specific high zoom-level), the programme should then download lower zoom-levels (= zoom-out - as a kind of overview maps). Calculating the lower zoom-levels and arrange calibration-files (imp) seems hard.

Image processing on the assembled (larger) png's within MapTileCacherIMP.perl. Especially increasing contrast or invert image.
Postprocessingscript that moves (?) renames and cleans up (deletes obsolte imp and png).

GUI?

CompeGPS rmap introduces ugly compression artifacts for text at high zoom-levels. Would be nice if Aventura could directly work with png's (instead of *.rtmap). Esp. the combination of imp-file and png's would be nice. Or use ecw (allows to set a compression level)? Any idea?

Instead of start-level plus number of further number of zoom-in levels, explicit list of levels wanted, e.g. 9, 12, 14, 15, 16
Instead of name-prefix, a definite name. Opinions?

Batch-rename *.rmap -> *.rtmap. Cannot be part of this "MapTileCacherIMP.perl", because the CompeGPS Land software batch raster-map conversion-process is involed in between. CompeGPS Land software should offer to save as *.rtmap directly.
May use for RMAP->RTMAP:
  Command Prompt: rename *.rmap *.rtmap (in "DOS-Box")
  perl:           for i in *.RMAP; do mv $i $(basename $i .RMAP).RTMAP;done

