source: subversion/applications/utils/import/srtm2wayinfo/documentation.h

Last change on this file was 17101, checked in by herm, 8 years ago

Support different storage systems for ways.

File size: 5.4 KB
Line 
1/* This file contains the main documentation. It's easier to read if you first
2 * process it using doxygen.Just run the command "doxygen" in this directory.
3 * You'll find the final documentation (which includes the code documentation
4 * embedded in the other files) in the directory "docs/html".
5 */
6/** \mainpage
7\author Hermann Kraus
8
9\section introduction Introduction
10This program reads OpenStreetMap files and calculates the altitude differences
11along each way that has a \e "highway" tag. The "up" and "down" values are
12output separately, so you can decide if it is a hilly way where just the start
13and end node are at almost the same altitude or if the way is really flat.
14
15This manual is divided in the following sections:
16- \subpage installation
17- \subpage usage
18- \subpage output
19- \subpage structure
20
21If you have any problems using this program contact me at <b>h e r m (at) s c r i b u s (dot) i n f o</b>.
22
23\page installation Installation
24\section Dependencies
25This program uses the following libraries:
26\li \b libcurl (debian packages: \e libcurl3 and \e libcurl4-gnutls-dev or
27    \e libcurl4-openssl-dev)
28\li \b zziplib (debian packages: \e libzzip-0-13 and \e libzzip-dev)
29\li \b QT4 (debian packages: \e libqtcore4 and \e libqt4-dev)
30
31and it uses
32
33\li \b cmake (debian package: \e cmake)
34
35as a build tool.
36Please make sure you have them installed.
37
38\section Compiling
39Just run the following sequence of commands:
40\verbatim
41mkdir build
42cd build
43cmake ..
44make
45\endverbatim
46optionally you can do
47\verbatim
48make install
49\endverbatim
50as root.
51
52More information about cmake's out-of-source builds can be found at
53http://www.cmake.org/Wiki/CMake_FAQ#What_is_an_.22out-of-source.22_build.3F
54
55\page usage Usage
56Typical usage:
57\verbatim
58bzcat planet.osm.bz2 | srtm2wayinfo -o altitude.osm
59\endverbatim
60
61For more details see the output of
62\verbatim
63srtm2wayinfo --help
64\endverbatim
65
66\page output Output format
67Only ways which have a \e "highway" tag are considered by this program. For
68example it would be quite useless to calculate the altitude differences along
69the perimeter of a forest.
70
71Each highway is split at each junction with another highway. Then for each
72segment a relation is created:
73
74\verbatim
75<relation id="-1" visible="true">
76        <member type="way" ref="100" role=""/>
77        <member type="node" ref="21" role="from"/>
78        <member type="node" ref="42" role="to"/>
79        <tag k="length" v="0.678"/>
80        <tag k="up" v="23.4"/>
81        <tag k="down" v="12.3"/>
82</relation>
83\endverbatim
84
85\li The \e way member refers to the way this relation was created for.
86\li The \e from node is either the first node of the way or the node of the
87    intersection where the last relation ended.
88\li The \e to node is either the last node of the way or a intersection node.
89\li The \e length, \e up, \e down values only apply to the part of the way, that
90    is between the \e from and the \e to node.
91
92
93\page structure Program structure
94\li SrtmDownloader is responsible for downloading the SRTM tiles (if available) and returning the
95altitude data.
96SrtmDownloader::getAltitudeFromLatLon() should be the only function you have to use after initialization, but of if you want to do other things with the tiles you can get the SrtmTile objects directly. An
97enhancement in the future might to be to download SRTM1 tiles where available. This is possible with the current achitecture, but not implemented yet. SrtmDownloader does not depend on other parts of the project and could easily be reused. It only need the server's address, which it gets in the main() function, by calling the functions from the Settings object.
98\li An OsmData object is used to parse the input file and create an internal representation using OsmNode and OsmWay. The format for storing nodes and ways depends on a Settings parameter and influences which OsmNodeStorage and OsmWayStorage class is used. This is a critical parameter, as memory usage and speed varies.
99\li A RelationWriter object then is used to produce the final output. This class could be customized by changing the RelationWriter::writeRelation() function to produce different output formats. It should be noted that the ways can only be accessed sequentially and therefore this class must not try to use random access.
100\li SrtmZipFile is just a helper class the does the zip file decompression using zziplib.
101
102Dependency graph: (connection from Settings to Output not shown for clarity)
103\dot
104  digraph structure {
105    srtmserver [label="SRTM server", shape=ellipse]
106    SrtmDownloader [URL="\ref SrtmDownloader", shape=box]
107    Settings [URL="\ref Settings", shape=box, color=blue]
108    Input [color=red]
109    Output [color=red]
110    OsmData [URL="\ref OsmData", shape=box]
111    OsmWayStorage [URL="\ref OsmWayStorage", shape=box]
112    OsmNodeStorage [URL="\ref OsmNodeStorage", shape=box]
113    RelationWriter [URL="\ref RelationWriter", shape=box]
114    SrtmZipFile [URL="\ref SrtmZipFile", shape=box]
115    srtmserver -> SrtmZipFile -> SrtmDownloader
116    Settings -> srtmserver [dir = none, color=blue]
117    Settings -> OsmWayStorage [dir = none, color=blue]
118    Settings -> OsmNodeStorage [dir = none, color=blue]
119    Settings -> Input [dir = none, color=blue]
120#    Settings -> Output [dir = none, color=blue]
121    Settings -> SrtmZipFile [dir = none, color=blue]
122    OsmNodeStorage -> OsmData [dir = both]
123    OsmWayStorage -> OsmData [dir = both]
124    Input -> OsmData [color=red]
125    RelationWriter -> Output [color=red]
126    OsmData -> RelationWriter
127    SrtmDownloader -> RelationWriter
128 }
129\enddot
130*/
Note: See TracBrowser for help on using the repository browser.