U-Bahn Navigator - How to create U-Bahn maps

U-Bahn Navigator can be extended with additional U-Bahn maps. U-Bahn maps normally contain a network description for a single city or town with one or more different means of transportation.

This is just the description of necessary files and the XML document format. You do not have to define U-Bahn maps by coding XML. There are some U-Bahn map tools available in the download area, that make the definition and testing of U-Bahn maps easier.

U-Bahn map files

Every U-Bahn map consists of the following files.

a control file named city.ubahn, that contains the directory and the names of the other files of the U-Bahn map. The name of this file will be displayed in the open map dialog.
a subway map file, usually called city_map.xml
an icon file, usually called city_icon.xml>
bitmap files (PNG format) for line icons

Directory structure

U-Bahn maps must be installed in the directory "/opt/QtPalmtop/ubahn/maps". Each U-Bahn map should be placed in a separate directory, that contains the subway map, icon file and icon bitmaps. Here is an example of the included U-Bahn map for Hamburg:

./hamburg.ubahn
./hamburg
./hamburg/hamburg_icon.xml
./hamburg/hamburg_map.xml
./hamburg/icon_S11.png
./hamburg/icon_U3.png
./hamburg/icon_110.png
./hamburg/icon_A1.png
./hamburg/icon_A2.png
./hamburg/icon_A3.png
./hamburg/icon_R60.png
./hamburg/icon_S1.png
./hamburg/icon_S21.png
./hamburg/icon_S3.png
./hamburg/icon_S31.png
./hamburg/icon_U1.png
./hamburg/icon_U2.png

Control file city.ubahn

The control file contains information about the directory and the other files of a city's U-Bahn map. Here is a sample control file (hamburg.ubahn):

MapDir=hamburg
SubwayMap=hamburg_map.xml
IconFile=hamburg_icon.xml
POIFile=hamburg_poi.xml

"MapDir" is the name of the directory, that contains the necessary files of the entire U-Bahn map. It must be given relative to the maps directory (/opt/QtPalmtop/ubahn/maps).
"SubwayMap" is the name of the XML document with the description of the subway map (lines, stations, routes).
"IconFile" is the name of an optional XML document, that describes the bitmaps to be used for graphical representation of lines and stations.
"POIFile" is the name of an optional XML document with points of interest descriptions. This file will not be used by the current version of U-Bahn Navigator.

Subway map file city_map.xml

The subway map file contains information about the entire subway network. It describes stations, lines and routes. Subway map files are XML documents with the following format:


<?xml version="1.0"?>

<subway_map>
 <info name="name of the map" city="name of the city"
       descr="description of the map"
       created_by="Dimitri Brukakis (nospam@nospam.net)"
       created="25.12.2003"
       version="0.5" last_change="07.02.2004">
 </info>
 <stations>
  <station id="ahrensbo" name="Ahrensburg Ost"><sl id="U1b"/></station>
  <station id="ahrensbw" name="Ahrensburg West"><sl id="U1b"/></station>
  <station id="allerm" name="Allermoehe"><sl id="S21"/></station>
  <!-- and so on -->
  <station id="wiemer" name="Wiemersdorf"><sl id="A1"/></station>
  <station id="willhbg" name="Wilhelmsburg"><sl id="S3"/><sl id="S31"/></station>
  <station id="wohlt" name="Wohltorf"><sl id="S21"/></station>
 </stations>
 
 <lines>
  <line name="U1" id="U1" class="U-Bahn">
   <route name="Norderstedt Mitte - Ohlstedt"
          startstation="Norderstedt Mitte" endstation="Ohlstedt"
          service_start="00:00" service_end="00:30">
    <stop at="norderstm" ttn="2" ttp="0"><ctl id="A2" ttc="2" from_dir="backw"/></stop>
    <stop at="richtwg" ttn="2" ttp="3"/>
    <!-- and so on -->
    <stop at="hoisbue" ttn="3" ttp="2"/>
    <stop at="ohlstd" ttn="0" ttp="2"/>
   </route>
  </line>

  <line name="U2" id="U2" class="U-Bahn">
   <route name="Niendorf Nord - Wandsbek-Gartenstadt"
          startstation="Niendorf Nord" endstation="Wandsbek-Gartenstadt"
          service_start="00:00" service_end="00:00">
     <stop at="niendrfn" ttn="1" ttp="0"/>
     <stop at="schippwg" ttn="2" ttp="2"/>
     <stop at="schlump" ttn="2" ttp="1"><ctl id="U3" ttc="1"/></stop>
     <stop at="messhl" ttn="1" ttp="3"/>
     <stop at="gaensem" ttn="2" ttp="1"/>
     <stop at="jungf" ttn="2" ttp="1"><ctl id="U1" ttc="3"/>
         <ctl id="S1" ttc="3"/><ctl id="S11" ttc="3"/>
         <ctl id="S3" ttc="3"/></stop><stop at="hbf" ttn="2" ttp="2">
         <ctl id="U1" ttc="3"/><ctl id="U3" ttc="3"/>
         <ctl id="S1" ttc="3"/><ctl id="S11" ttc="3"/>
         <ctl id="S21" ttc="3"/><ctl id="S3" ttc="3"/>
         <ctl id="S31" ttc="3"/></stop>
     <stop at="berltor" ttn="1" ttp="3"><ctl id="U3" ttc="1"/>
         <ctl id="S1" ttc="2"/><ctl id="S21" ttc="2"/></stop>
     <stop at="luebkstr" ttn="2" ttp="1"><ctl id="U1" ttc="1"/></stop>
     <stop at="wandbkg" ttn="0" ttp="2"><ctl id="U1" ttc="0"/></stop>
   </route>
  </line>

  <line name="110" id="110" class="Bus">
    <route name="Ohlsdorf - Flughafen (Airport-Express)"
           startstation="Olsdorf" endstation="Flughafen"
           service_start="00:00" service_end="00:00">
      <stop at="ohlsdrf" ttn="11" ttp="0"><ctl id="U1" ttc="1" from_dir="backw"/>
           <ctl id="S1" ttc="1" from_dir="backw"/>
           <ctl id="S11" ttc="1" from_dir="backw"/>
           </stop>
      <stop at="flugh" ttn="0" ttp="11"/>
    </route>
  </line>
 </lines>
</subway_map>

This is just the description of the XML file format. You do not have to define U-Bahn maps by coding XML. There are some tools available in the download area, that makes definition of U-Bahn maps easier.

Subway map document <subway_map>

A subway map document begins with the XML tag <subway_map> and ends with </subway_map>. Within this document tags, you can use the following tags to defines map information, stations and lines/routes:

<info> tag

<info> specifies information, that can be displayed by U-Bahn Navigator using the menu "View->Info". This tag can contain the following attributes:

name="name": Name of the subway map
city="city": Name of the city, the subway map belongs to
descr="free form description": Description of the subway map data
created_by="name and email address of the creator"
created="date of creation"
version="actual version"
last_change="date of the last change"

<stations> tag

<stations> groups the definition of all stations within the subway network. Stations must be defined before they are used in routes (<route>).

Each station must be defined using the XML tag <station>, which has the following attributes:

id="unique-id": The unique ID of a station. This ID will be used later in route definitions.
name="station name": The name of the station that will be displayed in U-Bahn Navigator dialogs and the route display.

Each station tag can contain a number of <sl>-Tags (serving line) to define lines, that can be used at this station. The serving lines are defined by its ID's (see <line>).

The complete definition of one station looks like this:

<station id="mystat" name="My Station">
   <sl id="line1"/>
   <sl id="line2"/>
</station>

This defines a station named "My Station" with the ID "mystat", that is served by the lines "line1" and "line2".

There must no stations without a serving line be defined.

<lines> tag

<lines> groups the definition of lines for the entire subway map. Each line must have exactly one route with a number of station it stops at.

A line definition starts with the XML tag <line>. A <line> tag must contain the following attributes:

id="unique-id": The unique ID of the line that will be used for relations between lines and stations
name="name of the line": The name of the line that will be displayed within U-Bahn Navigator
class="class of the line": a class of the line like "U-Bahn" or "S-Bahn".

<route> tag

A line definition must contain one or more <route> tags, that specifies the stations the line passes. The <route> tag can have the following attributes:

name="name of the route": The name of the route, e.g. "Start station - Endstation".
startstation="name of the start station": Name of a station, that may be shown at the front display of a subway train of the line. Will be used for the direction information within the U-Bahn Navigator route display area.
endstation="name of the end station": Name of a station, that may be shown at the front display of a subway train of the line. Will be used for the direction information within the U-Bahn Navigator route display area.
service_start="start of service"/service_end="end of service": Will be used in later versions to specifiy the operation time of a line.
oneway="true" or "false": This is an optional attribute for routes. If set to "true", the route is uni-directional. Use this attribute for circle lines or to define two lines with different stations on forward and backward direction.

<stop> tag

Each <route> tag contains two or more <stop> tags, that specify the stations, the train of the line passes on its way. The <stop> tag must have the following attributes:

at="station id": the ID of the station
ttn="time to next": time in minutes to the next station of the route
ttp="time to prev": time in minutes to the previous station of the route (for the way back)

If it is possible and usefull to change to other lines at this station, this can be specified with the additional tag <ctl> (change to line). The <ctl> tag contains the attributes

id="line id": ID of the line to change to.
ttc="time to change": The time in minutes to change to the line at this station.
(opt) from_dir="from direction": The direction in this route, where a change to the line is possible. Values "backw" or "forw"
(opt) to_dir="to direction": The search direction in the route(s) of the line to change to. Values "backw" or "forw"

If there are no possible connections between stations using a line or if it is shorter to go from one station to another by feet, you can use the tag <cts> (change to station). <cts> takes the same attributes like <ctl>:

id="station id": ID of the station to change to.
ttc="time to change": The time in minutes to change to this station by feet.
(opt) from_dir="from direction": The direction in this route, where a change to the other station is possible. Values "backw" or "forw".

A complete <stop> definition looks like this:

<stop at="mystat1" ttn="2" ttp="0">
   <ctl id="line1" ttc="3"/>
   <ctl id="line2" ttc="2" from_dir="forw"/>
</stop>
<stop at="mystat2" ttn="2" ttp="0">
   <cts id="mystat3" ttc="2"/>
   <ctl id="line2" ttc="2" from_dir="forw" to_dir="backw"/>
</stop>

The <stop> tag above defines a stop at station "mystat". It takes 2 minutes to the next station within the route and 0 minutes to the previous, which means, that "mystat" is the first station of the route.

At this station it is possible to change to line "line1", which may take 3 minutes or to line "line2", which may take 2 minutes. The change to "line2" is only possible/usefull, when the direction in this route is "backw" (backwards).

Icon file city_icon.xml

The icon file contains relations between line IDs and icon bitmaps for lines, that will be displayed within the U-Bahn Navigator route display and the line/station info dialogs. The icon file is an XML document with the following format:


<?xml version="1.0"?>

<icons>
  <lineicons>
    <icon line="U1" file="icon_U1.png"/>
    <icon line="U1b" file="icon_U1.png"/>
    <icon line="U2" file="icon_U2.png"/>
    <icon line="U3" file="icon_U3.png"/>
    <icon line="S1" file="icon_S1.png"/>
    <icon line="S3" file="icon_S3.png"/>
    <icon line="S11" file="icon_S11.png"/>
    <icon line="S21" file="icon_S21.png"/>
    <icon line="S31" file="icon_S31.png"/>
    <icon line="A1" file="icon_A1.png"/>
    <icon line="A2" file="icon_A2.png"/>
    <icon line="A3" file="icon_A3.png"/>
    <icon line="R60" file="icon_R60.png"/>
    <icon line="110" file="icon_110.png"/>
  </lineicons>
</icons>

Currently there are only icons for lines to be defined. These icons are grouped within the <lineicons> tag.

The tag <icon> defines the relation between a line id, specified in the subway map file and an icon bitmap file (PNG). This will display icons like

in addition to the name of the lines. Bitmap files should not be larger than 40x15 pixel.

This is an optional file to make U-Bahn Navigator more colourful. If it does not exist, the names of the lines will be displayed only.