Working with TMC References

The referencing module contains interfaces and classes that enable the conversion of location references to Optimized Map for Location Library vertices (reference resolution) and the creation of location references from Optimized Map for Location Library vertices (reference creation).

This module supports the TMC and Extended TMC location referencing methods described in detail below.

To use location referencing, you need to add the module to the project dependencies:

libraryDependencies ++= Seq(
  "com.here.platform.location" %% "location-referencing" % "0.21.788"
)

<dependencies>
    <dependency>
        <groupId>com.here.platform.location</groupId>
        <artifactId>location-referencing_${scala.compat.version}</artifactId>
        <version>0.21.788</version>
    </dependency>
</dependencies>

dependencies {
    compile group: 'com.here.platform.location', name: 'location-referencing_2.12', version:'0.21.788'
}

Resolving a Location Reference

The interface LocationReferenceResolver provides a method to resolve location references. Instances of the interface can be created through the factory object LocationReferenceResolvers.

The counterpart interface LocationReferenceCreator provides methods necessary to create location references. Instances of the type can be created through the factory object LocationReferenceCreators.

These factory objects provide factories for all the different location reference types supported by the library.

The snippet below demonstrates how to create a TMC resolver and how to resolve an existing TMC location reference with it.

import com.here.platform.location.referencing._
import com.here.platform.location.tpeg2.tmc.TMCLocationReference

val tmcReference: TMCLocationReference = getTmcLocationReference

val tmcResolver: LocationReferenceResolver[TMCLocationReference, BidirectionalLinearLocation] =
  LocationReferenceResolvers(optimizedMap).tmc

val location: BidirectionalLinearLocation = tmcResolver.resolve(tmcReference)

println(s"""Vertices in the:
           |  - location: ${location.location.path}
           |  - opposite location: ${location.oppositeLocation.map(_.path)}
           |""".stripMargin)

import com.here.platform.location.referencing.BidirectionalLinearLocation;
import com.here.platform.location.referencing.LocationReferenceResolver;
import com.here.platform.location.referencing.javadsl.LocationReferenceResolvers;
import com.here.platform.location.tpeg2.tmc.TMCLocationReference;

final TMCLocationReference tmcReference = getTmcLocationReference();

final LocationReferenceResolver<TMCLocationReference, BidirectionalLinearLocation> tmcResolver =
    new LocationReferenceResolvers(optimizedMap).tmc();

final BidirectionalLinearLocation location = tmcResolver.resolve(tmcReference);

System.out.println("Resolved location: " + location);

TMC location references can, at the same time, refer to the positive and negative direction of the linear location. Therefore, TMC resolvers return a BidirectionalLinearLocation.

Creating a Location Reference

The interface LocationReferenceCreator provides a method to create location references. Instances of the interface can be created through the factory object LocationReferenceCreators.

The snippet below demonstrates how to create a TMC creator and how to create a TMC location reference with it. TMC location references use a pre-coded referencing scheme, therefore you can only create a reference for paths that are covered by TMC tables.

import com.here.platform.location.referencing._
import com.here.platform.location.tpeg2.XmlMarshallers
import com.here.platform.location.tpeg2.lrc.LocationReferencingContainer
import com.here.platform.location.tpeg2.tmc.TMCLocationReference

val location: LinearLocation = findLinearLocation(optimizedMap)

val tmcRefCreator: LocationReferenceCreator[LinearLocation, TMCLocationReference] =
  LocationReferenceCreators(optimizedMap).tmc

val tmcRef: TMCLocationReference = tmcRefCreator.create(location)

XmlMarshallers.locationReferencingContainer
  .marshall(LocationReferencingContainer(Seq(tmcRef)), Console.out)

import com.here.platform.location.referencing.LinearLocation;
import com.here.platform.location.referencing.LocationReferenceCreator;
import com.here.platform.location.referencing.javadsl.LocationReferenceCreators;
import com.here.platform.location.tpeg2.XmlMarshallers;
import com.here.platform.location.tpeg2.lrc.LocationReferencingContainer;
import com.here.platform.location.tpeg2.tmc.TMCLocationReference;

import java.util.Collections;

final LinearLocation location = findLinearLocation(optimizedMap);

final LocationReferenceCreator<LinearLocation, TMCLocationReference> tmcRefCreator =
    new LocationReferenceCreators(optimizedMap).tmc();

final TMCLocationReference tmcRef = tmcRefCreator.create(location);

XmlMarshallers.locationReferencingContainer()
    .marshall(new LocationReferencingContainer(Collections.singletonList(tmcRef)), System.out);

If a path is not fully covered by TMC or cannot be covered by a single TMC reference, because it doesn't follow a single TMC linear location, there is the possibility to use the piecewiseExtendedTmc, which can return multiple TMC references along with the linear location that is covered by each one.

How TMC Works

This section provides more detail about the TMC and Extended TMC location references that can be embedded in TPEG2 messages. The first part explains the concepts of TMC locations and location tables.

The second part explains how to use these to refer to paths in the road network.

TMC Locations

The Traffic Message Channel (TMC) location referencing method uses tables of pre-coded locations. While TMC defines many different types of location codes, point and linear location codes are of particular interest as both these location codes are used to refer to locations on the road network.

Linear location codes refer to major roads or longer subsections of these roads. Point location codes refer to short stretches of a road involving exits and entries, such as where it intersects with another road.

When two roads that are coded in TMC intersect, there will be two point location codes describing their intersection: one from each road's point of view. For example, at the Frankfurter Kreuz junction, the motorways A3 and A5 intersect. The current version of the TMC table for Germany (version 18) has two point location codes for this junction: 10871 for the Frankfurter Kreuz on the A3, and 11623 for the Frankfurter Kreuz on the A5.

For each road coded in TMC, one direction is designated as the positive direction, and the opposite direction is designated as the negative direction.

A location code can potentially have references to the previous and next coded location along the positive direction of the road. The next location code is called the positive offset and the previous code the negative offset. (This use of "offset" can be somewhat confusing. It is helpful to think of the point locations being part of linked lists, with offsets being pointers to the next nodes in their respective directions.)

Each TMC code actually has four logical road sections associated with it: The internal and external road sections for each of the positive and negative directions. The internal road sections of a point location are the sections of the road that are within the area of the intersection, that is between the first and last of the many entries and exits involved in that intersection. The external road sections are the part of the road leading toward the internal sections.

In the Frankfurter Kreuz example given above, TMC point location code 10871 represents the part of east-west motorway A3 where it has a cloverleaf intersection with north-south motorway A5, with the westbound direction coded as the positive direction. The intersection involves four ramps interacting with each direction of the A3 (an off-ramp and an on-ramp heading to/from each direction of the A5). The internal section for a given direction is the stretch of motorway between the first off-ramp and the last on-ramp. The external positive section of location code 10871 is the westbound part of the A3 between the internal section of the preceding point location in that direction (location code 10871's negative offset: location code 59628) and the internal part of intersection with motorway B, and the external negative section of location code 123 will be the eastbound part of A3 between the previous point location in that direction (location code 10872) and the intersection with motorway B.

There can be multiple TMC location tables defined for a given country. For example, a country might use different tables for different location types or different administrative areas. For a given country, each table is assigned a number. To uniquely identify a table, it's necessary to specify both the country and the table number.

For historical reasons, TMC has two mechanisms to identify a country. Each country is assigned a country code, which is a nonzero 4-bit number represented as a single hexadecimal digit (1 through F). This is sufficient for radio broadcasts in border areas to distinguish between neighbouring countries, but there are not enough unique values to assign each country a unique code, so the country code doesn't uniquely identify a country. Each country is also assigned an extended country code, which is a 8-bit number represented by two hexadecimal digits. Unfortunately, there are also duplicate uses of the extended country code, but combining the country code and extended country code does uniquely identify the country.

A TMC location reference refers to a particular table as well as the location code. To work properly, the sender and receiver of a TMC reference must share the same location tables. This allows TMC references to be very small. However, not all locations are pre-coded and thus, there are locations that cannot be referred to using TMC location referencing.

TMC Location References

A TMC location reference is always built around a TMC location code. To uniquely identify the code, it is necessary to provide a country code, extended country code, table number, and the code itself. (The extended country code is optional in the TPEG formats, but we expect it to always be present.) The location code that is explicitly given in the reference is called the primary location.

The reference also specifies an extent. Extents allow you to specify a location that spans more than one road section by defining an integer number of preceding location codes that are involved in the reference. The furthest such location code is known as the secondary location. By convention, travel moves from the secondary location to the primary location.

Your need to specify the direction (positive or negative) as a boolean value, where true means positive and false means negative. The value here is the direction to follow from the primary location to the secondary location. Since traffic flow is from the secondary location to the primary location, the direction indicator is for the direction opposite to the traffic flow!

For example, assume that the TMC table includes the entries shown below, that the primary location code in the reference is 8, and the extent is 4. Then if the direction is false, we follow the negative offsets and the secondary location code is 2. If the direction is true, we follow the positive offsets and the secondary location code is 14.

When the extent is 0, there is no secondary location, and only the internal section of the primary location is included in the reference. The external section of the primary location is not included.

When the extent is greater than 1, we have the internal and external sections of the primary and secondary locations to consider, as well as all the the location codes in between:

• The external part of the secondary location is excluded.
• The inclusion/exclusion of the internal part of the secondary location is described below.
• All of the external and internal parts of the codes between the primary and secondary location are included.
• The external part of the primary location is included.
• The inclusion/exclusion of the internal part of the secondary location is described below.

There are actually two parts of TPEG2 that define TMC location references: The older TMC Location Referencing (TMC), represented by the code in our tmc package, and the newer Extended TMC Location Referencing (ETL), represented by the code in our etl package. Both of these packages have a class named TMCLocationReference. The etl version of TMC referencing allows the reference to explicitly specify whether the internal sections of the secondary location are included, and whether the internal sections of the primary location are included. The tmc version does not allow these to be specified: the internal sections of the secondary location are always excluded, and those of the primary location are always included. The following table shows how the etl flags affect the referenced location.

Extent	Use Primary Internal	Use Secondary Internal	Secondary External	Secondary Internal	Primary External	Primary Internal
0	_	_
1+	F	F
1+	F	T
1+	T	F
1+	T	T

You can then use "precise TMC" information in the form of a hazard distance and problem length to restrict the extent of the location. Both values are specified in hectometers (1 hectometer = 100 meters).

The hazard distance, when specified, is the distance backwards from the primary location to the start of the referenced location. In principle, the hazard distance shouldn't be longer than the combined length of all the road sections included by the parameters described above. When decoding references, if the hazard distance exceeds the combined road length, we use the combined road length (the same as if the hazard distance isn't specified).

The problem length, when specified, is the distance from the start of the referenced location (potentially modified by the hazard distance) to the end of the referenced location. In principle, the problem length shouldn't be longer than the combined length of the remaining road segments after they are modified by the hazard distance. When decoding references, if the problem length exceeds this length, we use the full remaining length (the same as if the problem length isn't specified).