OpenLR™ - Decoder package
The decoder package holds the reference implementation for the OpenLR™ decoder according to the OpenLR™ whitepaper. This decoder takes an OpenLR™ location reference and finds back the location in the decoder map database. The location reference is map independent and can be generated by the OpenLR™ encoder. Encoder and decoder map might differ in version and might also rely on different map vendors.
The decoder package requires the OpenLR™ data and map package. The interfaces in the map package must also be implemented in order to access the application map database. The data package provides a PhysicalDecoder interface so that different physical formats can be used. The implementation of this interface needs to be registered as a service and the decoder will find the corresponding physical decoder automatically during runtime. The decoder is capable to decode a single location reference as well as a set of location references in a row (see code example and pom.xml below). The decoding process is configurable using decoder properties (see configure the decoding process below). The implementation also offers logging functionality (log4j) which can be configured using the logging.properties file provided in the package or you need to put a file name log4j.properties in your classpath.
Details on the decoding steps can be found in the OpenLR™ whitepaper and also in the code documentation.The following table summarizes the decoder package related links on this website.
| Links | |
|---|---|
| The decoder software package can be downloaded in the software section. | Download |
| Accessing the decoder package with Maven | Maven access |
| Decoder package reports generated by Maven | Reports |
| Decoder package API documentation | API |
Code example
The following code example shows how the OpenLR™ decoder can be used. The code uses the "OpenLR Access Layer for SQLite" and the binary physical format.
import java.io.BufferedInputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;
import openlr.LocationReference;
import openlr.OpenLRRuntimeException;
import openlr.PhysicalFormatException;
import openlr.binary.ByteArray;
import openlr.binary.impl.LocationReferenceBinaryImpl;
import openlr.decoder.OpenLRDecoder;
import openlr.decoder.OpenLRDecoderParameter;
import openlr.location.Location;
import openlr.map.Line;
import openlr.map.MapDatabase;
import openlr.map.loader.MapLoadParameter;
import openlr.map.sqlite.loader.DBFileNameParameter;
import openlr.map.sqlite.loader.SQLiteMapLoader;
import openlr.properties.OpenLRPropertiesReader;
import openlr.properties.OpenLRPropertyException;
import org.apache.commons.configuration.Configuration;
import org.apache.log4j.PropertyConfigurator;
public class DecoderExample {
private static final String PATH_TO_DB = ".../tt_utrecht_2008_04.db3";
private static final InputStream DECODER_PROPERTIES = DecoderExample.class
.getClassLoader().getResourceAsStream(
"OpenLR-Decoder-Properties.xml");
private static final String PATH_TO_LOG_PROPERTIES = "...";
// first argument shall be the path to a file holding the binary
// location reference
public static void main(String[] args) {
// setup logging
PropertyConfigurator.configure(PATH_TO_LOG_PROPERTIES);
// instantiate map database
MapDatabase mdb = null;
SQLiteMapLoader mapLoader = new SQLiteMapLoader();
List<MapLoadParameter> params = new ArrayList<MapLoadParameter>();
DBFileNameParameter dbFile = new DBFileNameParameter();
dbFile.setValue(PATH_TO_DB);
params.add(dbFile);
try {
mdb = mapLoader.load(params);
} catch (Exception e) {
e.printStackTrace();
System.exit(1);
}
// check binary file
File binFile = new File(args[0]);
FileInputStream fib = null;
try {
fib = new FileInputStream(binFile);
} catch (FileNotFoundException fnfe) {
fnfe.printStackTrace();
System.exit(2);
}
// setup location reference
LocationReference locRef = null;
try {
ByteArray ba = new ByteArray(new BufferedInputStream(fib));
locRef = new LocationReferenceBinaryImpl("LocationID", ba);
} catch (IOException e) {
e.printStackTrace();
System.out.println("io error");
System.exit(2);
} catch (PhysicalFormatException e) {
e.printStackTrace();
System.out.println("invalid binary file");
System.exit(2);
}
// load decoder properties
Configuration prop = null;
try {
prop = OpenLRPropertiesReader.loadPropertiesFromStream(
DECODER_PROPERTIES, true);
} catch (OpenLRPropertyException e1) {
e1.printStackTrace();
}
// prepare decoder parameter with map database and properties
OpenLRDecoderParameter decParam = new OpenLRDecoderParameter.Builder()
.with(mdb).with(prop).buildParameter();
// start decoder
Location decodedLoc = null;
try {
OpenLRDecoder decoder = new OpenLRDecoder();
decodedLoc = decoder.decode(decParam, locRef);
} catch (OpenLRRuntimeException e) {
e.printStackTrace();
System.exit(5);
}
// check validity of decoding result
if (decodedLoc.isValid()) {
// decoded location is valid
List<? extends Line> decodedPath = decodedLoc.getLocationLines();
System.out.println("Location is valid -- number of lines: "
+ decodedPath.size());
} else {
// decoded location is not valid
System.out.println("Location is NOT valid -- return code: "
+ decodedLoc.getReturnCode());
}
}
}
Maven pom.xml for the code example
The following pom.xml can be used to run the code example.
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>openlr.examples</groupId>
<artifactId>decoderExample</artifactId>
<packaging>jar</packaging>
<version>0.0.1-SNAPSHOT</version>
<name>decoderExample</name>
<dependencies>
<dependency>
<groupId>openlr</groupId>
<artifactId>decoder</artifactId>
<version>1.3.0</version>
</dependency>
<dependency>
<groupId>openlr</groupId>
<artifactId>binary</artifactId>
<version>1.3.0</version>
</dependency>
<dependency>
<groupId>openlr-mapLoader</groupId>
<artifactId>tt-sqlite</artifactId>
<version>1.3.0</version>
</dependency>
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.14</version>
</dependency>
</dependencies>
<repositories>
<repository>
<id>openlr</id>
<url>http://www.openlr.org/nexus/content/repositories/releases</url>
</repository>
</repositories>
</project>
Configuring the decoding process
The OpenLR™ decoder can be configured using decoder properties in a xml-file. The following example shows the standard configuration of the decoding process.
<?xml version="1.0" encoding="UTF-8"?>
<!--
The Rating type defines four different categories indicating how good the
compared values match. The ranking of the categories from best to worst is:
EXCELLENT -> GOOD -> AVERAGE -> POOR. Each category will correspond to a rating
value which indicates the score being achieved in that particular category.
-->
<!--
The Rating interval type defines the boundaries of the difference intervals
defined by the rating type categories. It is assumed that the first interval
starts with a difference value of 0. The excellent category then defines the
interval beginning at zero and ending at the "excellent" value. The good
category defines the interval from "excellent" to "good", the average category
falls into the interval from "good" to "average" and all values inferior the
"average" value belong to the poor category.
-->
<!-- The decoder type encloses all configuration parameters for the OpenLR
decoder. -->
<ml:OpenLRDecoderProperties
xmlns:ml="http://www.example.org/OpenLRpropertiesProperties/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.example.org/OpenLRpropertiesProperties/
properties/OpenLRDecoderProperties.xsd ">
<!-- Defines the distance between the first and second point being used for
bearing calculation.The value is measured in meters and determined along
the line geometry. -->
<BearingDistance>20</BearingDistance>
<!-- Defines the maximum distance being used to search for map nodes to a
location reference point position. -->
<MaxNodeDistance>100</MaxNodeDistance>
<!-- Factor for the importance of the node rating. -->
<NodeFactor>3</NodeFactor>
<!-- Factor for the importance of the line attribute rating. -->
<LineFactor>3</LineFactor>
<!-- Defines the score values for each rating category for the functional
road class values. -->
<FRC_Rating>
<Excellent>100</Excellent>
<Good>75</Good>
<Average>50</Average>
<Poor>0</Poor>
</FRC_Rating>
<!-- Defines the interval boundaries for the functional road class
differences. -->
<FRC_Intervals>
<Excellent>0</Excellent>
<Good>1</Good>
<Average>2</Average>
</FRC_Intervals>
<!-- Defines the score values for each rating category for the form of way
values. -->
<FOW_Rating>
<Excellent>100</Excellent>
<Good>50</Good>
<Average>50</Average>
<Poor>25</Poor>
</FOW_Rating>
<!-- Defines the score values for each rating category for the bearing
values. -->
<Bearing_Rating>
<Excellent>100</Excellent>
<Good>50</Good>
<Average>25</Average>
<Poor>0</Poor>
</Bearing_Rating>
<!-- Defines the interval boundaries for the bearing differences. -->
<Bearing_Intervals>
<Excellent>6</Excellent>
<Good>12</Good>
<Average>18</Average>
</Bearing_Intervals>
<!-- Defines the variance being used during comparison of functional road
class values. -->
<FRC_Variance>2</FRC_Variance>
<!-- Defines the minimum rating value being accepted for a line. Values below
that minimum should be rejected. -->
<MinimumAcceptedRating>700</MinimumAcceptedRating>
<!-- Defines the maximum number of retries if a route search between two LRP
fails. -->
<MaxNumberRetries>3</MaxNumberRetries>
<!-- Defines the degradation of the rating value for two candidate lines.
Each LRP might have several candidate lines and for the route search
start line and end line needs to be chosen. The rating of such candidate
line pairs shall be degraded if start and end line are equal. -->
<SameLineDegradation>0.10</SameLineDegradation>
<!-- Defines the increase of the rating value for two candidate lines. Each
LRP might have several candidate lines and for the route search start
line and end line needs to be chosen. The rating of such candidate line
pairs shall be increased if the current start line is equal to the
previously chosen end line. This ensures that the resulting path is
connected and no recalculation of a previously calculated paths needs
to be done. -->
<ConnectedRouteIncrease>0.10</ConnectedRouteIncrease>
<!-- Defines the variance of the distance to next point values which will also be
accepted while checking the length of a calculated route. This value is used
to determine a lower and an upper bound of a length interval. The length of the
calculated route must fall into this interval. This variance is necessary if the
received DNP value is just an approximation of the real value. -->
<DNPVariance>118</DNPVariance>
<!-- Defines the maximum allowed angle difference between the bearing value resolved
from the physical format and the bearing of the candidate line. Candidate lines
with a bearing difference greater than the defined value will be rejected. -->
<maxBearingDifference>90</maxBearingDifference>
<!-- If set to true then the decoder shall also calculate the lines being (fully or partly)
covered by an area location -->
<Calc_Affected_Lines>false</Calc_Affected_Lines>
</ml:OpenLRDecoderProperties>