1. Home
  2. Documents
  3. Software
    1. Projects
    2. Download
    3. Maven
    4. API
    5. Tools
      1. OTK
  4. Test data
  5. FAQ
  6. Newsletter
  7. Users
  8. Contact

OpenLR™ toolkit

The OpenLR™ toolkit (OTK) is a bundle of useful command line tools regarding OpenLR™. It requires a Java installation on the target system. The tool is run by the following command schema:

otk [--help] COMMAND [ARGS]

The base command "otk" mentioned above and in the examples below represents the corresponding command scripts for Unix-like systems and Windows provided with the OTK bundle. On Unix-like systems the concrete call has to be "sh otk.sh"; Windows should work as specified. If there is anything to be said against using the scripts the following elaborate command to run the tool can be used:

java -jar otk-<version>-with-dependencies.jar [--help] COMMAND [ARGS]

This page describes the usage of the available commands. For further information on the options please see the usage output of the tool (option "--help") or the online version on the generated maven site.


binview

The binview tool prints the data contained in a binary location reference. The location reference can consist of either pure binary or base 64 encoded binary data provided via file, direct specification in the command line or piped in. The content is printed in a readable way or visualized via KML.

The following examples picture the output of the binary viewer tool. The concrete output data can be viewed by clicking the link provided by the corresponding value of the options "-o" or "-k".

otk binview -b64 -i CwOiYCUMoBNWAv9P/+MSBg== -o binview-line.txt -k binview-line.kml

otk binview -b64 -i IwOmrSUJ2g== -o binview-geo.txt -k binview-geo.kml

otk binview -b64 -i KwOn8iUMhCOaA/8UAFsjSsc= -o binview-point-along.txt -k binview-point-along.kml

otk binview -b64 -i KwOkMCUIMBthAwBdAMhbUGX/4gBu -o binview-poi.txt -k binview-poi.kml

otk binview -b64 -i AwOgxCUNmwEs -o binview-circle.txt -k binview-circle.kml

otk binview -b64 -i QwOgcSUNGgGHAX8= -o binview-rectangle.txt -k binview-rectangle.kml

otk binview -b64 -i QwOgNiUM5wFUANoAAwAC -o binview-grid.txt -k binview-grid.kml

otk binview -b64 -i EwOgUCUNEwJEAH7/yAEv/vMAxv7G/z0= -o binview-polygon.txt -k binview-polygon.kml

otk binview -b64 -i WwOgrCUNaiOLBiMD -o binview-closed-line.txt -k binview-closed-line.kml

The binview tool is able to process piped data. If the user leaves out the "-i" option the tool stays active and listens for data from standard input. This gives users the flexibility to utilize the tool in scripts on dynamically created input sources:

otk binview -b64 < loc-file.txt

echo "AwOgxCUNmwEs" | otk binview -b64

top

convert

The convert tool converts location references between the physical data formats. Please note that conversion from non-binary into the binary format incorporates a compression of the parameters. There will be a loss in accuracy.

The following examples picture the usage of the convert tool. The concrete output data as well as the input files can be viewed by clicking the link provided by the corresponding value of the options "-o" or "-i".

otk convert -if BINARY64 -i CwOiYCUMoBNWAv9P/+MSBg== -of XML -o convert-line.xml

otk convert -if XML -i convert-grid.xml -of BINARY64 -o convert-grid-b64.txt

otk convert -if BINARY -i convert-line.bin -of DATEX2 -o convert-line-datex2.xml

The convert tool is able to process piped data. If the user leaves out the "-i" option the tool stays active and listens for data from standard input. This gives users the flexibility to utilize the tool in scripts on dynamically created input sources:

otk convert -if xml -of binary64 < convert-grid.xml

echo "AwOgxCUNmwEs" | otk convert -if binary64 -of xml

top

xml2kml

The xml2kml tool creates KML representations from OpenLR location references in the XML format. The tool has two input modes. If the specified input source matches a directory the tool will process every file ending with ".xml" in it. If the input source links to a file the tool processes only this single file. The resulting KML files are placed into the current working directory of into a dedicated directory if specified. The file names match the input file, but with extension ".kml"

The following example command line assumes file xml2kml-line.xml to be found in the execution directory of the command. It generates the KML file from it provided by this link: xml2kml-line.kml.

otk xml2kml -i .

top

bbox

The bbox tool calculates bounding boxes from location references and draws them via KML. The created bounding box describes the sufficient part of the target map to decode the location reference.

The tool has two input modes. If the input source links to a file the tool processes only this single file. If the specified input source matches a directory the tool will process every file in it matching the following naming schema.

The tool assumes to find location reference in the contained files by the following conditions. Files ending with ".stream"are processed as pure binary OpenLR location references. Files ending with ".b64" are assumed to contain Base 64 encoded OpenLR binary location references. Files with suffix ".xml" are tried to process as OpenLR location references in XML format.

The resulting KML files are placed into the current working directory or into a dedicated directory if specified. The file names match the input file, but with suffix "-boundary.kml".

The following example command line assumes files bbox-line.stream, bbox-polygon.b64 and bbox-grid.xml to be found in the execution directory of the command. It generates the following KML files displaying the related bounding boxes: bbox-line.stream-boundary.kml, bbox-polygon.b64-boundary.kml, bbox-grid.xml-boundary.kml.

otk bbox -i .

top

loader-info

The loader-info tool provides information about an OpenLR map-loader implementation. This implementation can either be provided by specification of a path to a JAR archive or is searched in the Classpath of the current run of the OTK if no argument to the tool is specified.

In both cases the loader library has to provide access to an implementation of OpenLRMapLoader via Java ServiceLoader interface.

otk loader-info "tt-sqlite-1.4.0-with-dependencies.jar"

The command above runs the loader-info tool on the data access library "tt-sqlite" the can be found under test data. It will deliver output like this:

OpenLR map loaders found in tt-sqlite-1.4.0-with-dependencies.jar:

Loader name: "SQLite Map Loader (TomTom)"
-----------------------------------
Description: Loader of SQLite map databases
Parameters (ID, name, description, required/optional):
1, "Database file", "The SQLite database", required

Accessing the loader by specification of the JAR depends on the class loading behavior in the loader library. If there are any problems like ClassNotFoundExceptions the mentioned alternative via Classpath should be chosen. Therefore the loader library has to be added to the Classpath of the OTK execution. This is possible by running the tool directly by a Java call. The command therefore has to match the following scheme:

java -cp otk-<version>-with-dependencies.jar<delimiter><loader-jar-or-classes-folder> openlr.otk.OTK loader-info

The Classpath delimiter is ";" for Windows and ":" on Unix-like systems.

Example (Windows):

java -cp otk-1.4.0-with-dependencies.jar;tt-sqlite-1.4.0-with-dependencies.jar openlr.otk.OTK loader-info

top

encode/decode

The encode command encodes locations on an OpenLR™ map instance. The results can be stored in files or visualized via KML representation.

The decode command decodes location references on an OpenLR™ map instance. The result can be stored in a file or visualized via KML representation.

Location string format

The encoding and decoding commands utilize a special text format for describing network related locations. This format is explained in the following section.
The general structure of a location description is the following. It starts with a type identifier, followed by the location id and a list of comma separated attributes:

<location_type>;<id>;[<attributes>(,)]+

The following table lists the data elements for each location type. The attributes are given in the required sequence.

Location type Type identifier Attributes
Line LIN positive offset, negative offset, [line ID(,)]+
Geo coordinate GEO longitude, latitude
Point along line PAL line ID, positive offset, side of road, orientation
POI with access point POI line ID, positive offset, longitude POI, latitude POI, side of road, orientation
Circle CIR longitude, latitude, radius
Rectangle REC longitude lower left, latitude lower left, longitude upper right, latitude upper right
Grid GRI longitude lower left, latitude lower left, longitude upper right, latitude upper right, rows, columns
Polygon POL [longitude, latitude(,)]+
Closed line CLL [line ID(,)]+

Data types:
positive/ negative offset: integer >= 0
line ID: integer
longitude/ latitude: float; coordinate according to WGS84
side of road: integer constant; 0 (ON_ROAD_OR_UNKNOWN), 1 (RIGHT), 2 (LEFT), 3 (BOTH)
orientation:integer constant; 0 (NO_ORIENTATION_OR_UNKNOWN), 1 (WITH_LINE_DIRECTION), 2 (AGAINST_LINE_DIRECTION), 3 (BOTH)

Please see the encoding commands in the encoding/decoding examples below for examples of location strings!

Map access parameter

Encode and decode tool respectively provide a parameter that specifies the access to the map. This parameter ("-m") is a bit more complex, therefore it shall be explained here in more detail.

The expected value is a string that consists of the map loader identifier and a list of the loader's parameters and values. All the parts are separated by commas:

<loader ID> [,<loader param ID>,<value>]*

The loader identifier either contains the path to an OpenLR map loader JAR file or the name of a map loader instance searched in the Classpath. In the first example below the map loader is expected to reside in file "tt-sqlite-1.4.0-with-dependencies.jar" in the current working directory. The second searches the loader named "SQLite Map Loader (TomTom)" in the Java classes of the tool runtime. Please see the description of tool loader-info on how to extend the Classpath with a custom loader implementation.

Accessing the loader by specification of the JAR depends on the class loading behavior in the loader library. If there are any problems like ClassNotFoundExceptions the Classpath alternative should be chosen if possible. This alternative, using the loader name, is useful for cases where there are several loader implementations in the Classpath of OTK at runtime. The desired instance is then identified by the value OpenLRMapLoader.getName() returns. The proper name of a loader implementation can be retrieved with the tool loader-info.

In both cases the loader library has to provide access to an implementation of OpenLRMapLoader via Java ServiceLoader interface.

# points to a JAR:
"tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3"

# refers to a loader in the Classpath:
"SQLite Map Loader (TomTom),1,tomtom_utrecht_2008_04.db3"

The loader parameters follow the loader identifier, as mentioned, in form of a list of key-value pairs, all parts separated by commas. If there is a need to have a comma itself in a parameter key or value it has to be escaped by backslash "\". All backslashes in keys and values therefore have to be escaped too.

Examples:

The key of each parameter is expected to match the identifier delivered by the parameter implementation, see MapLoadParameter.getIdentifier(). The loader-info tool can be used to figure out the relevant parameter IDs.

The box below shows a valid map access string in the applicaton of the encode command:

otk encode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -of BINARY64

Please note that if there are any blanks in the map access value, the entire string must be quoted!

Encode/decode examples

For details about the parameters please see the usage output of the tool. The mentioned command lines below assume the test map samples and the tt-sqlite access library (that can be found in the test data section) to reside in the execution folder of the tool. The result of each command can be viewed by downloading the KML file via the link provided by the respective KML output option. The location references are represented in the base 64 encoded OpenLR™ binary format. The examples are illistrated by screen shots of the specific locations drawn by the MapViewer tool.

Line Location
example 1 Example 1 shows a location which consists of the three lines with map IDs 15280001229524,15280001349498 and -15280001349500 in the 2008.04 release of the map around Utrecht (The Netherlands). The result of the OpenLR™ encoding is Base64-encoded. This location reference is then decoded on the same map. Green lines describe the location path, the blue dot the starting point.
Encoding command otk encode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -of BINARY64 -i "LIN;openlr-line1-encoded;0,0,15280001229524,15280001349498,-15280001349500" -k kmlDirectory
Location Reference CwOiYCUMoBNWAv9P/+MSBg==
Decoding command otk decode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -if BINARY64 -id id -i "CwOiYCUMoBNWAv9P/+MSBg==" -k openlr-line1-decoded.kml
Decoded location LIN;id;0,0,15280001229524,15280001349498,-15280001349500

Example 2 illustrates the case of different maps. The location in the encoder map (area around Utrecht, 2008.04 map release) consists of six lines. The location reference is decoded on the map release 2007.07 and results in a location of nine lines. In the picture of the decoded location one can find offsets applied to cut the location down to the desired part. The positive offset is marked with a light blue quad, the negative offset with a read one.

example 2 encoded location example 2 decoded location
Encoded location in map 2008_04 Decoded location in map 2007_07
Encoding command otk encode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -of BINARY64 -i
"LIN;openlr-line2-encoded;0,0,15280049399532,15280049399523,15280049399521,-15280002764570,-15280049399525,-15280002736845"
-k kmlDirectory
Location Reference CwObNyUKhxuCFv3GA/YjblgR
Decoding command otk decode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2007_07.db3" -if BINARY64 -id id -i "CwObNyUKhxuCFv3GA/YjblgR" -k openlr-line2-decoded.kml
Decoded location
LIN;id;88,7,15280049343797,15280002736803,15280002764569,-15280002764567,15280002764532,15280002736874,15280002736875,-15280002736845,-15280002736844
Geo Coordinate Location
example geocoordinate The example shows encoding and decoding of the geo coordinate location of point longitude 5.09791, latitude 52.10888.
Encoding command otk encode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -of BINARY64 -i "GEO;openlr-geocoordinate-encoded;5.09791,52.10888" -k kmlDirectory
Location Reference IwOgDCUOIg==
Decoding command otk decode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2007_07.db3" -if BINARY64 -id id -i "IwOgDCUOIg==" -k openlr-geocoordinate-decoded.kml
Decoded location GEO;id;5.097903013205062,52.108873128642514
Point Along Line Location
example point along line The example shows encoding and decoding of the "point along a line" location at 79 meters after start of line 15280001229215. The affected network segment is marked in green with a blue dot illustrating its start. The light blue quad marks the actual location point.
Encoding command otk encode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -of BINARY64 -i "PAL;openlr-pointalong-encoded;15280001229215,79,0,0" -k kmlDirectory
Location Reference KwOgciUOBSOAAgBqAGYjU5A=
Decoding command otk decode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2007_07.db3" -if BINARY64 -id id -i "KwOgciUOBSOAAgBqAGYjU5A=" -k openlr-pointalong-decoded.kml
Decoded location PAL;id;15280001229215,79,0,0
POI With Access Point Location
example poi The example shows encoding and decoding of the "POI with access point" location at coordinate (5.10131, 52.10579) with an access point at 51 meters along line 15280001229305. The affected network segment is marked in green with a blue dot illustrating its start. The light blue quad marks the access point and the red triangle the actual location point.
Encoding command otk encode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -of BINARY64 -i "POI;openlr-poi-encoded;15280001229305,51,5.10131,52.10579,0,0" -k kmlDirectory
Location Reference KwOg5iUNnCOTAv+D/5QjQ1j/gP/r
Decoding command otk decode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2007_07.db3" -if BINARY64 -id id -i "KwOg5iUNnCOTAv+D/5QjQ1j/gP/r" -k openlr-poi-decoded.kml
Decoded location POI;id;15280001229305,51,5.1013007857593475,52.10578780058023,0,0
Circle Location
example circle The example shows encoding and decoding of a circle location of a radius of 300 meters around coordinate (5.10185, 52.10598). The image shows the circle above the road network. Due to the projection of the map in MapViewer it appears tilted.
Encoding command otk encode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -of BINARY64 -i "CIR;openlr-circle-encoded;5.10185,52.10598,300" -k kmlDirectory
Location Reference AwOgxCUNmwEs
Decoding command otk decode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2007_07.db3" -if BINARY64 -id id -i "AwOgxCUNmwEs" -k openlr-circle-decoded.kml
Decoded location CIR;id;5.101851224874965,52.105976342906445,300
Rectangle Location
example rectangle The example shows encoding and decoding of a rectangle location with lower left point at coordinate (5.10006, 52.10320) and upper right (5.10398, 52.10703). The image shows the bounds of the rectangle above the road network.
Encoding command otk encode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -of BINARY64 -i "REC;openlr-rectangle-encoded;5.10006,52.10320,5.10398,52.10703" -k kmlDirectory
Location Reference QwOgcSUNGgGIAX8=
Decoding command otk decode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2007_07.db3" -if BINARY64 -id id -i "QwOgcSUNGgGIAX8=" -k openlr-rectangle-decoded.kml
Decoded location
REC;id;5.100070238089084,52.10320830320309,5.103990238135576,52.10703830326277
Grid Location
example grid The example shows encoding and decoding of a grid location with lower left point at coordinate (5.09881, 52.10212) and upper right (5.10222, 52.10431). This base rectangle is multiplied to 2 rows and 3 columns. The image shows the outher bounds of the grid and the corner points of of each grid cell.
Encoding command otk encode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -of BINARY64 -i "GRI;openlr-grid-encoded;5.09881,52.10212,5.10222,52.10431,2,3" -k kmlDirectory
Location Reference QwOgNiUM5wFVANsAAwAC
Decoding command otk decode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2007_07.db3" -if BINARY64 -id id -i "QwOgNiUM5wFVANsAAwAC" -k openlr-grid-decoded.kml
Decoded location
GRI;id;5.098804235434061,52.10211396192502,5.102214235322451,52.104303961836955,2,3
Polygon Location
example polygon The example shows encoding and decoding of a polygon location with five corner points. The image shows the bounds of the polygon above the road network.
Encoding command otk encode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -of BINARY64 -i
"POL;openlr-polygon-encoded;5.09937,52.10306,5.10518,52.10433,5.10462,52.10736,5.10192,52.10935,5.09877,52.10740" -k kmlDirectory
Location Reference EwOgUCUNEwJFAH//yAEv/vIAx/7F/z0=
Decoding command otk decode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2007_07.db3" -if BINARY64 -id id -i "EwOgUCUNEwJFAH//yAEv/vIAx/7F/z0=" -k openlr-polygon-decoded.kml
Decoded location
POL;id;5.099362134909156,52.103058099498256,5.10517213491154,52.10432809950619,5.1046171640384586,52.10735410217496,5.101919264508285,52.10933963394091,5.0987655978872235,52.107395197482035
Closed Line Location
example closed line The example shows encoding and decoding of a closed line location that consists of four lines. The image shows the network seqments defining the closed line location.
Encoding command otk encode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -of BINARY64 -i "CLL;id;-15280001229314,15280001229304,15280001229188,15280001229305" -k kmlDirectory
Location Reference WwOgrCUNaiOLBiMD
Decoding command otk decode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2007_07.db3" -if BINARY64 -id id -i "WwOgrCUNaiOLBiMD" -k openlr-closedline-decoded.kml
Decoded location
CLL;id;-15280001229314,15280001229304,15280001229188,15280001229305

Piped input

The encode and decode tools are able to process piped in data. If the user leaves out the "-i" option the tool stays active and listens for data from standard input. This gives users the flexibility to utilize the tool in scripts on dynamically created input sources:

otk encode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -of BINARY64 < loc-file.txt

echo "AwOgxCUNmwEs" | otk decode -m "tt-sqlite-1.4.0-with-dependencies.jar,1,tomtom_utrecht_2008_04.db3" -if BINARY64

top