gpx_doctor 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1cba3a635e28b6b5731f9a178342323f6068e3954e03439c4c908045346d936
-  data.tar.gz: 0a9dd34154ee4c75abd3c9556bf69fb80e238ca0a4d940d9371607f299871b73
+  metadata.gz: e0ba71f5752f36af3efd9f3b12de47d843a85b3ecd7fbcabd7468a2eef43355e
+  data.tar.gz: b58cb9eb1f207c3ec26f127b615ba43f70efe741904c6e73aa2c4ab059a7b710
 SHA512:
-  metadata.gz: e9981e204bdf04c176e500920be0ff75b14a011e50d3a149590545adf4351d6e5f00e37ab51bb998f43b97d2619afa0927accb606ab584eab84f0d4e29d2229e
-  data.tar.gz: 4b226863088aac9b8af344985426bc4beeee6693f1772b710537edb7e6c7059623f0824621f20f40cee55fe13114af7acdd306c524f51cd1fcdec38e50b44fb9
+  metadata.gz: 053df672b67de8623f4749e7a5d0e8419667abd7227e31a8937d2434ebad3a0af73d04ae54af95112ecffe1e7824314634316cc1bc1793863d5c9289057cf4bd
+  data.tar.gz: 2376c74be6339f8aeeb535e8f79dbd9dd876bca7526713f9be8e09da3793718eaba4e285a455e4a07e1f182768affcf206c6ae7ba81483e37c6468e59bf96e27

data/README.md

@@ -24,6 +24,7 @@ GpxDoctor.configure do |config|
   config.elevation_server_url      = "https://elevation.example.com"
   config.elevation_server_user     = "user"
   config.elevation_server_password = "secret"
+  config.unit_system               = :imperial  # or :metric (default)
 end
 
 GpxDoctor.configuration.elevation_server_url # => "https://elevation.example.com"
@@ -36,6 +37,33 @@ GpxDoctor.reset_configuration!               # resets to defaults
 | `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 |
+| `unit_system` | Symbol | `:metric` | Unit system (`:metric` or `:imperial`) for distance and elevation values |
+
+### Unit System
+
+The `unit_system` configuration affects the following fields:
+
+- **`:metric` (default)**:
+  - `distance_to_next` and `elevation_change` are in **meters**
+  - `cumulative_distance` is in **kilometers**
+- **`:imperial`**:
+  - `distance_to_next` and `elevation_change` are in **feet**
+  - `cumulative_distance` is in **miles**
+
+```ruby
+# Use imperial units
+GpxDoctor.configure do |config|
+  config.unit_system = :imperial
+end
+
+result = GpxDoctor::Parser.parse("path/to/file.gpx", params: { 
+  segment_statistics: true, 
+  cumulative_distance: true 
+})
+
+# distance_to_next and elevation_change will be in feet
+# cumulative_distance will be in miles
+```
 
 ## Parsing
 
@@ -60,6 +88,7 @@ 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
+  cumulative_distance: true,         # add cumulative distance from start of each segment/route
   enhance_elevation:  true           # fetch missing elevations from the configured elevation server
 })
 ```
@@ -69,10 +98,13 @@ 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
+4. `cumulative_distance` — cumulative distance from the start of each segment/route
+5. `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.
 
+`cumulative_distance: true` adds a `cumulative_distance` field to each point, representing the cumulative distance in kilometers from the start of its segment or route. For tracks with multiple segments, each segment's cumulative distance starts at 0.0 (gaps between segments are not included in the calculation).
+
 ## Accessing data
 
 ```ruby
@@ -88,6 +120,121 @@ result.metadata  # => #<Metadata …>  (or nil)
 - `<rtept>` elements inside each `<rte>`
 - `<trkpt>` elements inside each `<trkseg>` inside each `<trk>`
 
+## Building GPX files
+
+The `GpxDoctor::Builder` class generates GPX 1.1 XML from a `Result` object (the same structure returned by the parser).
+
+### Build to a string
+
+```ruby
+result = GpxDoctor::Parser::Result.new(
+  waypoints: [],
+  routes: [],
+  tracks: [],
+  metadata: nil
+)
+
+xml_string = GpxDoctor::Builder.build(result)
+# => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<gpx version=\"1.1\"..."
+
+# Optional: specify a custom creator attribute (identifies the software that created the GPX file)
+xml_string = GpxDoctor::Builder.build(result, creator: 'My Application')
+```
+
+### Build to a file
+
+```ruby
+GpxDoctor::Builder.build_file(result, 'path/to/output.gpx')
+# Writes the GPX XML to the file and returns the XML string
+
+# Optional: specify a custom creator attribute
+GpxDoctor::Builder.build_file(result, 'path/to/output.gpx', creator: 'My Application')
+```
+
+### Input structure
+
+The builder expects a `GpxDoctor::Parser::Result` object with the following fields:
+
+- **`waypoints`** — Array of `GpxDoctor::Waypoint` objects (top-level waypoints)
+- **`routes`** — Array of `GpxDoctor::Route` objects
+- **`tracks`** — Array of `GpxDoctor::Track` objects
+- **`metadata`** — `GpxDoctor::Metadata` object (optional)
+
+All model classes are simple Ruby objects with attributes matching the GPX 1.1 specification (see **Model field reference** below).
+
+### Example: Creating a GPX file from scratch
+
+```ruby
+require 'gpx_doctor'
+
+# Create waypoints
+waypoint = GpxDoctor::Waypoint.new(
+  lat: 48.2093723,
+  lon: 16.356099,
+  ele: 160.0,
+  name: 'Vienna',
+  desc: 'Capital of Austria'
+)
+
+# Create a route with points
+route_point_1 = GpxDoctor::Waypoint.new(lat: 48.21, lon: 16.36, ele: 155.0)
+route_point_2 = GpxDoctor::Waypoint.new(lat: 48.22, lon: 16.37, ele: 162.0)
+
+route = GpxDoctor::Route.new(
+  name: 'City Tour',
+  desc: 'A route through the city',
+  points: [route_point_1, route_point_2]
+)
+
+# Create a track with segments
+track_point_1 = GpxDoctor::Waypoint.new(lat: 48.23, lon: 16.38, ele: 170.0)
+track_point_2 = GpxDoctor::Waypoint.new(lat: 48.24, lon: 16.39, ele: 175.0)
+
+segment = GpxDoctor::TrackSegment.new(points: [track_point_1, track_point_2])
+track = GpxDoctor::Track.new(
+  name: 'Morning Run',
+  desc: 'My morning jog',
+  segments: [segment]
+)
+
+# Create metadata (optional)
+metadata = GpxDoctor::Metadata.new(
+  name: 'My GPX File',
+  desc: 'A custom GPX file',
+  time: Time.now
+)
+
+# Build the result object
+result = GpxDoctor::Parser::Result.new(
+  waypoints: [waypoint],
+  routes: [route],
+  tracks: [track],
+  metadata: metadata
+)
+
+# Generate GPX XML
+xml_string = GpxDoctor::Builder.build(result, creator: 'My Application')
+
+# Or write directly to a file
+GpxDoctor::Builder.build_file(result, 'my_route.gpx', creator: 'My Application')
+```
+
+### Round-trip workflow
+
+You can parse an existing GPX file, modify it, and build it back:
+
+```ruby
+# Parse existing file
+result = GpxDoctor::Parser.parse('input.gpx')
+
+# Modify data
+result.routes.first.name = 'Updated Route Name'
+result.waypoints << GpxDoctor::Waypoint.new(lat: 48.5, lon: 16.5, name: 'New Point')
+
+# Build back to GPX
+GpxDoctor::Builder.build_file(result, 'output.gpx')
+```
+
 ## Model field reference
 
 ### `Waypoint`
@@ -114,6 +261,10 @@ result.metadata  # => #<Metadata …>  (or nil)
 | `pdop` | Float | |
 | `ageofdgpsdata` | Float | |
 | `dgpsid` | Integer | 0–1023 |
+| `distance_to_next` | Float | Distance to next point (metres or feet based on `unit_system`) — set by `segment_statistics: true` |
+| `elevation_change` | Float | Elevation change to next point (metres or feet based on `unit_system`) — set by `segment_statistics: true` |
+| `direction` | Float | Bearing to next point (0–360°) — set by `segment_statistics: true` |
+| `cumulative_distance` | Float | Cumulative distance from segment/route start (kilometres or miles based on `unit_system`) — set by `cumulative_distance: true` |
 
 `Waypoint#to_h` returns a hash of all non-nil fields.
 

data/lib/gpx_doctor/configuration.rb

@@ -5,13 +5,22 @@ module GpxDoctor
     attr_accessor :elevation_server,
                   :elevation_server_url,
                   :elevation_server_user,
-                  :elevation_server_password
+                  :elevation_server_password,
+                  :unit_system
 
     def initialize
       @elevation_server          = false
       @elevation_server_url      = nil
       @elevation_server_user     = nil
       @elevation_server_password = nil
+      @unit_system               = :metric
+    end
+
+    def unit_system=(value)
+      unless [:metric, :imperial].include?(value)
+        raise ArgumentError, "unit_system must be :metric or :imperial"
+      end
+      @unit_system = value
     end
   end
 end

data/lib/gpx_doctor/cumulative_distance_enhancer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  class CumulativeDistanceEnhancer
+    # Enhances each waypoint with cumulative distance from the start of the segment/route.
+    # The first point receives cumulative_distance = 0.0
+    # Each subsequent point receives cumulative_distance = previous.cumulative_distance + distance from previous
+    # Distance is stored in kilometers for metric and miles for imperial.
+    #
+    # Mutates waypoints in place.
+    def enhance(waypoints)
+      return if waypoints.nil? || waypoints.empty?
+
+      unit_system = GpxDoctor.configuration.unit_system
+
+      cumulative = 0.0
+      waypoints.first.cumulative_distance = cumulative
+
+      waypoints.each_cons(2) do |current, nxt|
+        distance_meters = DistanceCalculator.distance(current, nxt)
+        distance_km = distance_meters / 1000.0
+        distance_converted = UnitConverter.convert_cumulative_distance(distance_km, unit_system)
+        cumulative += distance_converted
+        nxt.cumulative_distance = cumulative
+      end
+    end
+  end
+end

data/lib/gpx_doctor/errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  class Error < StandardError; end
+  class InvalidGpxError < Error; end
+end

data/lib/gpx_doctor/geojson_builder.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module GpxDoctor
+  # Builds GeoJSON output from parsed GPX data according to RFC 7946.
+  #
+  # RFC 7946 compliance:
+  # - Coordinate order: [longitude, latitude, elevation]
+  # - LineString geometries require minimum 2 positions
+  # - MultiLineString segments require minimum 2 positions each
+  # - Empty or invalid geometries are filtered out
+  # - Properties member is null when no properties exist
+  class GeoJsonBuilder
+    class << self
+      def build(result)
+        new(result).build
+      end
+
+      def build_file(result, file_path)
+        json = build(result)
+        File.write(file_path, json)
+        json
+      end
+    end
+
+    def initialize(result)
+      @result = result
+    end
+
+    def build
+      features = []
+      features.concat(waypoint_features)
+      features.concat(route_features)
+      features.concat(track_features)
+
+      JSON.generate(
+        type: 'FeatureCollection',
+        features: features
+      )
+    end
+
+    private
+
+    def waypoint_features
+      @result.waypoints.map { |wpt| point_feature(wpt) }
+    end
+
+    def route_features
+      @result.routes.map do |route|
+        coords = route.points.map { |pt| coordinate(pt) }
+        # RFC 7946: LineString must have 2 or more positions
+        next if coords.length < 2
+
+        props = route_properties(route)
+        {
+          type: 'Feature',
+          properties: props.empty? ? nil : props,
+          geometry: {
+            type: 'LineString',
+            coordinates: coords
+          }
+        }
+      end.compact
+    end
+
+    def track_features
+      @result.tracks.map do |track|
+        # RFC 7946: Each LineString in MultiLineString must have 2+ positions
+        coords = track.segments.map do |seg|
+          seg_coords = seg.points.map { |pt| coordinate(pt) }
+          seg_coords if seg_coords.length >= 2
+        end.compact
+
+        # Skip tracks with no valid segments
+        next if coords.empty?
+
+        props = track_properties(track)
+        {
+          type: 'Feature',
+          properties: props.empty? ? nil : props,
+          geometry: {
+            type: 'MultiLineString',
+            coordinates: coords
+          }
+        }
+      end.compact
+    end
+
+    def point_feature(wpt)
+      props = waypoint_properties(wpt)
+      {
+        type: 'Feature',
+        properties: props.empty? ? nil : props,
+        geometry: {
+          type: 'Point',
+          coordinates: coordinate(wpt)
+        }
+      }
+    end
+
+    def coordinate(point)
+      coord = [point.lon, point.lat]
+      coord << point.ele if point.ele
+      coord
+    end
+
+    def waypoint_properties(wpt)
+      props = {}
+      props[:name]  = wpt.name  if wpt.name
+      props[:desc]  = wpt.desc  if wpt.desc
+      props[:sym]   = wpt.sym   if wpt.sym
+      props[:type]  = wpt.type  if wpt.type
+      props[:time]  = wpt.time.iso8601 if wpt.time
+      props
+    end
+
+    def route_properties(route)
+      props = {}
+      props[:name]   = route.name   if route.name
+      props[:desc]   = route.desc   if route.desc
+      props[:type]   = route.type   if route.type
+      props[:number] = route.number if route.number
+      props
+    end
+
+    def track_properties(track)
+      props = {}
+      props[:name]   = track.name   if track.name
+      props[:desc]   = track.desc   if track.desc
+      props[:type]   = track.type   if track.type
+      props[:number] = track.number if track.number
+      props
+    end
+  end
+end

data/lib/gpx_doctor/models/waypoint.rb

@@ -8,7 +8,7 @@ module GpxDoctor
         sym type fix sat hdop vdop pdop ageofdgpsdata dgpsid
       ].freeze
 
-      STATISTICS_FIELDS = %i[distance_to_next elevation_change direction].freeze
+      STATISTICS_FIELDS = %i[distance_to_next elevation_change direction cumulative_distance].freeze
 
       attr_accessor(*STATISTICS_FIELDS)
 

data/lib/gpx_doctor/parser.rb

@@ -20,7 +20,8 @@ module GpxDoctor
       end
 
       def parse_string(xml_string, params: {})
-        doc = Nokogiri::XML(xml_string)
+        Validator.validate!(xml_string)
+        doc = Nokogiri::XML(xml_string) { |config| config.nonet }
         ns  = detect_namespace(doc)
 
         new(doc, ns, params: params).parse
@@ -52,6 +53,7 @@ module GpxDoctor
       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_cumulative_distance(result) if @params[:cumulative_distance]
       enhance_elevations(result) if @params[:enhance_elevation]
 
       result
@@ -266,5 +268,13 @@ module GpxDoctor
         track.segments.each { |seg| enhancer.enhance(seg.points) }
       end
     end
+
+    def enhance_cumulative_distance(result)
+      enhancer = CumulativeDistanceEnhancer.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/statistics_enhancer.rb

@@ -3,20 +3,24 @@
 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)
+    #   - distance_to_next  (meters or feet depending on configuration)
+    #   - elevation_change  (meters or feet depending on configuration)
+    #   - 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
 
+      unit_system = GpxDoctor.configuration.unit_system
+
       waypoints.each_cons(2) do |current, nxt|
-        current.distance_to_next = DistanceCalculator.distance(current, nxt)
+        distance_meters = DistanceCalculator.distance(current, nxt)
+        current.distance_to_next = UnitConverter.convert_distance(distance_meters, unit_system)
 
         current.elevation_change = if current.ele && nxt.ele
-                                     nxt.ele - current.ele
+                                     elevation_change_meters = nxt.ele - current.ele
+                                     UnitConverter.convert_elevation(elevation_change_meters, unit_system)
                                    end
 
         current.direction = DistanceCalculator.bearing(current, nxt)

data/lib/gpx_doctor/unit_converter.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  module UnitConverter
+    METERS_TO_FEET = 3.28084
+    METERS_TO_MILES = 0.000621371
+    KILOMETERS_TO_MILES = 0.621371
+
+    module_function
+
+    # Convert meters to the configured unit system
+    # Returns feet for imperial, meters for metric
+    def convert_distance(meters, unit_system = :metric)
+      return meters if unit_system == :metric
+      meters * METERS_TO_FEET
+    end
+
+    # Convert meters to the configured unit system
+    # Returns feet for imperial, meters for metric
+    def convert_elevation(meters, unit_system = :metric)
+      return meters if unit_system == :metric
+      meters * METERS_TO_FEET
+    end
+
+    # Convert kilometers to the configured unit system
+    # Returns miles for imperial, kilometers for metric
+    def convert_cumulative_distance(kilometers, unit_system = :metric)
+      return kilometers if unit_system == :metric
+      kilometers * KILOMETERS_TO_MILES
+    end
+  end
+end

data/lib/gpx_doctor/validator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module GpxDoctor
+  class Validator
+    ALLOWED_VERSIONS = %w[1.0 1.1].freeze
+
+    # Matches a DOCTYPE declaration anywhere in the string (case-insensitive).
+    # DOCTYPE is rejected entirely because it can carry external-entity
+    # references (XXE) or internal entity bombs (billion-laughs).
+    DOCTYPE_PATTERN = /<!DOCTYPE/i.freeze
+
+    class << self
+      def validate!(xml_string)
+        new(xml_string).validate!
+      end
+    end
+
+    def initialize(xml_string)
+      @xml_string = xml_string
+    end
+
+    # Raises GpxDoctor::InvalidGpxError if the input is not a valid, safe GPX document.
+    def validate!
+      reject_doctype!
+      doc = parse_xml!
+      validate_root!(doc)
+      validate_version!(doc)
+      true
+    end
+
+    private
+
+    def reject_doctype!
+      return unless @xml_string.match?(DOCTYPE_PATTERN)
+
+      raise InvalidGpxError, 'DOCTYPE declarations are not allowed'
+    end
+
+    def parse_xml!
+      doc = Nokogiri::XML(@xml_string) { |config| config.nonet }
+      return doc if doc.errors.empty?
+
+      raise InvalidGpxError, "Invalid XML: #{doc.errors.map(&:message).join('; ')}"
+    end
+
+    def validate_root!(doc)
+      root = doc.root
+      return if root&.name == 'gpx'
+
+      raise InvalidGpxError, 'Root element must be <gpx>'
+    end
+
+    def validate_version!(doc)
+      version = doc.root['version']
+      return if ALLOWED_VERSIONS.include?(version)
+
+      raise InvalidGpxError,
+            "Unsupported GPX version: #{version.inspect}. Supported versions: #{ALLOWED_VERSIONS.join(', ')}"
+    end
+  end
+end

data/lib/gpx_doctor/version.rb

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

data/lib/gpx_doctor.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require 'gpx_doctor/version'
+require 'gpx_doctor/errors'
 require 'gpx_doctor/configuration'
+require 'gpx_doctor/validator'
 require 'gpx_doctor/models/email'
 require 'gpx_doctor/models/link'
 require 'gpx_doctor/models/copyright'
@@ -13,12 +15,15 @@ require 'gpx_doctor/models/track_segment'
 require 'gpx_doctor/models/route'
 require 'gpx_doctor/models/track'
 require 'gpx_doctor/distance_calculator'
+require 'gpx_doctor/unit_converter'
 require 'gpx_doctor/elevation_client'
 require 'gpx_doctor/statistics_enhancer'
+require 'gpx_doctor/cumulative_distance_enhancer'
 require 'gpx_doctor/segment_splitter'
 require 'gpx_doctor/point_selector'
 require 'gpx_doctor/parser'
 require 'gpx_doctor/builder'
+require 'gpx_doctor/geojson_builder'
 
 module GpxDoctor
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gpx_doctor
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Poltrax
@@ -47,8 +47,11 @@ files:
 - lib/gpx_doctor.rb
 - lib/gpx_doctor/builder.rb
 - lib/gpx_doctor/configuration.rb
+- lib/gpx_doctor/cumulative_distance_enhancer.rb
 - lib/gpx_doctor/distance_calculator.rb
 - lib/gpx_doctor/elevation_client.rb
+- lib/gpx_doctor/errors.rb
+- lib/gpx_doctor/geojson_builder.rb
 - lib/gpx_doctor/models/bounds.rb
 - lib/gpx_doctor/models/copyright.rb
 - lib/gpx_doctor/models/email.rb
@@ -63,6 +66,8 @@ files:
 - lib/gpx_doctor/point_selector.rb
 - lib/gpx_doctor/segment_splitter.rb
 - lib/gpx_doctor/statistics_enhancer.rb
+- lib/gpx_doctor/unit_converter.rb
+- lib/gpx_doctor/validator.rb
 - lib/gpx_doctor/version.rb
 homepage: https://github.com/Poltrax-live/gpx-doctor
 licenses: