1. Home
  2. Introduction
  3. Documents
  4. Software
    1. Projects
      1. Map
      2. Data
      3. Encoder
      4. Decoder
      5. Binary
      6. XML
      7. Datex2
    2. Download
    3. Maven
    4. API
    5. Tools
  5. Test data
  6. FAQ
  7. Newsletter
  8. Users
  9. Contact

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 ". Furthermore it requires the OpenLRâ„¢ data, decoder and binary packages in the classpath.

import java.io.BufferedInputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;

import openlr.LocationReference;
import openlr.OpenLRProcessingException;
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.MapDatabase;
import openlr.map.loader.MapLoadParameter;
import openlr.map.loader.OpenLRMapLoaderException;
import openlr.map.sqlite.loader.DBFileNameParameter;
import openlr.map.sqlite.loader.SQLiteMapLoader;
import openlr.properties.OpenLRPropertiesReader;

import org.apache.commons.configuration.Configuration;

public class DecoderExample {

    private static final String PATH_TO_DB = ".../tomtom_utrecht_2008_04.db3";

    private static final InputStream DECODER_PROPERTIES = Thread
            .currentThread().getContextClassLoader()
            .getResourceAsStream("OpenLR-Decoder-Properties.xml");
    
    /* needs to be adjusted */
    // private static final String PATH_TO_LOG4J_PROPERTIES = "...";    

    // first argument shall be the path to a file holding the binary
    // location reference
    public static void main(String[] args) {
        // setup logging, optional
        // PropertyConfigurator.configure(PATH_TO_LOG4J_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 (OpenLRMapLoaderException e) {
            e.printStackTrace();
            System.exit(1);
        }

        // check binary file
        File binFile = new File(args[0]);
        LocationReference locRef = null;
        try {
            FileInputStream fib = new FileInputStream(binFile);

            // setup location reference
            ByteArray ba = new ByteArray(new BufferedInputStream(fib));
            locRef = new LocationReferenceBinaryImpl(
                    "LocationID", ba);

        } catch (IOException e) {
            System.out.println("io error");
            e.printStackTrace();
            System.exit(2);
        } catch (PhysicalFormatException e) {
            System.out.println("invalid binary file");
            e.printStackTrace();
            System.exit(2);
        }

        Location decodedLoc = null;
        try {
            // load decoder properties
            Configuration prop = OpenLRPropertiesReader
                    .loadPropertiesFromStream(DECODER_PROPERTIES, true);

            // prepare decoder parameter with map database and properties
            OpenLRDecoderParameter decParam = new OpenLRDecoderParameter.Builder()
                    .with(mdb).with(prop).buildParameter();

            // start decoder
            OpenLRDecoder decoder = new OpenLRDecoder();
            decodedLoc = decoder.decode(decParam, locRef);


        } catch (OpenLRProcessingException e) {
            e.printStackTrace();
            System.exit(3);
        }

        // check validity of decoding result
        if (decodedLoc.isValid()) {
            // decoded location is valid
            System.out.println("Location is valid -- content: "
                    + decodedLoc);
        } 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>