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

How to use Feature Layer Truck Traffic Patterns

The Truck Traffic Patterns are derived from (car) Traffic Patterns, influenced by many other data like height data, truck speed limits or passing restrictions. So the Truck Traffic Patterns are like the car Traffic Patterns but are providing data for trucks instead of cars. It is important to use only one of these Feature Layers at the same time.

With Truck Traffic Pattern data the average traffic situation during the week is modelled like with the (car) Traffic Pattern data. This means that by using Truck Traffic Patterns the speeds used for route calculation are time dependent speeds. Speeds for example on Mondays or Fridays in average are much slower than the speeds on Saturdays or Sundays. Even the speeds during the day differ between the rush hours (for example 7-9 and 16-18 o'clock) and the night hours (1-5 o'clock). Also in the PTV_TruckSpeedPatterns theme a set of many thousands of different traffic patterns for the whole street network is modelled. Please note that the terms Truck Traffic Patterns and Truck Speed Patterns are used synonymously, but you have to use PTV_TruckSpeedPatterns for the theme name. Like the Traffic Pattern data, the Truck Traffic Pattern data is modelled with a so called freeFlowSpeed and a deviation in % relative to the freeFlowSpeed depending on the time layer specific properties.

Terminology

Check these terms to ensure you understand the whole use case:

PTV_TruckSpeedPatterns: This term is used for the theme name and all including files
Truck Traffic Patterns: This term is used in case of communication about this Feature Layer.

Benefits

PTV xRoute Server

With Truck Traffic Pattern data, purchased through licensing the PTV_TruckSpeedPatterns Feature Layer theme, the user can improve its ETA (Estimated time of arrival) calculation with PTV xRoute Server. By taking into account typical traffic situations like rush hours in the morning and in the evening as well as average inbound and outbound traffic situations around big cities, the calculated ETA will have an increased accuracy. When taking into account Truck Traffic Patterns in the route calculation the user can choose between two ways of influencing the calculated result by applying certain appropriate ProfileXMLSnippets:

Influencing the travelled route and the calculated ETA (default behaviour)
Only influencing the ETA without influencing the route trajectory (Routing/Course/DynamicRouting/@dynamicTimeOnStaticRoute need to be set to true).

The second use-case can be used to calculate a travel trend for commuters and thus determine the best starting time for a given fixed route.

PTV xMap Server

Additionally the user can easily visualise Truck Traffic Patterns data on the map using PTV xMap Server by colouring segments according to their level of service (the relative deviation from free flow speed in percent) at a particular date and time. The visualisation of the level of service on the map has the following benefits for the customer:

Improve the acceptance of a route which was calculated taking into account Truck Traffic Patterns
Give feedback to the customer about the expected typical traffic situation at a certain week day and a certain time of day.

Prerequisites

Expanding the License Scope

In order to use the Feature Layer theme PTV_TruckSpeedPatterns with the PTV xServer, you need to ensure that the following two license keys include the PTV_TruckSpeedPatterns theme

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

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

Feature Matrix for Feature Layer Truck Traffic Patterns

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

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

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 Truck Traffic Patterns 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_TruckTrafficPatterns_<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
As the feature layer Truck Traffic Patterns is a time dependent Feature Layer you also have to install the Feature Layer Time Zones in the same map.

Configuration Guide

After successful installation of PTV_TruckSpeedPatterns Feature Layer data in your map directory just do the following

In contrast to the Traffic Patterns, the vehicle profiles truckfast.xml, truckslow.xml, default.xml and trafficinfoloader.xml have to be adapted to use this Feature Layer. You have to delete the SpeedMappings there.

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_TruckSpeedPatterns theme can be done by referencing a specific XML profile or by adding an XML snippet to your request. Both adhere to 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_TruckSpeedPatterns

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

In this example both, the route path as well as the ETA could be influenced through the use of PTV_TruckSpeedPatterns. But it is notable that often the speeds in the speed pattern data are not varying enough to result in a deviated of route path but only in a difference of the resulting ETA.

The vehicle profiles truckfast.xml, truckslow.xml, default.xml and trafficinfoloader.xml have to be adapted to use this Feature Layer. You have to deactivate/delete the SpeedMappings in the DynamicRouting section. If you use the parent mechanism, you need to make sure the SpeedMapping values in the profile chain are set accordingly.

Flow:

Ensure that the PTV_TruckSpeedPatterns theme is correctly installed and licensed for your PTV xRoute Server
In order to activate the usage of PTV_TruckSpeedPatterns the sample JSON request below must set at least the following parameters:
- Start and destination coordinates
- Starting reference time (note that PTV_TruckSpeedPatterns is a time dependent theme)
- A valid ProfileXMLSnippet shown hereunder enabling the feature layer theme PTV_TruckSpeedPatterns to be used in route calculation
Send the JSON example request with start time 2014-02-05T08:00:00+02:00 to the PTV xRoute Server
Change the start time in the JSON example request
Send the modified JSON example request again to the PTV xRoute server
Now observe different results in travel time.

ProfileXMLSnippet: Enabling FeatureLayer PTV_TruckSpeedPatterns:

<Profile xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
 <FeatureLayer majorVersion='1' minorVersion='0'>
  <!--enable the time dependency because we are using the time-dependent PTV_TruckSpeedPatterns theme-->
  <GlobalSettings enableTimeDependency='true'/>
  <Themes>
   <!--enable the PTV_TruckSpeedPatterns theme-->
   <Theme id='PTV_TruckSpeedPatterns' enabled='true'/>
  </Themes>
 </FeatureLayer>
  <Routing majorVersion='2' minorVersion='0'>
   <Course>
    <!--enable additional data rules to enable routing with additional content like feature layer-->
    <AdditionalDataRules enabled='true'/>
    <!--tells the router to take the speeds from PTV_TruckSpeedPatterns data as they are-->
    <!--this means that the speeds from PTV_TruckSpeedPatterns data could be inferior to the speeds defined in your vehicle profile-->
    <!--set this parameter to true if you want to limit the speed pattern speeds to those defined in your vehicle profile-->
     <DynamicRouting>
     <!--Deactivate the SpeedMappings here!-->
     </DynamicRouting>
   </Course>
  </Routing>
</Profile>

Visualisation of PTV_TruckSpeedPatterns on the map

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

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

Flow:

Ensure that the PTV_TruckSpeedPatterns theme is correctly installed and licensed for your PTV xMap server.
In order to activate the usage of PTV_TruckSpeedPatterns the sample JSON request below must set at least the following parameters.
- Reference coordinates of the bounding box
- Starting reference time (note that PTV_TruckSpeedPatterns is a time dependent theme)
- 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 Feature Layer PTV_TruckSpeedPatterns

<Profile xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
 <FeatureLayer majorVersion='1' minorVersion='0'>
  <!--enable the time dependency because we are using the time dependent PTV_TruckSpeedPatterns theme-->
  <GlobalSettings enableTimeDependency='true'/>
  <Themes>
  <!--enable the PTV_TruckSpeedPatterns theme-->
   <Theme id='PTV_TruckSpeedPatterns' enabled='true'/>
   </Themes>
 </FeatureLayer>
</Profile>

Default rendering settings for PTV_TruckSpeedPatterns

The following section shows the default rendering settings of the PTV_TruckSpeedPatterns 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="HeavyTrafficOnMainRoad">
 <Filter>
  <Condition displayClass="LevelOfService" streetType="MOTORWAY_FREEWAY">
   <Range values="0-50">
  </Condition>
 </Filter>
 <Style>
  <Geometry displayRange="9-23">
   <RenderLevel renderOffset="-1"/>
   <Stroke color="#FF0000" transparency="0" perpendicularOffset="80%" width="160%"/>
  </Geometry>
 </Style>
</Class>
<Class name="DenseTrafficOnMainRoad">
 <Filter>
  <Condition displayClass="LevelOfService" streetType="MOTORWAY_FREEWAY">
   <Range values="51-70"/>
  </Condition>
 </Filter>
 <Style>
  <Geometry displayRange="9-23">
   <RenderLevel renderOffset="-1"/>
   <Stroke color="#F7A20E" transparency="0" perpendicularOffset="80%" width="160%"/>
  </Geometry>
 </Style>
</Class>
<Class name="NormalTrafficOnMainRoad">
 <Filter>
  <Condition displayClass="LevelOfService" streetType="MOTORWAY_FREEWAY">  
   <Range values="71-101"/> 
  </Condition>
 </Filter>
 <Style>
  <Geometry displayRange="9-23">
   <RenderLevel renderOffset="-1"/>
   <Stroke color="#F38AA0E" transparency="50" perpendicularOffset="80%" width="160%"/>
  </Geometry>
 </Style>
</Class>

PTV_TruckSpeedPatterns distinguish between higher-level streets (highways) and lower-level ones (city roads). Above is the section for higher-level streets. PTV_TruckSpeedPatterns are categorised into three classes based on the current speed (Range values="0-50", "51-70", "71-101"): HeavyTraffic-, DenseTraffic- and NormalTrafficOnMainNetwork. They are displayed as an offset line (perpendicularOffset="80%") and differ only in the display colour (Heavy=red, Dense=orange and Normal=green)

<Class name="HeavyTrafficOnLowNetwork">
 <Filter>
  <Condition displayClass="LevelOfService" streetType="URBAN_STREET">
   <Range values="0-50"/>
  </Condition>
  <Condition displayClass="LevelOfService" streetType="LOCAL_MNOR_ROAD">			
   <Range values="0-50"/>
  </Condition>
  <Condition displayClass="LevelOfService" streetType="LOCAL_MAJOR_ROAD">
   <Range values="0-50"/>	
  </Condition>
  <Condition displayClass="LevelOfService" streetType="SINGLE_CARRIAGE_HIGHWAY">
   <Range values="0-50"/>	
  </Condition>
  <Condition displayClass="LevelOfService" streetType="DUAL_CARRIAGE_HIGHWAY">
   <Range values="0-50"/>	
  </Condition>
 </Filter>
 <Style>
  <Geometry displayRange="14-23">
   <RenderLevel renderOffset="-1"/>
   <Stroke color="#FF0000" transparency="0" perpendicularOffset="80%" width="120%"/>
  </Geometry>
 <Style>
</Class>

For low-level streets, the classification is identical. Here therefore, for example, only the HeavyTrafficOnLowNetwork class is described. This differs from HeavyTrafficOnMainNetwork only in terms of the width of the line (width="120%") and in the display range. The remaining settings are the same.

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 3 pictures illustrating the different levels of service at different dates during a normal weekday in Luxemburg:


"referenceTime": "2014-02-05T08:00:00+02:00"	"referenceTime": "2014-02-05T12:00:00+02:00"	"referenceTime": "2014-02-05T18:00:00+02:00"

Visualisation of PTV_TruckSpeedPatterns on the map with changed Style of a given style class

This section describes how to visualise PTV_TruckSpeedPatterns on the map using a changed style. The changed style is defined in the request by using an appropriate ProfileXMLSnippet. For the general concept how to define your own styles or redefine existing styles please refer to the technical concept of Feature Layer Rendering capabilities here About Feature Layer Rendering..

Below you find the annotated snippet used in the example request hereafter which changes the following:

the color attribute of the style class NormalTrafficOnMainNetwork from green to light blue.

<Profile xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
 <FeatureLayer majorVersion='1' minorVersion='0'>
  <GlobalSettings enableTimeDependency='true'/>
  <Themes>
   <Theme id='PTV_TruckSpeedPatterns' enabled='true'/>
  </Themes>
 </FeatureLayer>
 <Rendering minorVersion='0' majorVersion='1'>
  <Country id='*'>
   <Theme id='PTV_TruckSpeedPatterns'>
    <!--reference the style class named "NormalTrafficOnMainNetwork" defined in default.xml shipped with the PTV xMap server-->
    <Class name='NormalTrafficOnMainNetwork'>
     <!--omit the Filter element because we do not want to change the filter settings-->
     <Style>
      <!--be sure to choose the same displayRange as defined in the default.xml for the referenced class "NormalTrafficOnMainNetwork"-->
      <!--otherwise PTV xMap server will throw an exception-->
      <Geometry displayRange='ALWAYS'>
       <!--only change the color, let the other Stroke attributes unchanged-->
       <Stroke color='#30B4DB'/>
      </Geometry>
     </Style>
    </Class>
   </Theme>
  </Country>
 </Rendering>
</Profile>

How to know particular class names defined in the default.xml which is shipped with xMap Server?

To get known the predefined style class name of a certain Feature Layer theme you can look in the PTV xServer Configuration reachable through PTV xServer Administration Console.

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.

Visualisation of PTV_TruckSpeedPatterns on the map with changed filter of a given style class

This section describes how to visualise PTV_TruckSpeedPatterns on the map using a changed filter. The changed filter is defined in the request by using an appropriate ProfileXMLSnippet. For the general concept how to define your own filters or redefine existing filters please refer to the technical concept of Feature Layer Rendering capabilities in About Feature Layer Rendering. Below you find the annotated snippet used in the example request hereafter which changes the filter conditions of the style class NormalTrafficOnMainNetwork in order to

limit the visualisation to show LOS exclusively on motorways and freeways
change the range value specifying the LOS intervals which should be visualised in different styles

ProfileXMLSnippet: Change filter for visualisation of a certain style class

<Profile xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
 <FeatureLayer majorVersion='1' minorVersion='0'>
  <GlobalSettings enableTimeDependency='true'/>
  <Themes>
   <Theme id='PTV_TruckSpeedPatterns' enabled='true'/>
  </Themes>
 </FeatureLayer>
 <Rendering minorVersion='0' majorVersion='1'>
  <Country id='*'>
   <Theme id='PTV_TruckSpeedPatterns'>
    <!--reference the style class named "NormalTrafficOnMainNetwork" defined in default.xml shipped with the PTV xMap server-->
    <Class name='NormalTrafficOnMainNetwork'>
     <!--set the reset attribute of the filter to true in order to completely redefine the filter of style class NormalTrafficOnMainNetwork
     <Filter reset='true'>
      <!--Note that the filter redefinition includes only one single Condition element defining a modified Range for displayClass LevelOfService-->
      <!--the filter is now limited to the streetType MOTORWAY_FREEWAY exclusively-->
      <Condition displayClass='LevelOfService' streetType='MOTORWAY_FREEWAY'>
       <Range values='0-70'/>
      </Condition>
     </Filter>
     <!--omit the Style element because we do not want to change the styles settings-->
    </Class>
    <!--...do the same with the other 2 style classes which should be redefined-->
    <Class name='DenseTrafficOnMainNetwork'>
     <Filter reset='true'>
      <Condition displayClass='LevelOfService' streetType='MOTORWAY_FREEWAY'>
       <!--take care of non-overlapping ranges!-->
       <Range values='71-80'/>
      </Condition>
     </Filter>
    </Class>
    <Class name='NormalTrafficOnMainNetwork'>
     <Filter reset='true'>
      <Condition displayClass='LevelOfService' streetType='MOTORWAY_FREEWAY'>
       <Range values='81-101'/>
     </Filter>
    </Class>
   </Theme>
  </Country>
 </Rendering>
</Profile>

Hereafter the JSON sample request can be found to be directly tested in the raw request runner of an xMap Server.

The resulting image below shows that modified visualisation ranges of LevelOfService