Az oldal magyarul: documentation-hu-html.html
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:
YAMA has a release for JavaSE and a release for .NET CF. The two versions are in separate sections.
The online version of YAMA uses the same controls as the standalone version.
YAMA can be used as a standalone Java application on your PC. To start YAMA as astandalone application you have to:
java -jar yama.jar
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.
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.
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.
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:
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.
The .NET version of YAMA contains no map converter, it is only a map viewer. Currently there is only release for PocketPC.
YAMA has no installer. You have to copy all files manually to your PocketPC.
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: .
The configuration file is first searched at: "
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.
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)
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 ().
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.
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.
Currently YAMA is developed by a single person. You can contact me and other users of YAMA using the following:
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.
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.
The eclipse project contains two important directories:
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.
Compiling the .NET version is the really tricky thing. Be prepared for much ugly hacking!
Not all .NET code is generated, just the pieces under the gen folder. Other codes are written in .NET.
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:
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.
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 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.
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:
The two descartes coordinate systems we use:
Earth middle coordinate system:
Local coordinate system:
Transformation steps: pre:
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:
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.
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 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.
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:
This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.71)
Copyright © 1993, 1994, 1995, 1996,
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-05Rizsi 2007-11-05