Allow customisation by transformers

[JarnoLeConte]

Code is now more generalised and has explicit build functions for the elements: <wpt>, <trkpt>, <rtept>, <trk>, <rte>, <gpx>

Additionally, developers could define options.transform to attach transform functions to each of these build functions. These transformers will post process the data and give the flexibility to set all fields defined in the GPX v1.1 specification.

This way developers could easily define their own helpers to fit their needs. The functions get_feature_title(), get_feature_description() and get_feature_coord_times() could have been implemented this way. Moreover this solves my initial problem where properties.coordTimes was defined on my features instead of properties.times.

EXAMPLES

• get_feature_title() implemented by a transformer to set the name of a waypoint <wpt>.

function set_title(wpt, feature, coord, index) {
  wpt.name = feature.properties.name;
}

togpx(geojson, {
  transform: {
    wpt: set_title
  }
})

• times + elevation implemented by a transformer on each track point <trkpt>.

function set_data(trkpt, feature, coord, index) {
  trkpt.time = feature.properties.coordTimes[index];
  trkpt.ele = coord[2];
}

togpx(geojson, {
  transform: {
    trkpt: set_data
  }
})

• Set additional route data in the element <extensions> (see GPX v1.1 specification)

function set_extensions(rte, feature, coords) {
  rte.extensions = [{
    distance: feature.properties.distance,
    viaPoints: coords.length
  }];
}

togpx(geojson, {
  transform: {
    rte: set_extensions
  }
})

• Transform final JXON object

functions modify(gpx, features) {
  gpx.wpt = [ ... ] // edit waypoints
  gpx.trk = [ ... ] // edit tracks
  gpx.rte = [ ... ] // edit routes
  gpx.metadata = [ ... ] // edit meta data
  gpx["@xmlns:trp"] = "http://www.garmin.com/xmlschemas/TripExtensions/v1"; // add attributes
}

togpx(geojson, {
  transform: {
    gpx: modify
  }
})

API

available transformers

togpx(geojson, {
  transform: {
    wpt: function(wpt, feature, coord, index) { // way point (Point)
      ...
    },
    trkpt: function(trkpt, feature, coord, index) { // track point (Point)
      ...
    },
    rtept: function(rtept, feature, coord, index) { // route point (Point)
      ...
    },
    trk: function(trk, feature, coordsList) { // track (MultiLineString)
      ...
    },
    rte: function(rte, feature, coords) { // route (LineString)
      ...
    },
    gpx: function(gpx, features) { 
      ...
    },
  }
})

[tyrasd]

This looks like great improvements, thank you very much!

But can you please complete a few more things before I can merge it (and make it into a v0.6 release):

1. rebase the code onto current master and fix the merge conflicts
2. modify the logic in the defaults helper method, so that it matches ES6's Object.assign (just removing the if condition should do the trick), rename it to assign (or so) and use it also override the default options at the very beginning of the code
3. document the new functionality in the project's readme, i.e. the new options (gpx.* flags and transforms) and maybe a dedicated chapter about how to use the transforms with one or two examples.

[JarnoLeConte]

Yes, I'll do that. Some comments: 2. Personally I would like to use the underscore for these things, like the _.defaults(...) function for example. But maybe you wouldn't depend on libraries? 3. I will start some documentation, but my English isn't very good, so I will appreciate if you would like to fix it afterwards to make it human readable ^^

[tyrasd]

For a small library such as this one, I usually try to keep external dependencies to an absolute minimum. I'll look over the documentation, of course.

[stevenhorner]

Just wondering if this pull request is going to be merged. I was about to try and add the ability to save routes to your code when I noticed @JarnoLeConte PR which includes this. Must admit I haven't done a PR before either so unsure why it stalled?

[nrenner]

See #16 for a merge of this PR for current master, with improvements applied, but still lacking documentation.