GPXIN-24: Waypoint Support

Replied with the following on Github:

Could conceivably be added, sure (for reference - relevant part of schema is http://www.topografix.com/gpx/1/1/#type_wptType ). In fact, it should be fairly straightforward to drop in as they'll need processing (at ingest) independently of the trackpoints anyway

I guess you'd then want to be able to do something like

$gpx->listWaypoints();

To return all included Waypoints, or

$gpx->getWaypoint($wp-id);

To grab by a numerical identifier. Maybe even be able to retrieve by the name specified in the source GPX?

$gpx->getWaypointByName('foo');

Probably also worth adding something to the JSON metadata to indicate whether there are any waypoints included.

An example GPX file (cobbled together using examples on Cycleseven) might be

<?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>
  <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>

So, we're going to want to look at creating a new object property to house the waypoints, and add the various possible attributes

Note that waypoints can have their own extensions (for example)

  <wpt lat="53.9927816" lon="-1.5425382">
    <ele>134.7094727</ele>
    <name>Bettys</name>
    <cmt>02-FEB-10 14:10:06</cmt>
    <desc>02-FEB-10 14:10:06</desc>
    <sym>Flag, Blue</sym>
    <extensions>
      <gpxx:WaypointExtension xmlns:gpxx="http://www.garmin.com/xmlschemas/GpxExtensions/v3">
        <gpxx:DisplayMode>SymbolAndName</gpxx:DisplayMode>
      </gpxx:WaypointExtension>
    </extensions>
  </wpt>

So support for those may need to be added later

Have come across a slight hiccup with the implementation so far.

When exporting JSON, we only pass out the journey property (and conversely, only populate that when reading in from a JSON source). The current implementation adds waypoints as a completely separate property (as, really, they should be), which means they won't be included in a JSON dump.

Changing the JSON output so that it no longer solely pushes out journey would change the structure of the output and break b/c.

Although I don't overly like it as a solution, waypoints (and if they're added at a later date, route points) should probably be added as a property of journey to ensure they're included in the JSON output. Perhaps grouped under "related" or similar

Have added 3 public methods to the class to provide basic handling of waypoints

public function getWayPointCount() // return INT
public function getWaypoints() // return array
public function getWaypoint($id) // return object

Where the structure of a waypoint is as follows

gpx->getWayPoint(0)
stdClass Object
(
    [name] => Position 1
    [description] => 
    [comment] => 
    [position] => stdClass Object
        (
            [lat] => 54.9328621088893
            [lon] => 9.860624216140083
            [ele] => 0.0
            [geoidheight] => 
        )

    [meta] => stdClass Object
        (
            [time] => 
            [magvar] => 
            [source] => 
            [link] => 
            [symbol] => 
            [type] => 
            [GPS] => stdClass Object
                (
                    [fix] => 
                    [sat] => 
                    [hdop] => 
                    [vdop] => 
                    [pdop] => 
                    [ageofdgpsdata] => 
                    [dgpsid] => 
                )
        )

)

All properties defined within wptType in the spec will always be present in the output, however if they weren't present in the source they will be null

Have updated the documentation to give details of the current waypoint support - https://www.bentasker.co.uk/documentation/development-programming/222-php-gpx-ingest#waypoints

Latest commit is here - https://github.com/bentasker/PHP-GPX-Ingest/commit/a1130853a64206bfc7b90e0921c51f09a5f3b021 - forgot to reference this issue