Skip to content

By The Way User Manual

Jump to bottom
orelkan edited this page Jun 26, 2018 · 36 revisions
Table of Contents

Table of Contents
By The Way User manual
Instalation Instructions
Activating BTW
The program's user interface

By The Way - User manual

By The Way is a program made in order to examine the effectiveness of different traffic lights control algorithms over a desired map. The program enables to simulate a city traffic in real or in a speedup time. User can choose to create a new map or to insert an existing map to the simulator. While simulation is running, the program writes to a log. After running the simulation, the user can open the log and analyze the system's behavior. To control the program, the user will have to go through its interface. We will now explain how to operate the system and exploit the different options the program offers.

Instalation Instructions:

Activating BTW:

In the IDE, in the project explorer, go to the java file in the path: BTW-Project/BTW-Application/src/main/java/il/ac/Technion/cs/yp/btw/app/BTW.java In the line of the class declaration of BTW click the little green play button, and then choose "Run 'BTW.main()'". these instructions are also appear in the instalation instructions page

The program user interface:

"Choose Running Configuration" screen:

when activating BTW, the first screen you will encounter is the "Choose Running Configuration" screen. In this screen you have five options to choose from:

  1. "Map From DB": the user writes a name of a map that is already exists in the data base. Which means he has created it or loaded it from a file and saved it to the data base in the past. As the user writes the map's name, a scroll bar will open with suggested maps, according to the name he has typed so far. The user can use the Up and Down keyboard keys to navigate in the scroll bar and Enter to choose map. he can also scroll and click on the map name with the mouse. this map insertion is only valid for the "Learning mode" and "Compare Different Algorithms" options. The other options get their maps in other screens.
  2. Learning Mode: The learning mode enables the user to run a long simulation and apply machine learning methods on it. by clicking the "Start Learning" button, the user will be moved to the "Verify Map" screen. If the user will accept the map he will go the "Learning" screen.
  3. "Compare Different Algorithms": by clicking the "Compare" button under "Compare Different Algorithms", the user chooses to make a comparison between two behavior setups on the same map. After choosing a map from the database and clicking the "compare" button, the user is moved to the "Verify Map" screen. If the user accepts the map, then he is moved to the "Choose Simulations" screen.
  4. Live Simulation: by clicking the "Start Simulation" button under "Live Simulation" the user chooses to simulate a map in a real time. That gives the user the ability to see the map's behavior and inspect it while the traffic is running. Clicking on this button will move us to a screen called "Choose Map".
  5. Prepare Map and Vehicles Config: this option enables the user to prepare before running the simulation. By clicking the "Prepare" button the program will move the user to the "Prepare Map and Vehicles Config" screen.

"Choose Map" screen:

This screen allows the user to choose which map he wants to run his simulation on. There are three different options suggested:

  1. "Load Map From DB": in case the user has created a map in the past and saved it to the data base, he can choose to open again the same map. All the user has to do is to click the "Insert Map Name" bar and type the map's name. While typing, a scroll window will open under the bar, suggesting all the maps in the data base which their name contains the sequence that was typed so far. The user will have to choose the wanted map and then click on the "Load" button under the "Insert Map Name" bar.
  2. "Insert Map URL": if the user has a map saved on his local computer as a geoJson file in our specific format (will be described later) he can load it to the simulation. The user has two options for providing the path. The first option is to click the "Insert Map URL" bar and type the full path to his file. The second option is to click the button with the paper clip icon located right to the "Insert Map URL" bar. When clicking on this icon a browser window will be opened. The user can then browse his computer and choose the map file. After choosing the geoJson file (using either of the possible options) the user will click the "Load File" button located under the "Insert Map URL" bar. Then the map will be loaded to the simulation.
  3. "Generate New Map": if the user does not have a previous generated map, he can choose to randomize a new one. Providing the right parameters to the map will be explained later. Choosing this alternative, there are two kinds of maps the user can choose from. Using the radio button, the user can choose between "Grid Road" and "Free Form". "Grid Road" is a map with only horizontal and vertical roads, as appropriate to the USA model. Marking this option in the radio button will advance the user to the "Generate Grid City" screen. The second option in the radio button is the "Free Form". This option will generate a map in the European Voronoi model. Marking this option will advance the user to "Generate Free Form City" screen. When the user has marked his wished map kind, all that left is to click the "Generate" button under the radio button. Than he will move to the "Verify Map" screen. If the user will accept the map he will be moved to one of the screens previously described in this section.
  4. Back: if the user wants to go back to the "Choose Running Configuration" screen he will click on the "Back" button in the upper right corner of the screen.

"Generate Grid City" screen:

In this screen the user will have to insert the parameters that will be used to randomize a new map of the grid kind. This model is common in USA cities. A grid map is a map contains only horizontal streets and vertical avenues. There are five optional parameters to insert. For each parameter there is an info button, a toggle button and a values bar. If the toggle is off, the values bar is marked gray and the default value will be chosen for this parameter. If the toggle is on, the values bar is marked black and the user will have to provide a value for this parameter. Before typing a value in it, the value bar presents its legal domain of values. To insert a value, click the values bar and type a value from the parameter's legal domain. If the user needs more information about a parameter, he can click the info button (the one with the question mark icon) on its left. When clicking the info button, an information window will pop up explaining what this parameter purpose is and how to use it. When finished to read the pop-up window, the user will have to close it either with the "OK" button on its right down corner, or with the "x" button on its right up corner. The user cannot continue to use the program until the info pop-up window is closed. The parameters to configure a map are:

  1. "Number Of Streets": this is the number of horizontal streets the user wants to have on the map. The parameter's legal values domain is 2-50 streets.
  2. Number Of Avenues: this is the number of vertical avenues the user wants to have on the map. The parameter's legal values domain is 2-50.
  3. Length Of Streets: this is the length of each horizontal street on the map. The parameter's legal values domain is 100-2000 meters.
  4. Length Of Avenues: this is the length of each vertical avenue on the map. The parameter's legal values domain is 100-2000 meters.
  5. Name Of map In Data Base: this name will be given to the map if the user will decide to save it to the data base. The Name must be alphanumeric and without spaces. There is an input check for every argument value inserted by the user. When clicking the "Generate" button with illegal input values, an alert window will pop up detailing all the invalid parameters. The user cannot continue until he closes this alert either with the "OK" button on its right down corner or with the "x" button on its right up corner. Then the user has a second chance to correct the values and try to generate the map again.

After finishing to set all parameters the user needs to click the "Generate" button which will start the map generation process. While the map is being generated there is an animation of a spinning wheel. When the generation is done, the user is moved to the next screen called "Verify Map" screen. if the user accept the map he will be moved to the "Choose Simulation" screen.

"Generate Free Form City" screen:

In this screen the user will have to insert the parameters allow him to randomize a new map of the free form kind. A free form map is a map built from a collection of blocks containing several streets and avenues, not necessarily horizontal or vertical. This is called the Voronoi model and it is common in European old cities. There are three optional parameters to insert. For each parameter there is an info button, a toggle button and a values bar. If the toggle is off, the values bar is marked gray and the default value will be chosen for this parameter. If the toggle is on, the values bar is marked black and the user will have to provide a value for this parameter. Before typing a value in it, the value bar presents its legal domain of values. To insert a value, click the values bar and type a value from the parameter's legal domain. If the user needs more information about a parameter, he can click the info button (the one with the question mark icon) on its left. When clicking the info button, an information window will pop up explaining what this parameter purpose is and how to use it. When finished to read the pop-up window, the user will have to close it either with the "OK" button on its right down corner, or with the "x" button on its right up corner. The user cannot continue to use the program until the info pop up window is closed.

The parameters to configure a map are:

  1. Maximum Number Of Blocks: the number of blocks the user wants to have on the map. The parameter's legal values domain is 30-250.
  2. Radius: the map is built within a circle. This parameter represents that circle's radius. The parameter's legal values domain is 2000-7000 meters.
  3. Name Of map In Data Base: this name will be given to the map if the user will decide to save it to the data base. The Name must be alphanumeric and without spaces. There is an input check for every argument value inserted by the user. When clicking the "Generate" button with illegal input values, an alert window will pop up detailing all the invalid parameters. The user cannot continue until he closes this alert either with the "OK" button on its right down corner or with the "x" button on its right up corner. Then the user has a second chance to correct the values and try again to generate the map.

After finishing to set all parameters the user needs to click the "Generate" button which will start the map generation process. While the map is being generated there is an animation of a spinning wheel. When the generation is done, the user is moved to the next screen called "Verify Map" screen. if the user accept the map he will be moved to the "Choose Simulation" screen.

"Verify Map" screen:

the user gets to this screen after the map was generated or loaded to our program. Here the Map is being presented so he can have an impression whether he likes it or wants another one. The user can scroll with the mouse on the map to zoom in and out. The zoom is done on the location of the mouse on the map. The user can also drag the map to all directions. If the user is satisfied with the map he can click the "Accept Map" button and go to the next screen. If the user does not want to work with the presented map he can click the "Home" button icon on the right up corner and go back to the "Choose Running Configuration" screen.

"Choose Simulation" screen:

In this screen the user gets to choose all three elements effecting the simulation behavior. The simulation's behavior consists of: the vehicle movements, the traffic light manager algorithm and the navigator manager algorithm. The parameters to configure a simulation behavior are:

  1. Choose Vehicle File: this parameter is optional. It allows the user to insert vehicles from a json file in our vehicles geoJson format and let them drive on the map. Every vehicle has a source, a destination and a start time. The user can add the vehicle file either by writing in the "insert file URL" bar the path to the file, or by clicking the brows button (the paper clip icon) and choose his vehicles file.
  2. Choose Traffic Light Manager: here the user chooses the behavior of the traffic lights in the simulation by using a radio button. The options are:
    • Naive Manager: for every crossroad it will iterate its roads. for every road in the crossroad it will open its traffic lights for a constant time and then close them and go the next road.
    • Simple Manager: works just like the Naïve manager. But if a road does not have cars on it, it does not open it.
    • Smart Manager: every crossroad is an individual unit. Every cross road calculates its overload by the overloads of its roads. Every road calculates its overload by the amount and state of the vehicles on it. The lights switching is done according to the current overload on the roads. algorithm described in the wiki page "Smart Algorithm".
  3. Choose Navigation Manager: choose how the cars will navigate on the map from their source to their destination by using a radio button. The options are:
    • Naïve Navigation: when a vehicle starts its journey, the navigator will plan its rout using the A* algorithm. The rout will stay the same until the vehicle will arrive the destination.
    • Statistics Navigation: calculate the vehicles rout at the start of the journey, also with A* algorithm. occasionally, check for a better rout. If found the rout is changed to the better one When finished to set the behavior parameters click the "Start!" button to start the simulation.

The Simulation Running Screen:

in this screen the user will run the simulation on the map and will see how it behaves over time. To run the simulation, click the play button at the top right of the screen. At the top of the screen there are the control buttons which are:

  1. Choose Vehicles To Add: when clicking this button, a new button appears called "Add Vehicles" and a bar is opened just under it. In this bar you can choose how many vehicles you want to add to the map. The legal values domain here is 1-200. After writing the number of vehicle to add, the user need to press the "Add vehicle" button. After clicking "Add vehicles" the bar disappear, and the "Add Vehicles" button becomes "Adding…" button. The "Adding…" button will become again "Choose Vehicles To Add" button when all vehicle was added to the simulation. The user can use this button several times. For every click on the "Add vehicle" button a new group of vehicles will be added to drive on the map. All the vehicles in the same group starts with the same source destination and rout. Vehicles from the same group starts to drive in separated time intervals, which means every few seconds another one of them leaving from source to destination.
  2. Clock: show how match time passed in the simulation. Can be played, paused and fast forward. The clock shows the time ticks every two seconds. It shows hours, minutes and seconds.
  3. Fast forward button: this icon is located right to the clock, with a shape of an arrow that points right. When clicking on it, the simulation skips ahead ten seconds. To use it, the simulation must be paused. the user cannot click it while the simulation is playing.
  4. Play button: this icon is located right to the fast-forward icon. When clicking on it the simulation is playing real time, and the button becomes a pause button (with a pause icon).
  5. Home button: this button has a home icon and located right to the play button. Clicking it move the user to to "Choose Running Configuration" screen.

At the button of this screen there is the map itself. the user can scroll on the map to zoom in and out. The zoom will be done on the location of the map. The map can also be dragged to all directions. The user can see on the map all the roads and the traffic lights. The roads' colors are changed according to the number of vehicles on the roads. A road with no vehicles will be colored in black. A road with a small number of vehicles will be green. When we pass a vehicles number threshold the road becomes yellow. The next threshold is orange and the highest threshold on road is colored in red. When clicking on a road a "Real Time Statistics" window pops up describing the road's state. This window show:

  1. Number of Vehicles
  2. Average speed (km/h)
  3. Length (meters)

"Choose Simulations" screen:

this screen allows the user to compare different behaviors on a chosen map, and later look on their statistics. the user needs to choose the following three parameters:

  1. "Choose vehicles config": There's a radio button that lets the user choose if he wants to input a vehicle file or generate new vehicle entries. If he chose the file option, the user needs to insert a vehicle file in the vehicles geoJson format we have defined. The user can insert the file either by typing the path to "Insert file URL" bar or by clicking the brows button (paper clip icon) and choose the file from the browser. If he chose the generate option he needs to insert a valid number of vehicles to generate (2-10000)
  2. "First Configuration"
  3. "Second Configuration" the first and second configurations has the same structure. In each of them the user needs to configure the behavior by choosing a traffic light manager and a navigation manager. Each of the managers has a radio button.
Choose Traffic Light Manager:

here the user chooses the behavior of the traffic lights in the simulation by using a radio button. The options are:

  • Naive Manager: for every crossroad it will iterate its roads. for every road in the crossroad it will open its traffic lights for a constant time and then close them and go to the next road.
  • Simple Manager: works just like the Naïve manager. But if a road does not have cars on it, it does not open it.
  • Smart Manager: every crossroad is an individual unit. Every cross road calculates its overload by the overloads of its roads. Every road calculates its overload by the amount and state of the vehicles on it. The lights switching is done according to the current overload on the roads. algorithm described in the wiki page "Smart Algorithm".
Choose Navigation Manager:

choose how the cars will navigate on the map from their source to their destination by using a radio button. The options are:

  • Naïve Navigation: when a vehicle starts its journey, the navigator will plan its rout using the A* algorithm. The rout will stay the same until the vehicle will arrive the destination.
  • Statistics Navigation: calculate the vehicles rout at the start of the journey, occasionally, check for a better rout. If found the rout is changed to the better one.

When finishing to choose vehicle file and all the configurations, the user needs to click the "Start!" button on the right down corner of the screen. Now both simulations will run faster then real time. While they are running the user will see an animation of a spinning wheel. When they finish the user will move to the "Statistics Comparison" screen.

"Statistics Comparison" screen:

in this screen we will see a table that compares between the two behaviors we chose in the "Choose Simulations" screen.

The columns of this tables are:
  1. first configuration behavior: the behavior the user chose for the first configuration.
  2. second configuration behavior: the behavior the user chose for the second configuration.
  3. Diff: the difference between the two behaviors.
  4. Percent: the difference between the two behaviors in percentages.
The rows of the tables are:

  1. Driving Time for Vehicle: the time the vehicle was moving on the roads of the map not including the time it was waiting on closed traffic lights.

  2. Waiting Time: the time the vehicle was waiting for traffic lights to open.

  3. Driving Time on Road: the time that a road had vehicles driving on it. every row in the table has two sub-rows:

    • Avg. which represents the average for each row
    • Empty sub-row, where there will be a list of objects that took part of the simulation and the user can choose from. in "Driving Time for Vehicle" the user will choose vehicle, in "Driving Time on Road" the user will choose road.

"Prepare Map and Vehicle Config" screen:

this screen allows the user to prepare the files and data base before running a simulation. The screen offers three options:

  1. "Create Vehicles File": if the user wants to create a new vehicles file, then he can choose the map that the vehicles will drive on and create vehicles file for that map in our json format. To create the map the user will have to fill all the following parameters:

    • Heavy Traffic Hours: there are two bars with a clock icon next to them. The left bar is the heavy traffic start time, and the right one is the end time. To decide the hours the user can either type the time he wants in the bar or click the clock icons. When clicking on a clock icon a widget of a clock will open. On its title there is the chosen time and on the bottom there is a drawing of a clock. To choose the hour, the user click the hour in the title (left side of the colon) and then mark on the clock the hour he wants (am hours in the outer circle and pm hours in the inner circle). To choose the minutes, the user needs to click the minutes on the title (right side of the colon) and then mark on the clock the minutes he wants. When finished, the user needs to click outside of the clock widget. The widget will be closed and the chosen time will appear in the matching bar.
    • Number of Vehicles: the number of vehicles we want to save in our file. the leagal values domain here is 2-10000.
    • DB Map Name: To choose the map, the user will click on the bar and then type the map name. the map must be in the data base. While typing, a scroll bar will be opened to suggest all the maps that match what the user has typed so far. The user can finish typing or choose from the suggested maps in the scroll bar.
    • Insert Vehicle File URL: here the user will provide a path to save the file. He can do it either by typing the path in the bar, or by clicking the paper clip icon, open the browser and choose it from there.
    • After the user chose the all the parameters, all he has to do is to click the "Generate Vehicles" button and the file will be created.

  2. "Save Map From File": this option allows the user to take a map from a file in our geoJson format, and upload it to the data base. In the "Name In Data Base" bar, the user will type the name he wants the map to have in the data base. To add the geoJson file the user can either type the path to the file, or click the brows button (paper clip icon) and choose the file in the browser. Then the user will click the "Load File" button to upload the map to the data base.

  3. "Generate New Map": this allows the user to randomize a new map. if the user does not have a previous generated map, he can choose to randomize a new one. Providing the right parameters to the map will be explained later. Choosing this alternative, there are two kinds of maps the user can choose from. Using the radio button, the user can choose between "Grid Road" and "Free Form". "Grid Road" is a map with only horizontal and vertical roads, as appropriate to the USA model. Marking this option in the radio button will advance the user to the "Generate Grid City" screen. The second option in the radio button is the "Free Form". This option will generate a map in the European Voronoi model. Marking this option will advance the user to "Generate Free Form City" screen. When the user has marked his wished map kind, all that left is to click the "Generate Map" button under the radio button. Than he will move to one of the screens previously described in this section.

  4. "Back": the back button takes the user back to the "Choose Running Configuration" screen.

"Learning" screen:

this screen allows the user to apply machine learning methods on a map from the data base. Before activating the machine learning mode, the user will have to configure the following parameters:

  1. Choose Unit For Learning Mode: the user will have to define the time unit the learning mode will use. There is a radio button allow us to choose the time unit and the options are: • Days • Weeks • Months
  2. Insert Duration: the amount of the time units the user learning mode will exploit.there is an info icon next to it specifying the legal values.
  3. Choose Numbers of Vehicles To Simulate: the user will insert the Number of vehicles he wants the learning algorithm to run with on the current simulation.
  4. Start Learning: after the user is done configuring all the parameters he will click the "Start Learning" button to activate the learning mode simulation. while the learning is running, there is an animation of a spinning wheel. when the learning process is over, the animation disappears. after the learning is done, all the produced information is saved to the data base.
  5. "Back": the back button takes the user back to the "Choose Running Configuration" screen.

The GeoJsom Map Format:

The map is written in a GeoJson format, which has been costumed to the needs of the system. This format was chosen due its ease of use and the adjustments were made in order to properly maintain the components and characteristics of the map. The map consists of roads, traffic lights, intersections, and streets (which can hold several roads), with roads and streets represented by line objects, and traffic lights and crossroads represented by point objects. Features and assumptions of each of the existing objects in the system:

  • Road type object: A road is defined by a name, length (in meters) ,overload on the road and a source node and a destination node, where each node is defined by x and y coordinates.
  • Traffic light type object: A traffic light is defined by name, x and y coordinates, length (in meters) and overload on the road.

Assumption: The name of a traffic light is int the format : form ... to ... When in the first place where the blanks are placed, the road from which you turn at the traffic light need to be placed, and in the second place the road to which you pass need to be placed.

  • Crossroad type object: A traffic light is defined by name, x and y coordinates.
  • Street type object: Street is defined by a name and a string of roads' names contained in it (chained in a string).

Restrictions: In the state of construction of a map using generation, street length can be at most 2000m.

The GeoJsom Vehicles File Format:

Vehicles File decribes helps us define part of the configuration of a simulation, by defining vehicles to be added in the simulation, in the scope of one day (24 hours, from 00:00:00 until 23:59:59), including source, destination, and time the vehicle starts to drive, with the following parameters:

  • sourceRoad - Json string with the source road's name
  • sourceRatio - The part of the road the vehicle is statring from, has to be between 0.0 to 1.0.
  • destinationRoad - Json string with the destination road's name
  • destinationRatio - The part of the road the vehicle is going to, has to be between 0.0 to 1.0.
  • timeOfDrivingStart - Json string in the following format: "HH:MM:SS", which desribes the exact time of the day the vehicle starts to drive from his source, to his destination. The file is of a Json format, and all of the vehicles are in a Json array, according to the following structure: [ { "sourceRoad": "source road name", "sourceRatio": 0.0, "destinationRoad": "destination road name", "destinationRatio": 1.0, "timeOfDrivingStart": "HH:MM:SS" }, ... { "sourceRoad": "source road name", "sourceRatio": 0.0, "destinationRoad": "destination road name", "destinationRatio": 1.0, "timeOfDrivingStart": "HH:MM:SS" } ]

footer

Table of Contents
By The Way User manual
Instalation Instructions
Activating BTW
The program's user interface

Clone this wiki locally