(a)
Snapshot
showing
a
part
of
transmit-receive
pairs
in
the
city
of
Porto. |
(b)
Street-level
view. |
Figure 1: Visualization of received power generated by GEMV2. Color bars are
in dBm.
Copyright © 2014-2015 Mate Boban
This user manual describes the MATLAB implementation of GEMV2, a geometry-based, efficient propagation model for vehicle-to-vehicle (V2V) and vehicle-to-infrastructure (V2I) communication [1]. The main features of GEMV2 are:
This user manual describes how to install and run GEMV2, what type of output it
generates, and gives a high-level overview of GEMV2 code. For a detailed
description of GEMV2 from a research standpoint, please refer to the following
paper:
Mate Boban, João Barros, and Ozan K. Tonguz: “Geometry-Based Vehicle-to-Vehicle
Channel Modeling for Large-Scale Simulation,” IEEE Transactions on Vehicular
Technology, Vol. 63, No. 9, November 2014,
doi:10.1109/TVT.2014.2317803 [PDF][BIB]
MATLAB implementation of GEMV2 can be used as a standalone tool for analyzing V2V and V2I communication in terms of key communications and networking performance metrics: received power, packet delivery rate, interference levels, neighborhood size, etc.). GEMV2 can also be used as a propagation model for discrete-time network simulators (e.g., NS-3, JiST/SWANS/STRAW), either offline (i.e., by providing the output from the MATLAB implementation to the simulator) or online (by re-implementing GEMV2 in the simulator).
Installation of GEMV2 is quite simple: download the .zip file containing GEMV2, unzip to a directory, and you’re ready to go! Since GEMV2 code is organized in package folders1 , there is no need to add any directories to MATLAB path. Furthermore, care has been taken so that GEMV2 depends on as few MATLAB toolboxes as possible. That said, mapping, statistics and machine learning toolbox can speed up the simulation considerably, since the “backup” functions, used in case these toolboxes are unavailable, are far slower. GEMV2 should work on any platform running recent version of MATLAB. However, because it uses package folders, it will not work with MATLAB R2007b and older without some modifications. It was tested with MATLAB R2011a, R2011b, R2012b, and R2013a under Mac OS X and Windows.
To run the simulation, go to GEMV2 root directory and type runSimulation in MATLAB command window. This will kick off the simulation by loading the script runSimulation.m, which in turn loads simSettings.m, the script that contains the default settings, including the source files for vehicle, building, and foliage outlines, propagation-related parameters, visualization options, etc.
After the simulation is finished, relevant variables related to received power, small- and large-scale variations, link types, etc., are saved in two formats:
Output files can be found in outputSim directory, located in the main GEMV2 directory. The file names are appended with current date; note that if you do not copy/rename the output files and if there were simulation runs previously that day, the output from those runs will be overwritten.
GEMV2 generates the V2V and V2I simulation output in Keyhole Markup Language (KML) format. To visualize the result, you can use Google Earth2 or NASA World Wind [2], though any tool for displaying three-dimensional virtual globe3 can be used, provided that it supports KML format.
Figure 1 shows the Google Earth visualization in terms of power, whereas Fig. 2 shows the visualization of neighborhood size (defined as the number of vehicles that the ego vehicle can communicate with directly/without multi-hop communication). If the simulation is composed of multiple time-steps, the output is an animation of all time-steps (a number of sample videos is available at http://vehicle2x.net/videos). The visualization enables easier understanding of propagation characteristics in vehicular communication. More details are available in the demo paper on visualization [3]. Note: if the output is large (large being a few hundred thousand communication pairs in total or, alternatively, a few hundred megabytes), the following can occur:
Therefore, make sure to turn the visualization off in such cases.
|
(a)
Snapshot
showing
a
part
of
transmit-receive
pairs
in
the
city
of
Porto. |
|
(b)
Street-level
view. |
Figure 3 shows GEMV2 function dependencies. The functions have been organized in package folders based on their functionality (e.g., functions for loading data are in +loadFunctions directory, functions for plotting are in +plotFunctions, etc.). Each function shown in Fig. 3 has been thoroughly commented; therefore, for a detailed description, open the containing .m file.
GEMV2 requires the following functions available at MATLAB Central File Exchange: http://www.mathworks.com/matlabcentral.
These functions are copyrighted by their respective authors and licensed under the BSD license. For convenience, they are included in the GEMV2 package in the +externalCode directory, along with their respective licenses. Some functions were modified to suit the purpose of GEMV2. Google Earth Toolbox and OpenStreetMap Functions are elaborate toolboxes with many functionalities not required by GEMV2. Therefore, the minimum set of required functions from these toolboxes is included in GEMV2 package. The original versions of functions can be downloaded from the MATLAB Central File Exchange as indicated above.
The complete GEMV2 .zip package contains the following:
The outlines of buildings and foliage are available from OpenStreetMap [5], which is the most comprehensive free geographical database. That said, the actual representation of buildings and (particularly) foliage in the OpenStreetMap can be limited, with many objects missing. You need to be judicious where you perform simulations, since a database missing a lot of buildings and foliage will likely result in unrealistic simulation output.
Buildings and foliage can be imported into MATLAB using the OpenStreetMap Functions package available at http://www.mathworks.com/matlabcentral/fileexchange/35819. A version of the package has been included with the model. It was modified to output a three-column array [objectID | Latitude | Longitude], each row representing one point of an object.
To use buildings and foliage from OpenStreetMap other than those already included in GEMV2 package, simply go to http://www.openstreetmap.org and export the objects for a desired location. Then, point the variable staticFile in simSettings.m to the downloaded .osm file. This will invoke the OpenStreetMap parser and save the processed data into an array, so that the conversion is performed only once.
If you plan to run the simulation over a large area (e.g., an entire city), follow these steps:
In practice, the input .osm file containing buildings and foliage can be up to approximately 50 MB in size. This limitation is mainly due to xml2struct function (www.mathworks.com/matlabcentral/fileexchange/28518), which requires approximately 5-10 times the size of .osm file in memory when converting the .osm file to MATLAB structure).
If you have buildings and foliage in shapefile format, to use them with GEMV2, one option is to first convert the data to OpenStreetMap format. This can be done using the shp-to-osm.jar utility available at http://wiki.openstreetmap.org/wiki/Shp-to-osm.jar (related GitHub project is located at: https://github.com/iandees/shp-to-osm/downloads). The conversion has been successfully tested with version shp-to-osm-0.8.6-jar-with-dependencies.jar (available on GitHub). Example of usage:
Once the OSM files have been generated, they can be converted to the
simulator-readable array as explained in Section 3.1.
Vehicular mobility generated by SUMO can be used as input for GEMV2. The function parseSUMOMobility.m converts SUMO XML output to a five-column array [ID | Latitude | Longitude | vehicleType | bearing], which is then converted to the three-column array [objectID | Latitude | Longitude] using the function generateVehiclePolygons.m.
First, export the vehicular mobility from SUMO by using –fcd-output option and outputting latitudes and longitudes. For example, in Windows:
Next, use SUMOMobility.xml as input to GEMV2. In terms of the size of the input SUMO mobility file, same considerations apply as in Section 3.1.
If you find GEMV2 useful in your work, please cite the following reference [1]:
Mate Boban, João Barros, and Ozan K. Tonguz: “Geometry-Based Vehicle-to-Vehicle
Channel Modeling for Large-Scale Simulation,” IEEE Transactions on Vehicular
Technology, Vol. 63, No. 9, November 2014, doi:10.1109/TVT.2014.2317803
[PDF][BIB]
If you primarily use “vehicles as obstacles” model implemented as part of GEMV2,
please cite the following reference [7]:
Mate Boban, Tiago T. V. Vinhoza, Michel Ferreira, João Barros, and Ozan K.
Tonguz, “Impact of Vehicles as Obstacles in Vehicular Ad Hoc Networks,” IEEE
Journal on Selected Areas in Communications, vol. 29, no. 1, pp. 15–28, January
2011, doi:10.1109/JSAC.2011.110103 [PDF][BIB]
Similarly, if you are primarily using the V2I propagation modeling, please cite the
following reference [8]:
Bengi Aygun, Mate Boban, Joao P. Vilela, and Alexander M. Wyglinski:
“Geometry-Based Propagation Modeling and Simulation of Vehicle-to-Infrastructure
Links”, under submission
This work was funded in part by the Portuguese Foundation for Science and Technology under grants SFRH/BD/33771/2009 and CMUPT/NGN/0052/2008.
[1] M. Boban, J. Barros, and O. Tonguz, “Geometry-based vehicle-to-vehicle channel modeling for large-scale simulation,” IEEE Transactions on Vehicular Technology, vol. PP, no. 99, pp. 1–1, 2014.
[2] D. G. Bell, F. Kuehnel, C. Maxwell, R. Kim, K. Kasraie, T. Gaskins, P. Hogan, and J. Coughlan, “NASA World Wind: Opensource GIS for mission operations,” in IEEE Aerospace Conference, 2007, pp. 1–9.
[3] M. Boban, “Demo: Visualization of vehicular communication: Insights into power, effective range, clustering, and neighborhood size,” in IEEE Vehicular Networking Conference (VNC 2014), December 2014, pp. 205–206.
[4] M. Ferreira, H. Conceição, R. Fernandes, and O. K. Tonguz, “Stereoscopic aerial photography: an alternative to model-based urban mobility approaches,” in Proceedings of the Sixth ACM International Workshop on VehiculAr Inter-NETworking (VANET 2009). ACM New York, NY, USA, 2009.
[5] M. Haklay and P. Weber, “OpenStreetMap: User-generated street maps,” IEEE Pervasive Computing, vol. 7, no. 4, pp. 12–18, 2008.
[6] D. Krajzewicz, G. Hertkorn, C. Rössel, and P. Wagner, “SUMO (simulation of urban mobility),” in Proc. of the 4th Middle East Symposium on Simulation and Modelling, 2002, pp. 183–187.
[7] M. Boban, T. T. V. Vinhoza, M. Ferreira, J. Barros, and O. K. Tonguz, “Impact of vehicles as obstacles in vehicular ad hoc networks,” IEEE Journal on Selected Areas in Communications, vol. 29, no. 1, pp. 15–28, January 2011.
[8] B. Aygun, M. Boban, J. Vilela, and A. Wyglinski, “Geometry-based propagation modeling and simulation of vehicle-to-infrastructure links,” in paper under review, 2015.
