Use Cases > PTV xMap > How to Display Routing Layer

How to Display Routing Layer

Introduction

This example shows how to display a route that was calculated with PTV xRoute Server in a map. To get the desired result, a map showing a route, we have to call two PTV xServer successively. The example is based on these two examples:

basic routing example
mapping example drawing with a line

We will omit steps that were dealt with in those examples. So you should be familiar with the examples before working through the code below.

Differences to the previous examples

General differences

Regards only C#: Previously, we used either the XMap or the XRoute namespace. As some classes exist in both namespaces, we now have to address the classes explicitly by namespace and name. Example: boundingBox.leftTop = new Point(); becomes boundingBox.leftTop = new XMap.Point();

Routing

The following is different from the basic routing example:

To retrieve the polygon information from PTV xRoute Server we have to make use of the ResultListOptions. Necessary are two properties:
- polygon tells the PTV xRoute Server to return the polygon information of the calculated route. In this example we request it as WKB (well-known binary).
- totalRectangle is required for the subsequent request to the PTV xMap Server, as we make use of the method with the BoundingBox.
To retrieve a polygon of the route as WKB we have to make use of the CallerContext, where we specify the ResponseGeometry.
Last but not least we have to call the method calculateRoute() instead of calculateRouteInfo()

Mapping

The following is different from the mapping example with a line:

We don't have to grab all the points from the polygon of the calculated route and put them into loads of point objects, we make it more simple. We request the polygon in the WKB format and put them directly into the polygon of the CustomLayer.
Our BoundingBox is fed with the different values of the totalRect.
We define the width of the underlying line as a negative value. We will explain why later.
We have to define the drawPriority to be sure that the line is placed in the right level of the map.
To see the complete route in the map we center the CustomLayer.

WKB (well-known binary) is the binary representation of WKT (well-known text). WKB can be used to encode vector geometry objects (such as points, lines, polygons, etc.) into a compact binary representation which is easy to store in databases and more efficient than XML regarding size. Both WKB and WKT are regulated by the Open Geospatial Consortium (OGC).

Defining the ResultListOptions

Here we have to define that we want to get the polygon and also the totalRectangle because both of them are used for the request to the PTV xMap Server.

Step 1: Instantiate a new object resultListOptions

Java snippet

ResultListOptions resultListOptions = new ResultListOptions();

resultListOptions.setPolygon(true);

resultListOptions.setTotalRectangle(true);

resultListOptions.setDetailLevel(DetailLevel.STANDARD);

Defining the CallerContext

As CallerContextProperty property ResponseGeometry we specify WKB as value to retrieve the polygon information of the route formatted as a WKB. This makes further handling of the polygon very easy.

Step 2: Create a new CallerContextProperty object property

Java snippet

CallerContextProperty property = new CallerContextProperty("ResponseGeometry", "WKB");

CallerContext callerContext = new CallerContext();

callerContext.setProperties(new CallerContextProperty[] { property });

Call to the PTV xRoute Server

Calling the method calculateRoute we are receiving the polygon information we are longing for.

Step 3: Return route using the method calculateRoute

Java snippet

Route route = xRouteClient.calculateRoute(waypointDescs, null, null, resultListOptions);

Putting the polygon into the LineString

Having requested the polygon information of the route formatted as a WKB, we can put it directly into our LineString. It's that easy!

Step 4: Define object lineStrings as a new array of LineString[]

Java snippet

LineString[] lineStrings = new LineString[]{ route.getPolygon()};

totalRectangle becomes BoundingBox

Creating a map requires either a MapSection or a BoundingBox. As the PTV xRoute Server responds something similar like the BoundingBox, we take the totalRectangle from PTV xRoute Server and put it into our renderMapBoundingBox().

With xRoute.Route the totalRectangle comes as[leftBottom/rightTop] and not as usually as [leftTop/rightBottom].

So far so good, but what to do with this information? Once we requested our polygon formatted as WKB the totalRectangle automatically returns wkb-formatted. So it is not possible to exchange the values cross over. But as we center our CustomLayer afterwards, this makes no problem. The only important thing is that we create some BoundingBox for our call to the PTV xMap Server. So it is just a gimmick to use the false values directly.

Step 5: Set leftTop and rightTop for boundingBox.

Java snippet

BoundingBox boundingBox = new BoundingBox();

boundingBox.setLeftTop( route.getTotalRectangle().getLeftBottom() );

boundingBox.setRightBottom( route.getTotalRectangle().getRightTop() );

A trick with negative line width

Later we will define the drawPriority such that the line is not drawn on top of the map but somewhere between the layers. Hence, we will have to make sure that the routing line isn't occluded with any zoom/scale value. To do this we can use a very valuable feature of the PTV xMap Server:

Setting the width to a negative value will ensure that the line is always broader than the motorways in the map by exactly the defined value.

Step 6: Use object options to define the properties of your line.

Java snippet

LineOptions options = new LineOptions();

LinePartOptions partoptions = new LinePartOptions();

partoptions.setColor(new Color(0, 0, 255));

partoptions.setVisible(true);

partoptions.setWidth(-10);

options.setMainLine(partoptions);

Characteristics of CustomLayer object

First, we have to specify the drawPriority of the CustomLayer as we don't want have our line drawn on top of the map, but somewhere between the other layers. We use the priority 100, which matches PRIORROUTE.

Second matter is that we want our route to be completely visible and centred in the map. To do this we have to set centerObjects to true.

Step 7: Set properties to class customLayer as described above.

Java snippet

CustomLayer customLayer = new CustomLayer();

customLayer.setVisible(true);

customLayer.setDrawPriority(100); // this is PRIORROUTE

customLayer.setLines(lines);

customLayer.setObjectInfos(ObjectInfoType.NONE);

customLayer.setCenterObjects(true);

Layer[] layers = new Layer[] { customLayer };

Source Code

The example drawing a route with CustomLayer is also executable as a stand-alone java program.