Skip to content

10 Guided navigation


This tutorial will show you how to calculate a tour with multiple destinations. Parts of the tour can be standard A to B routings, but they also can be guided navigation routings. Guided navigation routings are routings that lead over a list of SVPs (silent via points).

To accomplish this we will develop a simple JSON file format, which can be loaded by the tutorial from an e-mail attachment or from an open file intent.


As always you can use your results from the previous Tutorial09 as a base for our new project.


Please copy the following files from the Tutorial10 folder to your project directory:

  • CalcTourRunnable.cpp
  • CalcTourRunnable.h

Also replace the file

  • mainwindow.ui

with the one from Tutorial10.


When replacing an .ui file, the build system sometimes doesn't recognize the file has change. As a workaround simply modify the file (for example add and remove a space) and save it so that its time stamp changes.

Add the new files to the CMakeLists.txt file:



Also, we need some new resources, so copy the following file from the Tutorial10/res folder to your /res directory:

  • tour.json

And add it to the main.qrc file:


Call cmake ../ in the build directory or build the ALL_BUILD project of the solution to update it.
Also, always trigger a rebuild after copying to ensure that replaced files will be newly built.

Tour calculation

The NavigationSDK offers extended capabilites to calculate tours with the help of the following functions:

And the following structs:

As we described in Tutorial05, a tour is defined to be a route with one or multiple stations. A tour can contain "regular" stations and SVP stations. Regular stations are stations which are defined solely by a geo-coordinate. SVP stations are defined by a set of coordinates with directions (and other attributes) which describe a way to get to a destination.

To calculate a tour, do the following:

Example JSON data format

For laoding a tour from a file, we created a simple JSON data format. Our example data format is a simple json array containing regular and/or SVP destinations. A regular destination is basically a destination at point x,y in mercator coordinates. A SVP destination is a trace of points describing the route from the previous destination to the last point of the SVPs. Our default ending will be .tour.


SVP stations require a course. For this example we assume the course is given with North = 0 degrees and clockwise orientation. Please note that the SDK only accepts the course with East = 0 and counter clockwise orientation. We implemented a helper function called convertGeoHeading in the CalcTourRunnable. For details see below.

        "type" : "svp",
        "points" : [
        "type" : "regular",
        "point" :
            "x": 756107,
            "y": 6658347


The implementation of our CalcTourRunnable is straight forward. It parses the destinations from the file and passes them as a new tour to the NavigationSDK. First we call SDK_CreateTour() with our current position. Then we add all the destinations with SDK_AddStationToTour() and SDK_AddSVPsToTour(). Finally we call SDK_CalculateTour(). The parameters of this function are a progress callback to get progress information and an additional error code. If the route calculation fails, this error code gives information about the section of the tour the error belongs to. At the end, we delete the created tour with SDK_DeleteTour().

#include "../navigationsdk/SDKInterface.h"
#include "CalcTourRunnable.h"
#include "GPSManager.h"
#include <QApplication>
#include <QFile>
#include <QJsonDocument>
#include <QJsonObject>
#include <QJsonArray>

static CalcTourRunnable * pThis = 0;

CalcTourRunnable::CalcTourRunnable(MapWidget * map) : QObject(), QRunnable()
    pThis = this;
    mMap = map;

void CalcTourRunnable::run()
    QFile file;
    file.setFileName(":/res/tour.json"); | QIODevice::Text);
    QString value = file.readAll();
    QJsonParseError error;

    QJsonDocument doc = QJsonDocument::fromJson(value.toUtf8(), &error);
    QJsonObject obj = doc.object();
    QJsonArray array = doc.array();

    SDK_Waypoint start;


    SDK_Tour * tour = 0;

    SDK_CreateTour(&tour, start);

    for (int i = 0; i < array.count(); i++)
        QJsonObject point = array[i].toObject();
        if (point["type"].toString().toUpper() == "SVP")
            QJsonArray points = point["points"].toArray();
            int numPoints = points.count();

            SDK_SVPWaypoint * waypoints = new SDK_SVPWaypoint[numPoints];
            SDK_InitSVPWaypoints(waypoints, numPoints);

            for (int j = 0; j < numPoints; j++)
                QJsonObject p = points[j].toObject();
                waypoints[j].x = p["x"].toInt();
                waypoints[j].y = p["y"].toInt();
                waypoints[j].course = convertGeoHeading(p["course"].toInt());

            SDK_AddSVPsToTour(tour, numPoints, waypoints);
            mDestination.x = waypoints[numPoints - 1].x;
            mDestination.y = waypoints[numPoints - 1].y;
            SDK_Waypoint wayPoint;

            QJsonObject p = point["point"].toObject();
            wayPoint.x = p["x"].toInt();
            wayPoint.y = p["y"].toInt();
            wayPoint.course = convertGeoHeading(p["couse"].toInt());

            SDK_AddStationToTour(tour, wayPoint);
            mDestination.x = wayPoint.x;
            mDestination.y = wayPoint.y;


    SDK_INT2 sectionError = 0;

    SDK_ERROR rc = SDK_CalculateTour(tour, progressCallback, &sectionError);


    if (rc == SDK_ERROR_Ok)

    emit finished((int)rc);

SDK_INT2 CalcTourRunnable::convertGeoHeading(int heading)
    heading = 90 - heading;
    if (heading < 0)
        heading += 360;

    return (SDK_INT2)heading;

void CalcTourRunnable::getStart(SDK_Waypoint& start)
    SDK_GPSData gps;

    // get the current gps position
    SDK_ERROR rc = GPSManager::getInstance()->getCurrentPosition(gps);
    start.course = gps.course;
    start.x = gps.GPSPositionMerc.x;
    start.y = gps.GPSPositionMerc.y;

SDK_INT4 SDK_API CalcTourRunnable::progressCallback(SDK_INT4 current, SDK_INT4 total, SDK_INT4 job)
    emit pThis->progress(current);
    return 1;

In our MainWindow, we added a new menu entry to start a tour calculation. The menu entry triggers the action actionLoadSVPTour. So we have to create a new function and connect this signal with this new function in our MainWindow.

Add/Change the following in the MainWindow class:


protected slots:
    void actionLoadSVPTourTriggered(bool triggered);


#include "CalcTourRunnable.h"
MainWindow::MainWindow(QMainWindow * parent) : QMainWindow(parent)
    connect(ui.actionLoadSVPTour, SIGNAL(triggered(bool)), this, SLOT(actionLoadSVPTourTriggered(bool)));  
void MainWindow::actionLoadSVPTourTriggered(bool checked)

    if (!mProgressDialog)
        mProgressDialog = new QProgressDialog("Calculating tour...", "Cancel", 0, 100, this, Qt::WindowSystemMenuHint | Qt::WindowTitleHint);

    CalcTourRunnable * runnable = new CalcTourRunnable(;

    connect(runnable, SIGNAL(progress(int)), this, SLOT(onProgress(int)));
    connect(runnable, SIGNAL(finished(int)), this, SLOT(onCalcRouteFinished(int)));



First we connect the signal with the function actionLoadSVPTourTriggered(bool) in the constructor. In actionLoadSVPTourTriggered() we do nearly the same as what do in the "normal" route calculation in actionSearchAddressTriggered(). We disable the NavigationLoop and the map updates, show the progress dialog, create a new CalcTourRunnable, connect the progress and finished signals of our runnable to the appropriate slots in our MainWindow and push the runnable to our SDKJobQueue.



Alternative routes are currently only supported for the first destination of your tour and only if it is a regular destination.

Switch to next destination

Currently you have to create a new tour, add all destinations except the first and call SDK_CalculateTour() again. This will probably change in a future release.