View source for Marble/Routing/BasicRouting


{{TutorialBrowser|

series=Marble C++ Tutorial|

name=Basic Routing|

pre=[[Projects/Marble/OnlineServices|Tutorial 8 - OnlineServices]]|

next=[[Projects/Marble/Runners/Search|Tutorial 10 - Searching]]| 
}}

== Basic Routing ==
The Marble library 0.13 and later (KDE 4.8, Marble 1.3) has an API to calculate and manage routes. Let's start with a brief overview of the important classes and their interaction. The class <tt>RouteRequest</tt> holds parameters that are constraints for the route to be calculated: Start and destination, optional via points and further parameters (e.g. transport type). The <tt>RoutingManager</tt> passes such a request to backends (routing plugins) that calculate possible routes from it. The best route is chosen and displayed in a special layer in the <tt>MarbleWidget</tt>. Additionally you can access the route data via the <tt>RoutingModel</tt>. This model can be passed directly to e.g. a QListView to show the turn instructions, but also exposes further data like the waypoints of the route via the <tt>Route</tt> class. This one consists of a set of <tt>RouteSegment</tt> instances, each representing a number of waypoints and an optional turn instruction (<tt>Maneuver</tt>) at the end.

<source lang="cpp-qt">
#include <QtGui/QApplication>
#include <marble/MarbleWidget.h>
#include <marble/MarbleModel.h>
#include <marble/RouteRequest.h>
#include <marble/RoutingManager.h>

using namespace Marble;

int main(int argc, char** argv)
{
    QApplication app(argc,argv);

    // Create a Marble QWidget without a parent
    MarbleWidget *mapWidget = new MarbleWidget();

    // Load the OpenStreetMap map
    mapWidget->setMapThemeId( "earth/openstreetmap/openstreetmap.dgml" );
    mapWidget->setProjection( Mercator );

    // Access the shared route request (start, destination and parameters)
    RoutingManager* manager = mapWidget->model()->routingManager();
    RouteRequest* request = manager->routeRequest();

    // Use default routing settings for cars
    request->setRoutingProfile( manager->defaultProfile( RoutingProfile::Motorcar ) );

    // Set start and destination
    request->append( GeoDataCoordinates( 8.38942, 48.99738, 0.0, GeoDataCoordinates::Degree ) );
    request->append( GeoDataCoordinates( 8.42002, 49.0058, 0.0, GeoDataCoordinates::Degree ) );

    // Calculate the route
    manager->retrieveRoute();

    // Center the map on the route start point and show it
    mapWidget->centerOn( request->at( 0 ) );
    mapWidget->setDistance( 0.75 );
    mapWidget->show();

    return app.exec();
}
</source>

Copy and paste the code above into a text editor. Then save it as <tt>my_marble.cpp</tt> and compile it by entering the following command on the command line:

<source lang="bash">
 g++ -I /usr/include/qt4/ -o my_marble my_marble.cpp -lmarblewidget -lQtGui -lQtCore
</source>

If things go fine, execute <tt>./my_marble</tt> and you end up with a fully usable OpenStreetMap application: 

[[Image:Marble-basic-routing.png]]

The latest source code of this example can be found [https://quickgit.kde.org/?p=marble.git&a=blob&f=examples%2Fcpp%2Fbasic-routing%2Fmain.cpp here].

{{tip|
Here's a little checklist to tackle some problems that might arise when compiling the code above:

* You need Qt and '''Marble development packages''' (or comparable git installations), version 1.3 (Marble library 0.13), shipped e.g. with KDE 4.8
* If ''Qt headers'' are not installed in '''/usr/include/qt4''' on your system, change the path in the g++ call above accordingly.
* Likewise, '''add -I /path/to/marble/headers''' if they're not to be found in /usr/include
}}
{{note|
If you provide maps in your application please check the '''Terms of Use''' of the map material. The map material that is shipped with Marble is licensed ''in the spirit of Free Software''. This usually means at least that the authors should be credited and that the license is mentioned.
E.g. for ''OpenStreetMap'' the license is [http://creativecommons.org/license/by-sa/2.0 CC-BY-SA]. Other map data shipped with Marble is either public domain or licensed in the spirit of the BSD license.
}}