Migrating from v1¶

While all of the functionality from v1 is retained in v2, the API has been completely overhauled. The old Router class is no longer present (being replaced by simple functions, find_route() and find_route_without_turn_around()). Datastore has been replaced by osm.Graph and osm.LiveGraph classes.

Datastore¶

Main usage (instantiating a graph, finding nodes close to start and end position, finding the shortest path and converting node ids to lat-lon pairs) is presented in the main page.

Instead of r = Router("car", "my-local-file.osm.pbf", localFileType="pbf") do this:

with open("my-local-file.osm.pbf", "rb") as f:
    graph = pyroutelib3.osm.Graph.from_file(pyroutelib3.osm.CarProfile(), f)

To load data automatically from OSM, instead of r = Router("car"), do this:

graph = pyroutelib3.osm.LiveGraph(pyroutelib3.osm.CarProfile())

Initialization arguments

v1	v2
transport	profile
localfile	`osm.Graph.from_file()`, `buf` argument
localfileType	`osm.Graph.from_file()`, `format` argument
expireData	tile_expiry_seconds (`osm.LiveGraph` only)
ignoreDataErrs	no direct replacement, use `logging.getLogger("pyroutelib3.osm").setLevel(logging.ERROR)`
distFunction	not applicable, OSM data implies `haversine_earth_distance()`
pyroutelib3.TILES_ZOOM	`tile_zoom` (`osm.LiveGraph` only)

Attributes/Properties

v1	v2
rnodes	`nodes`
routing	`edges`
mandatoryMoves	not applicable, turn restrictions are directly represented in the graph
forbiddenMoves	not applicable, turn restrictions are directly represented in the graph
distance	not applicable, OSM data implies `haversine_earth_distance()`
transport	not applicable, some profiles have a `name` attribute
type	`profile`
localFile	not applicable, use `local_file = not isinstance(graph, pyroutelib3.osm.LiveGraph)`
pyroutelib3.TILES_ZOOM	`tile_zoom` (`osm.LiveGraph` only)

Methods

v1	v2
getArea	`load_tile_around()` (`osm.LiveGraph` only)
loadOsm	`add_features()` (use in conjunction with `osm.reader.read_features()`)
storeWay	not possible to add a single way
storeRestriction	not possible to add a single restriction
equivalent	depends on the `osm.Profile` implementation
findNode	`find_nearest_node()`, `id` attribute
nodeLatLon	`find_nearest_node()`, `position` attribute
report	no replacement
doRoute	see Router section

Profiles¶

Profiles (also called types in v1 documentation) has seen the largest overhaul in v2. In v1 routing profiles were represented by a dictionary of the profile name, weights and access tags; and pre-defined profiles could be provided as strings. In v2, profiles are abstracted away into a simple protocol, osm.Profile.

V2 comes with 4 base implementations of that interface: osm.SkeletonProfile, osm.RailwayProfile, HighwayProfile and NonMotorroadHighwayProfile.

Instead of using weights, preferences are now expressed using penalties. Version 1 calculated the cost of an edge as distance_between_nodes / weight, which lead to violations of the A* heuristic if weight was greater than 1. In version 2, the calculation was changed to distance_between_nodes * penalty, with a check that the penalty is not smaller than 1, ensuring the A* heuristic behaves correctly. To convert weights to penalties, divide each weight by the minimal weight, e.g.:

{"primary": 0.2, "secondary": 0.6, "tertiary": 1.0}
→ {"primary": 0.2 / 0.2, "secondary": 0.6 / 0.2, "tertiary": 1.0 / 0.2}
→ {"primary": 1.0, "secondary": 3.0, "tertiary": 5.0}

Pre-made profiles can be replaced by directly instantiating the following classes:

v1	v2
car	`osm.CarProfile`
bus	`osm.BusProfile`
cycle	`osm.BicycleProfile`
horse	∅
foot	`osm.FootProfile`
tram	`osm.TramProfile`
train	`osm.RailwayProfile`
∅	`osm.SubwayProfile`

Each of the pre-made profiles accepts custom name, penalties and access arguments, to override default values. Custom profiles can be implemented by inheriting from base profiles (see FootProfile for a good example of that), or by completely custom class implementing osm.Profile.

Router¶

The Router class is no longer present in version 2, the doRoute method has been replaced by the find_route_without_turn_around() and find_route() functions. Prefer to use the first function, unless you are absolutely sure there are no turn restrictions in your data.

The status string is no longer being used, instead, find_route family of functions behave in the following manner:

v1 status	v2 behavior
success	non-empty list returned
no_route	empty list returned
gave_up	`StepLimitExceeded` raised

Instead of the SEARCH_LIMIT module constants, find_route functions take a step_limit argument.

Instead of the distance Datastore attribute / distFunction init parameter, find_route functions take a distance parameter.

Distance functions¶

v1	v2
distHaversine	`haversine_earth_distance()`
distEuclidian	`euclidean_distance()`
∅	`taxicab_distance()`