veroviz.snapNodesToRoad module

getSnapLoc(loc=None, dataProvider=None, dataProviderArgs=None)

Snap a given single location, given by [lat, lon] coordinates, to the nearest location on a road network.

Parameters

• loc (list, Required) – Coordinates of a location, expressed as either [lat, lon, alt] or [lat, lon]. Note: This function returns only latitude and longitude; any altitude values provided as inputs will be lost in the return.

• dataProvider (string, Conditional, default as None) – Specifies the data source to be used for finding routes or generate nodes on a road network. See Data Providers for options and requirements of options.

• dataProviderArgs (dictionary, Conditional, default as None) – For some data provider, veroviz need some extra parameters such as API keys or database name. See Data Providers for the keys required for different data provider.

Returns

A snapped location in the format of [lat, lon]. Any altitude values provided as inputs in the loc parameter will be lost in the return.

Return type

list

Note

This function returns only latitude and longitude. Any altitude values provided as inputs in the loc parameter will be lost in the return.

Example

Import veroviz and check if the version is up-to-date:

>>> import veroviz as vrv
>>> vrv.checkVersion()

Snap a given location to the nearest street:

>>> loc = [42.00, -78.00]
>>> snapLoc = vrv.getSnapLoc(
...     loc          = loc,
...     dataProvider = 'OSRM-online')
>>> snapLoc
[41.999401, -78.003876]

View the original (red) and snapped (green) locations on a map

>>> myMap = vrv.addLeafletMarker(center=loc, fillColor='red')
>>> myMap = vrv.addLeafletMarker(center=snapLoc, fillColor='green', mapObject=myMap)
>>> myMap

NOTE: This function returns only latitude and longitude. Any altitude values provided as inputs in the loc parameter will be lost in the return.

>>> loc3D = [42.00, -78.00, 100]
>>> snapLoc = vrv.getSnapLoc(
...     loc          = loc3D,
...     dataProvider = 'OSRM-online')
>>> snapLoc
[41.999401, -78.003876]

getSnapLocBatch(locs=None, dataProvider=None, dataProviderArgs=None)

Snap multiple locations, each given by [lat, lon] coordinates, to their nearest locations on a road network.

Parameters

• locs (list of lists, Required) – A list of GPS coordinates of node locations, in the form of [[lat, lon], [lat, lon], …]

• dataProvider (string, Conditional, default as None) – Specifies the data source to be used for finding routes or generate nodes on a road network. See Data Providers for options and requirements of options.

• dataProviderArgs (dictionary, Conditional, default as None) – For some data provider, veroviz need some extra parameters such as API keys or database name. See Data Providers for the keys required for different data provider.

Returns

A list of snapped locations in the format of [[lat, lon], [lat, lon], …]. Note: Any altitude values provided as inputs in the loc parameter will be lost in the return.

Return type

list of lists

Example

Import veroviz and check if the version is up-to-date:

>>> import veroviz as vrv
>>> vrv.checkVersion()

Also, import os so we can use environment variables for data provider API keys:

>>> import os

Snap a given list of location to their nearest streets:

>>> locs = [
...     [42.00, -78.00],
...     [42.10, -78.00],
...     [42.20, -78.00]]
>>> snapLocs = vrv.getSnapLocBatch(
...     locs             = locs,
...     dataProvider     = 'MapQuest',
...     dataProviderArgs = {'APIkey': os.environ['MAPQUESTKEY']})
>>> snapLocs
[[41.999401, -78.003876], [42.100021, -77.995549], [42.1993, -78.001011]]

snapNodesToRoad(nodes=None, dataProvider=None, dataProviderArgs=None)

Updates the locations of nodes within a dataframe, such that each node becomes located on a road network.

Parameters

• nodes (Nodes, Required, default as None) – A Nodes dataframe containing an existing set of nodes.

• dataProvider (string, Conditional, default as None) – Specifies the data source to be used for generating nodes on a road network. See Data Providers for options and requirements.

• dataProviderArgs (dictionary, Conditional, default as None) – For some data providers, additional parameters are required (e.g., API keys or database names). See Data Providers for the additional arguments required for each supported data provider.

Returns

A copy of the input nodes dataframe, with updated lat/lon values.

Return type

Nodes dataframe

Example

Import veroviz and check if the version is up-to-date:

>>> import veroviz as vrv
>>> vrv.checkVersion()

Also, import os so we can use environment variables for data provider API keys:

>>> import os

Create a Nodes dataframe by createNodesFromLocs() with two nodes that are off the road network:

>>> exampleNodes = vrv.createNodesFromLocs(
...     locs = [[42.80, -78.00],
...             [42.81, -78.004]],
...     leafletColor = 'red')

These nodes are not aligned with the road network. The following examples demonstrate how to move the nodes to lat/lon locations that correspond to roads.

>>> # Use OSRM as data provider
>>> snappedNodes = vrv.snapNodesToRoad(
...     nodes        = exampleNodes,
...     dataProvider = 'OSRM-online')

Display the original (red) and OSRM-snapped (green) nodes to see the effects of snapping.

>>> myMap = vrv.createLeaflet(nodes=exampleNodes, mapBackground='Stamen Toner')
>>> myMap = vrv.createLeaflet(nodes=snappedNodesOSRM, mapObject=myMap)
>>> myMap

We can also use ORS, MapQuest, or pgRouting as the data source. In these cases, an API key or database name should be provided.

>>> # Use MapQuest as data provider, and change node colors to purple:
>>> snappedNodesMQ = vrv.snapNodesToRoad(
...     nodes            = exampleNodes,
...     dataProvider     = 'MapQuest',
...     dataProviderArgs = { 'APIkey' : os.environ['MAPQUESTKEY']})
>>> snappedNodesMQ['leafletColor'] = 'purple'

>>> # Add the MapQuest-snapped (purple) nodes to our map:
>>> myMap = vrv.createLeaflet(nodes=snappedNodesMQ, mapObject=myMap)
>>> myMap

>>> # Use ORS as data provider, and change node colors to blue:
>>> snappedNodesORS = vrv.snapNodesToRoad(
...     nodes            = exampleNodes,
...     dataProvider     = 'ORS-online',
...     dataProviderArgs = {'APIkey': os.environ['ORSKEY']})
>>> snappedNodesORS['leafletColor'] = 'blue'

>>> # Add the ORS-snapped (blue) nodes to our map:
>>> myMap = vrv.createLeaflet(nodes=snappedNodesORS, mapObject=myMap)
>>> myMap

>>> # Use pgRouting as data provider, and change node colors to black:
>>> snappedNodesPGR = vrv.snapNodesToRoad(
...     nodes        = exampleNodes,
...     dataProvider = 'pgRouting',
...     dataProviderArgs = {'databaseName': 'YOUR_DATABASENAME'})
>>> snappedNodesPGR['leafletColor'] = 'black'

>>> # Add the pgRouting-snapped (black) nodes to our map:
>>> myMap = vrv.createLeaflet(nodes=snappedNodesPGR, mapObject=myMap)
>>> myMap