GPXIN-27: Route Support



Issue Information

Issue Type: New Feature
 
Priority: Major
Status: Closed

Reported By:
Ben Tasker
Assigned To:
Ben Tasker
Project: PHP GPXIngest (GPXIN)
Resolution: Done (2017-07-04 14:28:40)
Target version: 1.03,

Created: 2016-02-20 23:35:36
Time Spent Working
Estimated:
 
120 minutes
Remaining:
  
75 minutes
Logged:
  
45 minutes


Description
GPXIN-24 introduced support for ingesting waypoints defined in the source GPX file. A natural extension of that would be to add support for the rteType .

For purposes of clarity: A route is the planned route, whereas the track is the path ultimately followed.

There'll normally only be the one route, but as with tracks, it's best to work on the basis that there may be more than one


Issue Links

rteType (GPX Documentation)
Toggle State Changes

Activity


An example GPX might be (from CycleSeven)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<gpx xmlns="http://www.topografix.com/GPX/1/1" version="1.1" creator="RouteConverter">
    <metadata>
        <name>Test file by Patrick</name>
   </metadata>
    <wpt lon="9.860624216140083" lat="54.9328621088893">
        <ele>0.0</ele>
        <name>Position 1</name>
    </wpt>
    <wpt lon="9.86092208681491" lat="54.93293237320851">
        <ele>0.0</ele>
        <name>Position 2</name>
    </wpt>
    <wpt lon="9.86187816543752" lat="54.93327743521187">
        <ele>0.0</ele>
        <name>Position 3</name>
    </wpt>
    <wpt lon="9.862439849679859" lat="54.93342326167919">
        <ele>0.0</ele>
        <name>Position 4</name>
    </wpt>
    <rte>
        <name>Patrick's Route</name>
        <rtept lon="9.860624216140083" lat="54.9328621088893">
            <ele>0.0</ele>
            <name>Position 1</name>
        </rtept>
        <rtept lon="9.86092208681491" lat="54.93293237320851">
            <ele>0.0</ele>
            <name>Position 2</name>
        </rtept>
        <rtept lon="9.86187816543752" lat="54.93327743521187">
            <ele>0.0</ele>
            <name>Position 3</name>
        </rtept>
        <rtept lon="9.862439849679859" lat="54.93342326167919">
            <ele>0.0</ele>
            <name>Position 4</name>
        </rtept>
    </rte>
  <trk>
    <name>24-JUL-09</name>
    <extensions>
      <gpxx:TrackExtension xmlns:gpxx="http://www.garmin.com/xmlschemas/GpxExtensions/v3">
        <gpxx:DisplayColor>DarkRed</gpxx:DisplayColor>
      </gpxx:TrackExtension>
    </extensions>
    <trkseg>
      <trkpt lat="53.623000" lon="-2.574910">
       <ele>143.94</ele>
       <time>2009-07-11T21:37:58Z</time>
      </trkpt>
      <trkpt lat="53.624500" lon="-2.569600">
       <ele>136.06</ele>
       <time>2009-07-11T21:38:55Z</time>
      </trkpt>
      <trkpt lat="53.624500" lon="-2.569410">
       <ele>138.03</ele>
       <time>2009-07-11T21:38:57Z</time>
      </trkpt>
      <trkpt lat="53.624700" lon="-2.567970">
       <ele>148.75</ele>
       <time>2009-07-11T21:39:12Z</time>
      </trkpt>
    </trkseg>
  </trk>
</gpx>


Note that rtept is of type wptType so as in GPXIN-24 need to consider that extensions may be present
Given that the handling for a rtept is exactly the same as that for a waypoint, it probably makes sense to break some of the logic implemented in GPXIN-24 out into a new method to avoid duplication
btasker changed status from 'Open' to 'In Progress'

Repo: PHP-GPX-Ingest
Commit: 5b2cf342baf967742f9c068ee68778f43156e393
Author: B Tasker <github@<Domain Hidden>>

Date: Sun Feb 21 00:07:10 2016 +0000
Commit Message: Moved wptType logic into new method. See GPXIN-27



Modified (-)(+)
-------
GPXIngest.class.php




Webhook User-Agent

GitHub-Hookshot/21f57ba


View Commit

Have created
private function buildWptType($wpt)

To handle building the object.

Now need to look at actually pulling the routes out of the GPX file so that they can be processed. They're more like tracks in the way that needs to be handled - there can be multiple routes (some named, but it's not mandatory) and it'll have multiple children.
Routes are now ingested under the related property of the journey object, with the following structure
                    [routes] => stdClass Object
                        (
                            [route0] => stdClass Object
                                (
                                    [name] => Patrick's Route
                                    [meta] => stdClass Object
                                        (
                                            [comment] => 
                                            [description] => 
                                            [src] => 
                                            [link] => 
                                            [number] => 
                                            [type] => 
                                        )

                                    [points] => stdClass Object
                                        (
                                            [rtpoint0] => stdClass Object

Need to add some public methods to allow retrieval of them yet though
btasker changed status from 'In Progress' to 'Open'
btasker changed timespent from '0 minutes' to '25 minutes'

Repo: PHP-GPX-Ingest
Commit: 7f429eee5695e5f578ca003f6f45a9a65dca87a5
Author: B Tasker <github@<Domain Hidden>>

Date: Sun Feb 21 00:26:09 2016 +0000
Commit Message: Added Route support into ingest method. See GPXIN-27



Modified (-)(+)
-------
GPXIngest.class.php




Webhook User-Agent

GitHub-Hookshot/21f57ba


View Commit


Repo: PHP-GPX-Ingest
Commit: e523b4600f46110b27d189c1b432daf2b0c6b38f
Author: B Tasker <github@<Domain Hidden>>

Date: Sun Feb 21 06:25:32 2016 +0000
Commit Message: Added basic functions for retrieving routes. See GPXIN-27



Modified (-)(+)
-------
GPXIngest.class.php




Webhook User-Agent

GitHub-Hookshot/21f57ba


View Commit

Added three methods for getting route information
public function getRouteNames()
public function getRouteByID($id)
public function getRouteCount()


It's a bit of a sledgehammer approach at the moment, there's no way to extract an individual route point. You'd need to use getRouteByID and then iterate over the points property.

Conversely, there's also no way to extract all routes in one hit either
btasker changed timespent from '25 minutes' to '45 minutes'
GPXIN-33 added support for various route related stats.

At the moment you access those by calling getJourneyStats() and then grabbing the attribute routestats but I think it might be helpful to have a utility function that does that for you.

Repo: PHP-GPX-Ingest
Commit: 5a692439f40192f01bfb9a51708d927e5ae91956
Author: B Tasker <github@<Domain Hidden>>

Date: Tue Jul 04 12:06:05 2017 +0100
Commit Message: Exposed new method getRouteStats for GPXIN-27

Returns the general route stats object



Modified (-)(+)
-------
src/GPXIngest/GPXIngest.php




Webhook User-Agent

GitHub-Hookshot/18889e1


View Commit

Essentially, we want to the utility functions to be structured as they are for tracks - https://www.bentasker.co.uk/documentation/development-programming/222-php-gpx-ingest#objectsextract

btasker added '1.03' to Fix Version
btasker removed '1.02' from Fix Version
btasker removed '1.02' from Version
So we already have
public function getRouteNames()
public function getRouteByID($id)
public function getRouteCount()


So we need some equivalents

- $gpx->getObject() = $gpx->getRoutesObject()
- $gpx->getTrack('journey0') = $gpx->getRouteByID('name')
- $gpx->getSegment('journey0','seg0') = no equivalent (there isn't really a segment equivalent in routes)
- $gpx->getTrackPoint('journey0','seg0','trackpt0') = $gpx->getRoutePoint('name','trkptname')

We also need equivalents to the ID fetchers - https://www.bentasker.co.uk/documentation/development-programming/222-php-gpx-ingest#IDS

- $gpx->getTrackIDs() = $gpx->getRouteIDs()
- $gpx->getTrackNames() = $gpx->getRouteNames()
- $gpx->getTrackSegmentNames('journey0') = no equivalent
- $gpx->getTrackPointNames('journey0','seg0') = $gpx->getRoutePointNames('name')

For the route related functions that already exist, might want to also create some stub functions so that naming is closer to their track counterparts, though I think there's only one that needs doing:

- getRouteByID() = getRoute()

OK, so far, we now have

public function getRoute($id)
public function getRouteIDs()
public function getRoutePointNames($route)


The following works as expected
$rid = $gpx->getRouteIDs()[0];
print_r($gpx->getRoute($rid));
echo "------------------\n";
print_r($gpx->getRoutePointNames($rid));

Repo: PHP-GPX-Ingest
Commit: aecb44005c70718244c9e7c1653dff4b69a38773
Author: B Tasker <github@<Domain Hidden>>

Date: Tue Jul 04 13:37:20 2017 +0100
Commit Message: GPXIN-27 - Implementing route related ID fetchers.



Modified (-)(+)
-------
src/GPXIngest/GPXIngest.php




Webhook User-Agent

GitHub-Hookshot/18889e1


View Commit

Ok, we now have

public function getRoutesObject()
public function getRoutePoint($route,$routepoint)


And the following works as expected
$rid = $gpx->getRouteIDs()[0];
$tpoint = $gpx->getRoutePointNames($rid)[0];
print_r($gpx->getRoutePoint($rid,$tpoint));


So that gives us the following public methods

getRoutesObject() // Retrieve the entire routes object
getRoute($id) // Retrieve a specific route object by ID
getRoutePoint($route,$ptid) // Retrieve a specific routepoint by ID
getRouteIDs() // list all route IDs
getRouteNames() // Get a list of all route names (with id also included in the array)
getRoutePointNames($route) // Get a list of all routepoint names for the given route

Repo: PHP-GPX-Ingest
Commit: f11dbc2ee9b25116ffd9151e16ed34e4c4864d5d
Author: B Tasker <github@<Domain Hidden>>

Date: Tue Jul 04 13:48:48 2017 +0100
Commit Message: GPXIN-27 Added route object fetchers.



Modified (-)(+)
-------
src/GPXIngest/GPXIngest.php




Webhook User-Agent

GitHub-Hookshot/18889e1


View Commit

Documentation will need updating, but otherwise I think we're done here.
Documentation has been updated with examples - https://www.bentasker.co.uk/documentation/development-programming/222-php-gpx-ingest?#routes - so while support is still minimal, I'd say we're done here.
btasker changed status from 'Open' to 'Resolved'
btasker added 'Done' to resolution
btasker changed status from 'Resolved' to 'Closed'

Work log


Ben Tasker
Permalink
2016-02-21 00:28:19

Time Spent: 25 minutes
Log Entry: Initial implementation

Ben Tasker
Permalink
2016-02-21 06:46:50

Time Spent: 20 minutes
Log Entry: Adding retrieval methods, testing and updating docs