Use Cases > PTV xMap > How to Use Feature Layer Theme PTV_PreferredRoutes

How to Use Feature Layer Preferred Routes

The feature layer preferred routes represents subnetworks of the road networks to be prioritised (for trucks with special loads or heavy vehicles for example).

During route calculation a certain bonus will be applied to the segments, if they belong to a preferred network. Depending on the international laws and regulations different types of preferred roads subnetworks are available in different countries. The preferred routes data of North America for example includes preferred routes data of the STAA (Surface Transportation Assistance Act of 1982), while the data of Australia for example includes special attributes for B-double trucks. The user can easily select by configuration which of them needs to be prioritised. The available types of preferred routes subnetworks are described in the feature layer theme specific documentation.

What are STAA Trucks?

The Surface Transportation Assistance Act of 1982 allows large trucks, referred to as STAA trucks, to operate on routes that are part of the National Network.

The Federal Highway Administration (FHWM) provides standards for STAA trucks based on the Code of Federal Regulations Tile 23 Part 658. These standards designate the minimum truck sizes that all states must allow on the National Network.

The National Network includes the Interstate System and other designated highways which were a part of the Federal-Aid Primary System on June 1, 1991. These other designated highways are listed in Tile 23 Part 658, appendix A, however, states are encouraged to allow access for STAA trucks on all highways

Which data is available in which country finally depends on the data provider. So please take a close look at the feature layer theme specific documentation.

Benefits

PTV xRoute Server

With preferred routes data, purchased through licensing the PTV_PreferredRoutes feature layer theme, the customer has the following benefits:

Calculate a route that will prioritise on one or more preferred route subnetworks according to the international laws and regulations.
Choose one or several preferred routes subnetworks to optimise a route by minimising the length driven outside the preferred network.
In the response route list the user can see for each segment, if it belongs to a certain preferred routes segment. For more information on this topic please refer to the technical concept about Feature Layer. This information can be evaluated to summarise the length driven on or outside a certain preferred routes network.

PTV xMap Server

Additionally the user can easily visualise PTV_PreferredRoutes data on the map using PTV xMap Server by colouring segments according to their preferred routes network type. This visualisation on the map has the following benefits for the customer:

Improve the acceptance of a route which was calculated taking PTV_PreferredRoutes into account.
Give visual feedback to the customer by showing the preferred route network on the map (for example to see the coverage of the tour on the preferred routes network).

Prerequisites

Expanding the License Scope

In order to use the feature layer theme PTV_PreferredRoutes with the PTV xServer, you need to ensure that the following two licence keys include the PTV_PreferredRoutes theme

For PTV xRoute Server: xroute.featureLayerThemes=PTV_PreferredRoutes, ...
For PTV xMap Server: xmap.featureLayerThemes=PTV_PreferredRoutes, ...

You can check the license content once the server has been started in the management console.

Feature Matrix for Feature Layer Preferred Routes

Find out which service method of PTV xRoute Server supports the PTV_PreferredRoutes feature layer theme.

service method	PTV_PreferredRoutes
calculateRouteInfo	x
calculateRoute	x
calculateExtendedRoute	x
calculateTour	x
calculateAdvancedTour	x
calculateMatrixInfo	x
calculateReachableObjects	-
searchForReachableObjects	-
calculateIsochrones	-

Concept

Feature layers are designed to provide various additional data to the user. The content depends on the feature layer theme and can be configured via XML profile. In the PTV xRoute server, feature layer data can be requested as generic FeatureDescription element for each route segment.

Installation Guide

Download the latest feature layer preferred routes from the Customer Area of the PTV Developer Zone according to the used map. If you don't have an account, please contact your account manager at PTV.
Unzip the PTV_PreferredRoutes_<Mapname>.zip file directly to the map folder of the PTV xRoute or xMap Server. The map folder is specified in the maps.path key of the configuration file <PTV xRoute folder>/conf/xroute.properties or of the configuration file <PTV xMap folder>/conf/xmap.properties.
Restart the PTV xRoute and xMap Server to activate the just installed feature layers.

Configuration Guide

After successful installation of PTV_PreferredRoutes feature layer data in your map directory just do the following.

PTV xRoute Server

Ensure that PTV xRoute Server has set the map.path key correctly in its PTV xRoute folder/conf/xroute.properties file.

If this is the case the Feature Layer data is automatically initialized on PTV xRoute Server startup.

PTV xMap Server

Ensure that PTV xMap Server has set the map.path key correctly in its PTV xMap folder/conf/xmap.properties file.

If this is the case the Feature Layer data is automatically initialized on PTV xMap Server startup.

Programming Guide

The consideration of PTV_PreferredRoutes can be done by referencing a specific XML profile or by adding an XML snippet to your request. Both adhere to the the structure of the PTV xServer Profiles and can also be combined. Please refer to the technical concept of the Profiles. It explains how XML Profiles and the Profile Snippet Mechanism work in general. A detailed documentation of each PTV xServer Profile Scheme (XSD) is available in the subchapters.

Calculate Route with PTV_PreferredRoutes

In this section the route calculation taking into account PTV_PreferredRoutes is explained. Below you can find a JSON sample request which can be directly copied and put into the Raw Request Runner of an PTV xRoute Server to be tested.

Flow

Ensure that the PTV_PreferredRoutes theme is correctly installed and licensed for your PTV xRoute Server.
In order to activate the usage of PTV_PreferredRoutes the sample JSON request below must set at least the following parameters.
- Start and destination coordinates.
- A valid ProfileXMLSnippet shown here under enabling the feature layer theme PTV_PreferredRoutes to be used in route calculation.
  Be aware that without a preferredRouteType by default all types of preferred routes are drawn.
Send the JSON sample request with PTV_PreferredRoutes enabled and network type 9 preferred to PTV xRoute Server.
Change the JSON sample request and switch of PTV_PreferredRoutes by setting the enable attribute to false.
Send the modified JSON example request again to the PTV xRoute Server.
Now different results in travel time and travel distance should be observed.

The second request should result in a smaller travel time and distance because it is not forced to take the preferred route network.

ProfileXMLSnippet: Enabling FeatureLayer PTV_PreferredRoutes

<?xml version='1.0' encoding='UTF-8'?>
<Profile>
   <FeatureLayer majorVersion='1' minorVersion='0'>
      <Themes>
         <!--enable the PTV_PreferredRoutes theme-->
         <Theme id='PTV_PreferredRoutes' enabled='true'>
            <!--activate the particular preferred routes network type 9-->
            <!--which types are supported by theme Preferred Routes is described in the feature layer specific data section-->
            <PropertyValue id='preferredRouteType' value='9'/>
         </Theme>
      </Themes>
</FeatureLayer>
<Routing majorVersion='2' minorVersion='0'>
   <Course>
      <!-- switch on additional data rules to take into account preferred routes during route calculation-->
      <AdditionalDataRules enabled='true'/>
   </Course>
</Routing>
</Profile>

Visualisation of PTV_PreferredRoutes on the map

This section describes the general flow how to visualise PTV_PreferredRoutes on the map.

Subsequent visualisation examples are just using different ProfileXMLSnippets - each of them described below - but following the same general Flow

Flow

Ensure that the PTV_PreferredRoutes theme is correctly installed and licensed for your PTV xMap Server.
in order to activate the usage of PTV_PreferredRoutes the sample JSON request below must set at least the following parameters
- reference coordinates of the bounding box
- the imageinfo element defining the size and format of the returned image
- a valid ProfileXMLSnippet shown hereunder enabling the FeatureLayer to be visualised
send the JSON sample request to PTV xMap Server and look at the resulting image

ProfileXMLSnippet: Enabling FeatureLayer PTV_PreferredRoutes

<?xml version='1.0' encoding='UTF-8'?>
<Profile>
   <FeatureLayer majorVersion='1' minorVersion='0'>
      <Themes>
         <!--enable the PTV_PreferredRoutes theme-->
         <Theme id='PTV_PreferredRoutes' enabled='true'>
            <!--activate the particular preferred routes network type 9-->
            <!--which types are supported by theme Preferred Routes is described in the feature layer specific data section-->
            <PropertyValue id='preferredRouteType' value='9'/>
         </Theme>
      </Themes>
   </FeatureLayer>
</Profile>

Default rendering settings for PTV_PreferredRoutes

The following section shows the default rendering settings of the PTV_PreferredRoutes feature layer. These settings are displayed and summarised with the associated XML snippets. Please refer to About Feature Layer Rendering for an overview of all rendering possibilities.

<Class name="STAA_and_BDouble">
 <Filer>
  <Condition displayClass="NetworkType">
   <Range values="0-200"/>
  </Condition>
 </Filter>
 <Style>
  <Geometry displayRange="9-23">
   <RenderLevel renderOffset="+5"/>
   <Stroke color="#154889" transparency="0" perpendicularOffset="0%" width="120%"/>
  </Geometry>
 </Style>
</Class>

This section above from the XML profile shows the display of the preferred routes as a blue stroke (color=“#154889"), which is shown above the road (renderOffset="+5") and is wider than the actual road (width="120%").

Be aware that a changed zoom level at DisplayRange can cause loss of performance!

Below you can find a JSON sample request which can be directly copied and put into the raw request runner of an PTV xMap Server to be tested.

Below you can see the resulting picture illustrating a sample preferred routes subnetwork in Luxemburg.

<PropertyValue id='preferredRouteType' value='9'/>

Visualisation of PTV_PreferredRoutes on the map with individual styles and filters

This section describes how you can define your own styles and filters to visualise PTV_PreferredRoutes on the map. The changed style is defined in the request by using an appropriate ProfileXMLSnippet. For the general concept how to define your own style classes filters and styles please refer to the technical concept of Feature Layer rendering capabilities here. Below you find the annotated snippet used in the example request hereafter which changes the following.

reset the complete default theme definition for visualisation
define your own style class named AllTypes
specify your own filter to define on which street types the preferred routes should be visualised
specify your own style with your own stroking attributes

ProfileXMLSnippet: Change Style of a given Style Class for Visualisation

<Profile>
   <FeatureLayer majorVersion='1' minorVersion='0'>
      <Themes>
         <Theme enabled='true' id='PTV_PreferredRoutes'>
            <PropertyValue id='preferredRouteType' value='9'/>
         </Theme>
      </Themes>
   </FeatureLayer>
   <Rendering minorVersion='0' majorVersion='1'>
      <Country id='*'>
         <!-- Redefine the complete styles of the complete PTV_PreferredRoutes theme by setting reset to true-->
         <Theme id='PTV_PreferredRoutes' reset='true'>
            <!-- define a new class style named "AllTypes"-->
            <Class name='AllTypes'>
               <Filter>
                  <!-- define a new filter for all NetworkTypes-->
                  <!-- as they are not limited to certain types by using a Range subelement-->
                  <Condition displayClass='NetworkType'>
                    <Range values="0-200"/>
                    </Condition>
               </Filter>
               <Style>
                  <!-- define a new style for zoom levels 9-23 -->
                  <Geometry displayRange='9-23'>
                     <RenderLevel renderOffset='+5'/>
                     <Stroke color='#22AA22' transparency='10' width='220%'/>
                  </Geometry>
               </Style>
            </Class>
         </Theme>
      </Country>
   </Rendering>
</Profile>

As in the examples above the JSON sample request below can be directly copied and put into the raw request runner of an PTV xMap Server to be tested.