# SumoNetVis
A Python library for visualizing a Sumo network and trajectories with matplotlib or as an OBJ file.
**Network and Trajectory Plotting**
**Highly Customizable**
**Trajectory Animation**
Basic trajectory plotting from FCD outputs is built in, but it is also possible to plot custom data and graphics on
top of the network with the full flexibility and power of matplotlib and other compatible libraries, such as seaborn.
3D geometry for a network can be generated and saved as a Wavefront-OBJ file.
## Installation
This package can be installed via pip with the command ```pip install SumoNetVis```.
You can then import the library with:
```python
import SumoNetVis
```
### Dependencies
* shapely (>=1.7.0 for stop lines and OBJ export)
* triangle (for OBJ terrain export)
* matplotlib
* numpy
## Usage
To plot a Sumo net file and trajectories, you can use the following code:
```python
import SumoNetVis
import matplotlib.pyplot as plt
# Plot Sumo Network
net = SumoNetVis.Net("path/to/yourfile.net.xml")
net.plot()
# Plot trajectories
trajectories = SumoNetVis.Trajectories("path/to/fcd-output.xml")
trajectories["vehicle_id"].assign_colors_speed()
trajectories["vehicle_id"].plot()
# Show figure
plt.show()
```
the ```Net.plot()``` function takes the following optional parameters:
* ax: matplotlib Axes object (defaults to currently active Axes)
* clip_to_limits: if True, only objects visible in the current view extents will be drawn
* zoom_to_extents: auto-zoom to Net extents (defaults to True)
* style: lane marking style to use ("USA" or "EUR")
* stripe_width_scale: scale factor for lane marking widths (defaults to 1)
* plot_stop_lines: whether to plot stop lines
* apply_netOffset: whether to translate the network by the inverse of the netOffset value
* lane_kwargs: dict of kwargs to pass to the lane plotting function (matplotlib.patches.Polygon()), for example alpha
* lane_marking_kwargs: dict of kwargs to pass to the lane markings plotting function (matplotlib.lines.Line2D())
* junction_kwargs: dict of kwargs to pass to the junction plotting function (matplotlib.patches.Polygon())
Any kwargs passed directly to ```Net.plot()``` will be passed to each of the plotting functions. These will, however,
be overridden by any object-type-specific kwargs (```lane_kwargs```, etc.).
To plot all junctions at 50% opacity and all other objects at 80% opacity, for example, one can use:
```python
net.plot(junction_kwargs={"alpha": 0.5}, alpha=0.8)
```
The color scheme of junctions and various lane types can be customized by modifying entries in the global variable
```COLOR_SCHEME```. For example, to plot bike lanes as dark green instead of dark red, do the following:
```python
SumoNetVis.COLOR_SCHEME["bicycle"] = "#006600"
```
Any color specification supported by matplotlib can be given here, such as RGB and RGBA hex strings and float tuples, as
well as color names and abbreviations. See the matplotlib documentation for more detailed information.
### Trajectory Colorization
When using the various "assign_colors" functions, when applicable, a corresponding matplotlib ```ScalarMappable``` will
be stored in the ```Trajectory.mappable``` property. The ```Trajectories``` class also contains a property,
```mappables```, which contains a dict of ```vehID: ScalarMappable``` pairs. Therefore, to automatically generate a
colorbar, one of the two following (equivalent) methods can be used:
```python
plt.colorbar(trajectories["vehicle_id"].mappable)
# OR
plt.colorbar(trajectories.mappables["vehicle_id"])
```
### Animation
Instead of visualizing Trajectories as lines, an animation can be generated using the ```matplotlib.animation``` module.
```python
import matplotlib.animation as animation
trajectories = SumoNetVis.Trajectories("path/to/fcd-output.xml")
fig, ax = plt.subplots()
a = animation.FuncAnimation(fig, trajectories.plot_points, frames=trajectories.timestep_range(), repeat=False,
interval=1000*trajectories.timestep, fargs=(ax,), blit=True)
plt.show()
```
The plot settings for each vehicle can be customized and the color of each point can be animated, as shown in the
following example.
```python
for trajectory in trajectories:
trajectory.assign_colors_speed()
trajectory.point_plot_kwargs["ms"] = 8 # set marker size. Can set any kwargs taken by matplotlib.pyplot.plot().
```
In order to animate the color of the points based on the assigned color scheme, an additional farg must be passed
when creating the animation.
```python
a = animation.FuncAnimation(fig, trajectories.plot_points, frames=trajectories.timestep_range(), repeat=False,
interval=1000*trajectories.timestep, fargs=(ax, True), blit=True)
```
### Additional Files
Currently, polygons, POIs, and bus stops are supported. Sumo additional files can be loaded and plotted in one of
two ways:
**Load directly with Network**
```python
net = SumoNetVis.Net("path/to/yourfile.net.xml", additional_files="path/to/additionals_file.add.xml")
```
**Load and handle additional files separately**
```python
addls = SumoNetVis.Additionals("path/to/additionals_file.add.xml", reference_net=net)
addls.plot()
```
The ```reference_net``` argument is optional, and only necessary for bus stops and for POIs whose position is defined
relative to a lane in the network.
#### Bus stop styles
Several styles of bus stop are supported. The style can be changed using the function
```SumoNetVis.set_bus_stop_style()```. See documentation for further details
### Generic Parameters
Generic parameter values are loaded for supported objects (edges, lanes, junctions, vehicles, polys) and are stored in
an attribute called ```params``` in each of the respective object classes. These can be used to aid in implementing
custom functionality on top of SumoNetVis. There are also some built-in features which can make use of these parameters.
For example:
* trajectory colorization
* OBJ export material
* OBJ export extrude height
See the Sumo documentation on generic parameters as well as the full SumoNetVis documentation for more information.
### OBJ Export
The Wavefront-OBJ format is a text-based file format. The ```Net.generate_obj_text()``` method generates the contents
of this file for the given Sumo network. In order to save an OBJ file, do the following:
```python
# Save a network as an OBJ file
with open("model.obj", "w") as f:
f.write(net.generate_obj_text())
# Save bus stops and polygons from an additional file as an OBJ file
with open("busstops.obj", "w") as f:
f.write(addls.generate_bus_stops_obj_text())
```
The axis configuration in the generated file is Y-Forward, Z-Up. Check these settings if the orientation of the model
is incorrect when importing the file into a 3D modelling program.
A flat planar "terrain" mesh can optionally be generated for all areas within a given distance of a network object.
See full documentation for further information.
Each type of object is defined with a corresponding material (i.e. all bike lanes have the same material, all sidewalks,
and so on), making it easy to quickly set the desired material properties before rendering. These can also be mapped
to user-defined material names if desired (see full documentation). Default material names are of the following forms:
for markings, "\[c\]\_marking", where \[c\] is the marking color ("w" for white, "y" for yellow, etc.);
for lanes, "\[type\]\_lane", where \[type\] is the lane type ("pedestrian", "bicycle", "no_passenger", "none", "other");
for junctions, "junction"; for terrain, "terrain".
### Extensibility
To aid in extensibility, each plotting function returns an iterable object consisting of all matplotlib Artist objects
generated by that function. Trajectory plotting functions return simple lists or tuples. Net and Additionals plotting
functions return an ```ArtistCollection``` object which is iterable just like a normal list, but also contains a list
attribute for each object type. Each artist is also given an attribute ```sumo_object``` which contains a reference to
the SumoNetVis object that generated it. The artists can then be acted on as desired, for example to create custom
animations or to make an interactive plot. An illustrative example of the latter is shown below. In the example,
when a user clicks on a lane, that lane's id and speed properties are printed out.
```python
def onpick(event):
sumo_object = event.artist.sumo_object
print("Lane ", sumo_object.id, "clicked. Speed limit: ", sumo_object.speed)
artists = net.plot()
for lane_artist in artists.lanes:
lane_artist.set_picker(True)
fig.canvas.mpl_connect("pick_event", onpick)
plt.show()
```
## Documentation
API documentation can be found [here](https://patmalcolm91.github.io/SumoNetVis/SumoNetVis.html)
## Contribution
Issues and pull requests are welcome.
Raw data
{
"_id": null,
"home_page": "https://github.com/patmalcolm91/SumoNetVis",
"name": "SumoNetVis",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "sumo, network, visualize, plot, matplotlib, traffic",
"author": "Patrick Malcolm",
"author_email": "patmalcolm91@gmail.com",
"download_url": "https://github.com/patmalcolm91/SumoNetVis/archive/v1.6.1.tar.gz",
"platform": null,
"description": "# SumoNetVis\nA Python library for visualizing a Sumo network and trajectories with matplotlib or as an OBJ file.\n\n**Network and Trajectory Plotting**\n\n\n\n**Highly Customizable**\n\n\n\n**Trajectory Animation**\n\n\n\nBasic trajectory plotting from FCD outputs is built in, but it is also possible to plot custom data and graphics on\ntop of the network with the full flexibility and power of matplotlib and other compatible libraries, such as seaborn.\n\n3D geometry for a network can be generated and saved as a Wavefront-OBJ file.\n\n\n## Installation\nThis package can be installed via pip with the command ```pip install SumoNetVis```.\nYou can then import the library with:\n\n```python\nimport SumoNetVis\n```\n\n### Dependencies\n* shapely (>=1.7.0 for stop lines and OBJ export)\n* triangle (for OBJ terrain export)\n* matplotlib\n* numpy\n\n## Usage\nTo plot a Sumo net file and trajectories, you can use the following code:\n\n```python\nimport SumoNetVis\nimport matplotlib.pyplot as plt\n# Plot Sumo Network\nnet = SumoNetVis.Net(\"path/to/yourfile.net.xml\")\nnet.plot()\n# Plot trajectories\ntrajectories = SumoNetVis.Trajectories(\"path/to/fcd-output.xml\")\ntrajectories[\"vehicle_id\"].assign_colors_speed()\ntrajectories[\"vehicle_id\"].plot()\n# Show figure\nplt.show()\n```\n\nthe ```Net.plot()``` function takes the following optional parameters:\n* ax: matplotlib Axes object (defaults to currently active Axes)\n* clip_to_limits: if True, only objects visible in the current view extents will be drawn\n* zoom_to_extents: auto-zoom to Net extents (defaults to True)\n* style: lane marking style to use (\"USA\" or \"EUR\")\n* stripe_width_scale: scale factor for lane marking widths (defaults to 1)\n* plot_stop_lines: whether to plot stop lines\n* apply_netOffset: whether to translate the network by the inverse of the netOffset value\n* lane_kwargs: dict of kwargs to pass to the lane plotting function (matplotlib.patches.Polygon()), for example alpha\n* lane_marking_kwargs: dict of kwargs to pass to the lane markings plotting function (matplotlib.lines.Line2D())\n* junction_kwargs: dict of kwargs to pass to the junction plotting function (matplotlib.patches.Polygon())\n\nAny kwargs passed directly to ```Net.plot()``` will be passed to each of the plotting functions. These will, however,\nbe overridden by any object-type-specific kwargs (```lane_kwargs```, etc.).\n\nTo plot all junctions at 50% opacity and all other objects at 80% opacity, for example, one can use:\n```python\nnet.plot(junction_kwargs={\"alpha\": 0.5}, alpha=0.8)\n```\n\nThe color scheme of junctions and various lane types can be customized by modifying entries in the global variable\n```COLOR_SCHEME```. For example, to plot bike lanes as dark green instead of dark red, do the following:\n```python\nSumoNetVis.COLOR_SCHEME[\"bicycle\"] = \"#006600\"\n```\nAny color specification supported by matplotlib can be given here, such as RGB and RGBA hex strings and float tuples, as\nwell as color names and abbreviations. See the matplotlib documentation for more detailed information.\n\n### Trajectory Colorization\nWhen using the various \"assign_colors\" functions, when applicable, a corresponding matplotlib ```ScalarMappable``` will\nbe stored in the ```Trajectory.mappable``` property. The ```Trajectories``` class also contains a property,\n```mappables```, which contains a dict of ```vehID: ScalarMappable``` pairs. Therefore, to automatically generate a\ncolorbar, one of the two following (equivalent) methods can be used:\n\n```python\nplt.colorbar(trajectories[\"vehicle_id\"].mappable)\n# OR\nplt.colorbar(trajectories.mappables[\"vehicle_id\"])\n```\n\n### Animation\nInstead of visualizing Trajectories as lines, an animation can be generated using the ```matplotlib.animation``` module.\n\n```python\nimport matplotlib.animation as animation\ntrajectories = SumoNetVis.Trajectories(\"path/to/fcd-output.xml\")\nfig, ax = plt.subplots()\na = animation.FuncAnimation(fig, trajectories.plot_points, frames=trajectories.timestep_range(), repeat=False,\n interval=1000*trajectories.timestep, fargs=(ax,), blit=True)\nplt.show()\n```\n\nThe plot settings for each vehicle can be customized and the color of each point can be animated, as shown in the\nfollowing example.\n\n```python\nfor trajectory in trajectories:\n trajectory.assign_colors_speed()\n trajectory.point_plot_kwargs[\"ms\"] = 8 # set marker size. Can set any kwargs taken by matplotlib.pyplot.plot().\n```\n\nIn order to animate the color of the points based on the assigned color scheme, an additional farg must be passed\nwhen creating the animation.\n\n```python\na = animation.FuncAnimation(fig, trajectories.plot_points, frames=trajectories.timestep_range(), repeat=False,\n interval=1000*trajectories.timestep, fargs=(ax, True), blit=True)\n```\n\n### Additional Files\nCurrently, polygons, POIs, and bus stops are supported. Sumo additional files can be loaded and plotted in one of\ntwo ways:\n\n**Load directly with Network**\n```python\nnet = SumoNetVis.Net(\"path/to/yourfile.net.xml\", additional_files=\"path/to/additionals_file.add.xml\")\n```\n\n**Load and handle additional files separately**\n```python\naddls = SumoNetVis.Additionals(\"path/to/additionals_file.add.xml\", reference_net=net)\naddls.plot()\n```\nThe ```reference_net``` argument is optional, and only necessary for bus stops and for POIs whose position is defined\nrelative to a lane in the network.\n\n#### Bus stop styles\nSeveral styles of bus stop are supported. The style can be changed using the function\n```SumoNetVis.set_bus_stop_style()```. See documentation for further details\n\n### Generic Parameters\nGeneric parameter values are loaded for supported objects (edges, lanes, junctions, vehicles, polys) and are stored in\nan attribute called ```params``` in each of the respective object classes. These can be used to aid in implementing\ncustom functionality on top of SumoNetVis. There are also some built-in features which can make use of these parameters.\nFor example:\n* trajectory colorization\n* OBJ export material\n* OBJ export extrude height\n\nSee the Sumo documentation on generic parameters as well as the full SumoNetVis documentation for more information.\n\n### OBJ Export\n\nThe Wavefront-OBJ format is a text-based file format. The ```Net.generate_obj_text()``` method generates the contents\nof this file for the given Sumo network. In order to save an OBJ file, do the following:\n\n```python\n# Save a network as an OBJ file\nwith open(\"model.obj\", \"w\") as f:\n f.write(net.generate_obj_text())\n\n# Save bus stops and polygons from an additional file as an OBJ file\nwith open(\"busstops.obj\", \"w\") as f:\n f.write(addls.generate_bus_stops_obj_text())\n```\n\nThe axis configuration in the generated file is Y-Forward, Z-Up. Check these settings if the orientation of the model\nis incorrect when importing the file into a 3D modelling program.\n\nA flat planar \"terrain\" mesh can optionally be generated for all areas within a given distance of a network object.\nSee full documentation for further information.\n\nEach type of object is defined with a corresponding material (i.e. all bike lanes have the same material, all sidewalks,\nand so on), making it easy to quickly set the desired material properties before rendering. These can also be mapped\nto user-defined material names if desired (see full documentation). Default material names are of the following forms:\nfor markings, \"\\[c\\]\\_marking\", where \\[c\\] is the marking color (\"w\" for white, \"y\" for yellow, etc.);\nfor lanes, \"\\[type\\]\\_lane\", where \\[type\\] is the lane type (\"pedestrian\", \"bicycle\", \"no_passenger\", \"none\", \"other\");\nfor junctions, \"junction\"; for terrain, \"terrain\".\n\n### Extensibility\nTo aid in extensibility, each plotting function returns an iterable object consisting of all matplotlib Artist objects\ngenerated by that function. Trajectory plotting functions return simple lists or tuples. Net and Additionals plotting\nfunctions return an ```ArtistCollection``` object which is iterable just like a normal list, but also contains a list\nattribute for each object type. Each artist is also given an attribute ```sumo_object``` which contains a reference to\nthe SumoNetVis object that generated it. The artists can then be acted on as desired, for example to create custom\nanimations or to make an interactive plot. An illustrative example of the latter is shown below. In the example,\nwhen a user clicks on a lane, that lane's id and speed properties are printed out.\n\n```python\ndef onpick(event):\n sumo_object = event.artist.sumo_object\n print(\"Lane \", sumo_object.id, \"clicked. Speed limit: \", sumo_object.speed)\n\nartists = net.plot()\nfor lane_artist in artists.lanes:\n lane_artist.set_picker(True)\nfig.canvas.mpl_connect(\"pick_event\", onpick)\nplt.show()\n```\n\n## Documentation\nAPI documentation can be found [here](https://patmalcolm91.github.io/SumoNetVis/SumoNetVis.html)\n\n## Contribution\nIssues and pull requests are welcome.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A python library to render Sumo network files and trajectories with matplotlib or as an OBJ file.",
"version": "1.6.1",
"project_urls": {
"Download": "https://github.com/patmalcolm91/SumoNetVis/archive/v1.6.1.tar.gz",
"Homepage": "https://github.com/patmalcolm91/SumoNetVis"
},
"split_keywords": [
"sumo",
" network",
" visualize",
" plot",
" matplotlib",
" traffic"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d222ed09fe40b7064e36d36b5d72a5fb0f92558e6dfcea6ab2c94b68fd838caa",
"md5": "8c8dcee76a1f21c89db207b372968e4c",
"sha256": "d8326a414d495345fda1cc9fe2d41542caa854aa36791d72321c13ec17554911"
},
"downloads": -1,
"filename": "SumoNetVis-1.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c8dcee76a1f21c89db207b372968e4c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 31424,
"upload_time": "2024-11-10T17:42:05",
"upload_time_iso_8601": "2024-11-10T17:42:05.277840Z",
"url": "https://files.pythonhosted.org/packages/d2/22/ed09fe40b7064e36d36b5d72a5fb0f92558e6dfcea6ab2c94b68fd838caa/SumoNetVis-1.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-10 17:42:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "patmalcolm91",
"github_project": "SumoNetVis",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sumonetvis"
}
JSON
