05 Route calculation

Overview

In this tutorial you will learn how to calculate a route from A to B and how to influence the routing by setting your vehicle parameters.

Base

You can use your results from Tutorial04 as a base for our new project.

Retrieving the destination

In the last tutorial we added a simple activity to search for addresses. To start a navigation to the search result we first add a FloatingActionButton as a start button.

<android.support.design.widget.CoordinatorLayout>

    ...

    <android.support.design.widget.FloatingActionButton
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="bottom|right"
        android:layout_margin="16dp"
        app:layout_anchor="@id/search"
        android:src="@android:drawable/ic_dialog_map"
        app:layout_anchorGravity="bottom|right|end"
        android:onClick="onFloatingButtonClicked"/>
</android.support.design.widget.CoordinatorLayout>

In onFloatingButtonClicked we then check which of the three search results are set. The finest/best result will be send to our MainActivity for the route calculation by bundling it to the MainActivity Intent.

Attention

We start the activity with the flags Intent.FLAG_ACTIVITY_CLEAR_TOP and Intent.FLAG_ACTIVITY_SINGLE_TOP to reuse the current MainActivity and avoid a new instance of it!

public void onFloatingButtonClicked(View view)
{
    Intent intent = new Intent(this, MainActivity.class);
    if (mCurrentHNRResult != null) {
        intent.putExtra("destination", mCurrentHNRResult.getPosition());
    } else if (mCurrentStreetResult != null) {
        intent.putExtra("destination", mCurrentStreetResult.getPosition());
    } else if (mCurrentTownResult != null) {
        intent.putExtra("destination", mCurrentTownResult.getPosition());
    }

    intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_SINGLE_TOP);
    startActivity(intent);
}

Now we only need to override the onNewIntent method of the MainActivity to retrieve the route calculation intent and extract the destination from the Intent bundle.

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);

    if (!intent.hasExtra("destination"))
        return;

    final Position destination = intent.getParcelableExtra("destination");
}

Calculating a route

Every long lasting operation should be performed in a background thread to avoid stalling the GUI thread and therefore the user interactions. So we put long lasting operations in a seperate thread. The NavigationSDK helps you with a simple worker thread (the SDKJobQueue) where you can queue your long lasting NavigationSDK operations.

Hint

You can easily use your own asynchronous mechanism. But be aware that most of the NavigationSDK functions are currently mutual exclusive and cannot be called concurrently. So try to call only one NavigationSDK method at a time to avoid locks in your application.

So we create a Runnable with all the route calculation operations and push it via SDKJobQueue.getInstance().push() to the SDKJobQueue. To calculate a route from our current position to our given destination we create a Tour with the current position in the constructor as the start. The destination is added via addStation. Then we call calculateTour with it.

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);

    if (!intent.hasExtra("destination"))
        return;

    final Position destination = intent.getParcelableExtra("destination");

    Runnable calcRoute = new Runnable() {
        @Override
        public void run() {
            WayPoint start;
            try {
                // set current position as starting point
                start = new WayPoint(GPSManager.getInstance().getCurrentPosition());
            } catch (NavigationException e) {
                // if it fails use Karlsruhe
                start = new WayPoint(934177, 6268747);
            }

            try {
                Tour tour = new Tour(start);

                tour.addStation(new WayPoint(destination));

                CalculateTourResult result =
                        NavigationSDK.calculateTour(tour, null);

                if (result.getError() != SDKErrorCode.Ok) {
                    Toast.makeText(MainActivity.this, "route calculation failed", Toast.LENGTH_LONG).show();
                }
            } catch (CalculateTourException | NavigationException e) {
                e.printStackTrace();
            }
        }
    };

    // don't forget to remove the extra to avoid handling it twice
    intent.removeExtra("destination");

    SDKJobQueue.getInstance().push(calcRoute);
}

The result for an example route from Karlsruhe to Stuttgart:

Attention

Try to avoid calling other NavigationSDK methods on another thread while the route calculation is running. For example drawing the map on the GUI thread while calculating the route will lock the GUI thread because most NavigationSDK methods are protected by the same mutex and cannot be called in a concurrent way.

To avoid calling other NavigationSDK methods on another thread while the route calculation is running, we push our NavigationLoop and our GPSManager.getInstance().pushLocation() call also to the SDKJobQueue. So we are save that all recurring NavigationSDK methods are called on the same thread.

public class MainActivity extends AppCompatActivity {
    ...
    private LocationListener locationListener = new LocationListener() {
        @Override
        public void onLocationChanged(final Location location) {
            SDKJobQueue.getInstance().push(new Runnable() {
                @Override
                public void run() {
                    GPSManager.getInstance().pushLocation(location);
                }
            });
        }
        ...
    };
    ...
    TimerTask navigationLoopTrigger = new TimerTask(){
        @Override
        public void run() {
            SDKJobQueue.getInstance().push(navigationLoop);
        }
    };
    ...
}

Retrieving progress information

Users should be notified about the progress of every long lasting operation so most of the long lasting operations in the NavigatioSDK can be called with an Observer to monitor their progress. To monitor the route calculation progress we implement an Observer as a member of the MainActivity and call calculateTour with it.

Observer calcRouteObserver = new Observer() {
    @Override
    public void onProgress(final int current, final int total, int job) {
    }

    @Override
    public void onFinished(final int error, int index) {
    }
};

CalculateTourResult result = NavigationSDK.calculateTour(tour, calcRouteObserver);

Attention

The onProgress and onFinished callbacks will be called from the thread in which the route calculation was started from. So in our example from the SDKJobQueue thread.

To show a ProgressDialog we have to bring the execution back to the GUI thread. So we give the MainActivity a Handler member and post our GUI code to it via a Runnable.

Handler handler = new Handler();
ProgressDialog progressDialog;

    private final Observer calcRouteObserver = new Observer() {
        @Override
        public void onProgress(final int current, final int total, int job) {
            handler.post(new Runnable() {
                @Override
                public void run() {
                    if (progressDialog == null) {
                        progressDialog = new ProgressDialog(MainActivity.this);
                        progressDialog.setTitle("Calculating route");
                        progressDialog.setProgressStyle(ProgressDialog.STYLE_HORIZONTAL);
                        progressDialog.setProgress(current);
                        progressDialog.setMax(total);
                        progressDialog.setCancelable(false);

                        progressDialog.show();
                    } else {
                        progressDialog.setProgress(current);
                    }
                }
            });
        }

        @Override
        public void onFinished(final int error, int index) {
            super.onFinished(error, index);
            handler.post(new Runnable() {
                @Override
                public void run() {
                    if (progressDialog != null) {
                        progressDialog.dismiss();
                        progressDialog = null;
                    }
                }
            });
        }
    };

Currently the intent is handled while the MainActivity is initializing so it is possible that the MainActivity tries to draw itself for the first time while the route calculation is running. This yields in a lock of the GUI thread for the time of the route calculation and mostly it leads to a black screen. To avoid this we delay the route calculation to the point when the MapView is fully drawn for the first time. For this we implement OnInitializeListener in the MainActivity and set it with setOnInitializeListener on the MapView. We can move the intent handling code to an own function called handleIntent and call it in onFirstTimeDrawn. In onNewIntent we just set the current intent via setIntent(intent).

public class MainActivity extends AppCompatActivity implements OnInitializeListener {
    ...

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        mapView = (MapView)findViewById(R.id.map);
        mapView.setOnInitializeListener(this);

        ...
    }

    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        setIntent(intent);
    }

    ...

    void handleIntent(Intent intent) {
        if (!intent.hasExtra("destination"))
            return;

        final Position destination = intent.getParcelableExtra("destination");

        Runnable calcRoute = new Runnable() {
            @Override
            public void run() {
                WayPoint start;
                try {
                    // set current position as starting point
                    start = new WayPoint(GPSManager.getInstance().getCurrentPosition());
                } catch (NavigationException e) {
                    // if it fails use Karlsruhe
                    start = new WayPoint(934177, 6268747);
                }

                try {               
                    Tour tour = new Tour(start);

                    tour.addStation(new WayPoint(destination));

                    CalculateTourResult result =
                            NavigationSDK.calculateTour(tour, null);

                    if (result.getError() != SDKErrorCode.Ok) {
                        Toast.makeText(MainActivity.this, "route calculation failed", Toast.LENGTH_LONG).show();
                    }
                } catch (CalculateTourException | NavigationException e) {
                    e.printStackTrace();
                }
            }
        };

        // don't forget to remove the extra to avoid handling it twice
        intent.removeExtra("destination");

        SDKJobQueue.getInstance().push(calcRoute);
    }

    @Override
    public void onInitialize() {
    }

    @Override
    public void onFirstTimeDrawn() {
        handleIntent(getIntent());
    }
}

RoutingOptions

Loading a vehicle profile

To avoid setting the routing options manually and to get a quick way to set them for a particular vehicle, we use so called profiles which describes certain standard vehicles like trucks, cars, transporters and so on. In these profiles (which are text files) the values for the relevant routing and lorry options are preset (some of the options are not in the profiles file, but will be adapted internally to the used vehicle). We highly recommend to use the profile loading mechanism which the SDK provides instead of setting the options manually, especially the speed tables.

Loading a profile is done by calling the method NavigationSDK.loadVehicleProfile(). The function takes as parameter the full path to the profile file which should be loaded.

We deliver a set of profiles in a directory called 'profiles' under the data directory of the tutorial app data.

public class Application extends android.app.Application {

    ...

    @Override
    public void onCreate() {
        super.onCreate();

        ...

        File profilePath = new File(getDataPath(), "profiles");
        NavigationSDK.loadVehicleProfile(new File(profilePath, "truck75.dat"));
    }

Manually setting the routing options

Setting the routing options manually is also possible but only recommended for experts. The NavigationSDK brings several methods to influence the result of the route calculation. For example you can avoid toll roads, decide, what kind of vehicle you are driving or if you want a routing optimized for short way or short time. To get you started we set a bunch of Options in the Application in a new method setDefaultRoutingOptions. By calling NavigationSDK.getRoutingOptions() we retrieve the default RouteOptions which we can alter to our needs afterwards. The example is only a starting point to play with and alter it to your custom wishes.

private void setDefaultRoutingOptions() {
    try
    {
        Result<RouteOptions> result = NavigationSDK.getRoutingOptions();
        RouteOptions options = result.getResult();

        boolean avoidToll = false;

        if (avoidToll) {
            options.setTollFactor(90);
            options.setTruckTollFactor(90);
            options.setUseTollLayer(true);
            options.setUseTruckTollLayer(true);
        } else {
            options.setUseTollLayer(false);
            options.setUseTruckTollLayer(false);
        }

        options.setTimeFactor(80);

        Result<LorryOptions> lorryResult = NavigationSDK.getLorryOptions();
        LorryOptions lorry = lorryResult.getResult();

        int vehicle = 0;

        if (vehicle == 0) {
            options.setLorry(true);
            lorry.setWeight((short)75);
            lorry.setHeight((short)37);
        } else if (vehicle == 1) {
            options.setLorry(true);
        } else {
            options = null;
        }

        options.setRoutingVehicle(RoutingVehicleType.USER);

        short[] speedTableRouteList = {82,75,74,66,60,45,56,51,48,38,35,23,30,30,15};
        short[] speedTableCalc = {84,76,74,66,60,40,50,38,26,22,11,5,5,5,2};

        options.setSpeedTable_RouteList(speedTableRouteList);
        options.setSpeedTable_Calc(speedTableCalc);

        NavigationSDK.setRoutingOptions(options);
        NavigationSDK.setLorryOptions(lorry);
    }
    catch (NavigationException e)
    {
        Log.e("Tutorial", e.getMessage());
    }
}