root/trunk/README

This is a freimap svn release.
The Licence is GNU GPL.

Copyleft by:
 * Thomas Hirsch <thomas hirsch gmail com>
 * Robert Schuster <robertschuster@fsfe.org>

== README FIRST ==

This is a static text file. Static information tends to get out of date each time you're not looking. If possible, please refer to the documentation in the freimap wiki at http://relet.net/trac/freimap for the latest documentation.

----

Freimap is an Open Source visualization and analysis framework for (mostly) mesh networks, such as for example Freifunk.net. It can read many a different data source and display them as different layers. The network can be browsed and queried in real time, and a time bar allows to trace back to past events. Some statistics of the topology and network traffic may also be generated.

A thorough documentation of the project is still expected to fall from the sky. Until then, here's a small outlook of what you can get running and how.

== Requirements ==

    * Java JDK 1.5.0 (Java2) or better.
    * A few, rather common java libraries, which are provided in the svn version. 

To make good use of freimap, you would need some data sources. Some of these are

    * Olsrd running with the dot_draw plugin, somewhere in the network.
    * A latlon.js file, generated by the nameservice plugin.
    * XML files containing node information, such as in certain freifunk maps. Some examples are provided in the data/ directory.
    * A database containing node information, topology data, or flow data, according to the provided SQL structures. 

== Installation == 

Download the latest precompiled build:

    * http://relet.net/trac/freimap/browser/freimap-latest.tbz?format=raw 

or get the sources using 'svn':

    * svn checkout http://relet.net/svn/freimap/trunk freimap 

=== Compiling (svn only) ===

    * ./compile (or "compile.bat") 

or, if ant is available:

    * ant 

== Running freimap ==

1. Configuration

This is probably the trickiest part of the process. The configuration for freimap is stored in the configuration file "config.yaml" in the YAML markup language. An example file is provided as "config.yaml.example". Read the Configuration Manual in the freimap wiki for up-to-date details on the available options.

The example config file will create two layers: A list of nodes read from the provided xml file, and one displaying topology information from an olsrd dot_info plugin listening on localhost:2004. This is probably the most common and easiest to provide set of data sources. Another simple option would be to get a latlon.js file generated by the nameservice plugin of your olsr daemon. There's an example in the configuration manual, too. 

2. Starting

    * ./run 

or

    * java -Xmx500m -jar freimap.jar 

If you have got less than 500mb free memory, you may want to adjust the -Xmx parameter. Freimap does not necessarily need that much unless you evaluate many months of collected data. 

== Using freimap ==

When freimap starts, the first thing it will do, is to parse the config file config.yaml. Beware, for since YAML is not very picky with its syntax, some typing errors in the structure may not be detected, and freimap will not necessarily complain if you made a mistake there. From the YAML data found in the config file, freimap will try to identify the Background and DataSource? layers to load, and initialize them with the given parameters. Layers will first be loaded, and initialized in a second run. Hence, cross-references should work from any layer to any other.

Freimap will output status information and error messages on the console while loading the layers and initializing data sources. For example

fetching node data from URL: file:latlon.js
This may take a while ... finished.

would be the output of successfully loading node coordinates using a LatLonJsDataSource. 

* The Graphical User Interface *

Once the freimap window appears, you should see a black-greenish screen, with some decorations and -if you have selected the OpenStreetMap? backdrop- a world map in the center.

** Status Information **

The second green bar on the top of the window displays your current location (longitude and latitude) and the map zoom factor. On the left side, where the URL of this site is displayed, at some point in the future, you might be able to see an actual place name.

The bottom bar displays the currently selected time, and the memory usage of the software. When the 'resource usage' runs towards 100%, you may experience some OutOfMemoryErrors. This would usually happen when you work with larger quantities of data, which freimap currently seeks to keep in memory.

** The Map / Navigation **

The main portion of the screen is occupied by the map. At the beginning, you will find that it zoomed out to the maximum, so that you will have to zoom in to your preferred location first. If your data source has provided some node coordinates, you should be able to identify that location easily.

Mouse control:

    * Left mouse button drag: Move the map
    * Mouse wheel, or right button drag up/down: Zoom the map
    * Double click: Print the current longitude/latitude to the console.
    * Right click on a link or node: Begin fetching additional information (see section "Layers" below) 

Keyboard control - Currently supported:

    * '+' - Zoom in
    * '-' - Zoom out 

** The Time Bar **

The time bar at the bottom of the screen displays which data source has provided information for which time interval. A dark green bar represents the total interval where any data is available. Lighter green bars stacked on top represent the various data sources. You may directly click on the time bar to select a specific data set.

A red/green play button to the left of the bar allows you to replay the recorded data in order. Currently, the replay speed is a bit arbitrary.

*Layers *

On the top left of the screen is a list of layers. Clicking on an item in this list will select it as the active layer, which reacts on your mouse actions. You may drag and drop layers to change the order of drawing. The eye icon to the left of the layer allows you to cycle between different display types of this layer - usually "on", "off" and "semi-transparent". More or less display types may be supported.

Data Layers may react differently on your mouse actions. Their usage will be described in the following.
** Node/Link Layers **

When moving over the displayed nodes and links, you will discover that the closest node or link to your mouse cursor will be highlighted. Additionally, an information pane is displayed on the top right of the screen. This information will display an identifier of the node or link, as well as more or less information provided by the data source. This list is usually followed by the words "+ right click for more +".

If you do right click, the data source will try to fetch further information concerning the given element. Depending on the element, this may include some statistics, generated over the available data, or add further elements to the information pane. This process may take some time. During this time, the information pane will display the message "retrieving information". When the process is finished, the additional information will be displayed automatically when hovering over the link.

Another right click on the node or link may refresh the information, for example in the case of statistics and charts.

* The Menus *

A menu bar is on top of the application. Currently, the only useful menu entries are the following.
> View 
> Hide unlocated nodes 

Stops/Starts interpolation and display of unlocated nodes.
> Display Filter 

Selecting this menu will show a popup window which allows you to specify a display filter for nodes and links. To enable a filter, enter a string, select "enable display filter" and click on the "Apply" button. Now, only nodes containing (normal mode) or matching (regular expression mode) the specified string will be displayed. 

== Final Words ==

Enjoy! 
Comments and bug reports are welcome. Either use the Bug reporting system 
at http://relet.net/trac/freimap or contact me at the address above.