1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<meta name="generator" content="http://www.nongnu.org/elyxer/"/>
<meta name="create-date" content="2014-06-20"/>
<link rel="stylesheet" href="http://elyxer.nongnu.org/lyx.css" type="text/css" media="all"/>
<title>CycloGraph User Manual</title>
</head>
<body>
<div id="globalWrapper">
<h1 class="title">
CycloGraph User Manual
</h1>
<h2 class="author">
Federico Brega, Pierluigi Villani
</h2>
<h1 class="Section">
<a class="toc" name="toc-Section-1">1</a> Introduction
</h1>
<div class="Unindented">
CycloGraph is an application born to let cyclists visualize their routes and estimate how difficult they are.
</div>
<div class="Indented">
It is important to stress that plotting the elevation of an altitude may be of interest also in other fields such as running, hiking or even skiing.
</div>
<div class="Indented">
The goal of the application is to show the altitude and the slope along the route and to do it as elegantly as possible. Many other programs can show a simple plot of the altitude, and some of them provide other functionality, but the graphics are essential. CycloGraph aims to be great at producing graphically appealing images to document the stages of a race or to be shown on web pages and journals.
</div>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-1.1">1.1</a> Features
</h2>
<div class="Paragraph">
<a class="toc" name="toc-Paragraph-1"></a>Manual insertion
</div>
<div class="Unindented">
The purpose of the application is to draw a graph; to do this a source of information is needed. The application can be fed manually, which is very straightforward but soon becomes tiring because you need to insert every single piece of information you wrote down while you were doing the run.
</div>
<div class="Paragraph">
<a class="toc" name="toc-Paragraph-2"></a>GPS tracks
</div>
<div class="Unindented">
GPS devices are very common nowadays, their problem is the very high rate of recording. CycloGraph lets you import a track recorded and stored in gpx (GPs eXchange format). If your GPS device produces files in another format you can use <span class="versalitas">GpsBabel</span> (<a class="FlexURL" href="www.gpsbabel.org">www.gpsbabel.org</a>) to convert it to GPX. Note that GPS tracking data is usually not enough to produce a high-quality plot because although it contains a lot of points, only a few really add any information to the plot. CycloGraph tries to import a reasonable number of points, but the best results can be achieved by importing more points than needed and then manually delete the ones that are not relevant. You may also want to edit some points to add labels.
</div>
<div class="Paragraph">
<a class="toc" name="toc-Paragraph-3"></a>Files produced by other applications
</div>
<div class="Unindented">
Interoperability is important and CycloGraph permits you to open files saved by other applications. Supported formats are:
</div>
<ul>
<li>
GPS eXchange format (.gpx)
</li>
<li>
Keyhole Markup Language format (.kml)
</li>
<li>
Salitaker format (.sal)
</li>
<li>
Training Center XML format (.tcx)
</li>
<li>
Ciclotour format (.crp)
</li>
<li>
Ciclomaniac format (.xml and .txt)
</li>
<li>
SportTracks Fitlog files (.fitlog)
</li>
</ul>
<div class="Paragraph">
<a class="toc" name="toc-Paragraph-4"></a>KML format and drawing on maps
</div>
<div class="Unindented">
A unique feature allow to import a slope from a KML file. This is a complex process because a KML file doesn’t contain the altitudes, so they are downloaded from an Internet server. You can choose any of many services, which offer different resolution levels and download speeds.
</div>
<div class="Indented">
<span class="versalitas">Google Earth</span> (<a class="FlexURL" href="earth.google.com">earth.google.com</a>) lets you create a route and save it in KML.
</div>
<div class="Indented">
CycloGraph includes a tool to create a KML file by tracing a polyline on a map (<span class="versalitas">Open Street Map</span> or <span class="versalitas">Google Maps</span>). The same tool can also interface to directions given by <span class="versalitas">Open Route Service, OSRM</span> and YOURS.
</div>
<div class="Indented">
This tool permits you to visualize how hard a slope is even if you have never been there. This is very useful in planning. Please note that using an automatic tool may lead to misleading results: if two consecutive points are too far apart you can miss a peak between them. On the other hand, if they are too close together the slope may be very inaccurate due to the resolution of the altitude data.
</div>
<h1 class="Section">
<a class="toc" name="toc-Section-2">2</a> Basic usage
</h1>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-2.1">2.1</a> Start the application
</h2>
<div class="Unindented">
CycloGraph has several interfaces, either graphical or command-line. If you are a Windows user you’re probably interested in the Qt 4 interface, because it is the only one which we support in the package for your platform.
</div>
<div class="Indented">
Note that all graphical interfaces have the same functionalities; the only difference is some minor aesthetic details. This is only relevant if you are a Linux user since only Qt interface is officially supported on Windows.
</div>
<div class="Indented">
The same Qt 4 interface can look different when used on different platforms so don’t be confused if the screenshots look a bit different from what you see on your screen.
</div>
<div class="Paragraph">
<a class="toc" name="toc-Paragraph-5"></a>Qt 4
</div>
<div class="Unindented">
The Qt interface uses the Qt4 framework to provide the graphic user interface. While for Windows packages Qt is the only interface available, for GNU/Linux there is also the GTK+ interface.
</div>
<div class="Paragraph">
<a class="toc" name="toc-Paragraph-6"></a>GTK+
</div>
<div class="Unindented">
The GTK+ interface uses GTK+ 3.0 or newer.
</div>
<div class="Paragraph">
<a class="toc" name="toc-Paragraph-7"></a>Command Line
</div>
<div class="Unindented">
This interface allows you to run the application in a console, without the need of a graphical server. This is intended for experts, not because it is hard to use but because usually only “experts” use the command line.
</div>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-2.2">2.2</a> Editing a new file
</h2>
<div class="Unindented">
You can start creating a new slope by selecting the first element of the toolbar or alternatively selecting the element <i>“New”</i> on the <i>File</i> menu. You can add check-points by selecting “<i>add check-point</i>” on the toolbar or by pressing “+” from the keyboard. To modify a point, select it from the list and then “modify check-point” on the toolbar. You can also delete one or more points by selecting them on the list and then pressing “<i>delete check-point</i>” or “-”.
</div>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-2.3">2.3</a> Show the plot
</h2>
<div class="Unindented">
To show the plot after you have created or loaded one, you have to press the “<i>plot your slope</i>” button on the toolbar. A new plot window will pop up showing the desired graph, drawn according to the settings on the Options>Preferences menu. If you want to change these settings you can use the menu of the plot window, these changes only affects the current plot window while the preferences settings are applied at the opening of every plot window.
</div>
<h3 class="Subsubsection">
<a class="toc" name="toc-Subsubsection-2.3.1">2.3.1</a> Save the plot as Image
</h3>
<div class="Unindented">
You can save the image as seen on the new window to a file.
</div>
<div class="Indented">
Many file formats are supported but the most common are:
</div>
<ul>
<li>
SVG: a vectorial format, which means that can be zoomed with no artifacts.
</li>
<li>
BMP: a raster format which means that changing the zoom level of the file will affect the quality of the image. No compression is used so the format is simple but the files are large.
</li>
<li>
PNG: a raster format with loose-less compression, which means that the quality is not affected by the compression level.
</li>
<li>
JPEG: a raster format that degrades the quality with the level of compression, but can achieve very small files.
</li>
</ul>
<h1 class="Section">
<a class="toc" name="toc-Section-3">3</a> Expert Usage
</h1>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-3.1">3.1</a> Command Line
</h2>
<div class="Unindented">
The command line interface exposes a subset of the features of the graphical interface. Many of them (such as drawing a path on a map) are not accessible because the console is not suitable for this use case.
</div>
<div class="Indented">
Editing is not possible but more appropriate tools can be used instead, see Subsection <a class="Reference" href="#sub:Editing-csv">3.2↓</a>.
</div>
<div class="Indented">
When CycloGraph is invoked without any option the application will guess a suitable graphical interface.
</div>
<div class="Indented">
A specific graphical interface can be selected by means of an option.
</div>
<div class="Indented">
The complete and updated list of supported flags can be shown using the “--help” option.
</div>
<div class="Indented">
If no graphical interface is selected but a file is opened (using “--file=filename”) the application will run from command-line. This means that the slope will be plotted and printed in SVG format to the standard output. If you want to save it you can simply use the output redirection operator of your shell (usually “>”).
</div>
<h2 class="Subsection">
<a class="toc" name="toc-Subsection-3.2">3.2</a> Editing the CycloGraph CSV file<a class="Label" name="sub:Editing-csv"> </a>
</h2>
<div class="Unindented">
CycloGraph CSV files use the delimiter “;” for fields in the same line.
</div>
<div class="Indented">
# line 1: 6 fields
</div>
<ol>
<li>
CSV version
</li>
<li>
slope name
</li>
<li>
slope state
</li>
<li>
author
</li>
<li>
author’s e-mail
</li>
<li>
comments
</li>
</ol>
<div class="Unindented">
# line 2+: check points, 3 fields
</div>
<ol>
<li>
distance
</li>
<li>
altitude
</li>
<li>
check point name
</li>
</ol>
<hr class="footer"/>
<div class="footer" id="generated-by">
Document generated by <a href="http://elyxer.nongnu.org/">eLyXer 1.2.5 (2013-03-10)</a> on <span class="create-date">2014-06-20T23:53:24.515918</span>
</div>
</div>
</body>
</html>
|
