How to use core, path matching customizations

This section describes the interfaces provided by the core module to construct path matchers from its components.

libraryDependencies ++= Seq(
  "com.here.platform.location" %% "location-core" % "<version>"
)

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

dependencies {
    compile group: 'com.here.platform.location', name: 'location-core_2.13', version:'<version>'
}

Candidate generator

The candidate generator is the component of the map matcher that expands a location (observation) into the list of candidate locations on the map (candidate states). The map matcher algorithm will in the end select the most likely state for each observation.

To obtain candidate states for an observation, use the CandidateGenerator.

The Location Library provides a CandidateGenerator that uses a proximity search, the ProximitySearchCandidateGenerator.

To construct a ProximitySearchCandidateGenerator, you need to provide a proximity search as well as a function that, for each observation, determines the search radius to use. Most of the time, your code will provide a constant radius but you may want your code to provide different radii depending on the observations. For example, you could use a smaller or larger search radius depending on the quality or number of visible satellites of the GPS signal.

The example below demonstrates how to use the factory method CandidateGenerators.fromProximitySearch to create a ProximitySearchCandidateGenerator from a proximity search and a constant radius.

// Use 40 meters as the search radius for every observation.
val FixedSearchRadius = 40.0

val candidateGenerator =
  CandidateGenerators.fromProximitySearch(proximitySearch, FixedSearchRadius)

** Note **

You can implement a custom CandidateGenerator, for example to make your path matcher filter out candidates not accessible by car in combination with the roadAccess attribute available in the PropertyMaps.

Emission probability

For assigning emission probabilities (initial probabilities) to candidate states, the path matcher uses the EmissionProbabilityStrategy.

One method to calculate emission probabilities is using the distance between the candidate and observation: The further the vertex from the observation, the lower the emission probability.

The DistanceEmissionProbabilityStrategy implements this heuristic.

val emissionProbabilityStrategy =
  new DistanceEmissionProbabilityStrategy[Point, Vertex](
    distanceForUnknown = FixedSearchRadius,
    // Defines how the probability decreases with distance
    // By default, a Gaussian distribution
    DistanceEmissionProbabilityStrategy.DefaultProbabilityDistribution
  )

You can also use the factory method usingDistance of the EmissionProbabilityStrategies to create a DistanceEmissionProbabilityStrategy.

In order to have other information than the distance, for example the heading, affect the emission probabilities, you can use your own logic here.

Transition probability

TransitionProbabilityStrategy computes the transition probability from one state to another.

There are various ways of calculating transition probabilities using the routing graph. The Location Library provides a few implementations.

The directDistance is the simplest (and also usually fastest) method and is only suitable for dense traces. This strategy only takes into account whether the routing graph directly connects the two states and is used in the carPathMatcher and understrictedPathMatcher.

type Transition = Seq[Vertex]
val transitionProbabilityStrategy: TransitionProbabilityStrategy[Point, Vertex, Transition] =
  TransitionProbabilityStrategies.directDistance[Point, Vertex, Edge](
    graph,
    length,
    roadAccess,
    new ProjectionDistanceCalculator(SinusoidalProjection))

There are a number of other implementations available via factory methods in TransitionProbabilityStrategies. For example, distanceWithTransitions creates a DistanceTransitionProbabilityStrategy, which calculates routes between states to compute transition probabilities. This makes it well suited to handle sparse data (as little as one point every 60 seconds). In some cases, if the observations are too far apart, they could be considered unreachable when computing transition probabilities. This strategy is used by the carPathMatcherWithTransitions and by the unrestrictedPathMatcherWithTransitions with different filters applied. There is a hard limitation of ~30km that is applied to the search when computing transitions.

Path matcher

In general you will create path matchers following the guide in Create Path Matchers.

To obtain fine-grained control and construct and use a path matcher from the core parts, you can use TransitionProbabilityStrategy and EmissionProbabilityStrategy, as follows:

val pathMatcher = new HMMPathMatcher[Point, Vertex, Transition](
  candidateGenerator,
  emissionProbabilityStrategy,
  transitionProbabilityStrategy
)

val matchedPath: MatchedPath[Vertex, Transition] = pathMatcher.matchPath(trip)

// Each element in matchedPath corresponds to an input point in trip.
for ((observation, candidateState) <- trip.zip(matchedPath.results)) {
  println(s"$observation was matched to $candidateState")
}