YAMA Yet Another Map Application

author - Schmidt András

7 October 2007

Az oldal magyarul: documentation-hu-html.html


Contents

Introduction

Welcome to YAMA, Yet Another Map Application. It is a map viewing application intended for use on PC, PDA, OpenMoko. YAMA uses a vector based map model to render the map.

YAMA also includes a converter that converts existing maps to YAMA own format (see [*]).

Current state of YAMA is pre-alpha, so it is not recommended for everyday users yet. Release can be downloaded from sourceforge http://sourceforge.net/projects/yamamap. If you would like to use the lates version you have to compile it from source. Source of the application is in the project's SVN version control system on sourceforge.net http://sourceforge.net/projects/yamamap.

There is a single release zip file that contains all platform release files. There is release for the following platforms:

Release is planned for the following platforms:

user's guide

This section is the user guide for YAMA. If you want just use it (certainly you are impatient), this is your section to read.

YAMA has a release for JavaSE and a release for .NET CF. The two versions are in separate sections.

Java version

Currently a Java JRE version 5 is required to run YAMA. You should find a JRE for your operating system. If you don't know where to obtain one, I recommend start at: http://java.sun.com/javase/downloads/index.jsp.

online usage

YAMA has an online version. To use the online version you will need a browser with Java applet support.

The online version of YAMA uses the same controls as the standalone version.

standalone use

YAMA can be used as a standalone Java application on your PC. To start YAMA as astandalone application you have to:

  1. locate the yama.jar file (download from sourceforge)
  2. yama.jar should start by double clicking it in your file browser (at least on user friendly operating systems such as Ubuntu).
  3. alternatively it can be started by typing:
    java -jar yama.jar
    
  4. When started YAMA will show an empty frame. First you have to load a map to browse it. See [*]

controls

This section describes how the user can browse the map in the standalone or web interface. The PDA version has a different interface as PDA is used with thumb or stylus instead of a mouse.

load map

When in standalone mode it is possible to load maps. Maps are a set of files stored in a directory. Map directories contain a contents.xml file that must be located by the user. If you have no map available in YAMA format, but in other format, read [*] to see if (and how) you can compile it into YAMA format.


compile a map

This section is about importing a map into YAMA format. The YAMA application only shows maps in this format, so this is the first step if you don't have a map in YAMA format already.

Currently there is importer for Polish Text file format. This is a widely used proprietary format for maps. cgpsmapper.exe can be used for exporting Garmin .img files into polish text format.

Polish text format defines a set of object types. People who draw maps use these object in their own dialect. The mapping from object types on the map to YAMA object types may be inaccurate. You have to choose a type mapping file for the conversion. I recommend selecting the best fit from the existing ones (found in the release package) then modifying it to fit exactly. The selected typeMap file must be copied to the directory where the input .mp file is located with name: "typemap.xml". If you don't specify a typemap file, YAMA uses a default one.

compiling

When compiling the whole map is loaded into memory. That means that the process will need much memory. The exact number must be experimented, in general you should add much memory for the process and try it. If it fails you can add more. So start the program this way (from command line in the directory where yama.jar is located):

java -Xmx512M -jar yama.jar

This command will add a maximum of 512 megabytes of memory to the JVM.

Next step is to localize your ``.mp'' polish text file. Click on convert button and in the file selector choose the file. After selecting the file, conversion is started immediately. The process of compilation can be folowed on the console of the application.

The output directory is located in the same directory where the ``.mp'' file is located. When you convert ``mymap.mp'' then a directory called ``mymap'' will be created. This directory will contain contents.xml file and levelxxx directories. The levelxxx directories contain the little rectangles of the map on different detail levels. All these files are required to view the map in the application.

making it available

YAMA is open source software with intention to be used by as many as possible. If you convert a map into YAMA format and the licence of the map allows it, please think of sharing it with the public! Upload the generated files on a public web server packed (eg tar.gz) and eventually also unpacked. Unpacked maps can be browsed by users without loading down them (see [*]). That is easy for the user to check whether she/he needs this map or not. Also I believe this method consumes more network bandwidth.

You can also make the map available for online browsing. To achieve this you must upload and configure (just a few parameters) the applet version of YAMA.

install map for online browse as applet

This section describes how to install an online YAMA map viewer on your web server.

If you would like to share a map but you don't have an own web server don't worry. YAMA requires no server side function (just publishing files) and the map files are divided into small parts. So maps can be installed on publicly available free web servers easily (even on servers with file size limit). So just register yourself on a free web server and follow the manual below!

What you need for installing a map:

We assume that you will install two maps. Steps are:

  1. Create a directory for your map applet on your server. (eg map/)
  2. Create a directory for your first map. (eg map/map1)
  3. Create a directory for your second map. (eg map/map2)
  4. Copy the map files into the directories. (So the first map's contents.xml is at map/map1/contents.xml)
  5. Copy yama.jar into map/
  6. Create the index.html file and copy into map/

The contents of the example index.html:

<html>
	<body>
		<h2>Yama - Yet Another Mapping Application by Schmidt András </h2>
<applet 
  width="640" height="640"
	archive="yama.jar"
	code="hu.schmidtsoft.map.render.YamaApplet"
	>
	<param name="mapUrl" value="map1/contents.xml,map2/contents.xml"/>
</applet>
</body>
</html>

In the example the width and height parameters and the map file URL-s must be replacedwith your own. In the mapUrl param you can reference any number of maps divided by a single comma. Full (http://...) or relative URL can be used. Most applet viewer security configurations only allow applets to download resource from their home server so only relative URL's on the same server should be used.

PocketPC (.NET CF) version

The .NET version of YAMA contains no map converter, it is only a map viewer. Currently there is only release for PocketPC.

installing

YAMA has no installer. You have to copy all files manually to your PocketPC.

.NET CF 2.0

YAMA requires .NET CF 2.0. It can be installed for Windows Mobile 3 and later. You can download it from Microsoft's pages and install it first on your PC, then on PDA using activesync. It is an ugly hack from MS.

directory structure

You will need a home directory for YAMA. The home directory contains the following files:
yamaHome/
 types.xml - definition of all object types and their render style - Required
 typemap.xml - a default type map. - Required
 custompois.xml - your own POI's - Optional
 maps/ - directory of all maps
  map1/ - directory of the first map (its name can be anything)
   contents.xml - the manifest of the first map
   levelXXX/ -  the XXX detail level of the map
    cutXXXXXX - a small part of the detail level of the map
   typemap.xml - type map of the map
  anymap2/ - directory of the second map 
   ... - all maps have the same structure

The types.xml and typemap.xml file are part of the distribution package.

"custompois.xml" will be created by the software when using it.

"maps" directory must be created by hand

the map subdirectories under the "map" directory are the maps in YAMA format. They can be generated from polish text format using: [*].

configuration file

The configuration file is first searched at: "
Storage Card
yama
yamaConfig.xml", then at "yamaConfig.xml". The yamaConfig.xml file contains the path to yamaHome and the COM port of GPS receiver. A sample config file is part of the distribution package. You have to modify it by hand and copy it to your desired location.

exe file

The exe file can be copied to anywhere on your Pocket PC and executed by clicking once in file explorer of your PDA. It is part of the distribution package.

After creating the home directory, config file and copiing the exe it should work. (hint: if your PocketPC calls your SD card Storage Card, then extracting the release zip into "
Storage Card" will configure it fully. The zip file contains a yama root directory)

how to contribute

If you like YAMA and intend to contribute you can :-). The chapter describes how you can contribute to YAMA project.

When you have any comment on YAMA please feel free to post on YAMA's forum at sourceforge or send me an email ([*]).

as user

If you are a user of YAMA you are a tester of YAMA as well. Testing a software is very valuable contribution. When you use the software and find an issue you should post a bug report on the bug tracker of YAMA. What you can report:

To report the bug or a wish you should use the infrastructure provided by sourceforge [*]. You can also start discussion on the sourceforge forum of the project on the same url.

as map converter

If you convert a map for YAMA you can contribute the following way:

If you have created a new map translation or a skin, please contact me ([*]). I will add the skin to the next release and link to the translated maps.


contact

Currently YAMA is developed by a single person. You can contact me and other users of YAMA using the following:

developer's guide

This section is a guide for developers who would like to compile and develop YAMA. The section describes how to set up and use the environment, and is not documentation for the source code.

obtaining the code

YAMA is hosted at http://sourceforge.net/projects/yamamap. Its project unix name is yamamap. The source code is handled by the sourceforge SVN server. Its URL is: https://yamamap.svn.sourceforge.net/svnroot/yamamap. It can be checked out by anonymous user and developers of the yamamap project can commit into it.

The SVN tree contains one single Eclipse (http://eclipse.org) project. This means that the easiest way to compile and develop YAMA is to use Eclipse. This document is about setting up YAMA environment in Eclipse.

  1. You will need subclipse plugin for Eclipse to reach SVN repository integrated in Eclipse (http://subclipse.tigris.org/).
  2. Add the yamamap repository to your known repositories: Window/show view/other..., SVN/SVN Repositories. In the SVN repositiry view right click to see the add repository wizard.
  3. browse the repostiory for the folder to check out (workspace/hu.schmidtsoft.map)
  4. right click on the folder and select checkout.... Then select check out as project hu.schmidtsoft.map
  5. After waiting for checking out the project will be in your workspace. Hopefully it compiles (Eclipse auto-compiles all sources, so if you see no error marking icons in package-explorer it is compiled)

The eclipse project contains two important directories:

starting from IDE

Right click on: hu.schmidtsoft.map.render.YamaWindow.java in the IDE. In the upcoming window select run as Java Application or debug as Java Application.

compiling the code

Eclipse auto compiles all projects in the workspace. If you want to export the project, use export.jardesc in the root of the project.

Currently there is no ant task for creating release from the project.

compile .NET versions

Compiling the .NET version is the really tricky thing. Be prepared for much ugly hacking!

generated code

First YAMA was written in Java. When I realized that there is no reliable (at least I could not find one - 20071010) JavaSE for PocketPC I decided to create a .NET version on YAMA. As I am a fan of DRY concept (http://en.wikipedia.org/wiki/Don't_repeat_yourself) and Java and .NET has more similarities than differences I decided to generate the .NET code from Java. To achieve this goal the code was Java code instrumented and a compiler was written. Compiler is in project hu.schmidtsoft.tocs (found in yamamap's SVN). The compiler is not a general Java to .NET compiler, only works for this project.

Not all .NET code is generated, just the pieces under the gen folder. Other codes are written in .NET.

compiling for PocketPC

Compiling .NET CF code is easy using Visual Studio. First I managed to create PocketPC application using the Microsoft IDE. The Visual Studio version of the project is still in SVN but is already outdated.

In my opinion an open source project should be compiled using a free compiler on a free platform. Searching the web for Compiling C# for PocketPC did not give many relevant results but one was found: http://evain.net/blog/articles/2006/03/31/mono-and-the-compact-framework-in-love-part-two. This blog entry showed the way how to compile .NET CF code for PocketPC using Mono (on Linux).

The .NET framework references dll's not only by name, but by version and public key of the dll's signature. The signature of the CF dll's are not the same as the signature of the "normal" .NET Framework dll's and Mono has a third signature.

The referenced article includes a patcher written for Mono (http://evain.net/public/cf-cecil-patcher.cs.html) that changes the reference's public key token in the compiled assembly. This patcher makes an .exe file compiled with Mono to reference the .NET CF libraries instead of the Mono libraries. I have added cf-cecil-patcher.cs to the SVN of YAMA. This is the same as the one on the referenced page, I have only added some log messages and a listing only function.

The assemblies only implicitly reference mscorelib, so the mscorelib of different frameworks can be mixed (at least compile time)

The executable assembly must be compiled against the .NET CF libraries. Its interface has some difference to the Mono System libraries'.

So the possibilities:

  1. compile against .NETCF mscorelib and .NETCF System libs - compiler fails to work
  2. compile against Mono mscorelib and .NETCF System libs - compiling OK. Patch changes the reference to mscorlib only. Created executable WORKS!
  3. compile against Mono mscorelib and Mono System libs, then patch references (to mscorlib and System libs) - created executable fails to load on PocketPC

So the second choice is selected :-).

The Mono project in SVN has references to the Mono libraries so in the MonoDevelop IDE we create executable for Mono that can be executed on PC.

The PocketPC version of YAMA is compiled using the yamaMono/script/yama.build nant file. This nant file references the PocketPC .NETCF 2.0 system dll's on a fix path. That path must be adjusted to a location where you store the dll's.

(Extracting the dlls: When installing the .NET framework 2.0 CF select install on SD card, then the files can be directly copied to your PC from the card's filesystem)

The nant script first compiles the patcher, then the CF version of YAMA (that references to Mono mscorelib), then uses the newly compiled patcher to patch the yamaMono.exe to reference the .NETCF mscorelib.

compiling the documentation

Documentation source is in folder hu.schmidtsoft.map/doc. The documentation is developed using LATEX. You need a compiler to use it. On Linuxes it is common to have one in your distribution, on Windows I recommend http://miktex.org/. Scripts for compiling the documentation are found in the doc directory named ``*.bat'' for Windows and ``*.sh'' for Linux. Note: to generate corrent Table Of Contents you must run the scripts twice!

concepts

Concepts used while developing the map application. This section is intended for developers who would like to understand the structure of YAMA (without or besides the details of obtaining and compiling the code).

Sections of this chapter were written in a brain storming style. They may or may not correspond to the actual implementation.

coordinate systems

Most data processed by the map application is some coordinates of locations of the map. These locations are on the surface of the Earth. Different coordinate systems are used by GPS and computer graphics. The essential to understand a vector based map application is its coordinate systems and transformations. The coordinate systems used by YAMA are discussed in this section.

Using the coordinate systems:

Maps are defined in the GPS cordinate system. For rendering we use descartes coordinate system.

The view point of the map can be thought of as a man above the point to be viewed arbitrarily far away(parallel projection is used). But the view point we define is on the earch surface level (0m high).

First Earth is treated as a sphere. That will cheat little on small areas. Earth's radius is R.

Transformation from GPS coordinates to descartes coordinates is:

  1. find the direction vector from earth's middle to the point on surface
  2. find the point on surface
  3. add some meters to find the point on the given height
Problem: which descartes coordinate system to use?

The two descartes coordinate systems we use:

Earth middle coordinate system:

Local coordinate system:

Transformation steps: pre:

actual:

Viewpoint transformation takes the viewpoint to origo, the direction to the Earth's middle to -z the direction to North to y:

Finding a point on the descartes from GPS:

gps interface

This section describes what the GPS is from our abstract view and how the map application use the GPS. Currently the application is not interfaced with the GPS it is in planned status.

our view of the GPS

The GPS is a source for: Besides transferring time and position coordinates the GPS can also transfer no signal.

Timing for GPS is defined by the GPS source. The map showing application receives and processes messages from the GPS instead of polling it for values.

tracking

Tracking means that the map shows the current location and direction of the avatar (the user of the GPS tool). Some levels of tracking can be defined:

All tracking options should be capable of switching on and off. There must be a default file for saving tracks. The current track in memory and this file can be saved into a selected file.

user interface

YAMA application is planned to work on PC an PDA. The two different platforms require different user interface. This section is about the PDA interface.

PDA interface has the following restrictions:

About this document ...

YAMA Yet Another Map Application

This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.71)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -dir ../docout -split=0 documentation-html.tex

The translation was initiated by Rizsi on 2007-11-05

Rizsi 2007-11-05