CycloGraph User Manual
======================
Federico Brega; Pierluigi Villani

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.

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 (http://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:

* GPS eXchange format (.gpx)
* Keyhole Markup Language format (.kml)
* Salitaker format (.sal)
* Training Center XML format (.tcx)
* Ciclotour format (.crp)
* Ciclomaniac format (.xml and .txt)
* SportTracks Fitlog files (.fitlog)

.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 (https://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.

Basic usage
-----------

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 5 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 5 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 5

The Qt interface uses the Qt5 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.

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 “-”.

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.

.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:

* SVG: a vectorial format, which means that can be zoomed with no
artifacts.
* 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.
* PNG: a raster format with loose-less compression, which means that the
quality is not affected by the compression level.
* JPEG: a raster format that degrades the quality with the level of
compression, but can achieve very small files.

Expert Usage
------------

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 <<editing-cs,Editing the CycloGraph CSV file>> .

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 “>”).

[[editing-csv]]
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

