veroviz.getShapepoints2D module

getShapepoints2D(odID=1, objectID=None, modelFile=None, startLoc=None, endLoc=None, startTimeSec=0.0, expDurationSec=None, routeType='euclidean2D', speedMPS=None, leafletColor='orange', leafletWeight=3, leafletStyle='solid', leafletOpacity=0.8, leafletCurveType='straight', leafletCurvature=0, useArrows=True, modelScale=100, modelMinPxSize=75, cesiumColor='orange', cesiumWeight=3, cesiumStyle='solid', cesiumOpacity=0.8, ganttColor='darkgray', popupText=None, dataProvider=None, dataProviderArgs=None)

This function generates all of the “shapepoints” between two given GPS coordinates, including timestamps indicating the departure and arrival times for each shapepoint. Shapepoints are pairs of GPS coordinates that are connected by straight lines. For a given origin and destination, numerous individual shapepoints can be combined to define a travel route along a road network.

Note

This function is for vehicles traveling on a ground plane (2-dimensional). For vehicles requiring an altitude component (e.g., drones), a 3D version of this function is provided by getShapepoints3D().

Parameters

• odID (int, Optional, default as 1) – This field allows grouping of dataframe rows according to common origin/destination pairs. Arc segments which are part of the same origin/destination share the same odID.

• objectID (int/string, Optional, default as None) – A descriptive name or index for a particular vehicle or object (e.g., ‘truck 1’, or ‘red car’).

• modelFile (string, Optional, default as None) – The relative path and filename of the 3D model associated with this object. The 3D model, typically in the format of .gltf or .glb, will be visualized in Cesium. The path should be relative to the directory where Cesium is installed (i.e., the modelFile should exist within the Cesium root directory).

• startLoc (list, Required, default as None) – The starting location, expressed as either [lat, lon, alt] or [lat, lon]. If no altitude is provided, it will be assumed to be 0 meters above ground level.

• endLoc (list, Required, default as None) – The ending location, expressed as either [lat, lon, alt] or [lat, lon]. If no altitude is provided, it will be assumed to be 0 meters above ground level.

• startTimeSec (float, Optional, default as 0.0) – The time, in seconds, at which the vehicle may leave the starting location.

• expDurationSec (float, Optional, default as None) – This is the number of seconds we expect to travel from the start to the end location. This value typically comes from the traval time matrix (see the getTimeDist functions). Including an expected duration will help keep these two values in alignment. If necessary, travel times for the individual shapepoints will be redistributed.

• routeType (string, Optional, default as 'euclidean2D') – This describes a characteristic of the travel mode. Possible values are: ‘euclidean2D’, ‘manhattan’, ‘fastest’, ‘shortest’, ‘pedestrian’, ‘cycling’, and ‘truck’. The ‘euclidean2D’ and ‘manhattan’ options are calculated directly from GPS coordinates, without a road network. Neither of these two options require a data provider. However, the other options rely on road network information and require a data provider. Furthermore, some of those other options are not supported by all data providers. See Data Providers for details.

• speedMPS (float, Conditional, default as None) – Speed of the vehicle, in units of meters per second. For route types that are not road-network based (i.e., ‘euclidean2D’ and ‘manhattan’), this field is required to calculate travel times. Otherwise, if a route type already incorporates travel speeds from road network data, (i.e., ‘fastest’, ‘shortest’, and ‘pedestrain’), this input argument may be ignored. If provided, speedMPS will override travel speed data used by the route type option.

• leafletColor (string, Optional, default as "orange") – The color of the route when displayed in Leaflet. See Leaflet Style for a list of available colors.

• leafletWeight (int, Optional, default as 3) – The pixel width of the route when displayed in Leaflet.

• leafletStyle (string, Optional, default as 'solid') – The line style of the route when displayed in Leaflet. Valid options are ‘solid’, ‘dotted’, and ‘dashed’. See Leaflet Style for more information.

• leafletOpacity (float in [0, 1], Optional, default as 0.8) – The opacity of the route when displayed in Leaflet. Valid values are in the range from 0 (invisible) to 1 (no transparency).

• leafletCurveType (string, Optional, default as 'straight') – The type of curve to be shown on leaflet map for :ref:Arc dataframes (curves will not be applied to :ref:Assignments dataframes). The options are ‘Bezier’, ‘greatcircle’, and ‘straight’. If Bezier is provided, the leafletCurvature is also required. If greatcircle is provided, the arc follow the curvature of the Earth.

• leafletCurvature (float in (-90, 90), Conditional, default as 45) – If leafletCurveType is ‘Bezier’, then leafletCurvature is required; otherwise this argument will not be used. The curvature specifies the angle between a straight line connecting the two nodes and the curved arc emanating from those two nodes. Therefore, this value should be in the open interval (-90, 90), although values in the (-45, 45) range tend to work best.

• useArrows (bool, Optional, default as True) – Indicates whether arrows should be shown on the route when displayed in Leaflet.

• modelScale (int, Optional, default as 100) – The scale of the 3D model (specified by the modelFile argument) when displayed in Cesium, such that 100 represents 100%.

• modelMinPxSize (int, Optional, default as 75) – The minimum pixel size of the 3D model (specified by the modelFile argument) when displayed in Cesium. When zooming out, the model will not be smaller than this size; zooming in can result in a larger model.

• cesiumColor (string, Optional, default as "orange") – The color of the route when displayed in Cesium. See Cesium Style for a list of available colors.

• cesiumWeight (int, Optional, default as 3) – The pixel width of the route when displayed in Cesium.

• cesiumStyle (string, Optional, default as 'solid') – The line style of the route when displayed in Cesium. Valid options are ‘solid’, ‘dotted’, and ‘dashed’. See Cesium Style for more information.

• cesiumOpacity (float in [0, 1], Optional, default as 0.8) – The opacity of the route when displayed in Cesium. Valid values are in the range from 0 (invisible) to 1 (no transparency).

• ganttColor (string, Optional, default as "darkgray") – The color of the route elements when displayed in a Gantt chart.

• popupText (string, Optional, default as None) – Text (or HTML) that will be displayed when a user clicks on the arc in either Leaflet or Cesium.

• dataProvider (string, Conditional, default as None) – Specifies the data source to be used for obtaining the shapepoints. 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

An Assignments dataframe containing an ordered sequence of paired GPS coordinates describing the collection of straight-line segments required to travel from a start location to an end location.

Return type

Assignments dataframe

Examples

Import veroviz and check if it’s the latest version:

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

The following examples assume the use of ORS as the data provider. If you have saved your API key as an environment variable, you may use os.environ to access it:

>>> import os
>>> ORS_API_KEY = os.environ['ORSKEY']
>>> # Otherwise, you may specify your key here:
>>> # ORS_API_KEY = 'YOUR_ORS_KEY_GOES_HERE'

Example 1 - A minimal example, using the fastest car route. The ORS-online data provider requires an API key.

>>> shapepoints2D = vrv.getShapepoints2D(
...     odID=1,
...     startLoc=[42.80, -78.80],
...     endLoc=[42.90, -78.80],
...     routeType='fastest',
...     dataProvider='ORS-online',
...     dataProviderArgs = {'APIkey': 'YOUR_ORSKEY'})

View the route in Leaflet. The green marker is the start, the red marker is the end:

>>> myMap = vrv.createLeaflet(arcs=shapepoints2D)
>>> myMap = vrv.addLeafletMarker(mapObject=myMap, center=[42.80, -78.80], fillColor='green')
>>> myMap = vrv.addLeafletMarker(mapObject=myMap, center=[42.90, -78.80], fillColor='red')
>>> myMap

Example 2 - Shapepoints with Euclidean travel can also be generated:

>>> shapepoints2D = vrv.getShapepoints2D(
...     odID             = 1,
...     startLoc         = [42.80, -78.80],
...     endLoc           = [42.90, -78.80],
...     routeType        = 'euclidean2D',
...     speedMPS         = vrv.convertSpeed(55, 'mi', 'hr', 'm', 's'),
...     dataProvider     = None,
...     dataProviderArgs = None)
>>> shapepoints2D

View the route in Leaflet. The green marker is the start, the red marker is the end:

>>> myMap = vrv.createLeaflet(arcs=shapepoints2D)
>>> myMap = vrv.addLeafletMarker(mapObject=myMap, center=[42.80, -78.80], fillColor='green')
>>> myMap = vrv.addLeafletMarker(mapObject=myMap, center=[42.90, -78.80], fillColor='red')
>>> myMap

Example 3 - Generate an Assignments dataframe that starts from 520 seconds and assumes the vehicle is driving at a constant constant speed of 16 m/s (or 35.8 mph). The OSRM-online data provider does not require an API key.

>>> shapepoints2D = vrv.getShapepoints2D(
...     odID         = 1,
...     startLoc     = [42.80, -78.80],
...     endLoc       = [42.90, -78.80],
...     startTimeSec = 520,
...     routeType    = 'fastest',
...     dataProvider = 'OSRM-online',
...     speedMPS     = 16)

View the route in Leaflet. The green marker is the start, the red marker is the end:

>>> myMap = vrv.createLeaflet(arcs=shapepoints2D)
>>> myMap = vrv.addLeafletMarker(mapObject=myMap, center=[42.80, -78.80], fillColor='green')
>>> myMap = vrv.addLeafletMarker(mapObject=myMap, center=[42.90, -78.80], fillColor='red')
>>> myMap

Example 4 - The expDurationSec argument ensures that the vehicle reaches the ending location at time startTimeSec + expDurationSec. This is useful when you are using data from different sources (e.g., time matrix data from pgRouting and shapepoints created by ORS) and you want to maintain consistency in timing. If expDurationSec and speedMPS are both provided, expDurationSec will override the speedMPS.

>>> [travelTimeSec, travelDistMeters]  = vrv.getTimeDistScalar2D(
...     startLoc         = [42.80, -78.80],
...     endLoc           = [42.90, -78.80],
...     outputDistUnits  = 'meters',
...     outputTimeUnits  = 'seconds',
...     routeType        = 'fastest',
...     dataProvider     = 'ORS-online',
...     dataProviderArgs = {'APIkey' : ORS_API_KEY})
>>> shapepoints2D = vrv.getShapepoints2D(
...     odID             = 1,
...     startLoc         = [42.80, -78.80],
...     endLoc           = [42.90, -78.80],
...     startTimeSec     = 520,
...     routeType        = 'fastest',
...     dataProvider     = 'ORS-online',
...     dataProviderArgs = {'APIkey' : ORS_API_KEY},
...     expDurationSec   = travelTimeSec)
>>> shapepoints2D

Example 5 - Note that getShapepoints2D() sometimes displays messages like “The origin/destination point is XXX meters away from the road”. This occurs if the start and/or end location provided is too far away from the nearest road. VeRoViz does not attempt to find a path from an arbitrary location to the nearest road. To avoid these warnings, one option is to snap the start/end locations to the road network before attempting to get the shapepoints. In this case, it is highly recommended to use the same data provider for both the snapping and shapepoint activities.

>>> startLoc = vrv.getSnapLoc(loc              = [42.80, -78.80],
...                           dataProvider     = 'ORS-online',
...                           dataProviderArgs = {'APIkey': ORS_API_KEY})
>>> endLoc   = vrv.getSnapLoc(loc              = [42.90, -78.80],
...                           dataProvider     = 'ORS-online',
...                           dataProviderArgs = {'APIkey': ORS_API_KEY})
>>> shapepoints2D = vrv.getShapepoints2D(
...          odID             = 1,
...          startLoc         = startLoc,
...          endLoc           = endLoc,
...          startTimeSec     = 520,
...          routeType        = 'fastest',
...          dataProvider     = 'ORS-online',
...          dataProviderArgs = {'APIkey': ORS_API_KEY})
>>> shapepoints2D

View the route in Leaflet. The green filled marker is the original start, the green outlined marker is the snapped start. The red filled marker is the original end, the red outlined marker is the snapped end.

>>> myMap = vrv.createLeaflet(arcs=shapepoints2D)
>>> myMap = vrv.addLeafletMarker(mapObject=myMap, center=[42.80, -78.80],
...                              fillColor='green')
>>> myMap = vrv.addLeafletMarker(mapObject=myMap, center=[42.90, -78.80],
...                              fillColor='red')
>>> myMap = vrv.addLeafletMarker(mapObject=myMap, center=startLoc,
...                              fillColor=None, lineColor='green')
>>> myMap = vrv.addLeafletMarker(mapObject=myMap, center=endLoc,
...                              fillColor=None, lineColor='red')
>>> myMap

Example 6 - If you are constructing the Assignments dataframe for use with Cesium, then the objectID and modelFile arguments are required. If you are just using it to generate Leaflet maps, those arguments can be left as default (None).

>>> shapepoints2D = vrv.getShapepoints2D(
...     odID             = 1,
...     objectID         = 'Blue Car',
...     modelFile        = '/veroviz/models/car_blue.gltf',
...     startLoc         = vrv.getSnapLoc(
...                          loc          = [42.80, -78.80],
...                          dataProvider = 'OSRM-online'),
...     endLoc           = vrv.getSnapLoc(
...                          loc          = [42.90, -78.80],
...                          dataProvider = 'OSRM-online'),
...     startTimeSec     = 520,
...     routeType        = 'shortest',
...     dataProvider     = 'MapQuest',
...     dataProviderArgs = {'APIkey': os.environ['MAPQUESTKEY']},
...     expDurationSec   = 1500)
>>> shapepoints2D

Example 7 - This example includes all of the functional arguments:

>>> start = [42.80, -78.80]
>>> end   = [42.90, -78.80]
>>> shapepoints2D = vrv.getShapepoints2D(
...     odID             = 1,
...     objectID         = 'Blue Car',
...     modelFile        = 'veroviz/models/car_blue.gltf',
...     modelScale       = 100,
...     modelMinPxSize   = 75,
...     startLoc         = start,
...     endLoc           = end,
...     startTimeSec     = 30.0,
...     expDurationSec   = 90,
...     routeType        = 'shortest',
...     speedMPS         = 5.2,
...     leafletColor     = 'blue',
...     leafletWeight    = 3,
...     leafletStyle     = 'dashed',
...     leafletOpacity   = 0.8,
...     useArrows        = True,
...     cesiumColor      = 'blue',
...     cesiumWeight     = 3,
...     cesiumStyle      = 'solid',
...     cesiumOpacity    = 0.8,
...     ganttColor       = 'blue',
...     popupText        = 'blue car route',
...     dataProvider     = 'MapQuest',
...     dataProviderArgs = {'APIkey': os.environ['MAPQUESTKEY']})
>>> myMap = vrv.createLeaflet(arcs = shapepoints2D)
>>> myMap = vrv.addLeafletMarker(mapObject=myMap, center=start, fillColor='green', lineColor='green')
>>> myMap = vrv.addLeafletMarker(mapObject=myMap, center=end, fillColor='red', lineColor='red')
>>> myMap

Generate a Cesium movie:

>>> vrv.createCesium(
...     assignments = shapepoints2D,
...     cesiumDir   = os.environ['CESIUMDIR'],
...     problemDir  = '/examples/shapepoints')