Additional Use Cases

How to Extend a Dima's Distance Table

When extending an existing distance table, the values are taken from the persistent distance table and transferred to a temporary distance table.

The new locations and the newly calculated distances and driving periods are added in these files.

If the extension is cancelled while being calculated or if a fatal error occurs, an old persistent distance table can be used to continue work.

The old persistent distance table is only deleted and replaced by the temporary persistent distance table after successful extension.

When extending, PTV xDima only calculates the distances and driving periods between the locations concerned and not between all locations in the Dima.

Here is an example:

The distance table in a Dima is newly generated with the locations A,B and C.

In the second step the distance table is extended with the locations B, D and E, so that the relevant values are newly calculated and the irrelevant values are identified.

How to Use the LRU Mechanism

LRU stands for "least recently used" and the LRU mechanism ensures that the distance table in a Dima can only grow to a specified size, in spite of constant extensions.

If the maximum number of locations is exceeded by extending the distance table, the location which has not been used for the longest amount of time for extensions must be removed from the distance table for each supernumerary new location.

An example is also provided here:

The distance table in a Dima was generated with the locations A, B and C and may contain a maximum of 5 locations.

In an extension the distances and driving periods between the locations A, B and D are added.

The location C was not used in the extension.

It must be noted here that the last row and column in the distance table does not exist at this point in time, but may exist potentially.

In the next extension of the distance table the locations B, D, E and F are to be taken into account.

As 6 locations would then be included in the distance table, the location, which has not been taken into account for the longest amount of time, must be deleted from the distance table.

In our example only the locations A and C come into consideration, as all others are taken into account in the current extension.

Location A was taken into account in the last extension, unlike location C, so that Location C is the location to be deleted.

The values for location E take up the free space in the distance table and location F takes over the place of location C.

How to Use the Reference Point-Mimic

It is often sufficient enough to roughly estimate distances and driving periods between locations, especially when considering a large number of locations, for example, which can be divided into smaller sections with the help of estimations.

In such a case, the large efforts required in calculating a complete distance table from locations is not justified, because most of the calculated distances and driving periods are no longer needed in the following planning steps. An estimation of the geometric distance would be possible but geographic conditions such as rivers or railway lines would lead to falsified results.

The reference point-mimic provides a clear improvement, but depends very much on the quality of the basic reference points. Selecting these reference points is a very complex task which PTV xDima does not perform.

The basic idea behind mimicking reference points is the assumption that the ratio between road distance and geometric distance between two neighbouring start and two neighbouring destination points is similar, because one often moves in the same section of the network when searching for the route.

If the distance between two locations L₁ and L₂ is to be approximated, locations in the reference Dima are searched through until the nearest neighbours R₁ and R₂ to the required locations are found. These are then used as reference point for which the same ratio for the distance between the required location is taken as between the road distance and geometric distance of the reference points.

Using the assumption made above, the following formula results from the distance d and driving period p between the locations L₁ and L₂ using the reference points R₁ and R₂.

d_ref (L₁,L₂) = d_road(R₁,R₂) / d_geo(R₁,R₂) * d_geo (L₁,L₂) and

p_ref (L₁,L₂) = d_geo(R₁,R₂) / d_geo(L₁,L₂) * p_road (R₁,R₂)

How to Use Truck Attributes for the Road Distance Calculation

The PTV xDima Server road distance calculation supports the manipulation of road attributes and restrictions by RoadEditor layers. In order to consider the RoadEditor attributes you have to set up the following configuration:

• Switch the RoadEditor initialization on: Set

  roadEditorParameter.enableRoadEditor=true

  in xdima.properties.
• RoadEditor Base Path: The location of the RoadEditor attributes data defaults to <maps.path>/re. If your path differs from the default location, you can specify it in xdima.properties:

  roadEditorParameter.binPath=./data/map/re

• RoadEditor Layer Name: Set the name of the RoadEditor layer in your profile (e. g. xdima-roadeditor.properties):

  roadEditorParameter.layerName = truckattributes

  Recommendation: If you want to apply truckattributes for every distance matrix calculation you can set the layerName in your xdima-default.properties. If not do not set it in the default profile but use a special profile and add a profile property with its name to the CallerContext when calling createDima.

• Configure the vehicle restrictions (e.g. dimaTruck.ini):

  [RoadEditorProperties]
  Segment.IsUrbanArea.Enabled = true
  Segment.BlocksCar.Enabled = true
  Segment.BlocksTruck.Enabled = true
  Segment.HasTollCar.Enabled = true
  Segment.HasTollTruck.Enabled = true
  Segment.MaxHeight.Enabled = true
  Segment.MaxHeight.MaxLevelDir1 = 300
  Segment.MaxHeight.MaxLevelDir2 = 300
  Segment.MaxWeight.Enabled = true
  Segment.MaxWeight.MaxLevelDir1 = 20000
  Segment.MaxWeight.MaxLevelDir2 = 20000
  Segment.MaxWidth.Enabled = true
  Segment.MaxWidth.MaxLevelDir1 = 200
  Segment.MaxWidth.MaxLevelDir2 = 200
  Segment.MaxLength.Enabled = true
  Segment.MaxLength.MaxLevelDir1 = 800
  Segment.MaxLength.MaxLevelDir2 = 800				

• Create the distance matrix.

How to Calculate and Administrate Distance Tables - Technical Information

The PTV xDima module offers the functionality to calculate and administrate distance tables.

Import and export Dima file formats: Further information about the binary file formats and the text file formats can be obtained.

Binary file formats for import and export Dima files

The file format of the binary location file is defined as follows:

• The X co-ordinate X_i and Y co-ordinate Y_i of each location L_i are
  stored in a 4 byte signed integer value.
• The tuples XY_i for i=1,..,n (number of locations) are stored linearly.

The file format of the binary distance table file is defined as follows:

• The distance d_ij and driving period p_ij between the locations L_i and
  L_j are each stored in a 4 byte signed integer value. The tuple from
  distance and period is referred to as dp_ij.
• The tuples dp_ij for i=1,..,n (number of locations) and j = 1,...,n are
  stored linearly.
• For example: A distance table that consists of the distances and driving
  periods between 3 locations is stored as follows:
  dp₁₁,dp₁₂,dp₁₃,dp₂₁,dp₂₂,dp₂₃,dp₃₁,dp₃₂,dp₃₃

The following possible error values are stored in the distance part of the tuple:

• -1: the tuple dp_ij of the associated relation is not calculated yet.
• -2: the route between the locations of the associated relation dp_ij could not been found.

Text file formats for import and export Dima files

The file format of the text location file is defined as follows:

• The X co-ordinate X_i and Y co-ordinate Y_i of each location L_i are
  stored in a separate row separated by a semicolon (;).

The file format of the text distance table file is defined as follows:

• The distance d_ij and driving period p_ij between the start-location L_i
  and each destination-location L_j for j = 1,...,n are stored in separate
  rows separated by a semicolon (;). The tuple from distance and driving
  period is referred to as dp_ij.
• For example: A distance table that consists of the distances and driving
  periods between 3 locations is stored as follows:
  dp₁₁;dp₁₂;dp₁₃
  dp₂₁;dp₂₂;dp₂₃
  dp₃₁;dp₃₂;dp₃₃

The following possible error values are stored in the distance part of the tuple:

• -1: the tuple dp_ij of the associated relation is not calculated yet.
• -2: the route between the locations of the associated relation dp_ij could not been found.

How to Watch the Progress of Jobs

Please find more general information on jobs (Asynchronous Protocol).

The service method calculateDistanceTable has a corresponding start-method startCalculateDistanceTable to start the calculation as a job. The synchronous method returns a Void object, the corresponding fetch-method is fetchVoid.

During the calculation the current progress can be watched using watchJob. This method returns an instance of DistanceMatrixProgress which delivers information on the number of rows to calculate and the number of rows already calculated.

Since there are no intermediate results for the distance matrix calculation, stopping a currently running job using stopJob will result in a user abort exception that will be returned by fetchVoid.

How to Configure the Directory of the Distance Matrices

By default the distance matrices will be stored in the subfolder data/dima until deleted by request. If need be, this folder can be changed in the file DimaCtrl.ini which can be found in the conf folder.

[Dima]
Root=data/dima

Under some circumstances such as a cloud installation it may be necessary to enter a path which is not located on the local machine but somewhere else on the network. This should be done with care as when multiple PTV xServer access the same distance matrix folder access violations may occur, for example when one PTV xServer calculates a distance matrix and another one on a different machine wants to access it. Therefore, subfolders are locked during access using the filesystem. Unfortunately, not all file systems, especially those for network shares do not support this locking feature. Windows or Linux (NFS) shares will be supported when all accessing PTV xServer are installed on the same operating system. Samba shares will not be supported.

If in doubt, check this by calculating a distance matrix on one machine and by deleting it from another machine at the same time. If deleting fails with an access violation which says that the distance matrix is locked, everything should be fine.

How to Use Tenant Namespaces for Distance Matrix IDs

IDs of distance matrices have to be unique in the scope of the PTV xDima Server: different users cannot use the same dima id in their requests and re-use their previously calculated distance matrices. To avoid such id conflicts, the id scope can be made user-specific by setting a tenant name for each user. The tenant name can be provided in two ways:

1. In the header field 'x-tenant' of the xServer request.
2. In the CallerContext property 'TenantId'.

The header field is meant to be set in a middleware that is responsible for user management, e.g. for PTV xDima Server as a private cloud service. If tenant names are used solely to provide user namespaces, you can use the CallerContext property instead. Both mechanisms can even be combined.

The tenant name is case insensitive and will be prepended to the numerical dima id requested by the user. Alpha-numerical dima ids will only be used internally for folder names of stored distance matrices. In exception messages or progress information, the numerical dima id is used.

Copyright © 2024 PTV Logistics GmbH All rights reserved. | Imprint