GPX Doctor

A Ruby gem for parsing and manipulating GPX 1.1 routes.

Installation

Add to your Gemfile:

gem "gpx_doctor"

Or install directly:

gem install gpx_doctor

Configuration

GpxDoctor.configure do |config|
  config.elevation_server          = true
  config.elevation_server_url      = "https://elevation.example.com"
  config.elevation_server_user     = "user"
  config.elevation_server_password = "secret"
end

GpxDoctor.configuration.elevation_server_url # => "https://elevation.example.com"
GpxDoctor.reset_configuration!               # resets to defaults

Option	Type	Default	Description
`elevation_server`	Boolean	`false`	Whether to use an elevation server
`elevation_server_url`	String	`nil`	URL of the elevation server
`elevation_server_user`	String	`nil`	Username for the elevation server
`elevation_server_password`	String	`nil`	Password for the elevation server

Parsing

From a file

result = GpxDoctor::Parser.parse("path/to/file.gpx")

From a string

result = GpxDoctor::Parser.parse_string(xml_string)

Parsing with processing parameters

Both parse and parse_string accept an optional params: hash to enable post-processing:

result = GpxDoctor::Parser.parse("path/to/file.gpx", params: {
  max_distance:       200,           # insert interpolated points so no two consecutive points exceed this distance (metres)
  max_points:         500,           # reduce each segment to at most this many points
  segment_statistics: true,          # compute distance_to_next, elevation_change, direction for each point
  enhance_elevation:  true           # fetch missing elevations from the configured elevation server
})

Processing is applied in the following order:

max_distance — segment splitting (interpolates intermediate points)
max_points — point reduction
segment_statistics — per-point statistics (distance, bearing, elevation change)
enhance_elevation — elevation lookup via the elevation server

enhance_elevation: true requires the elevation server to be configured (see Configuration above). It only fills in points that have no elevation value; existing elevations are left unchanged.

Accessing data

result.points    # => [#<Waypoint lat=…, lon=…, ele=…>, …]  (all geographic points)
result.waypoints # => [#<Waypoint …>]  (top-level <wpt> elements only)
result.routes    # => [#<Route …>]
result.tracks    # => [#<Track …>]
result.metadata  # => #<Metadata …>  (or nil)

result.points is a flat array containing all geographic points from:

Top-level <wpt> elements
<rtept> elements inside each <rte>
<trkpt> elements inside each <trkseg> inside each <trk>

Model field reference

`Waypoint`

Field	Type	Notes
`lat`	Float	Required
`lon`	Float	Required
`ele`	Float	Elevation in metres
`time`	Time
`magvar`	Float	Magnetic variation
`geoidheight`	Float
`name`	String
`cmt`	String	Comment
`desc`	String	Description
`src`	String	Source
`links`	Array
`sym`	String	Symbol
`type`	String
`fix`	String	`none`, `2d`, `3d`, `dgps`, `pps`
`sat`	Integer	Number of satellites
`hdop`	Float
`vdop`	Float
`pdop`	Float
`ageofdgpsdata`	Float
`dgpsid`	Integer	0–1023

Waypoint#to_h returns a hash of all non-nil fields.

`Metadata`

Field	Type
`name`	String
`desc`	String
`author`	Person
`copyright`	Copyright
`links`	Array
`time`	Time
`keywords`	String
`bounds`	Bounds

`Route`

Field	Type
`name`	String
`cmt`	String
`desc`	String
`src`	String
`links`	Array
`number`	Integer
`type`	String
`points`	Array

`Track`

Field	Type
`name`	String
`cmt`	String
`desc`	String
`src`	String
`links`	Array
`number`	Integer
`type`	String
`segments`	Array
`points`	Array (all points across all segments)

`TrackSegment`

Field	Type
`points`	Array

`Person`

Field	Type
`name`	String
`email`	Email
`link`	Link

`Copyright`

Field	Type
`author`	String
`year`	String
`license`	String

`Link`

Field	Type
`href`	String
`text`	String
`type`	String

`Email`

Field	Type
`id`	String
`domain`	String

Email#to_s returns "id@domain".

`Bounds`

Field	Type
`minlat`	Float
`minlon`	Float
`maxlat`	Float
`maxlon`	Float

Development

Building the gem

gem build gpx_doctor.gemspec

This produces a file like gpx_doctor-0.1.0.gem in the current directory.

Running tests

bundle install
bundle exec rspec

Publishing to RubyGems

Create an account at https://rubygems.org if you don't have one.
Set up credentials (one-time):

   gem signin

This stores your API key in ~/.gem/credentials.

Build and push:

   gem build gpx_doctor.gemspec
   gem push gpx_doctor-0.1.0.gem

Verify the release at https://rubygems.org/gems/gpx_doctor.

Tip: Bump GpxDoctor::VERSION in lib/gpx_doctor/version.rb before each release and tag the commit:
git tag -a v0.1.0 -m "Release 0.1.0"
git push origin v0.1.0

License

MIT