Pathfinder Technical

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

5 Testing and quality assurance

5.1 Testing script
5.2 Sample GPX/KML file descriptions
5.2.1 Bad test files
5.2.2 Good test files
6 Detailed technical documentation
6.1 Accessing reference documentation
6.2 Building reference documentation from source

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.

2.2 Performance requirements

The program should process a GPX file representing a fairly long (>100
miles) bicycle ride within a reasonable amount of time. Given that such
a file may require hundreds of server requests to process, it will not be
instantaneous; processing time may be improved upon further runs of
the program by caching of results. Pruning of waypoints may also be
necessary to improve performance. Performance testing with large
datasets will reveal bottlenecks and areas that may need
improvement.

2.3 Interface requirements

The program will present a user interface that consists primarily of a
map display and a list of turn-by-turn directions. The user will select a
GPX file using a standard File Open dialog box, and the program will
immediately begin processing the file once selected. Initially a map will

be displayed with the approximate route, and then processing will

commence with a progress bar to show the progress of the processing.
Once processing is complete, the generated cue sheet will be
displayed alongside the map. There will also be a turn viewer linked to
the cue sheet display, so that individual turns along the route can be
viewed in more detail.

2.4 Operational requirements

The program needs to run on commodity PCs running Windows OS
from XP to 7. Ideally it should also run on Mac OS X and Linux in the
Mono framework.

2.5 Resource requirements

The program will require an internet connection and an ability to
connect through that connection to a reverse geocoding service (either
Google or Geonames.org). It will also require a GPX file as input, which
the user will be responsible for loading on the operating PC before
executing the Pathfinder program.

2.6 Documentation requirements

Technical documentation (this document) and external/user
documentation will be created and maintained. User documentation
explains how to use the features of the program, while external
documentation describes how to install the program and provides a
README file and high-level overview of the program and
documentation.

3 System architecture and design

3.1 Technical design goals
3.1.1

Ease of use

The program must be simple to use and understand. This requires a

clear user interface with intuitive controls and helpful feedback
mechanisms. Users are able to adjust operational parameters to
modify the programs algorithm and operation, but the program should
work reasonably out of the box with no such adjustments.

3.1.2

Performance

The program minimizes the time required to perform cue sheet

generation by restricting expensive operations to as small a subset of
lat/long points as possible, and by caching results of expensive
operations. Users can decrease the number of lat/long points
processed and increase the minimum distance between adjacent
points, potentially at the expense of accuracy.

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

Maintainability and extensibility

The program is designed in a modular fashion to enable easy

modification of discrete modules, and to enable addition of new
features with relatively little effort. In addition, the source code is
commented in a manner that encourages use of document generation
tools. Doxygen is used for generating documentation directly from the
program source code.

3.1.5

Reliability and fault-tolerance

The program is designed to handle exceptional conditions gracefully.

Such conditions include bad input data, inability of the program to
access required web services, and corrupt cache data.

3.2 High-level architecture description

The program has three main components: an input file parser, a
location parser, and a directions generator. The main components and
their interactions are depicted in Figure 1. A more detailed description
of the architecture and sub-components is provided in section 3.3.
The input file parser takes as input a GPX file containing
latitude/longitude pairs along the path ridden. It passes these pairs to
the location parser, which obtains street names for each point by first
consulting its local cache and then consulting a reverse geocoding web
service (provided by Google or an alternate provider) if the result is not
already in cache. Then the directions generator uses the street names
and corresponding lat/long pairs to determine the street segments
along the route and the junctions where streets change. Finally, it takes
the street segments and computes the precise turn directions at each
junction, which results in a detailed turn-by-turn list of directions along
the route, with street names, street segment lengths between turns,
and turn instructions for each turn. This list is output as a CSV file with
an accompanying bitmap image (BMP) file showing the route map, or
as an HTML file with a BMP file.

Figure 1 High-level architecture

3.3 Architecture component details

The following descriptions refer to the subsystems depicted in Figure 2,
the Pathfinder detailed architecture diagram. The Pathfinder Strategy
class is the top-level controller for all of the software modules
described.

Figure 2 - Detailed architecture

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

Track Path / URL Builder

This module contains the set of waypoints generated by the parser,

and has methods for pruning the set of waypoints in preparation for
processing by a reverse geocoding service. It also is responsible for
creating a URL used to retrieve a static map of the route from the
Google Maps web service.
The program implements a modified version of the Douglas-Peucker
algorithm to reduce the number of waypoints required for accurate
route calculation. It does this by removing waypoints along a straight
line between turns, since those points are not necessary in calculating
the route. The points closest to turns are kept, while others are
discarded. This reduces the number of waypoints (and consequently,
the reverse geocoding time), by about 90% on average.

3.3.3

Web Interface

This module encapsulates http request and response functionality for

requesting images (such as maps) and accessing web services (such as
the reverse geocoding services).

3.3.4

Fiducial Strategy

This module processes a map image retrieved by the web interface

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

This module performs reverse geocoding of waypoints to obtain

address and street name data, which are added to the waypoint
objects.

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

This module transforms the cue sheet into comma-separated-values

(CSV) or HTML form for export by the user, facilitating easy import into
a spreadsheet program such as Excel. This module also exports an
image bitmap (BMP) file of the route map with annotations.

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

File Input and Output

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

HTTP requests and responses

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.

3.4 Cross-platform compatibility

The program is written in C#, using the Microsoft Visual Studio
development environment. The target operating system for the
executable program is Windows, though the program can be run on
Mac OS X and Linux using the Mono compatibility layer (see
http://www.go-mono.com). In addition, it can be built from source on
these platforms using the MonoDevelop software suite
(http://monodevelop.com). See section 4 for details.

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.

5 Testing and Quality Assurance

5.1 Testing script
To test the program, follow the steps below. This is the QA script used
in development, and should identify errors in the program.
1. File dialog box
A. Click on File dialog box.
B. Open dialog box
1) Click on Open dialog box.
2) Open .gpx files (see section 5.2 for GPX file sample
descriptions).
3) Open with corrupted GPX files.
4) Open other files beside .gpx.
C. Save dialog box
1) Click on Save dialog box.
2) Save regular .csv file.
3) Save with any given name for .csv file.
4) Save regular .html file.
5) Save with any given name for .html file.
6) Save with file type written in File Name space
(Example: name.exe).

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.

3) Repeat 2) and open up another file.

4) Repeat 1), 2), 3) for all the Geocode point dialog boxes.
5) Repeat 3) with combination of other Geocode Points.
3. Help dialog box
A. View Help dialog box
1) Click on View Help dialog box and verify that the User
Manual is downloaded and is viewable.
2) Examine to see if it uses the default browser.
B. About dialog box
1) Click on About dialog box and examine to see that the
PathfinderAboutBox opens up.
2) Verify that Product Name, Version, Copyright,
Company Name, Description are correct.
3) Examine OK button to see if it works properly.
4. Delete, Next, and Back buttons.
A. Click the button before opening a file.
B. After opening a file, click the button and examine changes in
Ride Map, Directions, Turn Inspector areas.
C. Click the button after using Next button multiple times.
D. Click the button after using Back button multiple times.
E. Delete multiple turns.
5. Status Strip
A. Test to see if Progress Bar works between the time of
opening a file and GUI display changes complete.
B. Examine the strip to see if it display exact number of
waypoints for the file opened.
C. Examine the changes in longitude and latitude when mouse is
moving over Ride Map area.
D. Examine appropriate address is displaying for the current
direction.
6. Cache function.
A. Test from a clean installation, with no cache file. Load a GPX
file and perform a lookup, then quit the program (which writes
the cache to disk).
B. Open the program a second time, and then load the same GPX
file again and verify that it used the cache (it will be much
faster). Close the program.
C. Delete the cache file, and copy a different file to the same
place and with the same name. This is to test what happens
when the program tries to load a cache file that isn't actually a
cache file, as if the cache file were corrupted. Then try to load a
GPX file and see what happens.

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

in Linux and repeat steps, 1. to 5.

in Window XP and repeat steps, 1. to 5.
in Window Vista and repeat steps, 1. to 5.
in Window 7 and repeat steps, 1. to 5.
in Mac OS X and repeat steps, 1. to 5.

5.2 Sample GPX/KML file descriptions

There are sample GPX and KML files bundled with the program. These
can be used to test the program with files of varying length, and with
various types of bad files. The files are packaged in the
technical_documentation/Test Cases directory. The files are described
below.

5.2.1

Bad test files

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

Good test files

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.

6 Detailed technical documentation

The classes that make up the Pathfinder program are well-documented
internally, and it is possible to create a web interface or a PDF file from
the internal code documentation using the Doxygen tool (see
http://www.doxygen.org).

6.1 Accessing reference documentation

The Pathfinder Reference Manual generated from the code via this
mechanism is included in the distribution, as PathfinderReference.pdf.

It is also possible to browse the HTML documentation by opening the

index.html file in the html directory of the distribution.

6.2 Building reference documentation from source

To build the Doxygen documentation from the source code, first
download the Doxygen package for your platform, then start the
Doxygen application and open the PathfinderDoxyfile file with the
File/Open dialog. From the Wizard screen, click Next twice to view the
list of possible output formats. HTML is the default, which will create all
of the files in the html directory. Select LaTeX to generate output files
that can be used to create a PDF file. Click Next again for the diagrams
selector; if GraphViz is installed leave the selection as is; otherwise
select No diagrams. Then click the Run tab and click the Run
doxygen button.
Assuming all went well, there will be an html directory and a latex
directory (if LaTeX output was selected in the wizard). Open the
index.html file in the html directory to view the HTML output. To
compile the PDF manual from LaTeX, compile the file refman.tex in the
latex directory with your TeX program. It will produce a file called
refman.pdf. This file has been renamed PathfinderReference.pdf in the
root level of the software distribution as described.