GPXIN-27: Route Support

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

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

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

Methods added so far have been added to the documentation - https://www.bentasker.co.uk/documentation/development-programming/222-php-gpx-ingest#routes

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.

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

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));

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

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.