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

How to Use Feature Layer TruckAttributes

The Feature Layer PTV_TruckAttributes provides additional restrictions that can be considered for your vehicle.

PTV_TruckAttributes provide data to calculate and display exact routes for extraordinary vehicles, for example vehicles exceeding the conventional height. It contains restrictions like maximum height of a tunnel, maximum weight allowed for bridges or restricted zones for vehicles carrying hazardous load. These restrictions are stored for single route segments and are consider depending on vehicle properties from the routing profile.

Terminology

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

Feature Layer: The Feature Layer defines the additional data mechanism. The data is partitioned into several themes that characterize different use-cases.

Benefits

Using TruckAttributes you can ...

calculate more exact routes for extraordinary vehicles.
list detailed restriction information of route segments.
visualize various route restrictions, such as tunnel height.

Prerequisites

Check if the following prerequisites are fulfilled before you start with the use case.

PTV xRoute Server or PTV xMap Server and a digital map of the area for route calculation.
Installation of Feature Layer PTV_TruckAttributes. The usage of this Feature Layer in conjunction with PTV xRoute Server and PTV xMap Server is available in version 1.20 or higher.
In order to request information from the feature layer theme PTV_TruckAttributes with PTV xRoute Server or PTV xMap Server, respectively, you need to ensure that the following license keys include the theme PTV_TruckAttributes
```
                xroute.featureLayerThemes=PTV_TruckAttributes, ...
                xmap.featureLayerThemes=PTV_TruckAttributes, ...
```

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.

For PTV_TruckAttributes this feature description element contains detailed information about the restrictions that are valid for the corresponding segment.

Consider total permitted versus maximum weight. Truck attributes with weight constraints are exclusively defined as maximum weights. The data providers don't differentiate between the total permitted and maximum weight (e.g. crossing bridges) which has a relevant impact on the following use cases:

Use maximum weight: Combination of empty and load weight has to be taken into account. But it might occur a conflict with restriction zones subject to the total permitted weight. Example: <Weight emptyWeight="6990" totalPermittedWeight="11990" loadWeight="0"/>. The physical value is around 7 tons but the total permitted weight is higher than 7.5 tons violating the restriction which relates to the total permitted weight (EU-Norm).
Take total permitted weight into account: Restriction zones related to this attribute shall be used for the route planning. The physical value is hereby less relevant. Example: <Weight emptyWeight="6990" totalPermittedWeight="11990" loadWeight="5000"/> (please note: is already defined as reference profile for trucks with 11.99t). The combination of empty and load weight corresponds to the total permitted weight. It is accepted that the maximum weight is adapted to the total permitted weight.

Caution: The user has to decide which use case is more relevant and should modify the values according to the current situation via request or application.

Installation Guide

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

Programming Guide

The following sample requests use routing requests (calculateRoute) to demonstrate routing with consideration of a height restriction. There is a height restriction of 460 centimeters maximum on the route between the coordinates (5.995894, 49.510518) and (5.999437, 49.505660). To consider this restriction in the routing, enable the use of the feature layer theme PTV_TruckAttributes by setting the following XML profile snippet in the CallerContext.

<Profile xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
 <FeatureLayer majorVersion='1' minorVersion='0'>
  <Themes>
   <!--enable the PTV_TruckAttributes theme-->
   <Theme id='PTV_TruckAttributes' 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'/>
  </Course>
 </Routing>
</Profile>

Using a vehicle with a height less than 460 cm

The vehicle configured in the default profile is a standard car, which has a height of 150 centimetres. If you use the default profile ( [xroute_root_folder]/conf/profiles/default.xml ), the resulting route should include the restricted segment, because the vehicle's height is below that restriction. The correct functioning of PTV_TruckAttributes and the presence of the height restriction can be checked using the FeatureDescription element. Feature descriptions are returned at each RouteListSegment of the xRoute response and can be activated by enabling segments and featureDescriptions in the request element ResultListOptions.

"details": {
    "segments": true,
    "featureDescriptions": true
  }

The calculated route should be about 800 meters long and takes around 100 seconds of travel time. To verify the correct use of PTV_TruckAttributes, check that the response contains feature description elements similar to the following:

"featureDescriptions": [
        {
          "themeId": "PTV_TruckAttributes",
          "description": "maxHeight=460|hazardousToWaters=0|hazardousGoods=0|combustibles=0|hasTrailer=0|freeForDelivery=0"
        }
      ]

Using a vehicle with a height more than 460 cm

To simulate a vehicle higher than 460 centimeters, we could alter the default profile using the XML profile snippet in the request's CallerContext. All vehicle parameters can be found under the element Vehicle in the routing profile. Add the following parts to the already existing XML snippet:

<Profile xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'> majorVersion='2' minorVersion='0'>
 <Routing majorVersion='2' minorVersion='0'>
  ...
  <Vehicle>
   <Physical>
     <Dimension height='480'/>
   </Physical>
  </Vehicle>
 </Routing>
</Profile>

Again, segments and featureDescriptions should be enabled in the ResultListOptions of the request.

The resulting route using the vehicle with increased height should be about 4000 meters long and take around 350 seconds of travel time. Since the vehicle is not allowed to use segments that contain height restrictions, the segment list does not contain any feature descriptions this time.

Visualization of PTV_TruckAttributes on the map

This section describes the general flow how to visualize PTV_TruckAttributes on the map.

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

Flow:

Ensure that the PTV_TruckAttributes theme is correctly installed and licensed for your xMapServer.
In order to activate the usage of PTV_TruckAttributes the sample JSON request below must set at least the following parameters.
- Reference coordinates of the bounding box
- Starting reference time (note that PTV_TruckAttributes is a partly 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 visualized
Send the JSON sample request to PTV xMap Server and look at the resulting image.

ProfileXMLSnippet: Enabling Feature Layer PTV_TruckAttributes

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

Default rendering settings for PTV_TruckAttributes

The following section shows the default settings of the PTV_TruckAttributes feature layer in the silkysand rendering style, which is used for the following examples. These settings are displayed and summarized with the associated XML snippets. Please refer to About Feature Layer Rendering for an overview of all rendering possibilities.

Here you can find a complete list of the categories and the regarding icons:Classes of Traffic Incidents and Truck Attributes

<Class name="Always_Blocked_Segments">
 <Filter>
  <!--leave range empty if it does not matter-->
  <Condition displayClass="BlockTrucks" timeRestriction="UNRESTRICTED"/>
  <Condition displayClass="BlockTrucksExceptDelivery" timeRestriction="UNRESTRICTED"/>
  <Condition displayClass="MaxHeight" timeRestriction="UNRESTRICTED"/>
  <Condition displayClass="MaxWeight" timeRestriction="UNRESTRICTED"/>
  <Condition displayClass="MaxWidth" timeRestriction="UNRESTRICTED"/>
  <Condition displayClass="MaxLength" timeRestriction="UNRESTRICTED"/>
  <Condition displayClass="MaxAxleLoad" timeRestriction="UNRESTRICTED"/>
  <Condition displayClass="HazardousToWaters" timeRestriction="UNRESTRICTED"/>
  <Condition displayClass="HazardousGoods" timeRestriction="UNRESTRICTED"/>
  <Condition displayClass="Combustibles" timeRestriction="UNRESTRICTED"/>
  <Condition displayClass="TunnelRestriction" timeRestriction="UNRESTRICTED"/>
  <Condition displayClass="HasTrailer" timeRestriction="UNRESTRICTED"/>
  <Condition displayClass="FreeForDelivery" timeRestriction="UNRESTRICTED"/>
 </Filter>
 <Style>
  <Geometry displayRange="9-14">
   <Stroke color="#FF0000" transparency="40" width="100%"/>
   <RenderLevel renderOffset="+10"/>
  </Geometry>
  <Geometry displayRange="15-23">
   <Stroke color="#FF0000" transparency="20" width="90%"/>
   <RenderLevel renderOffset="+10"/>
  </Geometry>
 </Style>
</Class>

The extract above shows the rendering settings for permanently blocked display classes. These are visualized as a red line (color="#F0000") on top of the road (renderOffset="+10") with changes in transparency and width depending on the DisplayRange. Please go to About Feature Layer Rendering for further information.

<Class name="Partly_Blocked_Segments">
 <Filter>
  <!--leave range empty if it does not matter-->
  <Condition displayClass="BlockTrucks" timeRestriction="RESTRICTED"/>
  <Condition displayClass="BlockTrucksExceptDelivery" timeRestriction="RESTRICTED"/>
  <Condition displayClass="MaxHeight" timeRestriction="RESTRICTED"/>
  <Condition displayClass="MaxWeight" timeRestriction="RESTRICTED"/>
  <Condition displayClass="MaxWidth" timeRestriction="RESTRICTED"/>
  <Condition displayClass="MaxLength" timeRestriction="RESTRICTED"/>
  <Condition displayClass="MaxAxleLoad" timeRestriction="RESTRICTED"/>
  <Condition displayClass="HazardousToWaters" timeRestriction="RESTRICTED"/>
  <Condition displayClass="HazardousGoods" timeRestriction="RESTRICTED"/>
  <Condition displayClass="Combustibles" timeRestriction="RESTRICTED"/>
  <Condition displayClass="TunnelRestriction" timeRestriction="RESTRICTED"/>
  <Condition displayClass="HasTrailer" timeRestriction="RESTRICTED"/>
  <Condition displayClass="FreeForDelivery" timeRestriction="RESTRICTED"/>
 </Filter>
 <Style>
  <Geometry displayRange="9-14">
   <Stroke color="#FF661A" transparency="40" width="100%"/>
   <RenderLevel renderOffset="+10"/>
  </Geometry>
  <Geometry displayRange="15-23">
   <Stroke color="#FF661A" transparency="20" width="90%"/>
   <RenderLevel renderOffset="+10"/>
  </Geometry>
 </Style>
</Class>

The strokes of the time-dependent blocks on the other hand are displayed in orange (color="#F661A")

The hazardous goods class is selected here as an example of connecting icons to a class.

<Class name="HazardousGoods-Class">
 <Filter>
 <!-- the default icon is defined if range * is given -->
  <Condition displayClass="HazardousGoods"/>
 </Filter>
 <Style>
  <Geometry displayRange="0-15">
   <Stroke visible="false/>
  </Geometry>
  <Icon displayRange="14-16" url="="./22x22/truck/truckblock_hazardous.bmp"/>
  <Icon displayRange="17-19" url="="./24x24/truck/truckblock_hazardous.bmp"/>
  <Icon displayRange="20-23" url="="./32x32/truck/truckblock_hazardous.bmp"/>
 </Style>
</Class>

The representation of icons can be configured with the Style tag of a class. A DisplayRange is specified for each icon, i.e. a range of the zoom level at which the icon should be displayed. By default, three icons are specified in different sizes depending on the DisplayRange. Bear in mind that each road segment with blocking has its own icon displayed. Please go to About Feature Layer Rendering for further information.

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 xMapServer to be tested.

Here you can see four images which illustrate the representation of the color and of the different icon sizes at different zoom levels:


"scale": 500	"scale": 250	"scale": 75	"scale": 25

For more information about scale look at PTV xMap Zoom Levels.

Drawing, Grouping and Hiding PTV_TruckAttributes Icons

As described above, every truck attribute type is assigned to an icon that xMap will draw within the specified display range. For an optimum use of drawing space and a self-explanatory meaning the icons are drawn following several rules:

Draw the icon on the center of the segment.
If there is more than one attribute on an segment, group them together into a box.
If there is not enough space to draw a group box, replace multiple grouped icons with a symbolic group icon.
The symbolic group icon is specified via the featureLayer.groupIcon property key located in the xmap.properties file.
If there is not enough space to draw an icon, hide it.


Several attributes grouped together	Symbolic group icon representing several attributes

Visualization of PTV_TruckAttributes on the map with changed Style of a given style class

This section describes the visualization of PTV_TruckAttributes using a modified Style. The Style is changed in the request by using a changed Profile XML snippet. For more general information on the possibilities for defining Styles, please look at About Feature Layer Rendering.

Below you can find a modified version of the XML snippet which causes the following change:

Change of color for always blocked segments from red to blue

<Profile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <FeatureLayer majorVersion="1" minorVersion="0">
  <GlobalSettings enableTimeDependency="true" enableVehicleDependency="false"/>
   <Themes>
    <Theme id="PTV_TruckAttributes" enabled="false"/>
   </Themes>
 <FeatureLayer/>
  <Rendering majorVersion="1" minorVersion="0">
   <Country id="*">
    <Theme id="PTV_TruckAttributes">
     <Class name="Always_Blocked_Segments">
     <Filter>...</Filter>
     <Style>
     <!-- Only change the color, let the other stroke attributes unchanged -->
      <Geometry displayRange="9-14">
       <Stroke color="#00639E"/>
       <RenderLevel renderOffset="+10"/>
      </Geometry>
      <Geometry displayRange="15-23">
       <Stroke color="#00639E"/>
       <RenderLevel renderOffset="+10"/>
      </Geometry>
     </Style>
    </Class>
   </Theme>
  </Country>
 </Rendering>
<Profile>

As in the example 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.

Here you can see the resulting image:

How to Use Feature Layer TruckAttributes

Related Topics

Terminology

Benefits

Prerequisites

Concept

Installation Guide

Programming Guide

Using a vehicle with a height less than 460 cm

Using a vehicle with a height more than 460 cm

Visualization of PTV_TruckAttributes on the map

Default rendering settings for PTV_TruckAttributes

Drawing, Grouping and Hiding PTV_TruckAttributes Icons

Visualization of PTV_TruckAttributes on the map with changed Style of a given style class