gpx_doctor 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c1cba3a635e28b6b5731f9a178342323f6068e3954e03439c4c908045346d936
+  data.tar.gz: 0a9dd34154ee4c75abd3c9556bf69fb80e238ca0a4d940d9371607f299871b73
+SHA512:
+  metadata.gz: e9981e204bdf04c176e500920be0ff75b14a011e50d3a149590545adf4351d6e5f00e37ab51bb998f43b97d2619afa0927accb606ab584eab84f0d4e29d2229e
+  data.tar.gz: 4b226863088aac9b8af344985426bc4beeee6693f1772b710537edb7e6c7059623f0824621f20f40cee55fe13114af7acdd306c524f51cd1fcdec38e50b44fb9

data/README.md

@@ -0,0 +1,255 @@
+# GPX Doctor
+
+A Ruby gem for parsing and manipulating GPX 1.1 routes.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "gpx_doctor"
+```
+
+Or install directly:
+
+```bash
+gem install gpx_doctor
+```
+
+## Configuration
+
+```ruby
+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
+
+```ruby
+result = GpxDoctor::Parser.parse("path/to/file.gpx")
+```
+
+### From a string
+
+```ruby
+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:
+
+```ruby
+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:
+
+1. `max_distance` — segment splitting (interpolates intermediate points)
+2. `max_points` — point reduction
+3. `segment_statistics` — per-point statistics (distance, bearing, elevation change)
+4. `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
+
+```ruby
+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<Link> | |
+| `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<Link> |
+| `time` | Time |
+| `keywords` | String |
+| `bounds` | Bounds |
+
+### `Route`
+
+| Field | Type |
+|---|---|
+| `name` | String |
+| `cmt` | String |
+| `desc` | String |
+| `src` | String |
+| `links` | Array<Link> |
+| `number` | Integer |
+| `type` | String |
+| `points` | Array<Waypoint> |
+
+### `Track`
+
+| Field | Type |
+|---|---|
+| `name` | String |
+| `cmt` | String |
+| `desc` | String |
+| `src` | String |
+| `links` | Array<Link> |
+| `number` | Integer |
+| `type` | String |
+| `segments` | Array<TrackSegment> |
+| `points` | Array<Waypoint> (all points across all segments) |
+
+### `TrackSegment`
+
+| Field | Type |
+|---|---|
+| `points` | Array<Waypoint> |
+
+### `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
+
+```bash
+gem build gpx_doctor.gemspec
+```
+
+This produces a file like `gpx_doctor-0.1.0.gem` in the current directory.
+
+### Running tests
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+### Publishing to RubyGems
+
+1. **Create an account** at <https://rubygems.org> if you don't have one.
+
+2. **Set up credentials** (one-time):
+
+   ```bash
+   gem signin
+   ```
+
+   This stores your API key in `~/.gem/credentials`.
+
+3. **Build and push**:
+
+   ```bash
+   gem build gpx_doctor.gemspec
+   gem push gpx_doctor-0.1.0.gem
+   ```
+
+4. **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:
+>
+> ```bash
+> git tag -a v0.1.0 -m "Release 0.1.0"
+> git push origin v0.1.0
+> ```
+
+## License
+
+MIT

data/lib/gpx_doctor/builder.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module GpxDoctor
+  class Builder
+    GPX_NS          = 'http://www.topografix.com/GPX/1/1'
+    XSI_NS          = 'http://www.w3.org/2001/XMLSchema-instance'
+    SCHEMA_LOCATION = "#{GPX_NS} http://www.topografix.com/GPX/1/1/gpx.xsd"
+
+    class << self
+      def build(result, creator: 'GPX Doctor')
+        new(result, creator: creator).build
+      end
+
+      def build_file(result, file_path, creator: 'GPX Doctor')
+        xml = build(result, creator: creator)
+        File.write(file_path, xml)
+        xml
+      end
+    end
+
+    def initialize(result, creator: 'GPX Doctor')
+      @result  = result
+      @creator = creator
+    end
+
+    def build
+      builder = Nokogiri::XML::Builder.new(encoding: 'UTF-8') do |xml|
+        xml.gpx(
+          'version'              => '1.1',
+          'creator'              => @creator,
+          'xmlns'                => GPX_NS,
+          'xmlns:xsi'            => XSI_NS,
+          'xsi:schemaLocation'   => SCHEMA_LOCATION
+        ) do
+          build_metadata(xml, @result.metadata) if @result.metadata
+          @result.waypoints.each { |wpt| build_waypoint(xml, wpt, tag: 'wpt') }
+          @result.routes.each    { |rte| build_route(xml, rte) }
+          @result.tracks.each    { |trk| build_track(xml, trk) }
+        end
+      end
+      builder.to_xml
+    end
+
+    private
+
+    def build_metadata(xml, metadata)
+      xml.metadata do
+        xml.name     metadata.name     if metadata.name
+        xml.desc     metadata.desc     if metadata.desc
+        build_person(xml, metadata.author)         if metadata.author
+        build_copyright(xml, metadata.copyright)   if metadata.copyright
+        metadata.links.each { |link| build_link(xml, link) }
+        xml.time     metadata.time.iso8601  if metadata.time
+        xml.keywords metadata.keywords      if metadata.keywords
+        build_bounds(xml, metadata.bounds)  if metadata.bounds
+      end
+    end
+
+    def build_person(xml, person)
+      xml.author do
+        xml.name person.name if person.name
+        build_email(xml, person.email) if person.email
+        build_link(xml, person.link)   if person.link
+      end
+    end
+
+    def build_email(xml, email)
+      xml.email('id' => email.id, 'domain' => email.domain)
+    end
+
+    def build_copyright(xml, copyright)
+      xml.copyright('author' => copyright.author) do
+        xml.year    copyright.year    if copyright.year
+        xml.license copyright.license if copyright.license
+      end
+    end
+
+    def build_link(xml, link)
+      xml.link('href' => link.href) do
+        # 'text' is a reserved method in Nokogiri::XML::Builder, so we must
+        # route through method_missing to produce a <text> element.
+        xml.send(:method_missing, :text, link.text) if link.text
+        xml.type link.type if link.type
+      end
+    end
+
+    def build_bounds(xml, bounds)
+      xml.bounds(
+        'minlat' => bounds.minlat,
+        'minlon' => bounds.minlon,
+        'maxlat' => bounds.maxlat,
+        'maxlon' => bounds.maxlon
+      )
+    end
+
+    # Builds wpt / rtept / trkpt elements (all share the same field set).
+    def build_waypoint(xml, wpt, tag: 'wpt')
+      xml.send(tag, 'lat' => wpt.lat, 'lon' => wpt.lon) do
+        xml.ele          wpt.ele                  if wpt.ele
+        xml.time         wpt.time.iso8601         if wpt.time
+        xml.magvar       wpt.magvar               if wpt.magvar
+        xml.geoidheight  wpt.geoidheight          if wpt.geoidheight
+        xml.name         wpt.name                 if wpt.name
+        xml.cmt          wpt.cmt                  if wpt.cmt
+        xml.desc         wpt.desc                 if wpt.desc
+        xml.src          wpt.src                  if wpt.src
+        Array(wpt.links).each { |link| build_link(xml, link) }
+        xml.sym          wpt.sym                  if wpt.sym
+        xml.type         wpt.type                 if wpt.type
+        xml.fix          wpt.fix                  if wpt.fix
+        xml.sat          wpt.sat                  if wpt.sat
+        xml.hdop         wpt.hdop                 if wpt.hdop
+        xml.vdop         wpt.vdop                 if wpt.vdop
+        xml.pdop         wpt.pdop                 if wpt.pdop
+        xml.ageofdgpsdata wpt.ageofdgpsdata       if wpt.ageofdgpsdata
+        xml.dgpsid       wpt.dgpsid               if wpt.dgpsid
+      end
+    end
+
+    def build_route(xml, route)
+      xml.rte do
+        xml.name   route.name   if route.name
+        xml.cmt    route.cmt    if route.cmt
+        xml.desc   route.desc   if route.desc
+        xml.src    route.src    if route.src
+        Array(route.links).each { |link| build_link(xml, link) }
+        xml.number route.number if route.number
+        xml.type   route.type   if route.type
+        route.points.each { |pt| build_waypoint(xml, pt, tag: 'rtept') }
+      end
+    end
+
+    def build_track(xml, track)
+      xml.trk do
+        xml.name   track.name   if track.name
+        xml.cmt    track.cmt    if track.cmt
+        xml.desc   track.desc   if track.desc
+        xml.src    track.src    if track.src
+        Array(track.links).each { |link| build_link(xml, link) }
+        xml.number track.number if track.number
+        xml.type   track.type   if track.type
+        track.segments.each do |seg|
+          xml.trkseg do
+            seg.points.each { |pt| build_waypoint(xml, pt, tag: 'trkpt') }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gpx_doctor/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  class Configuration
+    attr_accessor :elevation_server,
+                  :elevation_server_url,
+                  :elevation_server_user,
+                  :elevation_server_password
+
+    def initialize
+      @elevation_server          = false
+      @elevation_server_url      = nil
+      @elevation_server_user     = nil
+      @elevation_server_password = nil
+    end
+  end
+end

data/lib/gpx_doctor/distance_calculator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  module DistanceCalculator
+    # Approximate degrees-to-meters conversion factors.
+    # 1 degree latitude  ≈ 111_320 m
+    # 1 degree longitude ≈ 111_320 m * cos(latitude)
+    METERS_PER_DEGREE_LAT = 111_320.0
+
+    module_function
+
+    # Returns the flat-earth Pythagorean distance in meters between two waypoints.
+    def distance(a, b)
+      dlat_m, dlon_m = components(a, b)
+      Math.sqrt(dlat_m**2 + dlon_m**2)
+    end
+
+    # Returns geographic bearing in degrees (0 = North, 90 = East, 180 = South, 270 = West)
+    # between two waypoints.
+    def bearing(a, b)
+      dlat_m, dlon_m = components(a, b)
+      angle_rad = Math.atan2(dlon_m, dlat_m)
+      degrees = angle_rad * 180.0 / Math::PI
+      degrees % 360
+    end
+
+    # Returns [dlat_m, dlon_m] — the north and east displacement in meters between a and b.
+    def components(a, b)
+      dlat_m = (b.lat - a.lat) * METERS_PER_DEGREE_LAT
+      avg_lat_rad = (a.lat + b.lat) / 2.0 * Math::PI / 180.0
+      dlon_m = (b.lon - a.lon) * METERS_PER_DEGREE_LAT * Math.cos(avg_lat_rad)
+      [dlat_m, dlon_m]
+    end
+    module_function :components
+    private_class_method :components
+  end
+end

data/lib/gpx_doctor/elevation_client.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module GpxDoctor
+  class ElevationClient
+    MAX_REQUEST_LINE_BYTES = 1024
+    LOOKUP_PATH = '/api/v1/lookup'
+
+    def initialize(config = nil)
+      config    = config || GpxDoctor.configuration
+      @base_url = config.elevation_server_url
+      @user     = config.elevation_server_user
+      @password = config.elevation_server_password
+    end
+
+    # Enhances waypoints that have nil ele with elevation from the server.
+    # Mutates the waypoints in place.
+    def enhance(waypoints)
+      missing = waypoints.select { |wp| wp.ele.nil? }
+      return if missing.empty?
+
+      batches(missing).each do |batch|
+        elevations = fetch_elevations(batch)
+        batch.zip(elevations).each do |wp, elev|
+          wp.ele = elev if elev
+        end
+      end
+    end
+
+    private
+
+    # Splits points into batches that fit within the GET URL byte limit.
+    def batches(points)
+      base_uri_length = "#{@base_url}#{LOOKUP_PATH}?locations=".bytesize
+      available = MAX_REQUEST_LINE_BYTES - base_uri_length
+
+      result = []
+      current_batch = []
+      current_length = 0
+
+      points.each do |wp|
+        location = "#{wp.lat},#{wp.lon}"
+        # Account for the '|' separator between locations
+        entry_length = current_batch.empty? ? location.bytesize : (location.bytesize + 1)
+
+        if current_length + entry_length > available && !current_batch.empty?
+          result << current_batch
+          current_batch = [wp]
+          current_length = location.bytesize
+        else
+          current_batch << wp
+          current_length += entry_length
+        end
+      end
+
+      result << current_batch unless current_batch.empty?
+      result
+    end
+
+    def fetch_elevations(batch)
+      locations = batch.map { |wp| "#{wp.lat},#{wp.lon}" }.join('|')
+      uri = URI("#{@base_url}#{LOOKUP_PATH}?locations=#{locations}")
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+      http.open_timeout = 10
+      http.read_timeout = 30
+
+      request = Net::HTTP::Get.new(uri)
+      request.basic_auth(@user, @password) if @user && @password
+
+      response = http.request(request)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        return Array.new(batch.size)
+      end
+
+      parse_response(response.body, batch.size)
+    rescue StandardError => e
+      Array.new(batch.size)
+    end
+
+    def parse_response(body, expected_count)
+      data = JSON.parse(body)
+      results = data['results'] || []
+
+      elevations = results.map { |r| r['elevation']&.to_f }
+
+      # Pad with nils if the response has fewer results than expected
+      elevations.fill(nil, elevations.size...expected_count) if elevations.size < expected_count
+      elevations
+    end
+  end
+end

data/lib/gpx_doctor/models/bounds.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  module Models
+    Bounds = Struct.new(:minlat, :minlon, :maxlat, :maxlon, keyword_init: true)
+  end
+end

data/lib/gpx_doctor/models/copyright.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  module Models
+    Copyright = Struct.new(:author, :year, :license, keyword_init: true)
+  end
+end

data/lib/gpx_doctor/models/email.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  module Models
+    Email = Struct.new(:id, :domain, keyword_init: true) do
+      def to_s
+        "#{id}@#{domain}"
+      end
+    end
+  end
+end

data/lib/gpx_doctor/models/link.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  module Models
+    Link = Struct.new(:href, :text, :type, keyword_init: true)
+  end
+end

data/lib/gpx_doctor/models/metadata.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  module Models
+    Metadata = Struct.new(
+      :name, :desc, :author, :copyright, :links, :time, :keywords, :bounds,
+      keyword_init: true
+    ) do
+      def initialize(**)
+        super
+        self.links ||= []
+      end
+    end
+  end
+end

data/lib/gpx_doctor/models/person.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  module Models
+    Person = Struct.new(:name, :email, :link, keyword_init: true)
+  end
+end

data/lib/gpx_doctor/models/route.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  module Models
+    Route = Struct.new(
+      :name, :cmt, :desc, :src, :links, :number, :type, :points,
+      keyword_init: true
+    ) do
+      def initialize(**)
+        super
+        self.links  ||= []
+        self.points ||= []
+      end
+    end
+  end
+end

data/lib/gpx_doctor/models/track.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  module Models
+    Track = Struct.new(
+      :name, :cmt, :desc, :src, :links, :number, :type, :segments,
+      keyword_init: true
+    ) do
+      def initialize(**)
+        super
+        self.links    ||= []
+        self.segments ||= []
+      end
+
+      def points
+        segments.flat_map(&:points)
+      end
+    end
+  end
+end

data/lib/gpx_doctor/models/track_segment.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  module Models
+    TrackSegment = Struct.new(:points, keyword_init: true) do
+      def initialize(**)
+        super
+        self.points ||= []
+      end
+    end
+  end
+end

data/lib/gpx_doctor/models/waypoint.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  module Models
+    class Waypoint
+      FIELDS = %i[
+        lat lon ele time magvar geoidheight name cmt desc src links
+        sym type fix sat hdop vdop pdop ageofdgpsdata dgpsid
+      ].freeze
+
+      STATISTICS_FIELDS = %i[distance_to_next elevation_change direction].freeze
+
+      attr_accessor(*STATISTICS_FIELDS)
+
+      attr_accessor(*FIELDS)
+
+      def initialize(**attrs)
+        attrs.each { |k, v| public_send(:"#{k}=", v) }
+        @links ||= []
+      end
+
+      def to_h
+        (FIELDS + STATISTICS_FIELDS).each_with_object({}) do |field, hash|
+          value = public_send(field)
+          hash[field] = value unless value.nil?
+        end
+      end
+    end
+  end
+end

data/lib/gpx_doctor/parser.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'time'
+
+module GpxDoctor
+  class Parser
+    GPX_NS = 'http://www.topografix.com/GPX/1/1'
+
+    Result = Struct.new(:waypoints, :routes, :tracks, :metadata, keyword_init: true) do
+      def points
+        waypoints + routes.flat_map(&:points) + tracks.flat_map(&:points)
+      end
+    end
+
+    class << self
+      def parse(file_path, params: {})
+        xml = File.read(file_path)
+        parse_string(xml, params: params)
+      end
+
+      def parse_string(xml_string, params: {})
+        doc = Nokogiri::XML(xml_string)
+        ns  = detect_namespace(doc)
+
+        new(doc, ns, params: params).parse
+      end
+
+      private
+
+      def detect_namespace(doc)
+        root_ns = doc.root&.namespace&.href
+        root_ns == GPX_NS ? GPX_NS : nil
+      end
+    end
+
+    def initialize(doc, ns, params: {})
+      @doc = doc
+      @ns  = ns
+      @params = params
+    end
+
+    def parse
+      result = Result.new(
+        waypoints: parse_waypoints,
+        routes: parse_routes,
+        tracks: parse_tracks,
+        metadata: parse_metadata
+      )
+
+      eff_max_dist = @params[:max_distance] || effective_max_distance(result)
+      split_segments(result, eff_max_dist) if eff_max_dist
+      select_max_points(result) if @params[:max_points]
+      enhance_statistics(result) if @params[:segment_statistics]
+      enhance_elevations(result) if @params[:enhance_elevation]
+
+      result
+    end
+
+    private
+
+    def xpath(node, path)
+      if @ns
+        node.xpath(path, 'g' => @ns)
+      else
+        node.xpath(path.gsub('g:', ''))
+      end
+    end
+
+    def text_at(node, tag)
+      el = xpath(node, "g:#{tag}").first
+      el&.text&.strip
+    end
+
+    def float_at(node, tag)
+      v = text_at(node, tag)
+      v&.to_f
+    end
+
+    def int_at(node, tag)
+      v = text_at(node, tag)
+      v&.to_i
+    end
+
+    def time_at(node, tag)
+      v = text_at(node, tag)
+      v ? Time.parse(v) : nil
+    end
+
+    def parse_links(node)
+      xpath(node, 'g:link').map do |link_el|
+        Models::Link.new(
+          href: link_el['href'],
+          text: link_el.xpath('g:text', 'g' => @ns).first&.text&.strip,
+          type: link_el.xpath('g:type', 'g' => @ns).first&.text&.strip
+        )
+      end
+    end
+
+    def parse_waypoint(wpt_el)
+      Models::Waypoint.new(
+        lat: wpt_el['lat'].to_f,
+        lon: wpt_el['lon'].to_f,
+        ele: float_at(wpt_el, 'ele'),
+        time: time_at(wpt_el, 'time'),
+        magvar: float_at(wpt_el, 'magvar'),
+        geoidheight: float_at(wpt_el, 'geoidheight'),
+        name: text_at(wpt_el, 'name'),
+        cmt: text_at(wpt_el, 'cmt'),
+        desc: text_at(wpt_el, 'desc'),
+        src: text_at(wpt_el, 'src'),
+        links: parse_links(wpt_el),
+        sym: text_at(wpt_el, 'sym'),
+        type: text_at(wpt_el, 'type'),
+        fix: text_at(wpt_el, 'fix'),
+        sat: int_at(wpt_el, 'sat'),
+        hdop: float_at(wpt_el, 'hdop'),
+        vdop: float_at(wpt_el, 'vdop'),
+        pdop: float_at(wpt_el, 'pdop'),
+        ageofdgpsdata: float_at(wpt_el, 'ageofdgpsdata'),
+        dgpsid: int_at(wpt_el, 'dgpsid')
+      )
+    end
+
+    def parse_waypoints
+      xpath(@doc, '//g:gpx/g:wpt').map { |el| parse_waypoint(el) }
+    end
+
+    def parse_routes
+      xpath(@doc, '//g:gpx/g:rte').map do |rte_el|
+        Models::Route.new(
+          name: text_at(rte_el, 'name'),
+          cmt: text_at(rte_el, 'cmt'),
+          desc: text_at(rte_el, 'desc'),
+          src: text_at(rte_el, 'src'),
+          links: parse_links(rte_el),
+          number: int_at(rte_el, 'number'),
+          type: text_at(rte_el, 'type'),
+          points: xpath(rte_el, 'g:rtept').map { |el| parse_waypoint(el) }
+        )
+      end
+    end
+
+    def parse_tracks
+      xpath(@doc, '//g:gpx/g:trk').map do |trk_el|
+        Models::Track.new(
+          name: text_at(trk_el, 'name'),
+          cmt: text_at(trk_el, 'cmt'),
+          desc: text_at(trk_el, 'desc'),
+          src: text_at(trk_el, 'src'),
+          links: parse_links(trk_el),
+          number: int_at(trk_el, 'number'),
+          type: text_at(trk_el, 'type'),
+          segments: xpath(trk_el, 'g:trkseg').map do |seg_el|
+            Models::TrackSegment.new(
+              points: xpath(seg_el, 'g:trkpt').map { |el| parse_waypoint(el) }
+            )
+          end
+        )
+      end
+    end
+
+    def parse_metadata
+      meta_el = xpath(@doc, '//g:gpx/g:metadata').first
+      return nil unless meta_el
+
+      Models::Metadata.new(
+        name: text_at(meta_el, 'name'),
+        desc: text_at(meta_el, 'desc'),
+        author: parse_person(xpath(meta_el, 'g:author').first),
+        copyright: parse_copyright(xpath(meta_el, 'g:copyright').first),
+        links: parse_links(meta_el),
+        time: time_at(meta_el, 'time'),
+        keywords: text_at(meta_el, 'keywords'),
+        bounds: parse_bounds(xpath(meta_el, 'g:bounds').first)
+      )
+    end
+
+    def parse_person(person_el)
+      return nil unless person_el
+
+      Models::Person.new(
+        name: text_at(person_el, 'name'),
+        email: parse_email(xpath(person_el, 'g:email').first),
+        link: parse_links(person_el).first
+      )
+    end
+
+    def parse_email(email_el)
+      return nil unless email_el
+
+      Models::Email.new(
+        id: email_el['id'],
+        domain: email_el['domain']
+      )
+    end
+
+    def parse_copyright(copyright_el)
+      return nil unless copyright_el
+
+      Models::Copyright.new(
+        author: copyright_el['author'],
+        year: text_at(copyright_el, 'year'),
+        license: text_at(copyright_el, 'license')
+      )
+    end
+
+    def parse_bounds(bounds_el)
+      return nil unless bounds_el
+
+      Models::Bounds.new(
+        minlat: bounds_el['minlat'].to_f,
+        minlon: bounds_el['minlon'].to_f,
+        maxlat: bounds_el['maxlat'].to_f,
+        maxlon: bounds_el['maxlon'].to_f
+      )
+    end
+
+    def enhance_elevations(result)
+      config = GpxDoctor.configuration
+      return unless config.elevation_server && config.elevation_server_url
+
+      ElevationClient.new.enhance(result.points)
+    end
+
+    def effective_max_distance(result)
+      return nil unless @params[:max_points]
+
+      total = total_distance(result)
+      ratio = total / @params[:max_points].to_f
+      ratio > 1000 ? 500 : nil
+    end
+
+    def total_distance(result)
+      selector = PointSelector.new
+      all_point_collections(result).sum { |pts| selector.total_distance(pts) }
+    end
+
+    def all_point_collections(result)
+      collections = result.routes.map(&:points)
+      result.tracks.each { |t| t.segments.each { |s| collections << s.points } }
+      collections
+    end
+
+    def split_segments(result, max_dist)
+      splitter = SegmentSplitter.new
+      result.routes.each { |route| route.points = splitter.split(route.points, max_dist) }
+      result.tracks.each do |track|
+        track.segments.each { |seg| seg.points = splitter.split(seg.points, max_dist) }
+      end
+    end
+
+    def select_max_points(result)
+      selector = PointSelector.new
+      n = @params[:max_points]
+      result.routes.each { |route| route.points = selector.select(route.points, n) }
+      result.tracks.each do |track|
+        track.segments.each { |seg| seg.points = selector.select(seg.points, n) }
+      end
+    end
+
+    def enhance_statistics(result)
+      enhancer = StatisticsEnhancer.new
+      result.routes.each { |route| enhancer.enhance(route.points) }
+      result.tracks.each do |track|
+        track.segments.each { |seg| enhancer.enhance(seg.points) }
+      end
+    end
+  end
+end

data/lib/gpx_doctor/point_selector.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  class PointSelector
+    # Returns the total distance in meters for a sequence of +points+.
+    def total_distance(points)
+      return 0.0 if points.nil? || points.size < 2
+
+      total = 0.0
+      points.each_cons(2) { |a, b| total += DistanceCalculator.distance(a, b) }
+      total
+    end
+
+    # Selects up to +max_points+ points from +points+ with equal distance spread.
+    # Always includes the first and last points. Returns a new array; the original
+    # is not mutated. When +points+ already has fewer or equal elements than
+    # +max_points+, it is returned unchanged.
+    def select(points, max_points)
+      return points if points.nil? || max_points <= 0 || points.size <= max_points
+
+      m = points.size
+      n = max_points
+
+      # For n == 1 there is no denominator (n - 1 = 0), so just keep the first point.
+      return [points[0]] if n == 1
+
+      cumulative = [0.0]
+      points.each_cons(2) do |a, b|
+        cumulative << cumulative.last + DistanceCalculator.distance(a, b)
+      end
+      total = cumulative.last
+
+      # Degenerate case: all points are at the same location — fall back to index spread.
+      if total.zero?
+        indices = (0...n).map { |i| (i * (m - 1).to_f / (n - 1)).round }
+        return indices.uniq.map { |idx| points[idx] }
+      end
+
+      used = {}
+      selected_indices = (0...n).map do |i|
+        target = i * total / (n - 1).to_f
+        # Find the closest unused point to the target cumulative distance.
+        best_idx = cumulative
+          .each_with_index
+          .reject { |_, idx| used[idx] }
+          .min_by { |d, _| (d - target).abs }
+          .last
+        used[best_idx] = true
+        best_idx
+      end
+
+      selected_indices.sort.map { |idx| points[idx] }
+    end
+  end
+end

data/lib/gpx_doctor/segment_splitter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  class SegmentSplitter
+    # Splits a sequence of waypoints so that no two consecutive points are
+    # farther apart than +max_distance+ meters.  Pairs that are already within
+    # the limit are left untouched.  When a pair exceeds the limit, evenly
+    # spaced intermediate points are interpolated between them (lat/lon always;
+    # ele and time only when both endpoints have values).
+    #
+    # Returns a new array; the original is not mutated.
+    def split(points, max_distance)
+      return points if points.nil? || points.size < 2
+
+      result = [points.first]
+
+      points.each_cons(2) do |current, nxt|
+        dist = DistanceCalculator.distance(current, nxt)
+
+        if dist > max_distance
+          n_segments = (dist / max_distance).ceil
+          (1...n_segments).each do |i|
+            fraction = i.to_f / n_segments
+            result << interpolate(current, nxt, fraction)
+          end
+        end
+
+        result << nxt
+      end
+
+      result
+    end
+
+    private
+
+    def interpolate(a, b, fraction)
+      ele  = a.ele  && b.ele  ? a.ele  + fraction * (b.ele  - a.ele)  : nil
+      time = a.time && b.time ? a.time + fraction * (b.time - a.time) : nil
+
+      Models::Waypoint.new(
+        lat:  a.lat + fraction * (b.lat - a.lat),
+        lon:  a.lon + fraction * (b.lon - a.lon),
+        ele:  ele,
+        time: time
+      )
+    end
+  end
+end

data/lib/gpx_doctor/statistics_enhancer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  class StatisticsEnhancer
+    # Enhances each consecutive pair of waypoints with statistics:
+    #   - distance_to_next  (meters, flat-earth Pythagorean approximation)
+    #   - elevation_change   (meters, next.ele - current.ele; nil when elevation missing)
+    #   - direction          (degrees 0-360, geographic bearing to next point)
+    #
+    # The last point in the list receives nil for all three fields.
+    # Mutates waypoints in place.
+    def enhance(waypoints)
+      return if waypoints.nil? || waypoints.size < 2
+
+      waypoints.each_cons(2) do |current, nxt|
+        current.distance_to_next = DistanceCalculator.distance(current, nxt)
+
+        current.elevation_change = if current.ele && nxt.ele
+                                     nxt.ele - current.ele
+                                   end
+
+        current.direction = DistanceCalculator.bearing(current, nxt)
+      end
+    end
+  end
+end

data/lib/gpx_doctor/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  VERSION = '0.2.0'
+end

data/lib/gpx_doctor.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'gpx_doctor/version'
+require 'gpx_doctor/configuration'
+require 'gpx_doctor/models/email'
+require 'gpx_doctor/models/link'
+require 'gpx_doctor/models/copyright'
+require 'gpx_doctor/models/person'
+require 'gpx_doctor/models/bounds'
+require 'gpx_doctor/models/waypoint'
+require 'gpx_doctor/models/metadata'
+require 'gpx_doctor/models/track_segment'
+require 'gpx_doctor/models/route'
+require 'gpx_doctor/models/track'
+require 'gpx_doctor/distance_calculator'
+require 'gpx_doctor/elevation_client'
+require 'gpx_doctor/statistics_enhancer'
+require 'gpx_doctor/segment_splitter'
+require 'gpx_doctor/point_selector'
+require 'gpx_doctor/parser'
+require 'gpx_doctor/builder'
+
+module GpxDoctor
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: gpx_doctor
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Poltrax
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: GPX Doctor helps with manipulation of GPX routes. It parses GPX 1.1 files
+  into Ruby objects.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/gpx_doctor.rb
+- lib/gpx_doctor/builder.rb
+- lib/gpx_doctor/configuration.rb
+- lib/gpx_doctor/distance_calculator.rb
+- lib/gpx_doctor/elevation_client.rb
+- lib/gpx_doctor/models/bounds.rb
+- lib/gpx_doctor/models/copyright.rb
+- lib/gpx_doctor/models/email.rb
+- lib/gpx_doctor/models/link.rb
+- lib/gpx_doctor/models/metadata.rb
+- lib/gpx_doctor/models/person.rb
+- lib/gpx_doctor/models/route.rb
+- lib/gpx_doctor/models/track.rb
+- lib/gpx_doctor/models/track_segment.rb
+- lib/gpx_doctor/models/waypoint.rb
+- lib/gpx_doctor/parser.rb
+- lib/gpx_doctor/point_selector.rb
+- lib/gpx_doctor/segment_splitter.rb
+- lib/gpx_doctor/statistics_enhancer.rb
+- lib/gpx_doctor/version.rb
+homepage: https://github.com/Poltrax-live/gpx-doctor
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Parse and manipulate GPX routes
+test_files: []