Reference¶

Locations¶

Enums¶

class openlr.FRC¶

The functional road class is a road classification based on the importance of a road.

FRC0 = 0¶: Main road, highest importance

FRC1 = 1¶: First class road

FRC2 = 2¶: Second class road

FRC3 = 3¶: Third class road

FRC4 = 4¶: Fourth class road

FRC5 = 5¶: Fifth class road

FRC6 = 6¶: Sixth class road

FRC7 = 7¶: Other class road, lowest importance

class openlr.FOW¶

The form of way describes the physical road type.

UNDEFINED = 0¶: The physical road type is unknown

MOTORWAY = 1¶: A Motorway is defined as a road permitted for motorized vehicles only in combination with a prescribed minimum speed. It has two or more physically separated carriageways and no single level-crossings.

MULTIPLE_CARRIAGEWAY = 2¶: A multiple carriageway is defined as a road with physically separated carriageways regardless of the number of lanes. If a road is also a motorway, it should be coded as such and not as a multiple carriageway.

SINGLE_CARRIAGEWAY = 3¶: All roads without separate carriageways are considered as roads with a single carriageway.

ROUNDABOUT = 4¶: A Roundabout is a road which forms a ring on which traffic traveling in only one direction is allowed.

TRAFFICSQUARE = 5¶: A Traffic Square is an open area (partly) enclosed by roads which is used for non-traffic purposes and which is not a Roundabout.

SLIPROAD = 6¶: A Slip Road is a road especially designed to enter or leave a line.

OTHER = 7¶: The physical road type is known but does not fit into one of the other categories.

class openlr.SideOfRoad¶

The side of the road is valid only for point locations and indicates on which side of the referenced road the point location is located.

ON_ROAD_OR_UNKNOWN = 0¶: Point is directly on (or above) the road, or determination of right/left side is not applicable (default)

RIGHT = 1¶: Point is on right side of the road

LEFT = 2¶: Point is on the left side of the road

BOTH = 3¶: Point is on both sides of the road

class openlr.Orientation¶

The orientation is only valid for point locations and indicates for which direction the point information is relevant.

NO_ORIENTATION_OR_UNKNOWN = 0¶: Point has no sense of orientation, or determination of orientation is not applicable (default)

WITH_LINE_DIRECTION = 1¶: Point has orientation from first LRP towards second LRP

AGAINST_LINE_DIRECTION = 2¶: Point has orientation from second LRP towards first LRP

BOTH = 3¶: Point has orientation in both directions

Location Properties¶

openlr.Coordinates(lon, lat)¶: A coordinate pair longitude (lon) and latitude (lat) represented in WGS84 coordinates.

class openlr.LineAttributes(frc, fow, bear)¶

Line attributes consist of functional road class, form of way, and bearing.

bear multiplied by 11.25 is the bearing angle in degrees.

class openlr.PathAttributes(lfrcnp, dnp)¶: Path attributes consist of lowest FRC to next point, and distance in meters to next point.

class openlr.LocationReferencePoint(lon, lat, frc, fow, bear, lfrcnp, dnp)¶

A location reference point consists of coordinate, line attribute and path attribute data.

Refer to Coordinates, LineAttributes, and PathAttributes for more information.

Reference Locations¶

class openlr.LineLocationReference(points, poffs, noffs)¶: A line location reference describes a path within a map and consists of location reference point(s), a last location reference point and offset data.

class openlr.GeoCoordinateLocationReference(point)¶: GeoCoordinate is a point location which consists of exactly one Coordinate pair.

class openlr.PointAlongLineLocationReference(points, poffs, orientation, sideOfRoad)¶: Point along line is a point location which is defined by a line and an offset value. The line will be referenced by two location reference points and the concrete position on that line is referenced using the positive offset. Additionally information about the side of the road where the point is located and the orientation with respect to the direction of the line can be added.

class openlr.PoiWithAccessPointLocationReference(points, poffs, lon, lat, orientation, sideOfRoad)¶: Point along line with access is a point location which is defined by a line, an offset value and a coordinate. The line will be referenced by two location reference points and the concrete position of the access point on that line is referenced using the positive offset. The point of interest is identified by the coordinate pair. Additionally information about the side of the road where the point is located and the orientation with respect to the direction of the line can be added.

class openlr.CircleLocationReference(point, radius)¶

A CircleLocationReference represents a circle area location.

The radius is given in meters.

class openlr.RectangleLocationReference(lowerLeft, upperRight)¶: A RectangleLocationReference represents a rectangular area location.

class openlr.GridLocationReference(lowerLeft, upperRight, n_cols, n_rows)¶: A GridLocationReference represents a rectangular area location with a grid of n_cols columns and n_rows rows.

class openlr.PolygonLocationReference(corners)¶: A PolygonLocationReference represents a polygonal area location.

openlr.ClosedLineLocationReference¶

A ClosedLineLocationReference is defined by an ordered sequence of location reference points and a terminating last location reference point.

alias of openlr.locations.ClosedLineLocation

XML Format¶

XML OpenLR physical format conversion methods based on the white paper.

openlr.xml_decode_document(doc)¶: Decodes OpenLR xml minidom Document into a location

openlr.xml_decode_file(filename_or_file)¶: Decodes an OpenLR XML from a filename or file object

openlr.xml_decode_string(string)¶: Decodes an OpenLR XML from string

openlr.xml_encode_to_document(location)¶: Encodes location object to OpenLR xml minidom document

openlr.xml_encode_to_string(location, is_pretty=True)¶: Encodes location object into an OpenLR XML string

Binary Format¶

Binary OpenLR physical format conversion methods based on the white paper.

openlr.binary_decode(data, is_base64=True)¶

Decodes binary data into Location

Parameters

data (str, bytearray, bytes) – A bytes-like object that contains the binary data
is_base64 (bool) – Boolean flag for base64 encoded string data

Returns

location – Location object

Return type

NamedTuple

openlr.binary_encode(location, is_base64=True)¶

Encodes Location object into binary data

Parameters

location (NamedTuple) – Location object
is_base64 (bool) – Boolean flag for base64 encoded string data

Returns

data – A bytes-like object that contains the binary data

Return type

str, bytearray, bytes

Binary Internal APIs¶

Internal API for binary format conversion. It provides an extended io.BytesIO stream class to read/write OpenLR binary data.

openlr.openlr_bytes_io.deg_to_int(deg, resolution=24)¶

converts degree coordinate into integer

\[\mathrm{int} = 0.5 \times \mathop{\mathrm{sgn}}(\mathrm{deg}) + \frac{\mathrm{deg} \times 2^{\mathrm{resolution}}}{360^{\circ}}\]

Parameters

deg (float) – Coordinate Degree
resolution (int) – Resolution bits of this integer, default: 3 bytes = 24

Returns

val – Coordinate value in integer

Return type

int

openlr.openlr_bytes_io.int_to_deg(val, resolution=24)¶

converts degree coordinate into integer

\[\DeclareMathOperator{\sgn}{sgn} \mathrm{deg} = \frac{ \left ( \mathrm{int} - 0.5 \times \sgn(\mathrm{int}) \right ) \times 360^{\circ} }{2^{\mathrm{resolution}}}\]

Parameters

val (int) – Coordinate value in integer
resolution (int) – Resolution bits of the returned integer, default: 3 bytes = 24

Returns

deg – Coordinate value in degree

Return type

float

openlr.openlr_bytes_io.bytes_to_int(b, signed=True)¶: converts big endian bytes to signed/unsigned int

openlr.openlr_bytes_io.int_to_bytes(val, size=3, signed=True)¶: positive/negative int values to big endian

class openlr.openlr_bytes_io.OpenLRBytesIO¶

In-memory binary stream for reading/writing OpenLR data

read(size=-1)¶: Python 2 compatibility for str -> bytes

read_status()¶

Reads status from the first byte: version & location type

Returns

version (int) – OpenLR version: 3 bit
location_type (int) – Combination of Point flag, Area flag & Attributes flag: 4 bit

read_offset()¶

Reads offset rate from the stream, 1 byte

Returns: offset – offset rate in [0,1] range
Return type: float

read_dnp()¶

Reads distance to next point from the buffer, 1 byte

Returns: dnp – Distance to next point
Return type: int

read_point_attributes()¶

Reads point attributes from the buffer, 2 bytes

Returns

fow (int) – form of way (3 bits)
frc (int) – functional road class (3 bits)
bear (int) – Bearing (5 bits)
lfrcnp (int) – Lowest FRC to next point or offset flags (3 bits)
reserved (int) – mostly reserved for future use or Orientation/SideOfRoad (2 bits)

read_coords()¶

Reads absolute coordinates from the buffer, 6 bytes

Returns

lon (float) – Longitude
lat (float) – Latitude

read_coords_relative(prev_lon, prev_lat)¶

Reads coordinates from the buffer relative to the previous ones, 4 bytes

Parameters

prev_lon (float) – Previous Longitude
prev_lat (float) – Previous Latitude

Returns

lon (float) – Longitude
lat (float) – Latitude

read_radius()¶

Reads an integer from the remaining bytes till the end

Returns: radius – integer value
Return type: int

read_cols_rows()¶

Reads the number of columns and rows, 4 bytes

Returns

cols (int)
rows (int)

write_status(version, location_type)¶

Writes status byte to the stream

Parameters

version (int) – OpenLR version (3 bit)
location_type (int) – Combination of Point, Area and Attribute flags (4 bit)

write_offset(offset)¶

Writes offset rate to the stream, 1 byte

Parameters: offset (float) – offset rate in [0,1] range

write_dnp(dnp)¶

Writes distance to next point to the stream, 1 byte

Parameters: dnp (int) – distance to next point

write_point_attributes(fow, frc, bear, lfrcnp, reserved)¶

Writes 2 bytes point attributes to the stream

Parameters

fow – form of way (3 bits)
frc (int) – functional road class (3 bits)
bear (int) – Bearing (5 bits)
lfrcnp (int) – Lowest FRC to next point or offset flags (3 bits)
reserved (int) – mostly reserved for future use or Orientation/SideOfRoad (2 bits)

write_coords(lon, lat)¶

Writes the absolute coordinates to the stream, 6 bytes

Parameters

lon (float) – Longitude to be written
lat (float) – Latitude to be written

write_coords_relative(lon, lat, prev_lon, prev_lat)¶

Writes the relative coordinates to the stream, 4 bytes

Parameters

lon (float) – Longitude to be written
lat (float) – Latitude to be written
prev_lon (float) – Previous Longitude
prev_lat (float) – Previous Latitude

write_radius(radius)¶

Writes the radius, 1-4 bytes depending on the value size

Parameters: radius (int) – Radius value in [0, 4294967295] range

write_cols_rows(cols, rows)¶

Writes the number of columns and rows, 4 bytes

Parameters

cols (int) –
rows (int) –

Helper Functions¶

openlr.get_dict(location)¶: Helper to convert location object to dict

openlr.get_lonlat_list(location)¶: Helper to return a list of lonlat tuples of coordinates in a location