How to work 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: Migration to topology attributes

OLR creators and resolvers now use Topology Attributes instead of the
deprecated Navigation Attributes layer.

If you're using a map version where the Topology Attributes layer is empty,
you won't receive any exceptions when creating or resolving references.
Instead, you will receive incomplete results.

Refer to the documentation section how to
use deprecated layers in OLR.

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:

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:

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.

Attribute retention in OLR

By default, OLR creators and resolvers retain all Topology Attributes in memory,
which can lead to increased memory usage. To optimize memory consumption,
configure the map to retain only the attributes required for OLR functionality:

RoadUsage
FunctionalClass
PhysicalAttribute
SpecialTrafficAreaCategory

import com.here.platform.data.client.base.scaladsl.BaseClient
import com.here.platform.location.compilation.heremapcontent.TopologyAttributeDescription
import com.here.platform.location.integration.optimizedmap.OptimizedMapLayers
import com.here.platform.location.integration.optimizedmap.dcl2.OptimizedMapCatalog

val baseClient = BaseClient()
val optimizedMap: OptimizedMapLayers =
  OptimizedMapCatalog
    .from(optimizedMapHRN)
    .usingBaseClient(baseClient)
    .withTopologyAttributes(
      TopologyAttributeDescription.RoadUsage,
      TopologyAttributeDescription.FunctionalClass,
      TopologyAttributeDescription.PhysicalAttribute,
      TopologyAttributeDescription.SpecialTrafficAreaCategory
    )
    .newInstance
    .latest

import com.here.platform.data.client.base.javadsl.BaseClient;
import com.here.platform.data.client.base.javadsl.BaseClientJava;
import com.here.platform.location.compilation.heremapcontent.TopologyAttributeDescription;
import com.here.platform.location.integration.optimizedmap.OptimizedMapLayers;
import com.here.platform.location.integration.optimizedmap.dcl2.javadsl.OptimizedMapCatalog;
BaseClient baseClient = BaseClientJava.instance();
OptimizedMapLayers optimizedMap =
    OptimizedMapCatalog.from(optimizedMapHRN)
        .usingBaseClient(baseClient)
        .withTopologyAttributes(
            TopologyAttributeDescription.RoadUsage(),
            TopologyAttributeDescription.FunctionalClass(),
            TopologyAttributeDescription.PhysicalAttribute(),
            TopologyAttributeDescription.SpecialTrafficAreaCategory())
        .newInstance()
        .latest();

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.

Create and resolve geocoordinates:

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.

Create and resolve circle references:

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.

Create and resolve rectangle references:

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:

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));

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.

Create and resolve polygon references:

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.

Create and resolve linear location references:

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

Create and resolve closed linear location references:

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

Create and resolve point along a line references:

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

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

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);