openlr_dereferencer.decoding package

Submodules

openlr_dereferencer.decoding.candidate module

Contains the Candidate class

class openlr_dereferencer.decoding.candidate.Candidate

Bases: openlr_dereferencer.decoding.routes.PointOnLine

An LRP candidate, represented by a point on the road network along with its score

score = None

The candidate may be bundled together with it’s precomputed score.

openlr_dereferencer.decoding.candidates module

Contains functions for candidate searching and map matching

openlr_dereferencer.decoding.candidates.get_candidate_route(c1: openlr_dereferencer.decoding.candidate.Candidate, c2: openlr_dereferencer.decoding.candidate.Candidate, lfrc: openlr.locations.FRC, maxlen: float) → Optional[openlr_dereferencer.decoding.routes.Route]

Returns the shortest path between two LRP candidates, excluding partial lines.

If it is longer than maxlen, it is treated as if no path exists.

Args:

map_reader:

A reader for the map on which the path is searched

c1:

The starting point.

c2:

The ending point.

lfrc:

“lowest frc”. Line objects from map_reader with an FRC lower than lfrc will be ignored.

maxlen:

Pathfinding will be canceled after exceeding a length of maxlen.

Returns:

If a matching shortest path is found, it is returned as a list of Line objects. The returned path excludes the lines the candidate points are on. If there is no matching path found, None is returned.

openlr_dereferencer.decoding.candidates.make_candidates(lrp: openlr.locations.LocationReferencePoint, line: openlr_dereferencer.maps.abstract.Line, config: openlr_dereferencer.decoding.configuration.Config, is_last_lrp: bool) → Iterable[openlr_dereferencer.decoding.candidate.Candidate]

Return zero or more LRP candidates based on the given line

openlr_dereferencer.decoding.candidates.match_tail(current: openlr.locations.LocationReferencePoint, candidates: List[openlr_dereferencer.decoding.candidate.Candidate], tail: List[openlr.locations.LocationReferencePoint], reader: openlr_dereferencer.maps.abstract.MapReader, config: openlr_dereferencer.decoding.configuration.Config, observer: Optional[openlr_dereferencer.observer.abstract.DecoderObserver]) → List[openlr_dereferencer.decoding.routes.Route]

Searches for the rest of the line location.

Every element of candidates is routed to every candidate for tail[0] (best scores first). Actually not _every_ element, just as many as it needs until some path matches the DNP.

Args:

current:

The LRP with which this part of the line location reference starts.

candidates:

The Candidates for the current LRP

tail:

The LRPs following the current.

Contains at least one LRP, as any route has two ends.

reader:

The map reader on which we are operating. Needed for nominating next candidates.

config:

The wanted behaviour, as configuration options

observer:

The optional decoder observer, which emits events and calls back.

Returns:

If any candidate pair matches, the function calls itself for the rest of tail and returns the resulting list of routes.

Raises:

LRDecodeError:

If no candidate pair matches or a recursive call can not resolve a route.

openlr_dereferencer.decoding.candidates.nominate_candidates(lrp: openlr.locations.LocationReferencePoint, reader: openlr_dereferencer.maps.abstract.MapReader, config: openlr_dereferencer.decoding.configuration.Config, is_last_lrp: bool) → Iterable[openlr_dereferencer.decoding.candidate.Candidate]

Returns a list of candidate lines for the LRP along with their score.

openlr_dereferencer.decoding.configuration module

Contains the configuration object that can be passed to the decoder, as well as default values

class openlr_dereferencer.decoding.configuration.Config

Bases: tuple

A config object that provides all settings that influences the decoder’s behaviour

Customize the values where the default won’t fit you:

>>> myconfig = Config(min_score=0.9, search_radius=10)

bear_dist

The bearing angle is computed along this distance on a given line. Given in meters.

bear_weight

Defines the weight the bearing score has on the overall score of a candidate.

candidate_threshold

Partial candidate line threshold, measured in meters

To find candidates, the LRP coordinates are projected against any line in the local area. If the distance from the starting point is greater than this threshold, the partial line beginning at the projection point is considered to be the candidate. Else, the candidate snaps onto the starting point (or ending point, when it is the last LRP)

fow_standin_score

When comparing an LRP FOW with a candidate’s FOW, this matrix defines how well the candidate’s FOW fits as replacement for the expected value. The usage is fow_standin_score[lrp’s fow][candidate’s fow]. It returns the score.

fow_weight

Defines the weight the FOW score has on the overall score of a candidate.

frc_weight

Defines the weight the FRC score has on the overall score of a candidate.

geo_weight

Defines the weight the coordinate difference has on the overall score of a candidate.

max_bear_deviation

Defines a threshold for the bearing difference. Candidates differing too much from the LRP’s bearing value are pre-filtered.

max_dnp_deviation

Tolerable relative DNP deviation of a path

A path between consecutive LRPs may deviate from the DNP by this relative value plus tolerated_dnp_dev in order to be considered. The value here is relative to the expected distance to next point.

min_score

A filter for candidates with insufficient score. Candidates below this score are not considered. As this value is a score, it is in the range of [0.0, 1.0].

search_radius

Configures the default radius to search for map objects around an LRP. This value is in meters.

tolerated_dnp_dev

Additional buffer to the range of allowed path distance

In order to be considered, a path must not deviate from the DNP value by more than max_dnp_deviation (relative value) plus tolerated_dnp_dev. This value is in meters.

tolerated_lfrc

For every LFRCNP possibly present in an LRP, this defines what lowest FRC in a considered route is acceptable

openlr_dereferencer.decoding.configuration.DEFAULT_FOW_STAND_IN_SCORE = [[0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5], [0.5, 1.0, 0.75, 0.0, 0.0, 0.0, 0.0, 0.0], [0.5, 0.75, 1.0, 0.75, 0.5, 0.0, 0.0, 0.0], [0.5, 0.0, 0.75, 1.0, 0.5, 0.5, 0.0, 0.0], [0.5, 0.0, 0.5, 0.5, 1.0, 0.5, 0.0, 0.0], [0.5, 0.0, 0.0, 0.5, 0.5, 1.0, 0.0, 0.0], [0.5, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0], [0.5, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0]]

The default value for the fow_standin_score config option. The values are adopted from the openlr Java implementation.

openlr_dereferencer.decoding.configuration.load_config(source: Union[str, io.TextIOBase, dict]) → openlr_dereferencer.decoding.configuration.Config

Load config from a source

Args:

source:

Either an open text file containing a JSON dict, or the path to it, or a dictionary

Returns:

The read Config object

openlr_dereferencer.decoding.configuration.save_config(config: openlr_dereferencer.decoding.configuration.Config, dest: Union[str, io.TextIOBase, None] = None) → Optional[dict]

Saves a config to a file or a dictionary

Args:

config:

The config.

dest:

Either a path, or an already write-opened text file, or nothing.

Returns:

If no destination was given, returns the config as dictionary

openlr_dereferencer.decoding.line_decoding module

Contains the decoding logic for line location

openlr_dereferencer.decoding.line_decoding.decode_line(reference: openlr.locations.LineLocationReference, reader: openlr_dereferencer.maps.abstract.MapReader, config: openlr_dereferencer.decoding.configuration.Config, observer: Optional[openlr_dereferencer.observer.abstract.DecoderObserver]) → openlr_dereferencer.decoding.line_location.LineLocation

Decodes an openLR line location reference

Candidates are searched in a radius of radius meters around an LRP.

openlr_dereferencer.decoding.line_decoding.dereference_path(lrps: List[openlr.locations.LocationReferencePoint], reader: openlr_dereferencer.maps.abstract.MapReader, config: openlr_dereferencer.decoding.configuration.Config, observer: Optional[openlr_dereferencer.observer.abstract.DecoderObserver]) → List[openlr_dereferencer.decoding.routes.Route]

Decode the location reference path, without considering any offsets

openlr_dereferencer.decoding.line_location module

This module contains the LineLocation class and a builder function for it

class openlr_dereferencer.decoding.line_location.LineLocation(route: openlr_dereferencer.decoding.routes.Route)

Bases: object

A dereferenced line location. Create it from a combined Route which represents the line location path. The attribute lines is the list of involved Line elements. The attributes p_off and n_off contain the absolute offset at the first/last of these line elements. They are measured in meters. The method coordinates() returns the exact coordinates of the line location.

coordinates() → List[openlr.locations.Coordinates]

Return the exact list of coordinates defining the line location path

lines

The sequence of lines involved in this location

n_off

This location ends n_off meters before the last line

p_off

This location starts p_off meters into the first line

openlr_dereferencer.decoding.line_location.build_line_location(path: List[openlr_dereferencer.decoding.routes.Route], reference: openlr.locations.LineLocationReference) → openlr_dereferencer.decoding.line_location.LineLocation

Builds a LineLocation object from all location reference path parts and the offset values.

The result will be a trimmed list of Line objects, with minimized offset values

openlr_dereferencer.decoding.line_location.combine_routes(line_location_path: Iterable[openlr_dereferencer.decoding.routes.Route]) → openlr_dereferencer.decoding.routes.Route

Builds the whole location reference path

Args:

line_location_path:

Consecutive Routes, like those partial routes resulting from matching an LRP list onto a map

Returns:

The combined route

openlr_dereferencer.decoding.line_location.get_lines(line_location_path: Iterable[openlr_dereferencer.decoding.routes.Route]) → List[openlr_dereferencer.maps.abstract.Line]

Convert a line location path to its sequence of line elements

openlr_dereferencer.decoding.point_locations module

Decoding logic for point (along line, …) locations

class openlr_dereferencer.decoding.point_locations.PoiWithAccessPoint

Bases: tuple

A dereferenced POI with access point location.

access_point_coordinates() → openlr.locations.Coordinates

Returns the geo coordinates of the access point

line

Alias for field number 0

orientation

Alias for field number 3

poi

Alias for field number 4

positive_offset

Alias for field number 1

side

Alias for field number 2

class openlr_dereferencer.decoding.point_locations.PointAlongLine

Bases: tuple

A dereferenced point along line location.

Contains the coordinates as well as the road on which it was located.

coordinates() → openlr.locations.Coordinates

Returns the geo coordinates of the point

line

Alias for field number 0

orientation

Alias for field number 3

positive_offset

Alias for field number 1

side

Alias for field number 2

openlr_dereferencer.decoding.point_locations.decode_poi_with_accesspoint(reference: openlr.locations.PoiWithAccessPointLocationReference, reader: openlr_dereferencer.maps.abstract.MapReader, config: openlr_dereferencer.decoding.configuration.Config, observer: Optional[openlr_dereferencer.observer.abstract.DecoderObserver]) → openlr_dereferencer.decoding.point_locations.PoiWithAccessPoint

Decodes a poi with access point location reference into a PoiWithAccessPoint

openlr_dereferencer.decoding.point_locations.decode_pointalongline(reference: openlr.locations.PointAlongLineLocationReference, reader: openlr_dereferencer.maps.abstract.MapReader, config: openlr_dereferencer.decoding.configuration.Config, observer: Optional[openlr_dereferencer.observer.abstract.DecoderObserver]) → openlr_dereferencer.decoding.point_locations.PointAlongLine

Decodes a point along line location reference into a PointAlongLine object

openlr_dereferencer.decoding.point_locations.point_along_linelocation(route: openlr_dereferencer.decoding.routes.Route, length: float) → Tuple[openlr_dereferencer.maps.abstract.Line, float]

Steps length meters into the route and returns the Line + offset of the point in meters.

If the path is exhausted (length longer than route), raises an LRDecodeError.

openlr_dereferencer.decoding.routes module

Defines data types out of which line locations consist

class openlr_dereferencer.decoding.routes.PointOnLine

Bases: tuple

A point on the road network

distance_from_start() → float

Returns the distance in meters from the start of the line to the point

distance_to_end() → float

Returns the distance in meters from the point to the end of the line

classmethod from_abs_offset(line: openlr_dereferencer.maps.abstract.Line, meters_into: float)

Build a PointOnLine from an absolute offset value.

Negative offsets are recognized and subtracted.

line

The line element on which the point resides

position() → openlr.locations.Coordinates

Returns the actual geo position

relative_offset

Specifies the relative offset of the point. Its value is member of the interval [0.0, 1.0]. A value of 0 references the starting point of the line.

split() → Tuple[Optional[shapely.geometry.linestring.LineString], Optional[shapely.geometry.linestring.LineString]]

Splits the Line element that this point is along and returns the parts

class openlr_dereferencer.decoding.routes.Route

Bases: tuple

A part of a line location path. May contain partial lines.

absolute_end_offset

Offset on the ending line in meters

absolute_start_offset

Offset on the starting line in meters

coordinates() → List[openlr.locations.Coordinates]

Returns all Coordinates of this line location

end

The point on which this location is ending

length() → float

Length of this line location part in meters

lines

Returns all lines that take part in the route

path_inbetween

While the first and the last line may be partial, these are the intermediate lines.

shape

Returns the shape of the route. The route is has to be continuous.

start

The point with which this location is starting

openlr_dereferencer.decoding.scoring module

Scoring functions and default weights for candidate line rating

FOW_WEIGHT + FRC_WEIGHT + GEO_WEIGHT + BEAR_WEIGHT should always be 1.

The result of the scoring functions will be floats from 0.0 to 1.0, with 1.0 being an exact match and 0.0 being a non-match.

openlr_dereferencer.decoding.scoring.angle_difference(angle1: float, angle2: float) → float

The difference of two angle values.

Args:

angle1, angle2:

The values are expected in degrees.

Returns:

A value in the range [-180.0, 180.0]

openlr_dereferencer.decoding.scoring.score_angle_difference(angle1: float, angle2: float) → float

Helper for score_bearing which scores the angle difference.

Args:

angle1, angle2: angles, in degrees.

Returns:

The similarity of angle1 and angle2, from 0.0 (180° difference) to 1.0 (0° difference)

openlr_dereferencer.decoding.scoring.score_bearing(wanted: openlr.locations.LocationReferencePoint, actual: openlr_dereferencer.decoding.routes.PointOnLine, is_last_lrp: bool, bear_dist: float) → float

Scores the difference between expected and actual bearing angle.

A difference of 0° will result in a 1.0 score, while 180° will cause a score of 0.0.

openlr_dereferencer.decoding.scoring.score_frc(wanted: openlr.locations.FRC, actual: openlr.locations.FRC) → float

Return a score for a FRC value

openlr_dereferencer.decoding.scoring.score_geolocation(wanted: openlr.locations.LocationReferencePoint, actual: openlr_dereferencer.decoding.routes.PointOnLine, radius: float) → float

Scores the geolocation of a candidate.

A distance of radius or more will result in a 0.0 score.

openlr_dereferencer.decoding.scoring.score_lrp_candidate(wanted: openlr.locations.LocationReferencePoint, candidate: openlr_dereferencer.decoding.routes.PointOnLine, config: openlr_dereferencer.decoding.configuration.Config, is_last_lrp: bool) → float

Scores the candidate (line) for the LRP.

This is the average of fow, frc, geo and bearing score.

openlr_dereferencer.decoding.tools module

Some tooling functions for path and offset handling

exception openlr_dereferencer.decoding.tools.LRDecodeError

Bases: Exception

An error that happens through decoding location references

openlr_dereferencer.decoding.tools.compute_bearing(lrp: openlr.locations.LocationReferencePoint, candidate: openlr_dereferencer.decoding.routes.PointOnLine, is_last_lrp: bool, bear_dist: float) → float

Returns the bearing angle of a partial line in degrees in the range 0.0 .. 360.0

openlr_dereferencer.decoding.tools.coords(lrp: openlr.locations.LocationReferencePoint) → openlr.locations.Coordinates

Return the coordinates of an LRP

openlr_dereferencer.decoding.tools.linestring_coords(line: shapely.geometry.linestring.LineString) → List[openlr.locations.Coordinates]

Returns the edges of the line geometry as Coordinate list

openlr_dereferencer.decoding.tools.project(line: openlr_dereferencer.maps.abstract.Line, coord: openlr.locations.Coordinates) → openlr_dereferencer.decoding.routes.PointOnLine

Computes the nearest point to coord on the line

Returns: The point on line where this nearest point resides

openlr_dereferencer.decoding.tools.remove_offsets(path: openlr_dereferencer.decoding.routes.Route, p_off: float, n_off: float) → openlr_dereferencer.decoding.routes.Route

Remove start+end offsets, measured in meters, from a route and return the result

Module contents

The module doing the actual decoding work. This includes finding candidates, rating them and choosing the best path

openlr_dereferencer.decoding.decode(reference: LocationReference, reader: openlr_dereferencer.maps.abstract.MapReader, observer: Optional[openlr_dereferencer.observer.abstract.DecoderObserver] = None, config: openlr_dereferencer.decoding.configuration.Config = Config(search_radius=50.0, max_dnp_deviation=0.1, tolerated_dnp_dev=30, min_score=0.3, tolerated_lfrc={<FRC.FRC0: 0>: <FRC.FRC0: 0>, <FRC.FRC1: 1>: <FRC.FRC1: 1>, <FRC.FRC2: 2>: <FRC.FRC2: 2>, <FRC.FRC3: 3>: <FRC.FRC3: 3>, <FRC.FRC4: 4>: <FRC.FRC4: 4>, <FRC.FRC5: 5>: <FRC.FRC5: 5>, <FRC.FRC6: 6>: <FRC.FRC6: 6>, <FRC.FRC7: 7>: <FRC.FRC7: 7>}, candidate_threshold=20, max_bear_deviation=45.0, fow_weight=0.25, frc_weight=0.25, geo_weight=0.25, bear_weight=0.25, fow_standin_score=[[0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5], [0.5, 1.0, 0.75, 0.0, 0.0, 0.0, 0.0, 0.0], [0.5, 0.75, 1.0, 0.75, 0.5, 0.0, 0.0, 0.0], [0.5, 0.0, 0.75, 1.0, 0.5, 0.5, 0.0, 0.0], [0.5, 0.0, 0.5, 0.5, 1.0, 0.5, 0.0, 0.0], [0.5, 0.0, 0.0, 0.5, 0.5, 1.0, 0.0, 0.0], [0.5, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0], [0.5, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0]], bear_dist=20)) → MapObjects

Translates an openLocationReference into a real location on your map.

Args:

reference:

The location reference you want to decode

reader:

A reader class for the map on which you want to decode

observer:

An observer that collects information when events of interest happen at the decoder

config:

A definition of the decoding behaviour providing various settings

Returns:

This function will return one or more map object, optionally wrapped into some class. Here is an overview for what reference type will result in which return type:

reference	returns
GeoCoordinateLocationReference	Coordinates
LineLocationReference	LineLocation
PointAlongLineLocationReference	PointAlongLineLocation
PoiWithAccessPointLocationReference	PoiWithAccessPoint

Raises:

LRDecodeError:

Raised if the decoding process was not successful.