documentation/index.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
	<title>labels_for_osmarender</title>
</head>
<body>
<h1>Overview</h1>
<p>Osmarender is a complex XSLT stylesheet that allows to transform OSM files to SVG. OSM files contain map data
as produced by the OpenStreetMap community. Thus Osmarender is one of many renders to generate maps according
to your personal taste from OSM data.</p>
<h1>Osmarender and Labels</h1>
<p>The main drawback of Osmarender is that it is very limited when it comes to placing labels on the map.
Failing to place labels nicely results in overlapping labels and thus unreadable information.</p>
<p>Osmarender itself uses only very basic rules, such as centroids, to place its labels. Sadly, bad label
placement limits the areas where a map render can be used dramatically.</p>
<h1>labels_for_osmarender</h1>
<p>This project aims to put a postprocessing step after Osmarender to allow for nice labeling whilst still
being able to use Osmarenders rule files. The additional step only rearranges and possible hides labels in
dense regions of the map but does not touch the other map features or map styles.</p>
<h2>Setup</h2>
<p>Before labels_for_osmarender can be used, you need to make sure that all of the required libraries are in place.
A description how to set up the project within eclipse follows.</p>
<p>First, open up Eclipse and import the repositories data into a new general Java project. After doing so you'll find a lot of code problems being reported. This is because external libraries have not been included into the repository.</p>
<p>A dependency is Apache's Batik. Batik version 1.7 was used during development but other version might work equally well. After adding it, you'll find a lot of compilation problems disappear. Batik is used to read on display Osmarenders SVG files.</p>
<p>Go on by adding the next dependency – Vivid Solution's Java Topology Suite. JTS version 1.11 was used and its addition should make to remaining compilation problems disappear.</p>
<p>Verify everything works nicely by selecting runables.Gui and execute it as a Java application. A window appears that allows to select an OSM file and a Osmarender rule file.</p>
<h2>Usage</h2>
<p>To generate maps using pure Osmarender one has to invoke the osmarender stylesheet with an XSL processor as
detailed in the OSM wiki. To generate a map using labels_for_osmarender, execute the labels_for_osmarender.jar
and select your rule file as well as you OSM data file. Clicking “Generate map” invokes Osmarender using
xsltproc in the background, then applies the label placement rules and save the labeled map afterwards.</p>
<p>Note: If you're only interested in generating a map, you may stop reading now. The following sections
describe how the labeling works internally.</p>
<h2>Concepts</h2>
<p>In order to make the label placement happen, an artificial genome is created. It stores all the possibly
feasible label position and which position is in use for a map feature. Each gene represents one map feature.</p>
<p>For calculating a good label placement the positions are switched randomly several times. Once the genome
was generated it survives to the next generation/iteration only if its label overlaps are not significantly
more than those of the parent genome. Producing the next generation's genome works similar to inheritance
of viruses.</p>
<h2>Algorithms</h2>
<p>In general the algorithms start off by generating a set of potentially useful label positions and randomly
chooses from them.</p>
<h2>Coding</h2>
<p>There are dependencies on external tools that need to be added to your project. Those are:</p>
<ul>
	<li>Batik: Tool to manipulate and render SVG files</li>
	<li>JTS: Functions for spatial calculations</li>
	<li>Osmarender: A modified version that adds links between labels and objects.</li>
</ul>
</body>
</html>