R x: /* Example scripts */

2011-03-12T12:12:44Z

‎Example scripts

New page

= Overview =

This page describes the general use of Map Evaluator. If you are looking for a more detailed description there is a [[Fiddler|step-by-step manual]] showing how to develop a map source using and Map Evaluator and [[Fiddler]] (free, Windows .Net program).

= MOBAC Map Evaluator =

This program allows users to test and develop new map sources.

The latest version of Map Evaluator can be found in the [https://sourceforge.net/projects/mobac/files/Map%20Evaluator files section] here on SourceForge.

Map Evaluator can be started usually by double clicking the file '''Map Evaluator.jar'''. If that does not work you can start Map Evaluator via the following command line: <pre>java -jar "Map Evaluator.jar"</pre>

[[File:MapEvaluator.png|300px|thumb|right|Screenshot of TAC Map Evaluator]]

With only little knowledge about programming (no Java Development Kit required!) this program allows to interactively develop map sources that a more complex that the custom map format allows. Usage is pretty simple:

Modify the code and press the "Execute code" button. If it does not work you can switch back to "Google Maps" or "OSM".
If you use the reset button you can switch start new based on one of the three built in templates (OSM, Yahoo, Microsoft Bing). They show how a more complex example can look alike.

The tool is in an early alpha stage but it may be already useful for some people therefore I am publishing it. Any user feedback about the program is welcome.

== What Map Evaluator is not ==

Map Evaluator is closely related to the Mobile Atlas Creator (MOBAC) application but the developed map scripts from Map Evaluator can not be directly used in MOBAC.
The only way to get a Map Evaluator map script into MABAC is to transform the script into a real Java source code MapSource instance which can be added to the MOBAC source code and then compiled into a new revision of MOBAC. This requires to download MOBAC source code files (best from [https://sourceforge.net/scm/?type=svn&group_id=238075 project SVN]), modify the map sources implementation and finally compile everything (requires Java compiler as it is included in the [http://en.wikipedia.org/wiki/Java_Development_Kit Java Developmenkt Kit (JDK)])

== How to develop a map source ==

=== Trace the existing online map browser ===

The first step on developing a new map source is to find out which URLs are used by the existing website presenting the map.

This can be done for example by using a local proxy such as [http://www.fiddler2.com/ Fiddler (.Net)], [http://portswigger.net/suite/ Burp Suite (Java)], [http://www.owasp.org/index.php/Category:OWASP_WebScarab_Project WebScarab (Java)]. Alternatively you can use the Firefox addon [https://addons.mozilla.org/de/firefox/addon/1843/ FireBug] together with [https://addons.mozilla.org/en-US/firefox/addon/6683/ FireCookie] (optional).

For [[Fiddler]] there is a detailed [[Fiddler|step-by-step manual]] that shows how to grab the improtant map tile image URLs.

=== Check the tile image properties ===

Copy open one of the gathered URLs into your browser's address bar and load the image.
Only square tiles are supported. Ideally the tile size is 256x256 pixel.
...

=== Examine the gathered URLs ===

Next step is to identify how the x and y position on the map is encoded in the tile image URL.

[[File:OSMWorldMap.png|300px|thumb|right|World map example of 4 tiles with marked center]]
Usually there is an x and an y number identifying the tile images in each zoom layer (denoted by the variable z). The origin (x=0, y=0) is on most maps the "upper left corner" - respectively the point where the date border meets the north pole. Therefore the "center" of the map is where the Greenwich Meridian (red line in the image on the right) crosses the equator (blue line).

Therefore in MOBAC the following equations should be true for x, y and z:

* Zoom level 0 shows the world as one tile (20) of size 256x256
* The x and y coordinates on each zoom level should be within the range of 0 and 2z or mathematical [0..2z]

For more details about the map format see also the OpenStreetMap wiki topics [http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames Slippy map tilenames], [http://wiki.openstreetmap.org/wiki/Mercator Mercator], [http://wiki.openstreetmap.org/wiki/Height_and_width_of_a_map Height and width] and [http://wiki.openstreetmap.org/wiki/Zoom_levels Zoom levels]

Additionally there is often a small number in the server name for some load-balancing the downloads across different servers. For testing a map source you most map sources allow it to be static (just use one number and stick to it).

=== ... ===

=== Testing ===

=== Calibration ===

Currently Map Evaluator does not provide the necessary function for calibrate a map. If the map uses different zoom levels that those used by Google and OpenStreetmap the map can not be used.

Therefore test your code: Switching between different map sources (developed map source <-> Google) should only result in displaying the same map region using the different map sources. There must not be a relocation of roads and cities on the map when switching to/from your developed map source to Google. If for example a city is "bouncing" when changing the map source the developed map source can not be used at the moment with MOBAC.

=== Including the developed map source into MOBAC ===

If you managed the steps above and the map is correctly calibrated you can submit your newly developed map source in form of a [https://sourceforge.net/tracker/?group_id=238075&atid=1105497 MOBAC feature request]. Make sure to include the developed map source code into the feature request. If the code is correct, working and interesting for other MOBAc users as well it will be included into the next release.

== [[BeanShellMapSources|Example scripts]] ==

MapEvaluator - Revision history

R x: /* Example scripts */