CycloGraph User Manual

Federico Brega, Pierluigi Villani

1 Introduction

CycloGraph is an application born to let cyclists visualize their routes and estimate how difficult they are.
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.
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.

1.1 Features

Manual insertion
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.
GPS tracks
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 GpsBabel (www.gpsbabel.org) 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.
Files produced by other applications
Interoperability is important and CycloGraph permits you to open files saved by other applications. Supported formats are:
KML format and drawing on maps
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.
Google Earth (earth.google.com) lets you create a route and save it in KML.
CycloGraph includes a tool to create a KML file by tracing a polyline on a map (Open Street Map or Google Maps). The same tool can also interface to directions given by Open Route Service, OSRM and YOURS.
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.

2 Basic usage

2.1 Start the application

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.
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.
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.
Qt 4
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.
GTK+
The GTK+ interface uses GTK+ 3.0 or newer.
Command Line
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.

2.2 Editing a new file

You can start creating a new slope by selecting the first element of the toolbar or alternatively selecting the element “New” on the File menu. You can add check-points by selecting “add check-point” 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 “delete check-point” or “-”.

2.3 Show the plot

To show the plot after you have created or loaded one, you have to press the “plot your slope” 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.

2.3.1 Save the plot as Image

You can save the image as seen on the new window to a file.
Many file formats are supported but the most common are:

3 Expert Usage

3.1 Command Line

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.
Editing is not possible but more appropriate tools can be used instead, see Subsection 3.2↓.
When CycloGraph is invoked without any option the application will guess a suitable graphical interface.
A specific graphical interface can be selected by means of an option.
The complete and updated list of supported flags can be shown using the “--help” option.
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 “>”).

3.2 Editing the CycloGraph CSV file

CycloGraph CSV files use the delimiter “;” for fields in the same line.
# line 1: 6 fields
  1. CSV version
  2. slope name
  3. slope state
  4. author
  5. author’s e-mail
  6. comments
# line 2+: check points, 3 fields
  1. distance
  2. altitude
  3. check point name