GPX Import

Detailed Feature Description

We need to be able to upload GPX files into the platform in order to support the definition of location entity boundaries. There are two main approaches:

• To use this GPX imported data to generate the location boundaries automatically

• To use this GPX imported data as a support resource to draw the boundaries of location entities

Due to the potential inaccuracy of GPS data, the former is more difficult to achieve in a proper way, and it'd be necessary to manually manipulate this data in some way prior to generating the boundaries (we will describe this further below).

User Stories

1. As a data collector, I want to import GPS coordinates from a GPX file as a project resource.

2. As a data collector, I want to see the GPX coordinates presented as an overlay on top of the basemap in the platform (either OSM or satellite).

3. As a data collector, I want to define the boundaries of a location with the drawing tools using the GPX coordinates layer as a guidance.

4. As a data collector, I want to directly define the boundaries of a location based on the GPX imported coordinates without making use of the drawing tools.

5. As a data collector, I want to see some of the details of each of the waypoints when mousing over them.

6. As a data collector, I want to see clusters of waypoints instead of all the individual ones when they are close geographically .

Requirements

GPX files should be recorded as a project resource, so that it will be able to use them in the future as documentation for property rights issues.

User Stories from 1 to 3 will be addressed in a first stage, so the user will be still the last responsible of drawing the boundaries but using the tracks or waypoints as a guidance. User Story 4 will be tackled in a second stage, as the implementation is potentially more complex and there are other issues (like GPS accuracy) that we need to deal with.

Format and organization of the GPX information

GPX (GPS eXchange format) is an XML format designed to share GPS data among different applications. A simple XML document looks like this (example taken from Wikipedia):

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>

<gpx xmlns="http://www.topografix.com/GPX/1/1" xmlns:gpxx="http://www.garmin.com/xmlschemas/GpxExtensions/v3" xmlns:gpxtpx="http://www.garmin.com/xmlschemas/TrackPointExtension/v1" creator="Oregon 400t" version="1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd http://www.garmin.com/xmlschemas/GpxExtensions/v3 http://www.garmin.com/xmlschemas/GpxExtensionsv3.xsd http://www.garmin.com/xmlschemas/TrackPointExtension/v1 http://www.garmin.com/xmlschemas/TrackPointExtensionv1.xsd">
  <metadata>
    <link href="http://www.garmin.com">
      <text>Garmin International</text>
    </link>
    <time>2009-10-17T22:58:43Z</time>
  </metadata>
  <trk>
    <name>Example GPX Document</name>
    <trkseg>
      <trkpt lat="47.644548" lon="-122.326897">
        <ele>4.46</ele>
        <time>2009-10-17T18:37:26Z</time>
      </trkpt>
      <trkpt lat="47.644548" lon="-122.326897">
        <ele>4.94</ele>
        <time>2009-10-17T18:37:31Z</time>
      </trkpt>
      <trkpt lat="47.644548" lon="-122.326897">
        <ele>6.87</ele>
        <time>2009-10-17T18:37:34Z</time>
      </trkpt>
    </trkseg>
  </trk>
</gpx>

There are three basic types defined in the spec:

• wptType Individual waypoint consisting in a point expressed in WGS84 GPS coordinates.
• trkType It is a track that contains at least one waypoint (i.e. wptType) that are connected in a logical sequence. It is made of a sufficient number of points to precisely describe a boundary, for instance.
• rteType It is a route, an ordered list of waypoints leading to a destination.

The route is the plan for your navigation. The track is the recorded path a user did actually follow. GPX files define different XML elements for each of them, as it can be seen here.

A nicely done documentation can be found here, including:

• The official GPX XML Schema.
• The associated documentation.

GPX documents are formed by a metadata header followed by waypoints, routes and tracks.

We are not going to describe formally all the elements and types, as all of them are already available in the formal documentation. But we are going to strictly select the ones that we need to support to allow the data import and assist drawing locations boundaries.

The following types defined in the XML schema should be supported (others could be just ignored when importing the files).

• Element gpx: it is the root element of the XML file. It typically contains metadata, wpt, rte and trk elements.

• Complex Type gpxType: type for gpx element. In principle, we should only consider the version attribute to check that we are working with 1.1 documents.

• Complex Type metadataType: type for metadata element. It covers general information such as author, timestamp, copyrights, etc. In principle, it should be safe to ignore all of these with the only exemption of the <time> element (which is xsd:dateTime type) to record the timestamp.

• Complex Type wptType: type for waypoints (wpts). In principle, we just need to support lat and lon attributes for latitude and longitude. Within the waypoint elevation data could be contained (in a <ele> element with xsd:decimal data).

• Complex Type rteType: type for routes (rtes), which contains a collection of waypoints in rtept elements (type wptType). Other elements contained can be safely ignored.

• Complex Type trkType: type for tracks (trks). There is only one single element contained in here that is interesting for us, the trkseg (type trksegType), with the information regarding the track sequence (segments).

• Complex Type trksegType: type for the track's segments. It contains trkpts elements (type wptType) which include the latitude and longitude information.

• Simple type latitudeType: xsd:decimal restricted between -90 and 90.

• Simple type longitudeType: xsd:decimal restricted between -180 and 180.

Importing GPX files

GPX files shall be uploaded as another project resource, presumably using the same user interface and adding the the GPX files as a supported format.

Displaying GPX data as an overlay on top of the basemap

As the idea is to use the coordinates as a guidance for the user to accurately draw the location boundaries (a community, building, etc), we need the user to be able to activate and deactivate the visualization of this GPX overlay. We need then a new element on the map UI to activate or deactivate the GPX tracks.

Then the user would be able to select either OSM or Satellite view, plus enabling (or not) the tracks visualization layer. Maybe we can include a new icon right below the layer icon in the map (top right corner)?

Drawing boundaries using GPX coordinates as a guidance

Once the user activates the GPX layer, she should be able to use the drawing tools that are available when adding a new location (polyline, polygon, rectangle and marker).

When drawing the boundaries (or putting the marker) it would be nice to be able to easily connect the different waypoints by snapping to the different waypoints when the mouse pointer is really close to that point. That would help the user to draw the exact polygon that has in mind.

Semi-automatically generate location boundaries from imported GPX coordinates

Note: This should be refined later on when we will be closer to the implementation of this part

Where GPX data would be used to delimitate numerous locations (such as households instead of community borders for instance), it would be very useful to implement some kind of semi automatic mechanism that allows users to just "confirm" that the location boundaries are ok with those defined in the GPS coordinates.

Detailed pros and cons should be analyzed, but we will probably have two different options:

1. Import GPX files and generating automatically all the locations, so the user will be reviewing them after this. Although it'd be the fastest mechanism for the users, to deal with GPS inaccuracies specially in small properties could be challenging.

2. A probably safer option would be to present the potential locations (and their boundaries) to the user, and she will be confirming all of them after doing some fine tuning if needed.

Another (likely more complicated) option would be to use a least squares regression lines approach, predefining a (presumably high) number of vertex of the polygon to define a close figure from the imported GPS coordinates. That would help to "smooth" the GPS inaccuracies if the number of collected waypoints is high enough (i.e. wouldn't work if surveyor just collect waypoints in the corners of a household for instance).

In this case, it should be offered to the user the possibility of enabling or not this regression approach.

Details of waypoints when mousing over

Timestamp ('') and name ('') of each waypoint (this last one still on discussion) should be shown when the user mouses over the each waypoint, so it'd be easier to identify.

Clustering waypoints

Clustering of waypoints should be applied when several waypoints are close geographically, so it'd be more clear for the user. However, we need to make sure that when the user zooms in enough, the clustering is cleared, so the user can draw the location geometry assisted by the waypoints.

Ancillary Information

Regarding elevation, we could include this information when we are considering locations as geopoints (having for instance a new item in the questionnaire), but if we are managing geotraces or geoshapes to define the boundaries of a location, we would need to ignore this as we can not record several elevation measurements for one location.

Example with waypoints:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

<gpx creator="GPS Visualizer http://www.gpsvisualizer.com/" version="1.0">
  <wpt lat="45.44283" lon="-121.72904"><ele>1374</ele></wpt>
  <wpt lat="45.41000" lon="-121.71349"><ele>1454</ele></wpt>
  <wpt lat="45.41124" lon="-121.70404"><ele>1375</ele></wpt>
  <wpt lat="45.39260" lon="-121.69937"><ele>1333</ele></wpt>
</gpx>

Example with tracks:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

<gpx version="1.1" 
    creator="EMTAC BTGPS Trine II DataLog Dump 1.0 - http://www.ayeltd.biz"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.topografix.com/GPX/1/1"
    xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">

<metadata>
 (...) 
</metadata>

<trk>

  <trkseg>
    <trkpt lat="59.4408327" lon="24.74516185">
      <ele>1232.7</ele>
    </trkpt>
  </trkseg>

</trk>
</gpx>

Example with routes:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<gpx xmlns="http://www.topografix.com/GPX/1/1" version="1.1" creator="RouteConverter">
    <metadata>
      (...)
    </metadata>
    <trk>
        <trkseg>
            <trkpt lon="9.860624216140083" lat="54.9328621088893">
                <ele>872.3</ele>
            </trkpt>
            <trkpt lon="9.86092208681491" lat="54.93293237320851">
                <ele>923.6</ele>
            </trkpt>
            <trkpt lon="9.86187816543752" lat="54.93327743521187">
                <ele>888.7</ele>
            </trkpt>
            <trkpt lon="9.862439849679859" lat="54.93342326167919">
                <ele>902.6</ele>
            </trkpt>
        </trkseg>
    </trk>
</gpx>