gpx_doctor 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 804ebe2457e24c9688e6e8993d0dc3d4adab7b7fddc27478706eaf72a9d09f59
-  data.tar.gz: e1bb3e8d17ff968a1cd6414c736d9f444559f447d5e6cc8dd3c79175a394b68b
+  metadata.gz: 62f11c008dcbf53c4585d1cc1d4935555ddecbfc98ce4db4f0141476f2847ce3
+  data.tar.gz: ebf37bed3a22db9e84a6a0d1b593f2e3f9e9bf0146f114a06d8b900cc2e853f8
 SHA512:
-  metadata.gz: f8e5bd2ab41937b0faa004c5d1c1ae3c422ba9d332e3aa1ea353fe7f9c22706c0f53e5b3c8161361e8d38ead9bed4fa516d7415d580cc912bdc3976452107dfb
-  data.tar.gz: 68e78f3a4f84027272a1a96127b998d2a00c447e1f0b75daff611a8d3123c374df0ab6ebf92563e6ab516a4ff9d2bcaa2540dabdad8358a9d35f87fd4cd23860
+  metadata.gz: b096d0f32832c3ecd0147bd5b6066dd18f1fd19233af68101d486b5a4895febb2228da30fd907b849436a1feaca98bc707cfd2a0963b05b0587962d11a803f85
+  data.tar.gz: 5cf20d498a2247483904a86ca637bff0cc527bafe74f7c312d869694ef05fa798f675940f536980240eab12a90034bed42e841bcc6056bf43fb5505484baddc8

data/README.md

@@ -89,6 +89,7 @@ result = GpxDoctor::Parser.parse("path/to/file.gpx", params: {
   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
+  label_interval:     1.0,           # insert an interpolated, labelled point at every interval mark (kilometres or miles based on unit_system)
   enhance_elevation:  true,          # fetch missing elevations from the configured elevation server
   full_poi_data:      true           # populate result.pois with start/finish boundary data for the whole GPX and each track segment
 })
@@ -100,13 +101,16 @@ Processing is applied in the following order:
 2. `max_points` — point reduction
 3. `segment_statistics` — per-point statistics (distance, bearing, elevation change)
 4. `cumulative_distance` — cumulative distance from the start of each segment/route
-5. `enhance_elevation` — elevation lookup via the elevation server
-6. `full_poi_data` — POI boundary extraction (start, finish, and per-segment boundaries)
+5. `label_interval` — labelled point insertion
+6. `enhance_elevation` — elevation lookup via the elevation server
+7. `full_poi_data` — POI boundary extraction (start, finish, and per-segment boundaries)
 
 `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).
 
+`label_interval: 1.0` walks each route/segment and inserts an interpolated point at every multiple of the given interval (measured as cumulative distance from the start, in kilometres for `:metric` or miles for `:imperial` — see **Unit System** above), setting the new point's `label` field to that distance (e.g. `1.0` for the point at the 1.0 km/mi mark). A mark falling on an existing point (within a small tolerance) is skipped rather than duplicated. `label_interval` runs after `cumulative_distance`, reusing its `cumulative_distance` values instead of recalculating them when `cumulative_distance: true` is also given. **Because `label_interval` is applied after `max_points`, the resulting number of points may exceed `max_points`.**
+
 `full_poi_data: true` populates `result.pois` with the first and last geographic point of the entire GPX (across all routes and track segments), plus optional per-segment boundary data. Distances within each segment start at 0.0 and reflect that segment's length only. The `ele` key is omitted for points that have no elevation value. The global `finish` distance is the sum of all individual collection lengths. See **`result.pois`** below for the output shape.
 
 ## Accessing data
@@ -294,7 +298,8 @@ GpxDoctor::Builder.build_file(result, 'output.gpx')
 | `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` |
+| `cumulative_distance` | Float | Cumulative distance from segment/route start (kilometres or miles based on `unit_system`) — set by `cumulative_distance: true`; also set (to the same value as `label`) for points inserted by `label_interval` |
+| `label` | Float | Cumulative distance mark for a point inserted by `label_interval` (kilometres or miles based on `unit_system`); `nil` for points not created for labelling — set by `label_interval` |
 
 `Waypoint#to_h` returns a hash of all non-nil fields.
 

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 cumulative_distance].freeze
+      STATISTICS_FIELDS = %i[distance_to_next elevation_change direction cumulative_distance label].freeze
 
       attr_accessor(*STATISTICS_FIELDS)
 

data/lib/gpx_doctor/parser.rb

@@ -54,6 +54,7 @@ module GpxDoctor
       select_max_points(result) if @params[:max_points]
       enhance_statistics(result) if @params[:segment_statistics]
       enhance_cumulative_distance(result) if @params[:cumulative_distance]
+      label_points(result) if @params[:label_interval]
       enhance_elevations(result) if @params[:enhance_elevation]
       result.pois = build_pois(result) if @params[:full_poi_data]
 
@@ -278,6 +279,15 @@ module GpxDoctor
       end
     end
 
+    def label_points(result)
+      labeler = PointLabeler.new
+      interval = @params[:label_interval]
+      result.routes.each { |route| route.points = labeler.label(route.points, interval) }
+      result.tracks.each do |track|
+        track.segments.each { |seg| seg.points = labeler.label(seg.points, interval) }
+      end
+    end
+
     def point_to_poi(point, distance)
       poi = { lon: point.lon, lat: point.lat }
       poi[:ele] = point.ele if point.ele

data/lib/gpx_doctor/point_labeler.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module GpxDoctor
+  class PointLabeler
+    # Tolerance (in the configured distance unit) used to decide whether a
+    # label distance coincides with an existing point, to avoid inserting a
+    # near-duplicate point right next to it.
+    EPSILON = 1e-9
+
+    # Inserts an interpolated point at every multiple of +label_interval+
+    # measured as cumulative distance from the start of +points+ (kilometres
+    # for :metric, miles for :imperial — see GpxDoctor.configuration.unit_system).
+    #
+    # When +points+ already carry a +cumulative_distance+ (set by
+    # GpxDoctor::CumulativeDistanceEnhancer), those values are reused instead
+    # of being recalculated. Otherwise cumulative distance is computed from
+    # scratch.
+    #
+    # Existing points are left untouched. A new point is inserted between the
+    # two existing points that bracket each label distance, with lat/lon
+    # always interpolated, and ele/time interpolated only when both endpoints
+    # have values. The new point's +label+ field is set to the target
+    # distance (e.g. 1.0 for the point at the 1.0 km/mi mark).
+    #
+    # A label distance that falls (within a small tolerance) on an existing
+    # point is skipped — no duplicate point is inserted.
+    #
+    # Returns a new array; the original is not mutated. When +points+ has
+    # fewer than 2 elements, or +label_interval+ is nil, zero or negative,
+    # the original array is returned unchanged.
+    def label(points, label_interval)
+      return points if points.nil? || points.size < 2 || label_interval.nil? || label_interval <= 0
+
+      cumulative = cumulative_distances(points)
+
+      result = [points.first]
+      label_interval = label_interval.to_f
+      target = label_interval
+
+      points.each_cons(2).with_index do |(a, b), i|
+        start_dist = cumulative[i]
+        end_dist = cumulative[i + 1]
+
+        while target <= end_dist + EPSILON
+          if target > start_dist + EPSILON && target < end_dist - EPSILON
+            result << interpolate(a, b, start_dist, end_dist, target)
+          end
+          target += label_interval
+        end
+
+        result << b
+      end
+
+      result
+    end
+
+    private
+
+    # Returns the cumulative distance of every point, reusing each point's
+    # already-computed +cumulative_distance+ (see CumulativeDistanceEnhancer)
+    # when available, to avoid walking the points and recalculating distances
+    # a second time.
+    def cumulative_distances(points)
+      return points.map(&:cumulative_distance) if precomputed?(points)
+
+      unit_system = GpxDoctor.configuration.unit_system
+
+      cumulative = [0.0]
+      points.each_cons(2) do |a, b|
+        distance_km = DistanceCalculator.distance(a, b) / 1000.0
+        distance_converted = UnitConverter.convert_cumulative_distance(distance_km, unit_system)
+        cumulative << cumulative.last + distance_converted
+      end
+      cumulative
+    end
+
+    def precomputed?(points)
+      points.all? { |p| p.respond_to?(:cumulative_distance) && !p.cumulative_distance.nil? }
+    end
+
+    def interpolate(a, b, start_dist, end_dist, target)
+      fraction = (target - start_dist) / (end_dist - start_dist)
+      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,
+        label: target,
+        cumulative_distance: target
+      )
+    end
+  end
+end

data/lib/gpx_doctor/version.rb

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

data/lib/gpx_doctor.rb

@@ -21,6 +21,7 @@ require 'gpx_doctor/statistics_enhancer'
 require 'gpx_doctor/cumulative_distance_enhancer'
 require 'gpx_doctor/segment_splitter'
 require 'gpx_doctor/point_selector'
+require 'gpx_doctor/point_labeler'
 require 'gpx_doctor/parser'
 require 'gpx_doctor/builder'
 require 'gpx_doctor/geojson_builder'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gpx_doctor
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Poltrax
@@ -63,6 +63,7 @@ files:
 - lib/gpx_doctor/models/track_segment.rb
 - lib/gpx_doctor/models/waypoint.rb
 - lib/gpx_doctor/parser.rb
+- lib/gpx_doctor/point_labeler.rb
 - lib/gpx_doctor/point_selector.rb
 - lib/gpx_doctor/segment_splitter.rb
 - lib/gpx_doctor/statistics_enhancer.rb