Working with OLR

OLR offers a number of different location reference types. These types are embedded into an OpenLRLocationReference.

The Location Library offers a unifying interface/trait for these locations: ReferencingLocation.

The available types and their mappings in the Location Library are the following:

OLR Type Location Library Type
GeoCoordinateLocationReference GeoCoordinateLocation
RectangleLocationReference RectangleLocation
GridLocationReference GridLocation
CircleLocationReference CircleLocation
PolygonLocationReference PolygonLocation
LinearLocationReference LinearLocation
ClosedLinearLocationReference ClosedLinearLocation
PointAlongLineLocationReference AccessPoint
POIWithAccessPointLocationReference PointOfInterest

Note: TISA OLR vs TomTom OpenLR

The difference between TISA OLR and TomTom OpenLR relates to the history of the specification: TomTom submitted the OpenLR specification to TISA. It was adopted in a slightly modified form by TISA as part 22 of the TISA SP14006 (TPEG2) standard series. The TISA standard was later in turn adopted without modifications as ISO 21219-22:2017.

In the TISA standard the abbreviation OLR (OpenLR Location Referencing) is used to describe this location referencing method.

As part of the adoption by TISA the standard was modified to be in line with the conventions and rules used in the TPEG2 series of standards. The concepts and the information in the references are the same, but the TISA version uses some different field names and the binary and XML representations are slightly different from those found in the TomTom OpenLR version. This means there are now two versions of the standard that are not interoperable at the binary or XML level.

The implementation in the Location Library follows the TISA OLR (and thus also ISO 21219-22:2017) specification for marshalling and unmarshalling of OLR References. Whenever we use the terms OLR or OpenLR we refer to the TISA OLR version of the standard.

The snippets throughout this section assume that you have the following imports in scope:

Scala
Java
import com.here.platform.location.core.geospatial._
import com.here.platform.location.referencing._
import com.here.platform.location.tpeg2.olr._
import com.here.platform.location.core.geospatial.GeoCoordinate;
import com.here.platform.location.core.geospatial.GeoProjections;
import com.here.platform.location.referencing.*;
import com.here.platform.location.referencing.javadsl.LocationReferenceCreators;
import com.here.platform.location.referencing.javadsl.LocationReferenceResolvers;
import com.here.platform.location.tpeg2.olr.*;

The simplest way to create and resolve OLR references is to use, respectively, the LocationReferenceCreator and LocationReferenceResolver, which is independent of a location type. The following snippet shows how to use these abstractions:

Note: v2 snippets

New dcl2 based snippets are available in the v2 tab. See
Open a version of Optimized Map for Location Libraries section for an introduction on how to create an optimized map instance.

Scala
Java
Scala(v2)
Java(v2)
val location = GeoCoordinateLocation(52.521864, 13.413306)

val reference: OpenLRLocationReference =
  LocationReferenceCreators.olr(optimizedMap, cacheManager).create(location)

println(LocationReferenceResolvers.olr(optimizedMap, cacheManager).resolve(reference))
final ReferencingLocation location = new GeoCoordinateLocation(52.521864, 13.413306);

final OpenLRLocationReference reference =
    LocationReferenceCreators.olr(optimizedMap, cacheManager).create(location);

System.out.println(
    LocationReferenceResolvers.olr(optimizedMap, cacheManager).resolve(reference));
val location = GeoCoordinateLocation(52.521864, 13.413306)

val reference: OpenLRLocationReference =
  LocationReferenceCreators(optimizedMap).olr.create(location)

println(LocationReferenceResolvers(optimizedMap).olr.resolve(reference))
final ReferencingLocation location = new GeoCoordinateLocation(52.521864, 13.413306);

final OpenLRLocationReference reference =
    new LocationReferenceCreators(optimizedMap).olr().create(location);

System.out.println(new LocationReferenceResolvers(optimizedMap).olr().resolve(reference));

If you are working only with a single type of reference, it might be more convenient to use creators and resolvers for that particular type. Some of the reference types are not necessarily associated to a map, and therefore the factory methods for the corresponding creators and resolvers don't require a catalog.

OLR Reference Types

The reference types provided by OLR fall into two categories. There are those references that refer to locations that are described by geometric shapes given in terms of geocoordinates. And, there are those references that refer to locations in or in relation to the road network.

The following reference types are backed by geometric shapes:

  • Geocoordinate
  • Circle
  • Rectangle
  • Grid
  • Polygon

The following reference types are bound to the road network:

  • Linear location
  • Closed linear location
  • Point along a line
  • Point of Interest with access point

Geocoordinate Location Reference

A geocoordinate location reference is a simple reference type that refers to a single point in the map, described using WGS84 geocoordinates. This type is not bound to the road network, and can be used to indicate exact locations.

Visualization of a Geocoordinate Location Reference
Figure 1. Visualization of a Geocoordinate Location Reference

Create and resolve geocoordinates:

Scala
Java
val geoCoordinate = GeoCoordinateLocation(52.521864, 13.413306)

val reference: GeoCoordinateLocationReference =
  LocationReferenceCreators.olrGeoCoordinate.create(geoCoordinate)
println(LocationReferenceResolvers.olrGeoCoordinate.resolve(reference))
final GeoCoordinateLocation geoCoordinate = new GeoCoordinateLocation(52.521864, 13.413306);

final GeoCoordinateLocationReference reference =
    LocationReferenceCreators.olrGeoCoordinate().create(geoCoordinate);
System.out.println(LocationReferenceResolvers.olrGeoCoordinate().resolve(reference));

Circle Location Reference

A circle location reference describes a circle in terms of geocoordinates that define the center of the circle, and a radius. Real-world examples include a Wi-Fi hotspot with its signal range, or the center and radius used with a proximity search. This type is also not bound to the road network.

Visualization of a Circle Location Reference
Figure 2. Visualization of a Circle Location Reference

Create and resolve circle references:

Scala
Java
val circle = CircleLocation(52.521864, 13.413306, 1000.0)

val reference: CircleLocationReference = LocationReferenceCreators.olrCircle.create(circle)
println(LocationReferenceResolvers.olrCircle.resolve(reference))
final CircleLocation circle = new CircleLocation(52.521864, 13.413306, 1000.0);

final CircleLocationReference reference = LocationReferenceCreators.olrCircle().create(circle);
System.out.println(LocationReferenceResolvers.olrCircle().resolve(reference));

Rectangle Location Reference

A rectangle location reference is defined in terms of the geocoordinates of the southwesternmost and northeasternmost corners of a rectangle. It can be used to create references of rectangular areas, like a box containing a city. This type is not bound to the road network.

Visualization of a Rectangle Location Reference
Figure 3. Visualization of a Rectangle Location Reference

Create and resolve rectangle references:

Scala
Java
val boundingBox = RectangleLocation(52.576042, 52.422035, 13.502779, 13.194462)

val reference: RectangleLocationReference =
  LocationReferenceCreators.olrRectangle.create(boundingBox)
println(LocationReferenceResolvers.olrRectangle.resolve(reference))
final RectangleLocation location =
    new RectangleLocation(52.576042, 52.422035, 13.502779, 13.194462);

final RectangleLocationReference reference =
    LocationReferenceCreators.olrRectangle().create(location);
System.out.println(LocationReferenceResolvers.olrRectangle().resolve(reference));

Grid Location Reference

A grid location reference is similar to a rectangle location reference. It defines a base rectangle that is multiplied to the north by the the number of rows and to the east by the number of columns. The cells in the grid can, for instance, be used to encode local weather information, such as precipitation rates.

Create and resolve grid references:

Scala
Java
val grid = GridLocation(52.481352, 52.470520, 13.320212, 13.289946, 3, 4)

val reference: GridLocationReference = LocationReferenceCreators.olrGrid.create(grid)
val resolvedGrid = LocationReferenceResolvers.olrGrid.resolve(reference)

for {
  row <- resolvedGrid.rectangles(SinusoidalProjection)
  cell <- row
} println(cell)
final GridLocation grid = new GridLocation(52.481352, 52.470520, 13.320212, 13.289946, 3, 4);

final GridLocationReference reference = LocationReferenceCreators.olrGrid().create(grid);
final GridLocation resolvedGrid = LocationReferenceResolvers.olrGrid().resolve(reference);

resolvedGrid
    .getRectangles(GeoProjections.sinusoidal())
    .forEach(row -> row.forEach(System.out::println));
Visualization of a Grid Location Reference
Figure 4. Visualization of a Grid Location Reference

Polygon Location Reference

A polygon location reference defines a non-intersecting shape represented by a sequence of geocoordinate pairs. Examples for the use of polygon location references are low emission zones, an area with heavy traffic, or the geometry of a building.

Visualization of a Polygon Location Reference
Figure 5. Visualization of a Polygon Location Reference

Create and resolve polygon references:

Scala
Java
val polygon = PolygonLocation(
  Seq(
    GeoCoordinate(52.506730, 13.333547),
    GeoCoordinate(52.513119, 13.331632),
    GeoCoordinate(52.518681, 13.347873),
    GeoCoordinate(52.519508, 13.374674),
    GeoCoordinate(52.512330, 13.376650),
    GeoCoordinate(52.510150, 13.345835)
  ))

val reference: PolygonLocationReference = LocationReferenceCreators.olrPolygon.create(polygon)
println(LocationReferenceResolvers.olrPolygon.resolve(reference))
final PolygonLocation polygon =
    new PolygonLocation(
        java.util.Arrays.asList(
            new GeoCoordinate(52.506730, 13.333547),
            new GeoCoordinate(52.513119, 13.331632),
            new GeoCoordinate(52.518681, 13.347873),
            new GeoCoordinate(52.519508, 13.374674),
            new GeoCoordinate(52.512330, 13.376650),
            new GeoCoordinate(52.510150, 13.345835)));

final PolygonLocationReference reference =
    LocationReferenceCreators.olrPolygon().create(polygon);
System.out.println(LocationReferenceResolvers.olrPolygon().resolve(reference));

Linear Location Reference

Linear location references can refer to arbitrary paths in the road network. Another referencing scheme that supports important paths in the road network is TMC. However, OLR is more flexible, because it does not depend on any sort of predefined tables. This allows OLR linear location references to be used to refer to virtually any part of the road network.

Visualization of a Linear Location Reference
Figure 6. Visualization of a Linear Location Reference

Create and resolve linear location references:

Scala
Java
Scala(v2)
Java(v2)
val location: LinearLocation = findLinearLocation(optimizedMap, cacheManager)

val reference: LinearLocationReference =
  LocationReferenceCreators
    .olrLinear(optimizedMap, cacheManager)
    .create(location)

val resolvedLocation: LinearLocation =
  LocationReferenceResolvers
    .olrLinear(optimizedMap, cacheManager)
    .resolve(reference)

println(resolvedLocation)
final LinearLocation location = paths.findLinearLocation(optimizedMap, cacheManager);

final LinearLocationReference reference =
    LocationReferenceCreators.olrLinear(optimizedMap, cacheManager).create(location);

final LinearLocation resolvedLocation =
    LocationReferenceResolvers.olrLinear(optimizedMap, cacheManager).resolve(reference);

System.out.println(resolvedLocation);
val location: LinearLocation = findLinearLocation(optimizedMap)

val reference: LinearLocationReference =
  LocationReferenceCreators(optimizedMap).olrLinear
    .create(location)

val resolvedLocation: LinearLocation =
  LocationReferenceResolvers(optimizedMap).olrLinear
    .resolve(reference)

println(resolvedLocation)
final LinearLocation location = paths.findLinearLocation(optimizedMap);

final LinearLocationReference reference =
    new LocationReferenceCreators(optimizedMap).olrLinear().create(location);

final LinearLocation resolvedLocation =
    new LocationReferenceResolvers(optimizedMap).olrLinear().resolve(reference);

System.out.println(resolvedLocation);

Closed-linear Location Reference

Visualization of a Closed-linear Location Reference
Figure 7. Visualization of a Closed-linear Location Reference

Create and resolve closed linear location references:

Scala
Java
Scala(v2)
Java(v2)
val location: ClosedLinearLocation = findClosedLinearLocation(optimizedMap, cacheManager)

val reference: ClosedLinearLocationReference =
  LocationReferenceCreators
    .olrClosedLinear(optimizedMap, cacheManager)
    .create(location)

val resolvedLocation: ClosedLinearLocation =
  LocationReferenceResolvers
    .olrClosedLinear(optimizedMap, cacheManager)
    .resolve(reference)

println(resolvedLocation)
final ClosedLinearLocation location =
    paths.findClosedLinearLocation(optimizedMap, cacheManager);

final ClosedLinearLocationReference reference =
    LocationReferenceCreators.olrClosedLinear(optimizedMap, cacheManager).create(location);

final ClosedLinearLocation resolvedLocation =
    LocationReferenceResolvers.olrClosedLinear(optimizedMap, cacheManager).resolve(reference);

System.out.println(resolvedLocation);
val location: ClosedLinearLocation = findClosedLinearLocation(optimizedMap)

val reference: ClosedLinearLocationReference =
  LocationReferenceCreators(optimizedMap).olrClosedLinear
    .create(location)

val resolvedLocation: ClosedLinearLocation =
  LocationReferenceResolvers(optimizedMap).olrClosedLinear
    .resolve(reference)

println(resolvedLocation)
final ClosedLinearLocation location = paths.findClosedLinearLocation(optimizedMap);

final ClosedLinearLocationReference reference =
    new LocationReferenceCreators(optimizedMap).olrClosedLinear().create(location);

final ClosedLinearLocation resolvedLocation =
    new LocationReferenceResolvers(optimizedMap).olrClosedLinear().resolve(reference);

System.out.println(resolvedLocation);

Point along a line Location Reference

Visualization of a Point Along a Line Location Reference
Figure 8. Visualization of a Point Along a Line Location Reference

Create and resolve point along a line references:

Scala
Java
Scala(v2)
Java(v2)
val location: AccessPoint = findAccessPoint(optimizedMap, cacheManager)

val reference: PointAlongLineLocationReference =
  LocationReferenceCreators
    .olrPointAlongLine(optimizedMap, cacheManager)
    .create(location)

val resolvedLocation: AccessPoint =
  LocationReferenceResolvers
    .olrPointAlongLine(optimizedMap, cacheManager)
    .resolve(reference)

println(resolvedLocation)
final AccessPoint location = paths.findAccessPoint(optimizedMap, cacheManager);

final PointAlongLineLocationReference reference =
    LocationReferenceCreators.olrPointAlongLine(optimizedMap, cacheManager).create(location);

final AccessPoint resolvedLocation =
    LocationReferenceResolvers.olrPointAlongLine(optimizedMap, cacheManager).resolve(reference);

System.out.println(resolvedLocation);
val location: AccessPoint = findAccessPoint(optimizedMap)

val reference: PointAlongLineLocationReference =
  LocationReferenceCreators(optimizedMap).olrPointAlongLine
    .create(location)

val resolvedLocation: AccessPoint =
  LocationReferenceResolvers(optimizedMap).olrPointAlongLine
    .resolve(reference)

println(resolvedLocation)
final AccessPoint location = paths.findAccessPoint(optimizedMap);

final PointAlongLineLocationReference reference =
    new LocationReferenceCreators(optimizedMap).olrPointAlongLine().create(location);

final AccessPoint resolvedLocation =
    new LocationReferenceResolvers(optimizedMap).olrPointAlongLine().resolve(reference);

System.out.println(resolvedLocation);

POI with access point Location Reference

Visualization of a POI with Access Point Location Reference
Figure 9. Visualization of a POI with Access Point Location Reference

Create and resolve point of interest (POI) with access point references:

Scala
Java
Scala(v2)
Java(v2)
val location: PointOfInterest = findPointOfInterest(optimizedMap, cacheManager)

val reference: POIWithAccessPointLocationReference =
  LocationReferenceCreators
    .olrPoiWithAccessPoint(optimizedMap, cacheManager)
    .create(location)

val resolvedLocation: PointOfInterest =
  LocationReferenceResolvers
    .olrPoiWithAccessPoint(optimizedMap, cacheManager)
    .resolve(reference)

println(resolvedLocation)
final PointOfInterest location = paths.findPointOfInterest(optimizedMap, cacheManager);

final POIWithAccessPointLocationReference reference =
    LocationReferenceCreators.olrPoiWithAccessPoint(optimizedMap, cacheManager)
        .create(location);

final PointOfInterest resolvedLocation =
    LocationReferenceResolvers.olrPoiWithAccessPoint(optimizedMap, cacheManager)
        .resolve(reference);

System.out.println(resolvedLocation);
val location: PointOfInterest = findPointOfInterest(optimizedMap)

val reference: POIWithAccessPointLocationReference =
  LocationReferenceCreators(optimizedMap).olrPoiWithAccessPoint
    .create(location)

val resolvedLocation: PointOfInterest =
  LocationReferenceResolvers(optimizedMap).olrPoiWithAccessPoint
    .resolve(reference)

println(resolvedLocation)
final PointOfInterest location = paths.findPointOfInterest(optimizedMap);

final POIWithAccessPointLocationReference reference =
    new LocationReferenceCreators(optimizedMap).olrPoiWithAccessPoint().create(location);

final PointOfInterest resolvedLocation =
    new LocationReferenceResolvers(optimizedMap).olrPoiWithAccessPoint().resolve(reference);

System.out.println(resolvedLocation);

results matching ""

    No results matching ""