hillpace 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 865ed429b462ed2c5715b1ca6b582a47cde2fba3
+  data.tar.gz: 9f0b932215cd03f7d53a8672740b1e49ddc85cb8
+SHA512:
+  metadata.gz: b88e9025cf018b4bdf8dee78e4fe90335e879367496dee5817901bd6f73efaf38765a78ba1ab1270551e06fa5a6ff239f5e4b573f8a577e9fa2ba5462f0fdb00
+  data.tar.gz: 6496edc92a564a6abae32ba801f906c09b429ffb447daff16d1cb0641d98e88a4c0b343bfea492582f1f26ee6764bdaf500236982b66e03192dcf397a8ac4325

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Juan Ramírez Ruiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,77 @@
+# HillPace
+
+HillPace is a library for planning running races. It can take the GPX or TCX of a route and a reference pace (the pace you would go on ideal conditions) and generate planned paces by segments, based on configurable external factors like the climb grade of each segment.
+
+### Status
+
+This is a work in progress, but the core of the code is functional.
+
+[![Code Climate](https://codeclimate.com/github/juanramirez/hillpace/badges/gpa.svg)](https://codeclimate.com/github/juanramirez/hillpace)
+
+#### Installation
+
+Go to the root directory of the package and run:
+```
+bundle install
+```
+
+#### Main dependencies
+
+* [Nokogiri](http://www.nokogiri.org/)
+* [Geokit](https://github.com/geokit/geokit)
+* [geoelevation](https://github.com/tkrajina/geoelevations)
+
+**Important**: Notice that [geoelevation](https://github.com/tkrajina/geoelevations) needs the whole [SRTM database](https://en.wikipedia.org/wiki/Shuttle_Radar_Topography_Mission) to work and it will download it automatically on `~/.elevations.rb` on the first run (this can be hundreds of MB, but it is only necessary once).
+
+#### Code organization
+
+* [lib/hillpace](lib/hillpace): contains the core classes of the package, which manage paces, routes, segments and track points
+* [lib/hillpace/input](lib/hillpace/input) contains classes for importing routes (at the moment, just GPX)
+* [lib/hillpace/pace_adjuster](lib/hillpace/pace_adjuster) contains the pace adjuster and its strategies
+* [lib/hillpace/race_planner](lib/hillpace/race_planner) contains a convenient race planner to, based on a strategy, just obtain the data for a combination of route, split distances and reference pace.
+* [specs](specs) contains the specs :)
+* [example.rb](example.rb) contains an example of use (see the [Example](README.md####example) section)
+
+#### Tests
+
+All classes in the codebase are tested, and you can run those tests by typing:
+```
+bundle exec rake tests
+```
+
+#### Example
+
+An example can be found in [examples/race_planning.rb](race_planning.rb), and it can be run this way:
+```
+bundle exec rake example
+```
+
+We use a GPX exported from [this Garmin Connect activity](https://connect.garmin.com/modern/activity/770166012) which maps the [2015 Granada Half Marathon](http://www.granada.es/inet/MediaMaraton.nsf/xnotweb/3F5884FDDFD1A9EDC1257E43004048B9?open).
+
+The example is assumed to get that GPX and an input pace of 4:08 minutes per km, which is my theoretical pace for a flat course, and gives the following output:
+
+```
+Example: Granada Half Marathon (from flat surface pace: 4:08 min/km)
+0.0Km - 1.0Km (incline 1.85%): 04:30 min/km
+1.0Km - 2.0Km (incline 0.65%): 04:15 min/km
+2.0Km - 3.0Km (incline -2.7%): 03:41 min/km
+3.0Km - 4.0Km (incline 0.0%): 04:08 min/km
+4.0Km - 5.0Km (incline -1.6%): 03:51 min/km
+5.0Km - 6.0Km (incline 0.53%): 04:14 min/km
+6.0Km - 7.0Km (incline -1.03%): 03:57 min/km
+7.0Km - 8.0Km (incline 0.2%): 04:10 min/km
+8.0Km - 9.0Km (incline -0.4%): 04:03 min/km
+9.0Km - 10.0Km (incline 2.3%): 04:36 min/km
+10.0Km - 11.0Km (incline -0.47%): 04:02 min/km
+11.0Km - 12.0Km (incline -0.31%): 04:04 min/km
+12.0Km - 13.0Km (incline 1.99%): 04:32 min/km
+13.0Km - 14.0Km (incline -0.5%): 04:02 min/km
+14.0Km - 15.0Km (incline 1.47%): 04:25 min/km
+15.0Km - 16.0Km (incline 0.68%): 04:15 min/km
+16.0Km - 17.0Km (incline -0.95%): 03:57 min/km
+17.0Km - 18.0Km (incline 0.5%): 04:13 min/km
+18.0Km - 19.0Km (incline -1.6%): 03:51 min/km
+19.0Km - 20.0Km (incline -0.49%): 04:02 min/km
+20.0Km - 21.0Km (incline 0.19%): 04:10 min/km
+21.0Km - 21.23Km (incline -0.43%): 04:03 min/km
+```

data/lib/hillpace.rb

@@ -0,0 +1,16 @@
+require 'nokogiri'
+require 'geoelevation'
+
+require 'hillpace/version'
+require 'hillpace/pace'
+require 'hillpace/track_point'
+require 'hillpace/segment'
+require 'hillpace/route'
+require 'hillpace/import/kalman_filter'
+require 'hillpace/import/gpx/gpx_parser'
+require 'hillpace/import/tcx/tcx_parser'
+require 'hillpace/import/xml/xml_validator'
+require 'hillpace/pace_adjuster/pace_adjuster'
+require 'hillpace/pace_adjuster/strategies/mervs_running'
+require 'hillpace/pace_adjuster/strategies/lets_run_forum'
+require 'hillpace/race_planner/race_planner'

data/lib/hillpace/import/gpx/gpx_parser.rb

@@ -0,0 +1,100 @@
+module Hillpace
+  module Import
+    module Gpx
+      # Parser for GPX files (see http://www.topografix.com/gpx.asp).
+      class GpxParser
+        attr_reader :document
+
+        # Initializes a GpxParser object.
+        # @param gpx_content [string] The content of a GPX file.
+        def initialize(gpx_content)
+          @document = Nokogiri::XML gpx_content
+          @kalman_filter = KalmanFilter.new
+          @srtm = GeoElevation::Srtm.new
+        end
+
+        # Creates a new GpxParser object from a GPX file path.
+        # @param gpx_path [string] The path of the file to be parsed.
+        # @return [GpxParser]
+        def self.from_file(gpx_path)
+          new File.open gpx_path
+        end
+
+        # Creates a new GpxParser object from a GPX file URL.
+        # @param gpx_url [string] The URL of the file to be parsed.
+        # @return [GpxParser]
+        def self.from_url(gpx_url)
+          new open gpx_url
+        end
+
+        # Parses a GPX document.
+        # Looks for route nodes inside the document and parses them.
+        # @return [Route]
+        def parse
+          routes = Array.new
+          document.search('trk').each do |route_node|
+            routes << parse_route(route_node)
+          end
+          routes
+        end
+
+        private
+
+        # Parses a route node.
+        # Looks for segment nodes inside the route node and parses them.
+        # @param route_node [Nokogiri::XML::Node] The XML node corresponding to the route.
+        # @return [Route]
+        def parse_route(route_node)
+          segments = Array.new
+          route_node.search('trkseg').each do |segment_node|
+            segments << parse_segment(segment_node)
+          end
+          Route.new(segments)
+        end
+
+        # Parses a segment node.
+        # Looks for track point nodes inside the segment node and parses them.
+        # @param segment_node [Nokogiri::XML::Node] The XML node corresponding to the segment.
+        # @return [Segment]
+        def parse_segment(segment_node)
+          @kalman_filter.reset
+          track_points = Array.new
+
+          segment_node.search('trkpt').each do |track_point_node|
+            track_points << parse_track_point(track_point_node)
+          end
+
+          Segment.new track_points
+        end
+
+        # Parses a track point node.
+        # Looks for the attributes of a track node (longitude, latitude, elevation and time) and creates a TrackPoint object
+        # accordingly.
+        #
+        # Note: These attributes don't need to be exactly the ones the GPX provides.
+        # For longitude and latitude, a Kalman filter is applied if the time is also provided.
+        # Also, the elevation is not got from the GPX, but deduced from longitude and latitude.
+        #
+        # @param track_point_node [Nokogiri::XML::Node] The XML node corresponding to the track point.
+        # @return [TrackPoint]
+        def parse_track_point(track_point_node)
+          longitude = (track_point_node ['lon']).to_f
+          latitude = (track_point_node ['lat']).to_f
+
+          # Yes, we could do
+          # elevation = (track_point_node.at('ele').content).to_f
+          # but elevation from GPX not reliable in some cases.
+          # Google Maps API is expensive, so we get data from SRTM database
+          # (see https://en.wikipedia.org/wiki/Shuttle_Radar_Topography_Mission)
+          elevation = @srtm.get_elevation(latitude, longitude)
+
+          track_point = TrackPoint.new longitude, latitude, elevation
+          track_point.time = Time.parse track_point_node.at('time').content unless track_point_node.search('time').empty?
+          @kalman_filter.apply track_point
+        end
+
+        private_class_method :new
+      end
+    end
+  end
+end

data/lib/hillpace/import/kalman_filter.rb

@@ -0,0 +1,58 @@
+module Hillpace
+  module Import
+    # See https://en.wikipedia.org/wiki/Kalman_filter
+    # Based on this implementation by Stochastically: http://stackoverflow.com/a/15657798/1147175
+    class KalmanFilter
+      ACCURACY = 3.0
+
+      # Initializes a KalmanFilter object.
+      def initialize
+        reset
+      end
+
+      # Resets a KalmanFilter object.
+      def reset
+        @variance = -1.0
+      end
+
+      # Applies the filter to a track point
+      # @param track_point [TrackPoint] The track point which will be filtered.
+      # @return [TrackPoint]
+      def apply(track_point)
+        if track_point.time.nil?
+          return track_point
+        elsif @variance < 0
+          @track_point = track_point
+          @variance = ACCURACY ** 2
+        else
+          time_delta = track_point.time - @track_point.time
+          if time_delta > 0
+            @variance += time_delta * (get_speed(@track_point, track_point, time_delta) ** 2)
+            @track_point.time = track_point.time
+          end
+
+          k = @variance / (@variance + ACCURACY ** 2)
+          @track_point.longitude += k * (track_point.longitude - @track_point.longitude)
+          @track_point.latitude += k * (track_point.latitude - @track_point.latitude)
+          @track_point.elevation += k * (track_point.elevation - @track_point.elevation)
+
+          @variance = (1.0 - k) * @variance
+        end
+
+        @track_point.clone
+      end
+
+      private
+
+      # Gets the speed from two trackpoints with their time difference.
+      # @param previous_track_point [TrackPoint] The previous track point.
+      # @param track_point [TrackPoint] The current track point
+      # @param time_delta [Number] The time difference between the track points.
+      # @return [Number]
+      def get_speed(previous_track_point, track_point, time_delta)
+        distance_delta = previous_track_point.distance_meters_to track_point
+        distance_delta / time_delta
+      end
+    end
+  end
+end

data/lib/hillpace/import/tcx/tcx_parser.rb

@@ -0,0 +1,103 @@
+module Hillpace
+  module Import
+    module Tcx
+      # Parser for TCX files (see https://en.wikipedia.org/wiki/Training_Center_XML).
+      class TcxParser
+        attr_reader :document
+
+        # Initializes a TcxParser object.
+        # @param tcx_content [string] The content of a TCX file.
+        def initialize(tcx_content)
+          @document = Nokogiri::XML tcx_content
+          @kalman_filter = KalmanFilter.new
+          @srtm = GeoElevation::Srtm.new
+        end
+
+        # Creates a new TcxParser object from a TCX file path.
+        # @param tcx_path [string] The path of the file to be parsed.
+        # @return [TcxParser]
+        def self.from_file(tcx_path)
+          new File.open tcx_path
+        end
+
+        # Creates a new TcxParser object from a TCX file URL.
+        # @param tcx_url [string] The URL of the file to be parsed.
+        # @return [TcxParser]
+        def self.from_url(tcx_url)
+          new open tcx_url
+        end
+
+        # Parses a TCX document.
+        # Looks for route nodes inside the document and parses them.
+        # @return [Route]
+        def parse
+          routes = Array.new
+          document.search('Activity').each do |route_node|
+            routes << parse_route(route_node)
+          end
+          routes
+        end
+
+        private
+
+        # Parses a route node.
+        # Looks for segment nodes inside the route node and parses them.
+        # @param route_node [Nokogiri::XML::Node] The XML node corresponding to the route.
+        # @return [Route]
+        def parse_route(route_node)
+          segments = Array.new
+          route_node.search('Lap').each_with_index do |segment_node, index|
+            segment = parse_segment(segment_node)
+            # Start new segment with last known point, as segments are not consecutive in TCX.
+            segment.track_points.unshift(segments.last.track_points.last.clone) unless index == 0
+            segments << segment
+          end
+          Route.new(segments)
+        end
+
+        # Parses a segment node.
+        # Looks for track point nodes inside the segment node and parses them.
+        # @param segment_node [Nokogiri::XML::Node] The XML node corresponding to the segment.
+        # @return [Segment]
+        def parse_segment(segment_node)
+          @kalman_filter.reset
+          track_points = Array.new
+
+          segment_node.search('Trackpoint').each do |track_point_node|
+            track_points << parse_track_point(track_point_node)
+          end
+
+          Segment.new track_points
+        end
+
+        # Parses a track point node.
+        # Looks for the attributes of a track node (longitude, latitude and elevation) and creates a TrackPoint object
+        # accordingly.
+        #
+        # Note: These attributes don't need to be exactly the ones the TCX provides.
+        # For longitude and latitude, a Kalman filter is applied if the time is also provided.
+        # Also, the elevation is not got from the TCX, but deduced from longitude and latitude.
+        #
+        # @param track_point_node [Nokogiri::XML::Node] The XML node corresponding to the track point.
+        # @return [TrackPoint]
+        def parse_track_point(track_point_node)
+          longitude = track_point_node.at('Position').at('LongitudeDegrees').content.to_f
+          latitude = track_point_node.at('Position').at('LatitudeDegrees').content.to_f
+
+          # Yes, we could do
+          # elevation = (track_point_node.at('ele').content).to_f
+          # but elevation from GPX not reliable in some cases.
+          # Google Maps API is expensive, so we get data from SRTM database
+          # (see https://en.wikipedia.org/wiki/Shuttle_Radar_Topography_Mission)
+          elevation = @srtm.get_elevation(latitude, longitude)
+
+          track_point = TrackPoint.new longitude, latitude, elevation
+          track_point.time = Time.parse track_point_node.at('Time').content
+          @kalman_filter.apply track_point
+        end
+
+        private_class_method :new
+      end
+    end
+  end
+end

data/lib/hillpace/import/xml/xml_validator.rb

@@ -0,0 +1,59 @@
+require 'nokogiri'
+require 'open-uri'
+
+module Hillpace
+  module Import
+    module Xml
+      # Validator for XML files
+      class XmlValidator
+        DEFAULT_GPX_SCHEMA_URL = 'http://www.topografix.com/gpx/1/1/gpx.xsd'
+        DEFAULT_TCX_SCHEMA_URL = 'http://www8.garmin.com/xmlschemas/TrainingCenterDatabasev2.xsd'
+
+        attr_reader :schema
+
+        # Initializes a XmlValidator object.
+        # @param schema_content [string] The content of an XML schema file.
+        def initialize(schema_content)
+          @schema = Nokogiri::XML::Schema schema_content
+        end
+
+        # Creates a new XmlValidator object from an XML schema file path.
+        # @param schema_path [String] The path of the XML schema file to use.
+        # @return [XmlValidator]
+        def self.from_file(schema_path)
+          new File.open(schema_path)
+        end
+
+        # Creates a new XmlValidator object from an XML schema file URL.
+        # @param schema_url [String] The URL of the XML schema file to use.
+        # @return [XmlValidator]
+        def self.from_url(schema_url)
+          new open(schema_url)
+        end
+
+        # Creates a new XmlValidator object using the default GPX schema.
+        #   (see http://www.topografix.com/gpx.asp)
+        # @return [XmlValidator]
+        def self.from_gpx_schema
+          new open(DEFAULT_GPX_SCHEMA_URL)
+        end
+
+        # Creates a new XmlValidator object using the default TCX schema.
+        #   (see https://en.wikipedia.org/wiki/Training_Center_XML)
+        # @return [XmlValidator]
+        def self.from_tcx_schema
+          new open(DEFAULT_TCX_SCHEMA_URL)
+        end
+
+        # Validates an XML file content and return errors found.
+        # @return [Array<Nokogiri::XML::SyntaxError>]
+        def validate(xml_content)
+          document = Nokogiri::XML xml_content
+          schema.validate document
+        end
+
+        private_class_method :new
+      end
+    end
+  end
+end

data/lib/hillpace/pace.rb

@@ -0,0 +1,47 @@
+module Hillpace
+  # Represents a pace.
+  class Pace
+    METERS_PER_KILOMETER = 1000
+    SECONDS_IN_AN_HOUR = 3600
+
+    attr_reader :meters_per_second
+
+    # Inicializes a Pace object.
+    # @param meters_per_second [Number] The pace expressed in meters per second.
+    def initialize(meters_per_second)
+      @meters_per_second = meters_per_second
+    end
+
+    # Creates a new Pace object from a pace expressed in seconds per kilometer.
+    # @param seconds_per_km [Number] The pace expressed in seconds per kilometer.
+    def self.from_seconds_per_km(seconds_per_km)
+      meters_per_second = METERS_PER_KILOMETER / seconds_per_km.to_f
+      new meters_per_second
+    end
+
+    # Creates a new Pace object from a pace expressed in meters per second.
+    # @param meters_per_second [Number] The pace expressed in meters per second.
+    def self.from_meters_per_second(meters_per_second)
+      new meters_per_second
+    end
+
+    # Returns the pace in seconds per kilometer.
+    # @return [Number]
+    def seconds_per_km
+      METERS_PER_KILOMETER / @meters_per_second.to_f
+    end
+
+    # Returns the pace in minutes per kilometer.
+    # @return [String]
+    # @raise [RuntimeError] if the pace is slower than an hour per kilometer.
+    def minutes_per_km
+      if seconds_per_km >= SECONDS_IN_AN_HOUR
+        raise 'Too slow pace: more than an hour per kilometer.'
+      end
+
+      Time.at(seconds_per_km).strftime '%M:%S'
+    end
+
+    private_class_method :new
+  end
+end

data/lib/hillpace/pace_adjuster/pace_adjuster.rb

@@ -0,0 +1,20 @@
+module Hillpace
+  module PaceAdjuster
+
+    class PaceAdjuster
+      # Initializes a PaceAdjuster object.
+      # @param strategy [Proc] The adjust strategy that the pace adjuster will use.
+      def initialize(strategy)
+        @strategy = strategy
+      end
+
+      # Adjusts a reference pace depending on the incline.
+      # @param pace [Pace] A reference pace,
+      # @param incline [Number] An incline value.
+      # @return [Pace]
+      def adjust_pace(pace, incline)
+        @strategy.call pace, incline
+      end
+    end
+  end
+end

data/lib/hillpace/pace_adjuster/strategies/lets_run_forum.rb

@@ -0,0 +1,12 @@
+module Hillpace
+  module PaceAdjuster
+    module Strategies
+      # source: http://www.letsrun.com/forum/flat_read.php?thread=197366&page=0
+      LETS_RUN_FORUM = lambda do |pace, incline|
+        division_factor = 1.0 + (incline * 9)
+        Hillpace::Pace.from_meters_per_second(pace.meters_per_second / division_factor)
+      end
+    end
+  end
+end
+

data/lib/hillpace/pace_adjuster/strategies/mervs_running.rb

@@ -0,0 +1,11 @@
+module Hillpace
+  module PaceAdjuster
+    module Strategies
+      # source: http://merv.stanford.edu/runcalc?Request=explanation
+      MERVS_RUNNING = lambda do |pace, incline|
+        division_factor = 1.0 - (incline * 4.5)
+        Pace.from_seconds_per_km(pace.seconds_per_km / division_factor)
+      end
+    end
+  end
+end

data/lib/hillpace/race_planner/race_planner.rb

@@ -0,0 +1,30 @@
+module Hillpace
+  module RacePlanner
+    class RacePlanner
+
+      def initialize(strategy)
+        @pace_adjuster = Hillpace::PaceAdjuster::PaceAdjuster.new strategy
+      end
+
+      def plan_race(route, split_distances, reference_pace)
+        splitted_route = route.split split_distances
+        segments = splitted_route.segments.clone.lazy
+        race_plan = []
+
+        accumulated_distance = 0
+        segments.each do |segment|
+          segment_plan = {
+              :segment_start => accumulated_distance,
+              :segment_end => accumulated_distance + segment.distance_meters,
+              :incline => segment.incline,
+              :adjusted_pace => @pace_adjuster.adjust_pace(reference_pace, segment.incline)
+          }
+          race_plan << segment_plan
+          accumulated_distance += segment.distance_meters
+        end
+
+        race_plan
+      end
+    end
+  end
+end

data/lib/hillpace/route.rb

@@ -0,0 +1,94 @@
+module Hillpace
+  # Represents a geographic route in the Earth, made out of consecutive segments.
+  class Route
+    attr_reader :segments
+
+    # Initializes a Route object.
+    # @param segments [Array<Segment>] The segments of the route.
+    # @raise [RuntimeError] if _segments_ is not a collection of [Segment] objects.
+    # @raise [RuntimeError] if any of the _segments_ start is not the same point of the previous segment
+    #   end.
+    def initialize(segments)
+      raise 'Invalid segment array to initialize Route' unless segments.respond_to?('each') &&
+          segments.all? {|segment| segment.is_a? Segment}
+
+      unless segments.empty?
+        last_track_point = segments.first.track_points.first
+        segments.each do |segment|
+          raise 'Segments must be consecutive' unless last_track_point == segment.track_points.first
+          last_track_point = segment.track_points.last
+        end
+      end
+
+      @segments = segments
+    end
+
+    # Measures the distance of the route, in meters.
+    # @return [Number]
+    def distance_meters
+      segments.inject(0) {|result, segment| result + segment.distance_meters}
+    end
+
+    # Measures the elevation difference from the start to the end of the route, in meters.
+    # @return [Number]
+    def climb
+      segments.inject(0) {|result, segment| result + segment.climb}
+    end
+
+    # Measures the climb of the route relative to its distance.
+    # @return [Number]
+    def incline
+      self.climb / self.distance_meters
+    end
+
+    # Measures the sum of uphills between segments of the route.
+    # @return [Number]
+    def total_uphills
+      segments.inject(0) {|result, segment| result + segment.total_uphills}
+    end
+
+    # Measures the sum of downhills between segments of the route.
+    # @return [Number]
+    def total_downhills
+      segments.inject(0) {|result, segment| result + segment.total_downhills}
+    end
+
+    # Measures the duration of the route, in seconds.
+    # @return [Number]
+    def duration
+      segments.inject(0) {|result, segment| result + segment.duration}
+    end
+
+    # Measures the pace of the route.
+    # @return [Pace]
+    def pace
+      Pace.from_meters_per_second(distance_meters / duration)
+    end
+
+    # Splits the segments in the route in the distances indicated.
+    # @param split_distances [Array<Number>] Distances where the segments of the route should be splitted.
+    # @return [Route] A copy of this route, with splitted segments
+    def split(split_distances)
+      split_distances_enumerator = split_distances.sort.each
+      next_split_distance = split_distances_enumerator.next
+      accumulated_distance = 0
+      result = []
+
+      segments.lazy.each do |segment|
+        while next_split_distance < accumulated_distance + segment.distance_meters
+          subsegments = segment.split (next_split_distance - accumulated_distance)
+          result << subsegments.first
+          accumulated_distance += subsegments.first.distance_meters
+          if subsegments.length > 1
+            segment = subsegments.last
+            next_split_distance = split_distances_enumerator.next rescue Float::INFINITY
+          end
+        end
+        result << segment.clone
+        accumulated_distance += segment.distance_meters
+      end
+
+      Route.new result
+    end
+  end
+end

data/lib/hillpace/segment.rb

@@ -0,0 +1,132 @@
+require 'geokit'
+
+module Hillpace
+  # Represents a geographic segment in the Earth, made out of sorted track points.
+  class Segment
+    attr_reader :track_points
+
+    # Initializes a Segment object.
+    # @param track_points [Array<TrackPoint>] The track points of the segment.
+    # @raise [RuntimeError] if _track_points_ is not a collection of [TrackPoint]
+    #   objects.
+    def initialize(track_points)
+      raise 'Invalid track point array to initialize Segment' unless track_points.respond_to?('each') &&
+          track_points.all? {|track_point| track_point.is_a? TrackPoint}
+      @track_points = track_points
+    end
+
+    # Overwrites the #== operator to be able to use custom getters.
+    # @param other [Segment] The other segment to be compared.
+    # @return [boolean]
+    def ==(other)
+      self.class == other.class &&
+          track_points == other.track_points
+    end
+
+    # Measures the distance of the segment, in meters.
+    # @return [Number]
+    def distance_meters
+      return 0 if track_points.length <= 1
+
+      result = 0
+      latest_track_point = track_points.first
+      track_points.each do |track_point|
+        next if track_point.equal? latest_track_point
+        result += latest_track_point.distance_meters_to track_point
+        latest_track_point = track_point
+      end
+      result
+    end
+
+    # Measures the elevation difference from the start to the end of the segment, in meters.
+    # @return [Number]
+    def climb
+      return 0 if track_points.length <= 1
+      track_points.first.climb_to track_points.last
+    end
+
+    # Measures the climb of the segment relative to its distance.
+    # @return [Number]
+    def incline
+      return 0 if track_points.length <= 1
+      self.climb / self.distance_meters
+    end
+
+    # Measures the sum of uphills between track points of the segment.
+    # @return [Number]
+    def total_uphills
+      return 0 if track_points.length <= 1
+
+      result = 0
+      latest_track_point = track_points.first
+      track_points.each do |track_point|
+        if track_point.elevation > latest_track_point.elevation
+          result += latest_track_point.climb_to(track_point)
+        end
+        latest_track_point = track_point
+      end
+      result
+    end
+
+    # Measures the sum of downhills between track points of the segment.
+    # @return [Number]
+    def total_downhills
+      return 0 if track_points.length <= 1
+
+      result = 0
+      latest_track_point = track_points.first
+      track_points.each do |track_point|
+        if track_point.elevation < latest_track_point.elevation
+          result -= latest_track_point.climb_to(track_point)
+        end
+        latest_track_point = track_point
+      end
+      result
+    end
+
+    # Measures the duration of the segment, in seconds.
+    # @return [Number]
+    def duration
+      track_points.last.time.to_f - track_points.first.time.to_f
+    end
+
+    # Measures the pace of the segment.
+    # @return [Pace]
+    def pace
+      Pace.from_meters_per_second(distance_meters / duration)
+    end
+
+    # Returns an array of segments, result of splitting _self_ in the distance indicated.
+    # @param distance_meters [Number] The distance in the segment where it should be splitted.
+    # @return [Array<Segment>]
+    def split(distance_meters)
+      result = []
+      accumulated_distance = 0
+      latest_track_point = track_points.first
+      subsegment_track_points = [latest_track_point]
+
+      track_points.lazy.each_with_index do |track_point, index|
+        next if index == 0
+        distance_delta = latest_track_point.distance_meters_to track_point
+        accumulated_distance += distance_delta
+
+        if result.empty?
+          # in case the distance exceeds the reference distance, we add an interpolated track point
+          # both to the end of the actual subsegment and to the start of the next one
+          if accumulated_distance > distance_meters
+            bias = (distance_meters - (accumulated_distance - distance_delta)) / distance_delta
+            interpolated_track_point = latest_track_point.get_linear_interpolation_with track_point, bias
+            subsegment_track_points << interpolated_track_point
+            result << (Segment.new subsegment_track_points)
+            subsegment_track_points = [interpolated_track_point]
+          end
+        end
+
+        subsegment_track_points << track_point.clone
+        latest_track_point = track_point
+      end
+
+      result << (Segment.new subsegment_track_points)
+    end
+  end
+end

data/lib/hillpace/track_point.rb

@@ -0,0 +1,123 @@
+require 'geokit'
+
+module Hillpace
+  # Represents a geographic track point in the Earth.
+  class TrackPoint
+    attr_reader :longitude, :latitude, :elevation, :time
+
+    MINIMUM_LONGITUDE = -180
+    MAXIMUM_LONGITUDE = 180
+    MINIMUM_LATITUDE = -90
+    MAXIMUM_LATITUDE = 90
+
+    METERS_PER_KILOMETER = 1000
+
+    # Initializes a TrackPoint object.
+    # @param longitude [Number] The geographic longitude of the track point.
+    # @param latitude [Number] The geographic latitude of the track point.
+    # @param elevation [Number] The elevation of the track point relative to sea level.
+    # @param time [Time] The time when the track point was registered.
+    def initialize(longitude, latitude, elevation, time = nil)
+      self.longitude = longitude
+      self.latitude = latitude
+      self.elevation = elevation
+      self.time = time
+    end
+
+    # Overwrites the #== operator to be able to use custom getters.
+    # @param other [TrackPoint] The other track point to be compared.
+    # @return [boolean]
+    def ==(other)
+      self.class  == other.class &&
+          longitude   == other.longitude &&
+          latitude    == other.latitude &&
+          elevation   == other.elevation &&
+          time        == other.time
+    end
+
+    # Setter for the longitude class member.
+    # @param longitude [Number] The longitude value to be set.
+    # @raise [RuntimeError] if _longitude_ is invalid
+    def longitude=(longitude)
+      raise 'Invalid longitude' unless
+          longitude.is_a?(Numeric) &&
+              longitude >= MINIMUM_LONGITUDE &&
+              longitude <= MAXIMUM_LONGITUDE
+      @longitude = longitude
+    end
+
+    # Setter for the latitude class member.
+    # @param latitude [Number] The latitude value to be set.
+    # @raise [RuntimeError] if _latitude_ is invalid
+    def latitude=(latitude)
+      raise 'Invalid latitude' unless
+          latitude.is_a?(Numeric) &&
+              latitude >= MINIMUM_LATITUDE &&
+              latitude <= MAXIMUM_LATITUDE
+      @latitude = latitude
+    end
+
+    # Setter for the elevation class member.
+    # @param elevation [Number] The elevation value to be set.
+    # @raise [RuntimeError] if _elevation_ is not [Numeric]
+    def elevation=(elevation)
+      raise 'Invalid elevation' unless elevation.is_a? Numeric
+      @elevation = elevation
+    end
+
+    # Setter for the time class member.
+    # @param time [Time] The time to be set.
+    # @raise [RuntimeError] if _time_ is not a [Time]
+    def time=(time)
+      raise 'Invalid time' unless time.nil? || time.is_a?(Time)
+      @time = time
+    end
+
+    # Measures the distance to other track point, in meters.
+    # @param other [TrackPoint] The other track point to compare.
+    # @raise [RuntimeError] if _other_ is not a TrackPoint object
+    # @return [Number]
+    def distance_meters_to(other)
+      raise 'Invalid track point' unless other.is_a? TrackPoint
+      a = Geokit::GeoLoc.new({:lat => latitude, :lng => longitude})
+      b = Geokit::GeoLoc.new({:lat => other.latitude, :lng => other.longitude})
+      METERS_PER_KILOMETER * (a.distance_to b, {:units => :kms})
+    end
+
+    # Measures the elevation difference to other track point, in meters.
+    # @param other [TrackPoint] The other track point to compare.
+    # @raise [RuntimeError] if _other_ is not a TrackPoint object
+    # @return [Number]
+    def climb_to(other)
+      raise 'Invalid track point' unless other.is_a? TrackPoint
+      other.elevation - elevation
+    end
+
+    # Measures the elevation difference to other track point relative to the distance to it.
+    # @param other [TrackPoint] The other track point to compare.
+    # @raise [RuntimeError] if _other_ is not a TrackPoint object
+    # @return [Number]
+    def incline_to(other)
+      raise 'Invalid track point' unless other.is_a? TrackPoint
+      distance_meters = self.distance_meters_to other
+      return 0 if distance_meters == 0
+
+      (self.climb_to other) / distance_meters
+    end
+
+    # Returns a linear interpolation between _self_ and the one provided.
+    # @note For small distances between track points, a linear interpolation should be accurate enough.
+    # @param other [TrackPoint] The other track point to compare.
+    # @param bias [Number] Value which will determine the position in that line. *0* would be the position of _self_,
+    #   *1* would be _other_ position.
+    # @raise [Runtimeerror] if _other_ is not a TrackPoint object
+    # @return [Number]
+    def get_linear_interpolation_with(other, bias = 0.5)
+      raise 'Invalid track point' unless other.is_a? TrackPoint
+      TrackPoint.new longitude * (1.0 - bias) + other.longitude * bias,
+                     latitude * (1.0 - bias) + other.latitude * bias,
+                     elevation * (1.0 - bias) + other.elevation * bias,
+                     time.nil? || other.time.nil? ? nil : Time.at(time.to_f * (1.0 - bias) + other.time.to_f * bias)
+    end
+  end
+end

data/lib/hillpace/version.rb

@@ -0,0 +1,3 @@
+module Hillpace
+  VERSION = "0.0.2"
+end

metadata

@@ -0,0 +1,181 @@
+--- !ruby/object:Gem::Specification
+name: hillpace
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Juan Ramírez Ruiz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-11-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: zip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: geokit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: geoelevation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+description: |2
+      Hillpace is a gem for running races planning. It can take a route an a reference pace (the pace you would go on a
+      flat course of the same distance) and generate planned paces by segments, based on the incline of each segment.
+email:
+- juan.ramirez.ruiz@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/hillpace.rb
+- lib/hillpace/import/gpx/gpx_parser.rb
+- lib/hillpace/import/kalman_filter.rb
+- lib/hillpace/import/tcx/tcx_parser.rb
+- lib/hillpace/import/xml/xml_validator.rb
+- lib/hillpace/pace.rb
+- lib/hillpace/pace_adjuster/pace_adjuster.rb
+- lib/hillpace/pace_adjuster/strategies/lets_run_forum.rb
+- lib/hillpace/pace_adjuster/strategies/mervs_running.rb
+- lib/hillpace/race_planner/race_planner.rb
+- lib/hillpace/route.rb
+- lib/hillpace/segment.rb
+- lib/hillpace/track_point.rb
+- lib/hillpace/version.rb
+homepage: https://github.com/juanramirez/hillpace
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Estimate running paces depending on climb grade
+test_files: []
+has_rdoc: