VIMSys
User Manual
Steve Crummel - Naim Falandino
Michael Volk - Tim Seeger
1.0 Website Overview
This website is fully compliant with the BOBBY triple A standard. This standard
tests for compliance with government standards, including the U.S. Government’s
Section 508. This tool give prioritized suggestions based on the World Wide Web
Consortium’s Web Accessibility Initiative. Using this tool the website has been
formatted to be completely compliant with accessibility software for visually
impaired users. A BOBBY triple A logo at the bottom of the pages denotes this.
The general navigation outline for all pages will be four links at the top of the page.
From left to right these links read “search”, “resource”, “help”, and “about”, all
discussed below.
1.1 Search Form
The Search form is a standard setup for a mapping site. From top to bottom, there are
the fields for Name, Street, City, a dropdown box for State with a field for Zip Code
on the same vertical level, a dropdown for Type of building, two checkboxes for
Braille and Ramps, with a Submit button at the bottom. To search for a location, a
user can fill in any number of fields as long as at least one field is filled out, then
press Submit to get the results of the search.
Once this list is generated, the user may select any of the matching items by clicking
on the name of the item. Doing this will bring the user to a description page for that
location, giving a written description of the location, pertinent data such as phone
number, address, and whether or not the building has Braille signs and ramps for
accessibility. Below all this are two buttons that allow the user to either download the
map for the location or download the client software for their Pocket PC. Currently,
the Client Software download is not linked to a downloadable package due to
Evaluation License Agreements with the text-to-speech engine being employed by the
VIMSys SureStep application.
1.2 Resource Form
The Resource form has several links on it relative to the VIMSys SureStep
application. At time of release, there are links to the following sites:
The CSE498 Team Website:
The website for the designers of the application.
JAWS for Windows:
A popular text reading program, used to test this site.
Acapela Group:
The website of the company that provided the text-to-speech engine employed in
the design stages of the application.
BOBBY Online Free Portal:
The site used to test for BOBBY compatibility for the VIMS website.
1.3 Help Form
The Help form is there to provide directions in setting up the client software on the
user’s Pocket PC. However, due to Evaluation License Agreements with the provider
of the text-to-speech engine, the executable cannot yet be released for use amongst
the public. Therefore, this form is currently unused for any practical purpose.
1.4 About Form
The About form is a simple description of what VIMS is. That is the sole purpose of
this page at the time of release.
2.0 Administration Webpage
The administration page is setup as a standard log-in site, with the user being asked to
enter a Username, probably related to company name, and a Password. Upon
successfully logging in, the user will be presented with two buttons as options: an
Add button for creating a new location, and an Edit button for changing or removing
the information about a location already in the database that was entered by this
administrator.
2.1 Adding a Location
After choosing to add a location, the user will see a page with several fields, similar
to what is seen on the Search page. The fields associated with the Search page are all
there in the same order, with a field for Phone number, Map file name, and a larger
field for the user to enter a description about the location. When the user is finished
entering information, pressing the Add button at the bottom of the page will submit
the location description to the database. All text fields must be completed before a
user may submit. Upon completion, the user will be returned to the Add/Edit page
described above.
2.2 Editing a Location
Pressing the Edit button will bring up a display of all the locations that the particular
username has access to for editing. This is very similar to the Search Results page
and acts in the same manner, with the user clicking on the name of the location to be
edited. Once a location is selected, a page will be displayed that shows all the
information currently contained in the database in the format discussed in the Section
2.1. The user may make all desired changes and save those changes by pressing the
Edit button at the bottom of the page, or simply remove the location from the
database altogether by choosing the Remove button. Pressing either of these buttons
will return the user to the list of locations that the user may edit.
3.0 VIMSys XML Map Schema
To describe a building for the SureStep client software, a portable and lightweight
XML schema was created. This schema is able to represent buildings and locations
within buildings in the most general sense. Note that attribute ordering is significant,
as is attribute and element case for strings.
After the standard XML header, a location element serves as the document root. This
element has three attributes in this order: name (string), scale (integer), and size
(integer 3-tuple, separated by commas). The name attribute denotes the name for the
entire structure. The scale attribute represents the entire scaling factor for the
structure. Lastly, the size attribute is a 3-tuple of integers representing the width of
the building (in the east-west direction) followed by a comma, followed by the depth
of the building (in the north-south direction) followed by a comma, ending with the
number of floors that the structure has.
The scaling factor requires some elaboration. Ultimately, this value is used as a
divisor for all size, position, and vertex data that follows in the map data file. It is a
scaling factor in that it determines the number of nodes in the search matrix. For
example, if you have a 10 by 10 area, with a scaling factor of 2, in the search the area
is only 5 by 5. To account for this the scaling factor is then used in the generation of
textual directions as a multiplier, to return the distances back to their original values.
Some rounding error is involved, however it is insignificant up to a point. For this
reason it is not recommended to use a scale factor greater than 4. Using a scale factor
of 4 can result in a 80-94% reduction of the search space, depending on the size of the
structure, with only an introduction of error in given distances by some small multiple
(usually no greater than 2) of the scale factor, e.g. 8 feet. This validated by the time
and space savings of the search algorithm. For example, a search that would take 10
seconds with a 1 to 1 scale factor might only take 2-3 seconds with a scale factor of 4.
By allowing the author of the mapping data to adjust the search space scaling factor
we allow for some adjustment of how the searching algorithm performs without
having to modify any code. Smaller buildings can use a small scaling factor for fast
searches with an exact precision, while larger buildings can adjust the scaling factor
up to regain some performance while only introducing minor error to the directions.
The size attribute noted that width was in the east-west direction and depth in northsouth. If the building is not oriented parallel or perpendicularly to north, a pseudonorth must be used to orient the building. Currently rectangular areas for buildings are
only allowed, though if you have a non-rectangular building you can simply increase
the width or depth to account for any outlying parts of the structure.
The first element within the document root is the info element. The inner XML of
this section has 0 or more item elements. The item element is a general element with
two attributes, name (string) and value (string). There is no limit as to what info
about a structure these info elements can store.
Following the info element is some number of level elements. Each level element has
three attributes: id (integer), size (integer pair, separated by a comma), and railCost
(float). The id attribute must be a unique integer identifier for each level of the
structure. Size is similar to the size attribute for the location, except there is no third
parameter for the number of levels. Lastly is the railCost attribute. This assigns a
default cost for all rails on that level. It is strongly suggested that all rails use a cost
of 1.0, however this value can be adjusted depending on the structure. The cost of the
rail has a significant impact on which nodes are expanded and the “niceness” of the
path produced. Having a rail cost that is to close to the cost of the path spaces
(described below) can negatively impact the searching aspects of the project.
The first elements contained in a level are pathSpace elements. There is no limit to
the number of pathSpace elements allowed. These elements describe the searchable
areas within a building, such as hallways. This is accomplished by using an attribute
named verts. This attribute contains a list of vertices (two integers specifying x and y
position separated by a comma) with each vertex separated by a semicolon, e.g.
1,2;1,30;40,30;40,2. These points are used to describe a shape within the level, such
as a rectangle. At a minimum, three points are needed (which would describe a
triangle) while the number of points allowed is unbounded. The order these points
are given is important. They must be given so that the shape is “drawn” in a counterclockwise manner. Further, the first point given must be the lowest, left-most point
of the shape, with “lowness” having precedence over “leftness”. The last point in this
list of vertices wraps around, that is, the last point connects back to the first point in
the list implicitly. A second attribute of the pathSpace element is the cost (float)
element. This has the path cost for that entire area. It is recommended a relatively
high cost is used for all path spaces for a level, such as 10.0. Again this variable is
exposed to the creator of the map file so that adjustments may be made, but such
changes should be made with caution and be tested before release, as they can cause
serious alterations on the performance and quality of the search.
Next is the vertPath element. These elements are used to identify elevators, stairs and
other paths that allow a user to change floors. Three attributes describe a vertPath
element: type (string), position (integer pair, separated by a comma), and floors
(integer range, denoted by start-end). Type specifies elevator, stairs, etc. Position is
an x,y coordinate of that vertical path. Floors specifies the range of levels (specified
by level id) which that vertical path is able to visit.
The next element is rail. It has one attribute verts that is formatted exactly the same
as the verts attribute for pathSpace. The difference is that the rail does not describe a
shape with area, rather a line. This “virtual rail” is what is used to constrain the
search. Care should be used in describing it, since it is the primary path that users
will follow. In general a rail should pass through each pathSpace of a level. Each
point in the verts attribute connects to the one that follows it. If it is the last point
then it is only connected to the point before it. Because of this it may sometimes be
necessary to repeat a point to go “into” an area and then “come back out” of it.
The final element within a level is a landmarks element. This contains other elements
that describe notable features of that level. For instance, the primary element
currently supported by the schema within the landmarks element is the obstacle
element, used to describe obstacles on that level. Obstacle elements have two
attributes: type (string) and position (integer pair, separated by a comma). The type
describes what the obstacle is, e.g. drinking fountain. The position is the familiar x,y
coordinate that locates that obstacle within the current level.
After all the levels in a building have been described using the above format, a new
section is started using an interestPoints element. All the interest points (rooms,
action points, restrooms, etc.) are described here, each one with its own ip element.
Each ip element has three attributes: name (string), type (string), and position (integer
3-tuple, separated by commas). Names for interest points must be unique. Types for
interest points are used filter out interest points on the client to limit the number of
possible choices. Any types may be used that make sense for the structure you are
describing, however the names and case must match among all interest points that use
that type. Finally the position attribute has an x,y coordinate followed by a comma
and the level (denoted by id) that the interest point is located on.
The last section is the commonRoutes. This element contains route elements, each
with four attributes: otype (string), origin (string), dtype (string), destination (string).
Otype and origin refer to an interest point described in the interestPoints section.
Otype specifically refers to the type attribute of an interest point, while origin
specifically refers to the name of an interest point. The same applies to dtype and
destination. Having the type for the origin match the specified origin’s type (and
similarly for the destination type and destination) is essential, as interest points are
filtered based on their type.
Note that it is not necessary to have any route elements inside a commonRoutes
section, as these can be saved by the user while using the application. However,
having an empty commonRoutes element is required for the document to conform to
the VIMSMAP schema.
4.0 Using the VIMSys SureStep
Installing the application is, unfortunately, not an easy process at this point. This is
due primarily to the fact that the text-to-speech engine is on loan from the Elan
Group. Installing the evaluation SDK required copying of many files to the device by
hand, as well as running an application to register where the text-to-speech engine
files are stored. Because of this no installer or other easy deployment strategy could
be developed, both for technical and legal reasons. In accord with the evaluation
SDK EULA we are not allowed to redistribute or repackage any of the files
associated with the SDK. Further, the PocketPC device must have the .NET Compact
Framework (updated to at least service pack 3). The application is written using C#
and uses features found in the latest service pack of the compact framework. Older
versions of the framework are not supported at this time.
To start the application, use the File Explorer on the Pocket PC to browse to the
Program Files\SureStep directory. The SureStep executable located here will start the
application. Currently there is no shortcut registering the application in the start
menu, so executing the application directly from the File Explorer is necessary.
Once the application is started the user will hear “Welcome to VIMSys SureStep,"
notifying them that the application is ready to be used. All control of the application
is handled via the directional pad (up, down, left, and right buttons on the face of the
Pocket PC) and the selection button (located in the center of the directional pad).
Pressing buttons on the visible form has no effect, since we do not want the user to
accidentally activate something not wanted.
On the initial form (known as the search form) the up and down buttons control
which part of the form has focus. For instance, pressing the down button will move
the user’s focus on the form down to the next currently enabled control on the form.
Also, when the user’s focus on the form changes, the text-to-speech (TTS) engine
will voice the name of that control, making the user aware of where they are. The up
button will similarly move the user’s focus up the form to the next currently enabled
control.
The left button reads help text about the currently focused control, namely what
action the selection button will perform on that control. The right button tells the user
what control will become active if the user was to press up or down.
When the application first starts on the search form the initially selected control is the
“load map” button. Selecting this button with the selection key will bring up a load
file dialog. This dialog defaults to the My Documents\VIMSys directory, which is
where users should keep map files. Once a file has been selected it will be parsed and
loaded, creating an in memory representation of that location. The TTS engine will
read the name of the location and state that it was successfully loaded, or that there
was an error parsing the map file.
Once a map file has been loaded several controls on the form will become active:
Origin Type, Destination Type, and Common Routes (if there are any defined in the
map file). Moving down will take you to the Origin Type drop down list. This serves
as a filter for the Origin drop down list. Once an origin type has been selected the
Origin drop down list will become active. Similarly, selecting a Destination Type
will activate the Destination drop down list. Once an origin and destination have
been selected the Generate Directions button will become active. Alternatively,
simply selecting a common route (which describes a path from an origin to a
destination) will also enable the Generate Directions button. In the event that both
the Origin and Destination drop down lists have a valid interest point and a common
route is selected, the common route will have precedence over the origin/destination
pair. If the origin and destination are equal a message will be voiced, stating that a
unique origin and destination is required.
Moving to the help form will begin voicing general instructions about how the
application is used. Pressing the center button will return the user to the search form.
Using the generate directions button will use the map file data to find an optimal path
from the origin to the destination. English directions will then be generated, and the
user will be moved to the directions form. On this form the buttons behave somewhat
differently. Pressing the down button will move to the next direction in the list of
steps from the origin to the destination. Pressing up will move to the previous one.
The center selection button will repeat the currently selected direction. The right
button will save the current selected origin/destination pair as a common route in that
location’s map data file. Lastly, the left button will move the user back to the search
form to perform a new search.
Using the exit button on the search form will terminate the application.