Schematizing Maps
Design Description
Version 1.3
Doc. No.:
Schematizing maps
Design Description
Version:
1.3
Date: 2010-12-17
Revision History
Date
Version
Description
Author
2010-10-08
0.05
Initial Draft
Dominik Pavlović
2010-10-08
0.1
Revised Ch. 3
Dominik Pavlović,
Zhixiang Gao
2010-10-08
0.2
Added more description to Ch. 2
Martin Vrkljan
2010-10-08
1.0
Reviewed and adjusted the content
Pavel Chen
2010-10-09
1.1
Adis Mustedanagić
2010-11-14
1.2
2010-12-17
1.3
Renamed Ch. 4 to Ch. 5. Added Ch. 4 on
Detailed Software Design
Updated the architecture, interfaces, error
handling and algorithm description
Updated the document according to the
comments from the SCORE Preparation
Plan v1.3
Pavel Chen
Pavel Chen
Page 2
Schematizing maps
Design Description
Version:
1.3
Date: 2010-12-17
Table of Contents
1.
2.
3.
Introduction
4
1.1
1.2
1.3
1.4
Purpose of this document
Intended Audience
Scope
Definitions and acronyms
1.4.1 Definitions
1.4.2 Acronyms and abbreviations
1.5
References
4
4
4
4
4
4
4
User interfaces
5
2.1
5
Interface examples for map drawing
Software architecture
7
3.1
3.2
8
8
8
8
8
8
8
Conceptual design
System specification
3.2.1 Software specifications
3.2.2 Hardware specifications
3.2.3 Other specifications
3.3
Error handling
3.3.1 Exception handling mechanism
3.3.1.1 User input errors
3.3.1.2 Algorithm errors
3.3.1.3 Other errors
3.3.2 Error logging mechanism
4.
Detailed software design
4.1
4.2
5.
Algorithm implementation
Main software components
Approvals
8
9
9
9
9
9
10
12
Page 3
Schematizing maps
Design Description
Version:
1.3
Date: 2010-12-17
1.
Introduction
1.1
Purpose of this document
The purpose of this document is to describe the design of the product of Schematizing maps project.
1.2
Intended Audience
The audience that is going to use this document includes:
 customer – will reference this document for technical aspects of the product of Schematizing
Maps project
 project supervisor and lecturers – will evaluate solution and correctness of proposed design
 team members – will reference this document for implementation of the application
1.3
Scope
The focus of this document lays on the design of the product, along with the conceptual model of the
software architecture. The document doesn’t include the implementation code, however covers some design
decisions of the implementation.
1.4
Definitions and acronyms
1.4.1
Definitions
Keyword
Schematizing maps
Singleton pattern
Swing
1.4.2
Acronyms and abbreviations
Acronym or
abbreviation
IDE
API
GUI
MVC
JUNG
MDM
1.5
Definitions
Project name and also team name.
Software design pattern with one object instance for global access
Java library for GUI components
Definitions
Integrated development environment
Application programming interface
Graphical user interface
Model - View – Controller
Java Universal Network/Graph Framework
Application file extension
References




MVC - http://www.oracle.com/technetwork/articles/javase/mvc-136693.html
Singleton pattern - http://en.wikipedia.org/wiki/Singleton_pattern
JUNG Framework - http://jung.sourceforge.net/
“Automated Drawing of Metro Maps” by Nöllenburg M. http://i11www.iti.uni-karlsruhe.de/en/projects/geonet/mm
Page 4
Schematizing maps
Design Description
2.
Version:
1.3
Date: 2010-12-17
User interfaces
Our application will be the standalone application, so the interfaces between users and the application
will consist mostly of the windows with toolbars for drawing the schematizing map, importing different maps as
a templates upon which the schematizing map will be drawn and importing and exporting the schematized map.
The main frame of the GUI is where the user will mark the stations and draw the lines that connect those
stations. In order to provide the user with the easier way of drawing stations and lines he will have the option to
import a real map as a template upon which the schematic map can be drawn, and also the option to zoom in or
out, to get the better view of the template map, or of the sketch that he drew.
2.1
Interface examples for map drawing
The input data for the application will be input through the interfaces displayed below.
The interfaces will feature a simple menu bar, with File, Import, Application and Help menu options.
Through the File menu, the user will be able to create a new project, save/load a project and export the user's
work as an image. The Import menu option offers the user two types of background import: from an image file
on a local computer or a Google Map static image by referencing it with a link. The Help option offers the user
access to a set of help documents and information about the program. The input and output (schematic) maps are
divided into two tabs, enabling the user to easily switch between them for comparison purposes.
Figure 1: Basic panel view
The main panel to the left holds the drawing controls for the input data and the generate buttons. The
panel can be collapsed to offer a better view of the map.
The user is able to use Station and Route tools from the toolbox in order to draw an input map. The
routes can have different colors and they can be named. Stations can be renamed also and moved by dragging
them with a mouse. The input map is on a top layer above a lower layer with a background image. The drawing
process consists of selecting a one of the drawing tools and using the mouse cursor to place stations or trace
route lines that connect those stations. Stations and lines can be deleted by moving the cursor over them to call
the contextual menu and choose an option for deleting the object. Same applies to the renaming of the stations
which can be made by using the contextual menu and providing the desired name in a popup box.
Page 5
Schematizing maps
Design Description
Version:
1.3
Date: 2010-12-17
A user is also able to scroll up and down in the drawing panel to reach the areas that are beyond the
screen size region. The next figure shows a screenshot after a user has drawn some routes and stations.
Figure 2: Input map view
After a user clicks on any of generate buttons and switches the tab to Schematic map tab, he will see a
panel with white background and a generated map on top of the background as following:
Figure 3: Schematic map view
Page 6
Schematizing maps
Design Description
Version:
1.3
Date: 2010-12-17
Some user actions may cause a prompt dialog popup window to appear (e.g. when exitting the
application without saving the project, or drawing a route without starting station). This looks like the following:
Figure 4: Prompt dialog view
3.
Software architecture
The software architecture of Schematizing maps application will be a modified MVC (Model-ViewController) architecture. The view includes the GUI of the application. The model is application logic layer and
it will present schematizing maps algorithm along with two sets of entities: stations and routes. The controller is
a link between model and view.
When the user inputs the stations or routes, then the underlying map topology is modified. In case the
user clicks the schematic map generation button the controller reacts, and invokes the algorithm which provides
the modified map. After that the controller delegates that data from model to view and the user can see output.
Mediator
Controller
Property
Update
Model
Observer
View
Property
Change
User
Action
Java Swing
Figure 5: MVC Architecture of the software
Page 7
Schematizing maps
Design Description
Version:
1.3
Date: 2010-12-17
3.1
Conceptual design
The view is where the user will input data: mark the stations and draw routes of a schematic map, and
after that the algorithm reformats the map. This is where the result will be displayed for a user, so he can
validate the result, and make some additional changes if needed. The controller will take data that user inputs
and delegate it to a model. When the user clicks on generate button the algorithm will invoke, form a schematic
map from the data that user inputs, and return the result. Then the controller takes result and delegates it to view
for displaying. There is no need for a database; the final output (fully finished schematic map) of the application
can be saved to disk, which is much easier than into the database.
3.2
System specification
3.2.1
Software specifications
Software specification must conform to the following:
 Platform – Java Runtime Environment (minimal version is 1.5) must be installed in order to
run Schematizing Maps application.
 Operating system – any operating system that supports Java Virtual Machine (minimal version
is 1.5). Windows will be used as a main operating system for development and acceptance
test.
 JUNG Framework – an open source library to work with graphs and networks of objects for
handling map topology operations. This library will be supplied as a part of application
package.
3.2.2
Hardware specifications
In order to run Schematizing Maps application a PC must have the following components:
 Monitor – for display of GUI of the application
 Mouse – to support the input from a user (drawing a map)
 Keyboard – for renaming stations and routes, as well as using keyboard shortcuts for specific
commands (refer to User manual documentation)
3.2.3
Other specifications
The Internet connection must be setup for using some specific features related to Google Maps access.
Refer to the Feature List document for a full list of those features.
3.3
Error handling
3.3.1
Exception handling mechanism
It is important for a program to continue running in a normal fashion without data loss and
interruption for a user in situations when errors occur. This is handled by exception handling
mechanism which is present in the programming code. There are several types of errors that are
expected to occur. Following subsections describe those errors according to types.
3.3.1.1 User input errors
Error
Action
Placing a station on top User is not allowed to do this. The program must check for this
of another station
condition and if there is a station at a particular point already, then
no more stations will be added after a click
I/O errors on importing User is notified by an error message, importing / exporting are
background
image, aborted and user is returned to the original state before he tried to
exporting schema map import / export. The same applies to saving the project files.
and saving project files
Starting a route on a User will be notified that it is not possible.
place other than station
Page 8
Schematizing maps
Design Description
Version:
1.3
Date: 2010-12-17
3.3.1.2 Algorithm errors
Error
Algorithm errors
Action
If the algorithm fails to generate the map, the user will be notified
and prompted for retry with suggested parameters.
3.3.1.3 Other errors
Error
Action
No connection to The user should be notified that there is a connection problem, and
Google Maps server
suggested to verify that PC is connected to the Internet and a
firewall doesn’t block traffic
3.3.2
Error logging mechanism
The program will log the occurred errors to a file (name and extension of a file are arbitrary)
which is stored in a root directory where the program executable is located. Date and time of when the
error has occurred and the block where it occurred are recorded in the log file as well. In addition all
logging events are replicated to the system console. There are several levels of error importance, which
also have to be recorded in the file:
 SEVERE – when user input or algorithm errors occur
 MEDIUM – when other errors occur
4.
Detailed software design
4.1
Algorithm implementation
Before deciding how to solve the problem of drawing a schematic map, it's important to clarify which
kind of problem is presented. Other studies (namely “Automated Drawing of Metro Maps” by Dr. Martin
Nöllenburg) have effectively proven that the problem faced is NP-complete. The proof shows that drawing an
octi-linear metro map is a problem equivalent to the 3-SAT problem, which is a well-known NP-complete
problem. The mathematics behind the proof will be omitted here.
Having established that the problem presented is NP-complete, we will not attempt to solve it, simply
because there is no yet any solution available for any of the NP-complete problems, but instead, the solution will
be based on some approximation (heuristic) algorithm.
The study by Dr. Nöllenburg proposes the problem to be solved by a method known as Mixed-integer
programming. This method is used when the problem can be reduced to a set of integers, with a subset of those
unknown. This method is often used to solve problems like SAT problems, and as such, will be one of the
methods of choice for solving the current problem (which is equivalent to the 3-SAT problem).
If the above option is not suitable due to time constraints, or other reasons such as availability of the
technical tools, then we will work on our own algorithm. The algorithm will be based on the concept of
weighing and adjusting the stations on a two-dimensional grid by aligning them to the nearest grid junctions and
calculating distance based on neighboring stations. The process of adjusting stations coordinates is based on two
parameters: granularity and bandwidth, which are also controlled by a user for advanced schematic map
generation.
Granularity defines the shortest distance between any two junction points on a two-dimensional grid;
hence the distance between any two stations can’t be shorter than a value of granularity.
A bandwidth is a width of a sweeping band within which the algorithm adjusts the stations to new
locations. A junction point is located in the middle of the specified slot, so when the algorithm iteration reaches
a horizontal band, then it will adjust station Y coordinate, and X coordinate when it reaches a vertical band.
Bandwidth is measured in number of slots of a grid (horizontal or vertical slots).
Page 9
Schematizing maps
Design Description
Version:
1.3
Date: 2010-12-17
The effects of two above parameters are as following:
Parameter/value
Granularity
Bandwidth
Lower
Less station movements
Less stations overlap
Higher
Greater distance
Better routes angle
4.2
Main software components
In implementation of the described architecture we rely on the singleton pattern design. For this
purpose we have identified several components which will serve for handling input, map generation and output
operations. The data flow among those components can be seen in the diagram below:
DrawingManager
GraphController
GraphManager
OutputManager
OutputGraphManager
GraphProcessor
Figure 6: Data flow of schematic map generation
All of the components above, except Algorithm, conform to the singleton pattern design. The
application has exactly one copy of each of them. By following this pattern, it will allow us to access commonly
used components in the application in an easier manner and manage the logic with less impacts on the whole
application. The following is a brief description of the purposes of those components:
 DrawingManager – defines visual settings of a map: routes and stations color, shape, and width
 GraphController – handles all the modifications of the maps
 GraphManager – contains the input map and related data
 GraphProcessor – processes the input map and provides the schematized map as output
 OutputGraphManager – contains the output map
 OutputManager – defines the visual settings of the output map
In order to accept input from a user and display output schematic map, there are two components called
SmDrawingPanel and SmOutputPanel. They extend JPanel class of Java Swing library, and contain GUI
components for displaying maps. DrawingManager and OutputManager refresh these components depending on
a user action.
SmBasicToolBox represents the toolbox on the left hand side of the window and contains various
controls for corresponding tools and actions for a user. It extends class SmToolBox. SmAdvancedToolBox is an
advanced version of a toolbox; however it might not be implemented due to time constraints.
There are several other models defined which are:
 Edge and Vertex – represent edges (route sections) and vertices (stations) of a graph
 Route – represents a route in a graph and associated with edges and vertices
 ToolMode and GenerateMode – enumerations for tools and types of map generations
 VertexFactory and VertexType – define how vertices are created
 MdmFile – represents a custom file to be used for reading and writing .MDM files to a file system
Page 10
Schematizing maps
Design Description
Version:
1.3
Date: 2010-12-17
Below are sequence diagrams for drawing and generating a map:
DrawingManager
GraphController
GraphManager
Add station or route object
Pass the object properties
Modify the graph
Figure 7: Stations and routes drawing sequence
GraphController
GraphManager
GraphProcessor
Generate graph
Get the graph object
Return the graph
Pass the graph copy to produce schematic map
Provide the schematic map
Display graph
Figure 8: Graph generation sequence
Page 11
Schematizing maps
Design Description
5.
Version:
1.3
Date: 2010-12-17
Approvals
Name
Title
Date
yyyy-mm-dd
Signature
Page 12