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™ - Encoder package

The encoder package holds the reference implementation for the OpenLR™ encoder according to the OpenLR™ whitepaper. This encoder takes a location in a map and generates an OpenLR™ location reference for this specific location. The location reference is map independent and the OpenLR™ decoder uses this location reference for finding back the location in the decoder map. Encoder and decoder map might differ in version and might also rely on different map vendors.

The encoder 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 PhysicalEncoder interface so that different physical formats can be used. The implementation of this interface needs to be registered as a service and the encoder will find all physical encoders automatically during runtime. The encoder is capable to encode a single location as well as a set of locations in a row (see code example and pom.mxl below). The encoding process is configurable using encoder properties (see configuration of the encoding 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 oo the encoding steps can be found in the OpenLR™ whitepaper and also in the code documentation.

The following table summarizes the encoder package related links on this website.

Links
The encoder software package can be downloaded in the software section. Download
Accessing the encoder package with Maven Maven access
Encoder package reports generated by Maven Reports
Encoder package API documentation API



Code example

The following code example shows how the OpenLR™ encoder can be used. The code uses the "OpenLR Access Layer for SQLite ". Furthermore it requires the OpenLR™ data, encoder and binary packages in the classpath.

import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;

import openlr.LocationReference;
import openlr.OpenLRProcessingException;
import openlr.binary.ByteArray;
import openlr.encoder.LocationReferenceHolder;
import openlr.encoder.OpenLREncoder;
import openlr.encoder.OpenLREncoderParameter;
import openlr.location.Location;
import openlr.location.LocationFactory;
import openlr.map.Line;
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 EncoderExample {
    /* needs to be adjusted */
    private static final String PATH_TO_DB = ".../tomtom_utrecht_2008_04.db3";

    /* needs to be adjusted */
    // private static final String PATH_TO_LOG4J_PROPERTIES = "...";

    private static final InputStream ENCODER_PROPERTIES = Thread
            .currentThread().getContextClassLoader()
            .getResourceAsStream("OpenLR-Encoder-Properties.xml");

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

        // load location path with n lines
        List<Line> path = new ArrayList<Line>();
        path.add(mdb.getLine(15280002805007L));
        path.add(mdb.getLine(15280002805010L));
        path.add(mdb.getLine(15280002805011L));
        path.add(mdb.getLine(15280002805003L));

        // instantiate Location object without offsets
        Location location = LocationFactory.createLineLocation("Location-1",
                path);

        LocationReferenceHolder locRef = null;
        try {
            // prepare encoder parameter with map database and properties
            Configuration conf = OpenLRPropertiesReader
                    .loadPropertiesFromStream(ENCODER_PROPERTIES, true);

            OpenLREncoderParameter encParams = new OpenLREncoderParameter.Builder()
                    .with(mdb).with(conf).buildParameter();

            // encode the location
            OpenLREncoder encoder = new OpenLREncoder();
            // prepare encoding result object
            locRef = encoder.encodeLocation(encParams, location);
        } catch (OpenLRProcessingException e) {
            e.printStackTrace();
            System.exit(2);
        }

        // check validity of the location reference
        if (locRef.isValid()) {

            // location reference is valid
            // e.g. get binary format
            LocationReference lr = locRef.getLocationReference("binary");
            ByteArray ba = (ByteArray) lr.getLocationReferenceData();

            System.out.println("Location reference is valid -- size [bytes]: "
                    + ba.size());
        } else {
            // location reference is not valid, print out error code
            System.out
                    .println("Location reference is NOT valid -- error code: "
                            + locRef.getReturnCode());
        }
    }
}


Maven pom.xml for the code example

The following pom.xml can be used for 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>encoderExample</artifactId>
        <packaging>jar</packaging>
        <version>0.0.1-SNAPSHOT</version>

        <name>encoderExample</name>

        <build>
                <plugins>
                        <plugin>
                                <artifactId>maven-compiler-plugin</artifactId>
                                <configuration>
                                        <source>1.6</source>
                                        <target>1.6</target>
                                </configuration>
                        </plugin>
                </plugins>
        </build>

        <dependencies>
                <dependency>
                        <groupId>openlr</groupId>
                        <artifactId>encoder</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 encoding process

The OpenLR™ encoder can be configured using encoder properties in a xml-file. The following example shows the standard configuration of the encoding process.

<?xml version="1.0" encoding="UTF-8"?>

<!-- The encoder type encloses all configuration parameters for the OpenLR 
     encoder. -->  
<p:OpenLREncoderProperties 
  xmlns:p="http://www.example.org/OpenLREncoderProperties/" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://www.example.org/OpenLREncoderProperties/
  properties/OpenLREncoderProperties.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 between two subsequent location reference 
       points.  -->
  <MaximumDistanceLRP>15000</MaximumDistanceLRP>
  
  <!-- Enables/Disables the check for turn restrictions along the location 
       path.  -->
  <CheckTurnRestrictions>false</CheckTurnRestrictions>
  
  <!-- The location reference cache can be used to store only location references where
       the computation time exceeds the defined value. The time is defined in ms. This shall
       help to store only complex location references and therefore to reduce the total cache size -->
  <CompTime4Cache>2500</CompTime4Cache>
  
  <!-- OPTIONAL -->
  <!-- Choosing a special version for a physical format. If no choices are made then
       the latest version will be used. -->
  <PhysicalFormatVersions>
        <PhysicalFormatVersion>
                <FormatIdentifier>binary</FormatIdentifier>
                <Version>3</Version>    
        </PhysicalFormatVersion>
  </PhysicalFormatVersions>

</p:OpenLREncoderProperties>