tb.RouteNetwork

tb.RoutingProfile

class tebetebe.RoutingProfile.RoutingProfile(lua_path, name=None, default=False, **kwargs)[source]

Bases: object

A RoutingProfile is a configuration script which represents a routing behaviour, such as for bike or car routing. It describes whether or not to traverse a particular type of way or node in OSM data, and the speed at which those elements are traversed.

Check out the osrm-backend wiki for more information! https://github.com/Project-OSRM/osrm-backend/wiki/Profiles

Parameters

  • lua_path (str) – Path to .lua configuration script

  • name (str, optional) – Name of routing profile. If not provided, the .lua filename is used.

  • default (bool, optional) – If RoutingProfile is a default profile

get_name()[source]

Return name of routing profile

get_path()[source]

Return path of routing profile

is_default()[source]

Return if routing profile is a default or not

tb.Scenario

class tebetebe.Scenario.Scenario(osm_dataset, routing_profile, name=None, algorithm='MLD', tmp_dir=PosixPath('/tmp'), overwrite=False, verbose=False, **kwargs)[source]

Bases: object

Scenario is an abstraction of OSRM executables in order to compile, serve, and query a routable network.

A Scenario is initialized with (1) an OSM Dataset and (2) a Routing Profile. When called, Scenario compiles the OSMDataset and RoutingProfile into an OSRM routable network, provides a context manager to serve the scenario’s HTTP API, and returns various methods to query that API.

The HTTP API methods (match, nearest, simple_route, table, trip) are provided by the python-osrm module (https://github.com/ustroetz/python-osrm)

Example

>>> from tebetebe.profiles import foot
>>> import tebetebe as tb
>>>
>>> ## initialize scenario with GeoFabrik extract & default foot profile
>>> scenario = tb.Scenario("./swaziland-latest.osm.pbf", foot)
>>>
>>> with scenario() as api: ## compile scenario and serve HTTP API
>>>     api.simple_route()... ## query HTTP API for a simple route, match, nearest, trip...
Parameters

  • osm_dataset (str / OSMDataset) – OSM dataset from which the route network will be extracted

  • routing_profile (str / RoutingProfile) – Routing profile to be used in scenario

  • name (str, optional) – Scenario name used in output file and log entries. If not supplied, it will be built based upon the OSMDataset and RoutingProfile names

  • algorithm (str, optional) – Algorithm to be used (either “CH” or “MLD”)

  • tmp_dir (str, optional) – Temporary directory to store files generated by osrm binaries

  • overwrite (bool, optional) – Overwrite scenario if .osrm* files already exist. Otherwise, the existing .osrm* files will be used.

  • verbose (bool, optional) – Print output of OSRM compilation

  • **kwargs – To pass any custom arguments to the OSRM executables (“osrm-routed”, “osrm-contract”, …) pass the kwarg “{executable}_args” (ex. “routed_args”, “contract_args”, …) with a dictionary of key:values to be passed

get_name()[source]

Return the Scenario name

get_path()[source]

Return the Scenario path

is_alive()[source]

True if Scenario process is running, False otherwise

match(steps=False, overview='simplified', geometry='polyline', timestamps=None, radius=None, annotations='false', gaps='split', tidy=False, waypoints=None, url_config=http://localhost:5000/*/v1/driving)

Function wrapping OSRM ‘match’ function, returning the reponse in JSON

Parameters

  • points (list of tuple/list of point) – A sequence of points as (x ,y) where x is longitude and y is latitude.

  • steps (bool, optional) – Default is False.

  • overview (str, optional) – Query for the geometry overview, either “simplified”, “full” or “false” (Default: “simplified”)

  • geometry (str, optional) – Format in which decode the geometry, either “polyline” (ie. not decoded), “geojson”, “WKT” or “WKB” (default: “polyline”).

  • timestamps (list of timestamp, optional) –

  • radius (list of float, optional) –

  • annotations (bool, optional) –

  • gaps (str, optional) –

  • tidy (bool, optional) –

  • waypoints (list of tuple/list of point, optional) –

  • url_config (osrm.RequestConfig, optional) – Parameters regarding the host, version and profile to use

Returns

The response from the osrm instance, parsed as a dict

Return type

dict

nearest(number=1, url_config=http://localhost:5000/*/v1/driving)

Useless function wrapping OSRM ‘nearest’ function, returning the reponse in JSON

Parameters

  • coord (list/tuple of two floats) – (x ,y) where x is longitude and y is latitude

  • number (int, optional) –

  • url_config (osrm.RequestConfig, optional) – Parameters regarding the host, version and profile to use

Returns

result – The response from the osrm instance, parsed as a dict

Return type

dict

simple_route(coord_dest, coord_intermediate=None, alternatives=False, steps=False, output='full', geometry='polyline', overview='simplified', annotations='true', continue_straight='default', url_config=http://localhost:5000/*/v1/driving, send_as_polyline=True)

Function wrapping OSRM ‘viaroute’ function and returning the JSON reponse with the route_geometry decoded (in WKT or WKB) if needed.

Parameters

  • coord_origin (list/tuple of two floats) – (x ,y) where x is longitude and y is latitude

  • coord_dest (list/tuple of two floats) – (x ,y) where x is longitude and y is latitude

  • coord_intermediate (list of 2-floats list/tuple) – [(x ,y), (x, y), …] where x is longitude and y is latitude

  • alternatives (bool, optional) – Query (and resolve geometry if asked) for alternatives routes (default: False)

  • output (str, optional) – Define the type of output (full response or only route(s)), default : “full”.

  • geometry (str, optional) – Format in which decode the geometry, either “polyline” (ie. not decoded), “geojson”, “WKT” or “WKB” (default: “polyline”).

  • annotations (str, optional) –

  • continue_straight (str, optional) –

  • overview (str, optional) – Query for the geometry overview, either “simplified”, “full” or “false” (Default: “simplified”)

  • url_config (osrm.RequestConfig, optional) – Parameters regarding the host, version and profile to use

Returns

result – The result, parsed as a dict, with the geometry decoded in the format defined in geometry.

Return type

dict

table(coords_dest=None, ids_origin=None, ids_dest=None, output='np', minutes=False, annotations='duration', url_config=http://localhost:5000/*/v1/driving, send_as_polyline=True)

Function wrapping OSRM ‘table’ function in order to get a matrix of time distance as a numpy array or as a DataFrame

Parameters

  • coords_src (list) –

    A list of coord as (longitude, latitude) , like :
    list_coords = [(21.3224, 45.2358),

    (21.3856, 42.0094), (20.9574, 41.5286)] (coords have to be float)

  • coords_dest (list, optional) –

    A list of coord as (longitude, latitude) , like :
    list_coords = [(21.3224, 45.2358),

    (21.3856, 42.0094), (20.9574, 41.5286)] (coords have to be float)

  • ids_origin (list, optional) – A list of name/id to use to label the source axis of the result DataFrame (default: None).

  • ids_dest (list, optional) – A list of name/id to use to label the destination axis of the result DataFrame (default: None).

  • output (str, optional) –

    The type of annotated matrice to return (DataFrame or numpy array)

    ’raw’ for the (parsed) json response from OSRM ‘pandas’, ‘df’ or ‘DataFrame’ for a DataFrame ‘numpy’, ‘array’ or ‘np’ for a numpy array (default is “np”)

  • annotations (str, optional) – Either ‘duration’ (default) or ‘distance’

  • url_config (osrm.RequestConfig, optional) – Parameters regarding the host, version and profile to use

Returns

  • - if output==’raw’ (a dict, the parsed json response.)

  • - if output==’np’ (a numpy.ndarray containing the time in minutes,) – a list of snapped origin coordinates, a list of snapped destination coordinates.

  • - if output==’pandas’ (a labeled DataFrame containing the time matrix in minutes,) – a list of snapped origin coordinates, a list of snapped destination coordinates.

trip(steps=False, output='full', geometry='polyline', overview='simplified', roundtrip=True, source='any', destination='any', annotations='false', url_config=http://localhost:5000/*/v1/driving, send_as_polyline=True)

Function wrapping OSRM ‘trip’ function and returning the JSON reponse with the route_geometry decoded (in WKT or WKB) if needed.

Parameters

  • coord_origin (list/tuple of two floats) – (x ,y) where x is longitude and y is latitude

  • steps (bool, default False) –

  • output (str, default 'full') – Define the type of output (full response or only route(s))

  • geometry (str, optional) – Format in which decode the geometry, either “polyline” (ie. not decoded), “geojson”, “WKT” or “WKB” (default: “polyline”).

  • overview (str, optional) – Query for the geometry overview, either “simplified”, “full” or “false” (Default: “simplified”)

  • roundtrip (bool, optional) –

  • source (str, optional) –

  • destination (str, optional) –

  • annotations (str, optional) –

  • url_config (osrm.RequestConfig, optional) – Parameters regarding the host, version and profile to use

Returns

  • - if ‘only_index’ (a dict containing respective indexes) – of trips and waypoints

  • - if ‘raw’ (the original json returned by OSRM)

  • - if ‘WKT’ (the json returned by OSRM with the ‘route_geometry’ converted) – in WKT format

  • - if ‘WKB’ (the json returned by OSRM with the ‘route_geometry’ converted) – in WKB format

tb.POIDataset

class tebetebe.POIDataset.POIDataset(*args, name=None, **kwargs)[source]

Bases: geopandas.geodataframe.GeoDataFrame

Extension of a GeoDataFrame which stores Points only, to be used as origin, destination, and waypoints in routing.

Parameters

name (str) – Name of POIDataset (required)

classmethod from_features(features, name=None, **kwargs)[source]

Initialize POIDataset from GeoJSON features

classmethod from_file(path, name=None, **kwargs)[source]

Initialize POIDataset from file. If no name is given, the filename will be used

classmethod from_overpass(query, name=None, overwrite=False, tmp_dir=PosixPath('/tmp'), **kwargs)[source]

Initialize POIDataset from Overpass API query. Any returned nodes or closed ways with center attributes will be included in the dataset.

Parameters

  • query (str) – Query to be sent to overpass API. This query should not include an out directive (eg. [out:json];)

  • name (str) – Name of the POI dataset

  • overwrite (bool) – Overwrite POIDataset if it already exists on disk

  • tmp_dir (str) – Temporary directory to save POIDataset

get_name()[source]

Return POI dataset name

tb.Environment

class tebetebe.Environment.Environment(**kwargs)[source]

Bases: object

Environment is a convenience class to set default options for the tebetebe base classes.

Many of the tebetebe operations require writing a file to disk in order to be passed to the OSRM executables, and it’s useful to set a uniform tmp_dir for a particular set of commands so that all of these files generated by those commands are contained in the same place.

In addition to tmp_dir, any **kwarg passed to Environment will be passed to all of the classes available under the Environment. Useful examples of these kwargs include verbose and overwrite

Any **kwargs set in Environment classes will be overridden if the argument is specified during subclass initialization.

Parameters

**kwargs – Arbitrary keyword arguments to be passed to each class available under the Environment

tb.OSRM

class tebetebe.OSRM.OSRM(verbose=False)[source]

Bases: object

Base class wrapper around all the osrm-* binaries. All functions accept additional **kwargs to be passed upon execution. This class is used in the background and need not be initialized directly.

Parameters

verbose (bool) – Output stdout from osrm commands.

contract(osrm_file, **kwargs)[source]

Call osrm-contract on a .osrm file

customize(osrm_file, **kwargs)[source]

Call osrm-customize on a .osrm file

extract(osm_path, profile_path, **kwargs)[source]

Call osrm-extract with a path to the osm route network and lua profile.

get_version()[source]

Return OSRM binaries version

partition(osrm_file, **kwargs)[source]

Call osrm-partition for a .osrm file

routed(osrm_file, ready_callback, done_callback, verbose=False, **kwargs)[source]

Call osrm-routed on a .osrm file

Parameters

  • osrm_file (str) – Path to *.osrm

  • ready_callback (function) – Function to be called when osrm-routed is ready for HTTP requests

  • done_callback (function) – Function to be called when osrm-routed has exited

  • verbose (bool) – osrm-routed output is so verbose it is default off even if the parent class verbose=True. Set this to true if you want to see osrm-routed output anyway.

  • **kwargs – Any additional parameters to be passed to osrm-routed