SumoNetVis package

SumoNetVis Basic Features

Net

class SumoNetVis.Net(file, additional_files=None)

Bases: object

Parameters

  • file (str) – path to Sumo network file

  • additional_files (Union[str, list[str]]) – optional path to additional file (or list of paths) to include with the network.

Variables

  • edges – dict with edge IDs as keys and _Edge objects as values

  • junctions – dict with junction IDs as keys and _Junction objects as values

  • connections – list of all _Connection objects

  • netOffset – (x, y) tuple of the netOffset parameter from the net file

  • projParameter – the projParameter from the net file

generate_obj_text(style=None, stripe_width_scale=1, terrain_distance=0, terrain_z=0, terrain_hi_q=False, material_mapping=None, material_param=None, extrude_height_param=None, extrude_height_param_transform=None)

Generates the contents for a Wavefront-OBJ file which represents the network as a 3D model.

This text can be saved as text to a file with the *.obj extension and then imported into a 3D software. The axis configuration in the generated file is Y-Forward, Z-Up.

Sumo “generic parameters” can be used to override the extrude height and material of lanes, junctions, and polys.

Parameters

  • style (str) – lane marking style to use for rendering (“USA” or “EUR”). Defaults to last used or “EUR”.

  • stripe_width_scale (float) – scale factor for lane striping widths. Defaults to 1.

  • terrain_distance (float) – if > 0: distance from network to which to generate terrain plane.

  • terrain_z (float) – z value for terrain plane

  • terrain_hi_q (bool) – if True, generates “high-quality” mesh for terrain (no interior angles > 20°). WARNING: this can be very computationally intensive for large or complex networks.

  • material_mapping (dict) – a dictionary mapping SumoNetVis-generated material names to user-defined ones

  • material_param (str) – generic parameter to use to override material, if present. material_mapping is applied also to this value.

  • extrude_height_param (str) – generic parameter to use to override extrude height, if present

  • extrude_height_param_transform – function to apply to extrude_height_param values. Defaults to str->float conversion.

Returns

None

load_additional_file(file)

Load the specified additional file and associate it with this Net.

Parameters

file – path to additionals file

Returns

None

plot(ax=None, clip_to_limits=False, zoom_to_extents=True, style=None, stripe_width_scale=1, plot_stop_lines=None, apply_netOffset=False, lane_kwargs=None, lane_marking_kwargs=None, junction_kwargs=None, additionals_kwargs=None, **kwargs)

Plots the Net. Kwargs are passed to the plotting functions, with object-specific kwargs overriding general ones.

Parameters

  • ax (plt.Axes) – matplotlib Axes object. Defaults to current axes.

  • clip_to_limits (bool) – if True, only objects in the current view will be drawn. Speeds up saving of animations.

  • zoom_to_extents (bool) – if True, window will be set to the network extents. Ignored if clip_to_limits is True

  • style (str) – lane marking style to use for plotting (“USA” or “EUR”). Defaults to last used or “EUR”.

  • stripe_width_scale (float) – scale factor for lane striping widths

  • plot_stop_lines (bool) – whether to plot stop lines

  • apply_netOffset (bool) – whether to translate the network by the inverse of the netOffset value

  • lane_kwargs – kwargs to pass to the lane plotting function (matplotlib.patches.Polygon())

  • lane_marking_kwargs – kwargs to pass to the lane markings plotting function (matplotlib.lines.Line2D())

  • junction_kwargs – kwargs to pass to the junction plotting function (matplotlib.patches.Polygon())

  • additionals_kwargs – kwargs to pass to the additionals plotting function (Additionals.plot())

Returns

SumoNetVis.ArtistCollection object containing all generated artists

Trajectories

class SumoNetVis.Trajectories(file=None)

Bases: object

Object storing a collection of trajectories.

Individual trajectories can be retrieved by indexing with a number or by vehID. The object is also iterable.

Parameters

file (str) – file from which to read trajectories. Currently only FCD exports supported.

Variables

mappables – dict of vehID: ScalarMappable pairs. Useful for generating colorbars.

property mappables

dict of vehID: ScalarMappable pairs. Useful for generating colorbars, like so: plt.colorbar(trajectories.mappables[vehID])

plot(ax=None, start_time=0, end_time=inf, **kwargs)

Plots all of the trajectories contained in this object.

Parameters

  • ax (plt.Axes) – matplotlib Axes object. Defaults to current axes.

  • start_time (float) – time at which to start drawing

  • end_time (float) – time at which to stop drawing

  • kwargs – keyword arguments to pass to plot function

Returns

list of artists (LineCollection objects)

plot_points(time, ax=None, animate_color=False)

Plots the position of each vehicle at the specified time as a point. The style for each point is controlled by each Trajectory’s point_plot_kwargs attribute.

Parameters

  • time (float) – simulation time for which to plot vehicle positions.

  • ax (plt.Axes) – matplotlib Axes object. Defaults to current axes.

  • animate_color (bool) – If True, the color of the marker will be animated using the Trajectory’s color values.

Returns

matplotlib Artist objects corresponding to the rendered points. Required for blitting animation.

read_from_fcd(file)

Reads trajectories from Sumo floating car data (fcd) output file.

Parameters

file (str) – Sumo fcd output file

Returns

None

timestep_range()

Returns a numpy ndarray consisting of every simulation time

Returns

ndarray of all simulation times

class SumoNetVis.Trajectory

Bases: object

Class containing a single trajectory.

Variables

mappable – ScalarMappable object. Useful for generating colorbars. None if no applicable colorization.

assign_colors_angle(cmap=None, angle_mode='deg')

Assigns colors to trajectory points based on the angle.

Parameters

  • cmap – cmap object or name of cmap to use

  • angle_mode (str) – units of the angle value. “deg”, “rad”, or “grad”

Returns

None

assign_colors_constant(color)

Assigns a constant color to the trajectory

Parameters

color – desired color

Returns

None

assign_colors_lane(cmap=None, color_dict=None)

Assigns colors to the trajectory points based on the lane value

Parameters

  • cmap – cmap object or name of cmap to use to color lanes

  • color_dict (dict) – dict to override random color selection. Keys are lane IDs, values are colors.

Returns

None

assign_colors_param(key, transformation=None, cmap=None, vmin=None, vmax=None)

Assigns colors based on values of the generic parameter with the given key. Colors can be assigned in one of two ways:

  • Provide a cmap. transformation will be interpreted as a matplotlib norm (default Normalize(vmin, vmax)).

  • Provide a transformation and no cmap, where transformation has signature transformation(param) -> color.

In the first case, the trajectory mappable will be generated, allowing automatic colorbar creation. If neither a transformation nor a cmap is given, the parameter value will be interpreted as a color.

Parameters

  • key (str) – generic parameter key

  • transformation – (optional) callable if no cmap provided or matplotlib norm if cmap provided

  • cmap – (optional): cmap to use to assign colors

  • vmin – minimum value for norm (used to scale values onto cmap)

  • vmax – maximum value for norm (used to scale values onto cmap)

Returns

None

assign_colors_speed(cmap=None, min_speed=0, max_speed=None)

Assigns colors to trajectory points based on the speed.

Parameters

  • cmap – cmap object or name of cmap to use

  • min_speed (float) – speed corresponding to low end of the color scale. If None, trajectory’s min value is used

  • max_speed (float) – speed corresponding to high end of the color scale. If None, trajectory’s max value is used

Returns

None

property mappable

ScalarMappable object corresponding to colorization of trajectory. Useful for generating colorbars, like so: plt.colorbar(trajectory.mappable)

plot(ax=None, start_time=0, end_time=inf, zoom_to_extents=False, **kwargs)

Plots the trajectory

Parameters

  • ax (plt.Axes) – matplotlib Axes object. Defaults to current axes.

  • start_time (float) – time at which to start drawing

  • end_time (float) – time at which to end drawing

  • zoom_to_extents (bool) – if True, window will be set to Trajectory extents

  • kwargs – keyword arguments to pass to LineCollection or matplotlib.pyplot.plot()

Returns

artist (LineCollection)

Additionals

class SumoNetVis.Additionals(file, reference_net=None)

Bases: object

Stores objects from a Sumo additional XML file.

Parameters

  • file (str) – path to Sumo additional file

  • reference_net (SumoNetVis.Net) – network to use for objects which reference network elements (optional)

generate_bus_stops_obj_text(area_kwargs=None, markings_kwargs=None, **kwargs)

Generates the contents for a Wavefront-OBJ file which represents the bus stops as a 3D model.

This text can be saved as text to a file with the *.obj extension and then imported into a 3D software. The axis configuration in the generated file is Y-Forward, Z-Up.

Object-specific kwargs override general kwargs. Options are: “z”, “extrude_height”, and “include_bottom_face”.

Parameters

  • area_kwargs (dict) – kwargs for 3D area object generation.

  • markings_kwargs (dict) – kwargs for 3D lane markings object generation.

generate_polygons_obj_text(**kwargs)

Generates the contents for a Wavefront-OBJ file which represents the polygons as a 3D model.

This text can be saved as text to a file with the *.obj extension and then imported into a 3D software. The axis configuration in the generated file is Y-Forward, Z-Up.

Possible kwargs are: “z”, “extrude_height”, and “include_bottom_face”. Defaults are 0, 0, False.

plot(ax=None, polygon_kwargs=None, poi_kwargs=None, bus_stop_area_kwargs=None, bus_stop_marking_kwargs=None, **kwargs)

Plot all supported objects contained within the Additionals object. Kwargs are passed to the plotting functions, with object-specific kwargs overriding general ones.

Parameters

  • ax (plt.Axes) – matplotlib Axes object

  • polygon_kwargs (dict) – kwargs to pass to the polygon plotting function

  • poi_kwargs (dict) – kwargs to pass to the POI plotting function

  • bus_stop_area_kwargs (dict) – kwargs to pass to the bus stop area plotting function

  • bus_stop_marking_kwargs (dict) – kwargs to pass to the bus stop markings plotting function

Returns

SumoNetVis.ArtistCollection object containing all generated artists

plot_bus_stops(ax=None, area_kwargs=None, marking_kwargs=None, **kwargs)

Plots all bus stops.

Parameters

  • ax – matplotlib Axes object

  • area_kwargs – kwargs to pass to the bus stop area plotting function

  • marking_kwargs – kwargs to pass to the bus stop markings plotting function

Returns

list of artists

plot_pois(ax=None, **kwargs)

Plot all POIs.

Parameters

  • ax (plt.Axes) – matplotlib Axes object

  • kwargs – kwargs to pass to the plotting function

Returns

list of artists

plot_polygons(ax=None, **kwargs)

Plot all polygons.

Parameters

  • ax (plt.Axes) – matplotlib Axes object

  • kwargs – kwargs to pass to the plotting function

Returns

list of artists

Settings

SumoNetVis.set_style(style=None, plot_stop_lines=None)

Sets the lane marking style settings.

Parameters

  • style (str) – desired style (“USA” or “EUR”)

  • plot_stop_lines (bool) – whether to plot stop lines

Returns

None

SumoNetVis.set_stripe_width_scale(factor=1)

Sets the lane striping width scale factor.

Parameters

factor (float) – desired scale factor

Returns

None

SumoNetVis.set_bus_stop_style(style)

Sets the bus stop plotting style. Valid values are ‘SUMO’, ‘GER’, ‘UK’, and ‘USA’.

Parameters

style – desired bus stop plotting style

Returns

None

SumoNetVis Advanced Features

class SumoNetVis._Utils.ArtistCollection

Collection of Artist objects generated by various SumoNetVis plotting functions.

Consists of multiple lists of artists broken down by the type of Sumo object that generated them. The object can also be iterated and indexed just like a list. For example:

for artist in artist_collection:

artist.do_something()

Variables

  • lanes – list of artists created by lanes

  • lane_markings – list of artists created by lane markings

  • junctions – list of artists created by junctions

  • polys – list of artists created by additionals polygons

  • pois – list of artists created by additionals POIs

  • bus_stops – list of artists created by bus stops