Académique Documents
Professionnel Documents
Culture Documents
Manual
Jungyul Cho, Kurt Mueller, Ka Long Ng, Weston Turner, and Hang Xu
CIS 422/522
3/4/2011
Contents
1
Introduction
2 System requirements
2.1 Functional requirements
2.2 Performance requirements
2.3 Interface requirements
2.4 Operational requirements
2.5 Resource requirements
2.6 Documentation requirements
3 System architecture and design
3.1 Technical design goals
3.1.1 Ease of use
3.1.2 Performance
3.1.3 Accuracy
3.1.4 Maintainability and extensibility
3.1.5 Reliability and fault tolerance
3.2 High-level architecture description
3.3 Architecture component details
3.3.1 GPX/KML Parser
3.3.2 Track path / URL Builder
3.3.3 Web Interface
3.3.4 Fiducial Strategy
3.3.5 Location Parser
3.3.6 Cache
3.3.7 Directions Generator
3.3.8 CSV/HTML Writer
3.3.9 User Interface
3.3.10
File Input and Output
3.3.11
HTTP requests and responses
3.4 Cross-platform compatibility
4
Build support
1 Introduction
The purpose of this document is to describe the technical aspects of
the Pathfinder software project, created by Jungyul Cho, Kurt Mueller,
Ka Long Ng, Weston Turner, and Hang Xu for Michal Youngs CIS
422/522 class in Winter Quarter, 2011. Pathfinder assists cyclists in
creating cue sheets (lists of turn-by-turn directions) from GPS track
recordings, to enable sharing routes with other cyclists.
2 System requirements
2.1 Functional requirements
The program takes as input a file containing position coordinates
accumulated by a GPS receiver during a bicycle ride. A standard format
for such files is called GPX, for GPs eXchange. The program will also
accept KML format files; GPX will be used to refer to both GPX and
KML files in this manual. From the GPX file input, which is simply a
sequence of latitude/longitude points on a path, the program identifies
streets traveled and turns made along the path and outputs a list of
turn-by-turn directions with street names, distances between turns,
and turn directions at each junction. This cue sheet can be saved as a
comma separated values (CSV) file.
Additionally, the program should display a map of the riders path. In a
future revision the program should allow the user to mark and label
arbitrary points of interest along the path, which will be integrated into
the cue sheet.
Ease of use
3.1.2
Performance
3.1.3
Accuracy
The program may not be completely accurate for all possible rides, but
it should be reasonably accurate for rides of moderate length (up to
200 miles), and it provides a mechanism for users to remove
inaccurate turn information from generated results. Accuracy can be
improved by increasing the number of lat/long points processed and
decreasing the minimum distance between adjacent points, at the
expense of performance.
3.1.4
3.1.5
3.3.1
GPX/KML Parser
This module accepts as input an XML file containing data in GPX or KML
format. It parses the file to create Waypoint objects, each of which
contains the lat/long coordinates of a point along the path described by
the set of points in the file. The waypoints are stored in a TrackPath
object.
Note that Pathfinder only works with simple KML files, in which all the
geographic coordinates are contained within a single
<coordinates></coordinates> tag, like so:
<coordinates>
-113.061720,37.677350,1782.000
-113.062320,37.667740,1814.400
-113.079700,37.653970,1828.800
</coordinates>
The KML file format supports very complicated structures, and parsing
arbitrarily nested and named structures is beyond the scope of this
program.
3.3.2
3.3.3
Web Interface
3.3.4
Fiducial Strategy
depicting the route. The map image contains start and finish markers,
which the Fiducial Strategy locates on the map image. Since the
program knows where to expect the markers (because it requested
they be included in the map), once they are identified then they can
serve as anchor points for overlaying a coordinate system on the
image in the UI. Mouse pointer movement is tracked in the UI, with
pointer coordinates displayed in the status bar along the bottom edge
of the screen. Having the ability to track mouse movement over an
image and obtain coordinates of the mouse pointer will allow future
map interactivity, including adding arbitrary waypoints along the route
and obtaining their approximate addresses through reverse geocoding.
3.3.5
Location Parser
3.3.6
Cache
This module manages a cache data structure that is read from disk
upon program start (if a cache file exists) and is consulted before each
reverse geocode request to determine if the waypoint in question has
been processed previously. Newly-retrieved reverse geocode results
are inserted into the cache, which is written to disk upon program exit.
In addition, map images retrieved for display in the Turn Inspector (see
section 3.3.9) are cached for subsequent use.
3.3.7
Directions Generator
This module uses the list of waypoints with attached street addresses
and street names to determine individual route segments, where a
segment is a subsection of the route along a single street. It
determines the location of junctions between segments and calculates
the turn direction at each junction, generating a turn-by-turn list
detailing street names and lengths of each segment and turn
instructions at each junction. This list is a cue sheet.
3.3.8
CSV/HTML Writer
3.3.9
User Interface
This provides the map display for the route, as well as a panel for the
list of calculated turn-by-turn directions (i.e., the cue sheet), and a
smaller map display that shows individual turns along the route (known
as the Turn Inspector). The Turn Inspector provides buttons to jump
forward and backward between turns in the cue sheet, and it highlights
the cue sheet text corresponding to the displayed turn as the forward
and back buttons are pressed. It also provides a button to delete the
displayed turn from the cue sheet in case the user decides that the
turn is not necessary or desired.
The user may click on an individual turn in the Directions list to see
that turn displayed in the Turn Inspector.
The turn that is displayed in the Turn Inspector is also highlighted on
the main map by a set of red dots connected by a thin red line.
The user may double-click anywhere on the main map to add a Point of
Interest (POI) to the map, and provide the POI with a name and short
description. POIs are displayed in the Directions list and on the main
map, and may be edited like a turn.
The user may view an Elevation Profile graph for the current route by
selecting the Elevation Profile Display menu.
The user interface is constructed using the Windows Forms framework.
3.3.10
The program interacts with the local file system when reading input
files, reading and writing cache files, and writing output CSV, HTML,
and BMP files.
3.3.11
The program requests image maps via HTTP from the Google Maps
service for the overall route as well as for individual turns. It also
requests reverse geocode results via HTTP from Googles reverse
geocoding service, or an alternate service if necessary.
4 Build support
Because the program is developed using Microsofts Visual Studio
environment, the source code is distributed with accompanying files to
enable easy integration and building in that environment. The
Pathfinder.sln file is a Solution file, which organizes the project
contents. This file is not user-editable; changes made in the
development environment are saved to this file automatically.
To build the program in Visual Studio (or in Mono Develop), unzip the
source tree and open the Pathfinder.sln file. This will make the project
available in the development environment. Click the Run menu item or
button to compile and run the program.
The Pathfinder.suo is a Solution User Options file for the project. Like
the Pathfinder.sln file, it is not user-editable. Likewise, the
Pathfinder.userprefs file is not directly editable; it will reflect changes
made in the development environment.
The PathfinderDoxyfile contains configuration information for building
detailed technical documentation using the Doxygen documentation
tool. See section 5 for details and instructions.
7) Copy to clipboard.
D. Exit dialog box
1) Click on Exit dialog box.
2. Options dialog box
A. Click on Options dialog box.
B. Units dialog box
1) Click on Units dialog box to check next list of menu
comes up.
2) Click on Meters and check appropriate changes
appear on Ride Map, Direction textbox, and Turn
Inspector area.
3) Click on Kilometers and check appropriate changes
appear on Ride Map, Direction textbox, and Turn
Inspector area.
4) Click on Miles and check appropriate changes appear
on Ride Map, Direction textbox, and Turn Inspector
area.
C. Map Type dialog box
1) Click on Map Type dialog box and check next list of
menu comes up.
2) Click on Roadmap dialog box and ensure appropriate
changes appear on Ride Map, and Turn Inspector area.
3) Click on Satellite dialog box and ensure appropriate
changes appear on Ride Map, and Turn Inspector area.
4) Click on Terrain dialog box and ensure appropriate
changes appear on Ride Map, and Turn Inspector area.
5) Click on Hybrid dialog box and ensure appropriate
changes appear on Ride Map, and Turn Inspector area.
D. Path Resolution dialog box
1) Click on Path Resolution dialog box and check next list
of menu comes up.
2) Click on 10m dialog box and ensure appropriate
changes appear on Ride Map, and Turn Inspector area.
3) Click on 15m dialog box and ensure appropriate
changes appear on Ride Map, and Turn Inspector area.
4) Click on 20m dialog box and ensure appropriate
changes appear on Ride Map, and Turn Inspector area.
5) Click on 30m dialog box and ensure appropriate
changes appear on Ride Map, and Turn Inspector area.
E. Geocode Points dialog box
1) Click on Geocode Points dialog box and check next list
of menu comes up.
2) Click on one Geocode Point, open up new file and
change Geocode Point to another.
7. KML file.
A. Perform steps 1. To 5. with a KML file, rather than a GPX file.
8. Point Of Interest
A. Test adding POI while file is opening.
B. Test adding POI after file is properly opened.
C. Perform steps 2., and 4. after POI is inserted.
9. View Elevation Profile
A. Test View Elevation Profile before open the file.
B. Test View Elevation Profile after opening the file.
C. Test View Elevation Profile after adding a POI.
D. Test View Elevation Profile after removing an existing POI.
10. Operating system.
A. Linux
- Open the application
B. Window XP
- Open the application
C. Linux
- Open the application
D. Linux
- Open the application
E. Linux
- Open the application
5.2.1
ChangedAlphbetLongLatitude.gpx
In this file some of the longitude and latitude values have been
changed to letters. This is to simulate corrupt GPS data. It should
display an error message to the user. The result is, No locations,
check your input .gpx file.
Empty.gpx
This file contains no text inside. The program should do nothing and
display an error message. The program displays, No locations, check
your input .gpx file.
NoTagGPS.gpx
This simulates a file in which there is valid XML but missing longitude
or latitude tags. The program in this situation should display an error
message. The result from the program is, No locations, check your
input .gpx file.
TextOnly.gpx
This simulates a file that doesnt have any XML syntax. It only contains
plain text. The program should not run the .gpx file since it doesnt
have any data. The result is, No locations, check your input .gpx file.
XmlFileWithGPSTracking.gpx
This file contains XML type syntax with GPS data inside, but with the
tags out of order. The program should do nothing and display error
message. The result from program is, No location, check the input
.gpx file.
XmlTypeFile.gpx
This file contains XML but no GPX tags. The program should display an
error message. The result is, No location, check your input .gpx file.
Empty.kml
This file contains no text inside. The program should do nothing and
display an error message. The program will display Parsing error,
cannot read input file.
Error_data.kml
This file contains incorrect .kml data. The program should do nothing
and display an error message. The program will display Parsing error,
cannot read input file.
Miss_tag.kml
This file misses important open <coordinates> tag. The program
should do nothing and display an error message. The program will
display Parsing error, cannot read input file.
NoContent_in_coordinates.kml
This file contains no content between coordinates tag. The program
should do nothing and display an error message. The program will
display Parsing error, cannot read input file.
TextOnly.kml
This simulates a file that doesnt have any XML syntax. It only contains
plain text. The program should not run the .kml file since it doesnt
have any data. The program will display Parsing error, cannot read
input file.
XmlTypeFile.kml
This file contains XML but no .kml tags. The program should display an
error message. The program will display Parsing error, cannot read
input file.
5.2.2
ExtraLongPath.gpx
This route in this file has a distance of 6513.3 miles. This is to simulate
whether the program can process very long-distance GPS data. The
result of the route is correct.
LongPath.gpx
This file simulates a route that has the start point and end point near
to each other. The expected result is correct output.
LongPathGood.gpx
This file has a distance of 143.3 miles. It is to test whether it can
process a long path. The result is correct and the turn inspector is
accurate.
MediumPath.gpx
This file has a distance of 56.5 miles. This is to verify that the program
can take a medium path as an input. The result of the program is
correct.
ShortPath.gpx
This file is to simulate a very short path with a distance of 3.8 miles.
The program should produce a route without any error. The result is
correct and accurate.
Sample.kml
This file should produce a route without any error.