calcpace 1.9.1 → 1.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed70195cc42127f49e9dac13a4ff5bc99b3a7b59fc9564261f4b03d52434d002
-  data.tar.gz: aa679a9e3876e166be6a3b5f74ccdb0293dcb017366e727331b9ca8579684917
+  metadata.gz: 9ee49b6b99023d43bef8396cb0c1ab9ba4ef99e6c96285b4c4405eb3d163807d
+  data.tar.gz: 442169e5414c141390261da86e5cc312eda98c685bbc64530ca7692d39773119
 SHA512:
-  metadata.gz: 5ae91d0ac1241bede3bb3723cde7af96c6b6cc8499a9f18306b6b9ca5b5cbd805c41c134a05a08d16e0495d9eac1b4b36e1431351fa4e3b612069623738ade5a
-  data.tar.gz: c0e2f265b25767744e92729ba5f3e8d83b57d0d262fbf9c72a94288ab3a28543c8581bb5c5944959813f73bcafbb523f0b290c2f787e00ae02f3ab07028312a3
+  metadata.gz: ae31a9047296eb8848030d08d35af80bd9af22f5ae5ac65de727e99b7448155918198caa2467edb5a3371c92d6f3f4b4c54adef1d0d8da51bc19b4b9cafb680d
+  data.tar.gz: 57b06d49de20b1415ec230c1d2bfd3ac495dc4c8c3ed25e684fcdf3072fef142728394942706aa39892b69eea3ce9b1b1e9f8c2fdb3efea7fbd3bd7e90016fa3

data/.rubocop.yml

@@ -62,6 +62,7 @@ Metrics/ClassLength:
 Metrics/ModuleLength:
   Exclude:
     - 'lib/calcpace/race_splits.rb'
+    - 'lib/calcpace/track_calculator.rb'
 
 # Allow both single and double quotes for strings
 Style/StringLiteralsInInterpolation:

data/README.md

@@ -1,404 +1,193 @@
-# Calcpace [![Gem Version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=rb&r=r&ts=1683906897&type=6e&v=1.9.0&x2=0)](https://badge.fury.io/rb/calcpace)
+# Calcpace [![Gem Version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=rb&r=r&ts=1683906897&type=6e&v=1.9.3&x2=0)](https://badge.fury.io/rb/calcpace)
 
-Calcpace is a Ruby gem designed for calculations and conversions related to distance and time. It can calculate velocity, pace, total time, and distance, accepting time in various formats, including HH:MM:SS. The gem supports conversion to 42 different units, including kilometers, miles, meters, and feet. It also provides methods to validate input.
+A Ruby gem for running and cycling calculations: pace, time, distance, unit conversions, race predictions, GPS track analysis, and VO2max estimation.
 
 ## Installation
 
-### Add to your Gemfile
-
 ```ruby
 gem 'calcpace', '~> 1.9'
 ```
 
-Then run:
-
-```bash
-bundle install
-```
-
-### Install the gem manually
-
-```bash
-gem install calcpace
-```
-
 ## Usage
 
-Before performing any calculations or conversions, create a new instance of Calcpace:
-
 ```ruby
 require 'calcpace'
-
-calculate = Calcpace.new
+calc = Calcpace.new
 ```
 
-### Calculate using Integers or Floats
+---
 
-Calcpace provides methods to calculate velocity, pace, total time, and distance. The methods are unit-agnostic, and the return value is a float. Here are some examples:
+### Basic Calculations
 
 ```ruby
-calculate.velocity(3625, 12275) # => 3.386206896551724
-calculate.pace(3665, 12) # => 305.4166666666667
-calculate.time(210, 12) # => 2520.0
-calculate.distance(9660, 120) # => 80.5
-```
-
-Tip: Use the `round` method to round a float. For example:
+calc.velocity(3625, 12275)          # => 3.386  (distance / time)
+calc.pace(3665, 12)                 # => 305.4  (time / distance)
+calc.time(210, 12)                  # => 2520.0 (pace × distance)
+calc.distance(9660, 120)            # => 80.5   (velocity × time)
 
-```ruby
-calculate.velocity(3625, 12275).round(3) # => 3.386
+# Clocktime input/output (HH:MM:SS or MM:SS)
+calc.clock_pace('01:00:00', 10)     # => "00:06:00"
+calc.clock_time('00:05:31', 12.6)   # => "01:09:30"
+calc.checked_distance('01:21:32', '00:06:27') # => 12.64
 ```
 
-Remember:
-
-- Velocity is the distance divided by the time (e.g., m/s or km/h).
-- Pace is the time divided by the distance (e.g., minutes/km or minutes/miles).
-- Total time is the distance divided by the velocity.
-- Distance is the velocity multiplied by the time.
+---
 
-### Calculate using Clocktime
+### Unit Conversions
 
-Calcpace also provides methods to calculate using clocktime (HH:MM:SS or MM:SS format string). The return value will be in seconds or clocktime, depending on the method called, except for `checked_distance`. Here are some examples:
+30+ units supported. String or symbol format:
 
 ```ruby
-# The return will be in the unit you input/seconds or seconds/unit you input
-calculate.checked_velocity('01:00:00', 12275) # => 3.4097222222222223
-calculate.checked_pace('01:21:32', 10) # => 489.2
-calculate.checked_time('00:05:31', 12.6) # => 4170.599999999999
-
-calculate.checked_distance('01:21:32', '00:06:27') # => 12.640826873385013
+calc.convert(10, :km_to_mi)         # => 6.21371
+calc.convert(10, 'mi to km')        # => 16.0934
+calc.convert(1, :m_s_to_km_h)       # => 3.6
 
-# The return will be in clocktime
-calculate.clock_pace('01:21:32', 10) # => "00:08:09"
-calculate.clock_velocity('01:00:00', 10317) # => "00:00:02"
-calculate.clock_time('00:05:31', 12.6) # => "01:09:30"
-```
-
-Note: Using the `clock` methods may be less precise than using other methods due to conversions.
-
-You can also use BigDecimal for more precise calculations. For example:
-
-```ruby
-require 'bigdecimal'
-calculate.checked_velocity('10:00:00', 10317).to_d # => #<BigDecimal:7f9f1b8b1d08,'0.2865833333 333333E1',27(36)>
+# Chain conversions
+calc.convert_chain(1, [:km_to_mi, :mi_to_feet])  # => 3280.84
 ```
 
-To learn more about BigDecimal, check the [documentation](https://ruby-doc.org/stdlib-2.7.1/libdoc/bigdecimal/rdoc/BigDecimal.html).
-
-### Convert Distances and Velocities
-
-Use the `convert` method to convert a distance or velocity. The first parameter is the value to be converted, and the second parameter is the unit to which the value will be converted. The unit can be a string (e.g. 'km to meters') or a symbol (e.g. :km_to_meters). The gem supports 42 different units, including kilometers, miles, meters, knots, and feet.
-
-Here are some examples:
-
-```ruby
-converter.convert(10, :km_to_meters) # => 1000
-converter.convert(10, 'mi to km') # => 16.0934
-converter.convert(1, :nautical_mi_to_km) # => 1.852
-converter.convert(1, 'km h to m s') # => 0.277778
-converter.convert(1, :m_s_to_mi_h) # => 2.23694
-```
-
-| Conversion Unit      | Description                 |
-|----------------------|-----------------------------|
-| :km_to_mi            | Kilometers to Miles         |
-| :mi_to_km            | Miles to Kilometers         |
-| :nautical_mi_to_km   | Nautical Miles to Kilometers |
-| :km_to_nautical_mi   | Kilometers to Nautical Miles |
-| :meters_to_km        | Meters to Kilometers        |
-| :km_to_meters        | Kilometers to Meters        |
-| :meters_to_mi        | Meters to Miles             |
-| :mi_to_meters        | Miles to Meters             |
-| :m_s_to_km_h         | Meters per Second to Kilometers per Hour    |
-| :km_h_to_m_s         | Kilometers per Hour to Meters per Second    |
-| :m_s_to_mi_h         | Meters per Second to Miles per Hour    |
-| :mi_h_to_m_s         | Miles per Hour to Meters per Second    |
-| :m_s_to_feet_s       | Meters per Second to Feet per Second    |
-| :feet_s_to_m_s       | Feet per Second to Meters per Second    |
-| :km_h_to_mi_h        | Kilometers per Hour to Miles per Hour    |
-| :mi_h_to_km_h        | Miles per Hour to Kilometers per Hour    |
-
-You can list all the available units [here](/lib/calcpace/converter.rb), or using `list` methods. The return will be a hash with the unit and a description of the unit.
-
-```ruby
-converter.list_all
-# => {:km_to_mi=>"KM to MI", :mi_to_km=>"MI to KM", ...}
-
-converter.list_distance
-# => {:km_to_mi=>"KM to MI", :mi_to_km=>"MI to KM", ...}
-
-converter.list_speed
-# => {:m_s_to_km_h=>"M S to KM H", :km_h_to_m_s=>"KM H to M S", ...}
-```
-
-### Chain Conversions
-
-Perform multiple conversions in sequence with the converter chain feature:
-
-```ruby
-calc = Calcpace.new
-
-# Convert kilometers to miles to feet in one call
-calc.convert_chain(1, [:km_to_mi, :mi_to_feet])
-# => 3280.84 (1 km = 0.621 mi = 3280.84 feet)
-
-# Convert with description for debugging
-calc.convert_chain_with_description(100, [:meters_to_km, :km_to_mi])
-# => { result: 0.0621371, description: "100 → meters_to_km → km_to_mi → 0.0621" }
-
-# Speed conversions
-calc.convert_chain(10, [:m_s_to_km_h, :km_h_to_mi_h])
-# => 22.3694 (10 m/s = 36 km/h = 22.37 mi/h)
-```
+See all units: `calc.list_all`, `calc.list_distance`, `calc.list_speed`.
 
-### Race Pace Calculator
+---
 
-Calcpace includes a race pace calculator for standard race distances (5K, 10K, half-marathon, and marathon):
+### Pace Conversions
 
 ```ruby
-calc = Calcpace.new
-
-# Calculate finish time for a race given a pace
-calc.race_time(300, '5k')              # => 1500.0 (5:00/km pace for 5K = 25:00)
-calc.race_time_clock('05:00', 'marathon') # => '03:30:58' (5:00/km pace for marathon)
-
-# Calculate required pace for a target finish time
-calc.race_pace('00:30:00', '5k')       # => 360.0 (need 6:00/km to finish 5K in 30:00)
-calc.race_pace_clock('04:00:00', 'marathon') # => '00:05:41' (need 5:41/km for 4-hour marathon)
-
-# List available race distances
-calc.list_races
-# => { '5k' => 5.0, '10k' => 10.0, 'half_marathon' => 21.0975, 'marathon' => 42.195 }
+calc.pace_km_to_mi('05:00')   # => "00:08:02"
+calc.pace_mi_to_km('08:00')   # => "00:04:58"
 ```
 
-Supported race distances:
-- `5k` - 5 kilometers
-- `10k` - 10 kilometers
-- `half_marathon` - 21.0975 kilometers
-- `marathon` - 42.195 kilometers
-- `1mile` - 1.60934 kilometers
-- `5mile` - 8.04672 kilometers
-- `10mile` - 16.0934 kilometers
+---
 
-### Pace Conversions
-
-Convert running pace between kilometers and miles:
+### Race Pace & Time
 
 ```ruby
-calc = Calcpace.new
-
-# Convert pace from km to miles
-calc.pace_km_to_mi('05:00')           # => '00:08:02' (5:00/km = 8:02/mi)
-calc.convert_pace('05:00', :km_to_mi) # => '00:08:02' (same as above)
-
-# Convert pace from miles to km
-calc.pace_mi_to_km('08:00')           # => '00:04:58' (8:00/mi ≈ 4:58/km)
-calc.convert_pace('08:00', :mi_to_km) # => '00:04:58' (same as above)
-
-# Works with numeric input (seconds) as well
-calc.pace_km_to_mi(300)               # => '00:08:02' (300 seconds/km)
-calc.pace_mi_to_km(480)               # => '00:04:58' (480 seconds/mi)
-
-# String format also supported
-calc.convert_pace('05:00', 'km to mi') # => '00:08:02'
+calc.race_time_clock('05:00', 'marathon')          # => "03:30:58"
+calc.race_pace_clock('04:00:00', 'marathon')       # => "00:05:41"
+calc.list_races  # => { '5k' => 5.0, '10k' => 10.0, 'half_marathon' => 21.0975, ... }
 ```
 
-The pace conversions are particularly useful when:
-- Planning races in different countries (metric vs imperial)
-- Comparing training paces with international runners
-- Converting workout plans between pace formats
+---
 
 ### Race Splits
 
-Calculate split times for races to help pace your race strategy:
-
 ```ruby
-calc = Calcpace.new
-
-# Even pace splits for half marathon (every 5k)
+# Even pace — default
 calc.race_splits('half_marathon', target_time: '01:30:00', split_distance: '5k')
 # => ["00:21:20", "00:42:40", "01:03:59", "01:25:19", "01:30:00"]
 
-# Kilometer splits for 10K
-calc.race_splits('10k', target_time: '00:40:00', split_distance: '1k')
-# => ["00:04:00", "00:08:00", "00:12:00", ..., "00:40:00"]
-
-# Mile splits for marathon
-calc.race_splits('marathon', target_time: '03:30:00', split_distance: '1mile')
-# => ["00:08:02", "00:16:04", ..., "03:30:00"]
-
-# Negative splits strategy (second half faster)
+# Strategies: :even (default), :negative (second half faster), :positive (first half faster)
 calc.race_splits('10k', target_time: '00:40:00', split_distance: '5k', strategy: :negative)
-# => ["00:20:48", "00:40:00"] # First 5k slower, second 5k faster
-
-# Positive splits strategy (first half faster)
-calc.race_splits('10k', target_time: '00:40:00', split_distance: '5k', strategy: :positive)
-# => ["00:19:12", "00:40:00"] # First 5k faster, second 5k slower
+# => ["00:20:48", "00:40:00"]
 ```
 
-Supported strategies:
-- `:even` - Constant pace throughout (default)
-- `:negative` - Second half ~4% faster (progressive race)
-- `:positive` - First half ~4% faster (conservative start)
-
-Split distances can be:
-- Standard race distances: `'5k'`, `'10k'`, `'1mile'`, etc.
-- Custom distances: `2.5` (in kilometers), `'3k'`, etc.
+---
 
 ### Race Time Predictions
 
-Predict your race times at different distances based on a recent performance using the **Riegel formula**:
+**Riegel formula** (`T2 = T1 × (D2/D1)^1.06`):
 
 ```ruby
-calc = Calcpace.new
-
-# Predict marathon time from a 5K result
-calc.predict_time_clock('5k', '00:20:00', 'marathon')
-# => "03:11:49" (predicts 3:11:49 marathon from 20:00 5K)
-
-# Predict 10K time from half marathon
-calc.predict_time_clock('half_marathon', '01:30:00', '10k')
-# => "00:40:47"
-
-# Get predicted pace for target race
-calc.predict_pace_clock('5k', '00:20:00', 'marathon')
-# => "00:04:32" (4:32/km pace for predicted marathon)
-
-# Get complete equivalent performance info
+calc.predict_time_clock('5k', '00:20:00', 'marathon')   # => "03:11:49"
+calc.predict_pace_clock('5k', '00:20:00', 'marathon')   # => "00:04:32"
 calc.equivalent_performance('10k', '00:42:00', '5k')
-# => {
-#      time: 1209.0,
-#      time_clock: "00:20:09",
-#      pace: 241.8,
-#      pace_clock: "00:04:02"
-#    }
+# => { time: 1209.0, time_clock: "00:20:09", pace: 241.8, pace_clock: "00:04:02" }
 ```
 
-#### How the Riegel Formula Works
-
-The Riegel formula is a mathematical model that predicts race performance across different distances:
+**Cameron formula** (exponential correction — tends to be more conservative from short distances):
 
-**Formula:** `T2 = T1 × (D2/D1)^1.06`
-
-Where:
-- **T1** = your known time at distance D1
-- **T2** = predicted time at distance D2
-- **D1** = known race distance (in km)
-- **D2** = target race distance (in km)
-- **1.06** = fatigue/endurance factor
+```ruby
+calc.predict_time_cameron_clock('10k', '00:42:00', 'marathon')  # => "02:57:46"
+calc.predict_pace_cameron_clock('10k', '00:42:00', 'marathon')  # => "00:04:13"
+```
 
-**The 1.06 exponent** represents how pace slows as distance increases. If endurance was perfect (1.0), doubling distance would simply double time. But in reality, you slow down slightly - the 1.06 factor accounts for this accumulated fatigue.
+---
 
-**Example:** From a 5K in 20:00, predict marathon time:
-- T1 = 1200 seconds (20:00)
-- D1 = 5 km
-- D2 = 42.195 km (marathon)
-- T2 = 1200 × (42.195/5)^1.06
-- T2 = 1200 × 9.591 = 11,509 seconds
-- T2 = **3:11:49**
+### GPS Track Analysis
 
-The formula works best for:
-- Distances from 5K to marathon
-- Recent race results (within 6-8 weeks)
-- Similar terrain and weather conditions
-- Well-trained runners with consistent pacing
+Accepts an array of hashes with `:lat`, `:lon`, and optionally `:ele` (metres) and `:time` (`Time`):
 
-**Important notes:**
-- Predictions assume equal training and effort across distances
-- Results are estimates - actual performance varies by individual fitness, training focus, and race conditions
-- The formula is most accurate when predicting between similar distance ranges (e.g., 10K to half marathon)
+```ruby
+points = [
+  { lat: -23.5505, lon: -46.6333, ele: 760.0, time: Time.parse('2024-01-01 07:00:00') },
+  { lat: -23.5510, lon: -46.6400, ele: 765.0, time: Time.parse('2024-01-01 07:05:00') },
+  { lat: -23.5520, lon: -46.6480, ele: 758.0, time: Time.parse('2024-01-01 07:10:00') },
+]
 
-### Race Time Predictions — Cameron Formula
+calc.haversine_distance(-23.5505, -46.6333, -23.5510, -46.6340)  # => 0.089 km
+calc.track_distance(points)    # => 0.87 km
+calc.elevation_gain(points)    # => { gain: 5.0, loss: 7.0 }
+calc.track_splits(points, 1.0) # => [{ km: 1, elapsed: 312, pace: "05:12" }, ...]
+```
 
-An alternative predictor using the **Cameron formula**, which applies an exponential correction based on the known distance. Unlike Riegel's fixed power-law exponent, Cameron's correction is larger when predicting from shorter races (where anaerobic capacity plays a bigger role) and diminishes as the known distance increases.
+**Haversine formula** — great-circle distance on a sphere (R = 6,371 km). Accuracy: ~0.3% of GPS/WGS84. Best for running and cycling distances; not for geodetic surveying.
 
-```ruby
-calc = Calcpace.new
+---
 
-# Predict marathon time from 10K
-calc.predict_time_cameron_clock('10k', '00:42:00', 'marathon')
-# => "02:57:46"
+### VO2max Estimation
 
-# Predict 10K from 5K
-calc.predict_time_cameron_clock('5k', '00:20:00', '10k')
-# => "00:42:24"
+Estimate aerobic fitness from a race result using the **Daniels & Gilbert formula** (1979):
 
-# Get predicted pace per km
-calc.predict_pace_cameron_clock('10k', '00:42:00', 'marathon')
-# => "00:04:13"
+```ruby
+calc.estimate_vo2max(10.0, '00:40:00')   # => 51.9 ml/kg/min
+calc.estimate_vo2max(42.195, '03:30:00') # => 44.8
+calc.estimate_vo2max(5.0, 2400)          # also accepts total seconds
 
-# Raw seconds (useful for further calculations)
-calc.predict_time_cameron('5k', '00:20:00', 'half_marathon')
-# => 5382.7 (approximately 1:29:42)
+calc.vo2max_label(51.9)  # => "Very Good"
 ```
 
-#### How the Cameron Formula Works
+| VO2max (ml/kg/min) | Level     |
+|--------------------|-----------|
+| ≥ 70               | Elite     |
+| 60–69              | Excellent |
+| 50–59              | Very Good |
+| 40–49              | Good      |
+| 30–39              | Fair      |
+| < 30               | Beginner  |
 
-**Formula:** `T2 = T1 × (D2/D1) × [(a + b × e^(-D1/c)) / (a + b × e^(-D2/c))]`
-
-Where:
-- **T1** = known time, **D1** = known distance (km)
-- **T2** = predicted time, **D2** = target distance (km)
-- **a = 0.000495**, **b = 0.000985**, **c = 1.4485** (empirical constants)
-
-The exponential correction factor `f(d) = a + b × e^(-d/c)` decreases as distance grows. When predicting from a short race to a long one, `f(D1) > f(D2)`, making `T2` grow slightly faster than a pure linear extrapolation — accounting for the greater fatigue at longer distances.
+**Formula:**
+```
+velocity (m/min) = distance_m / time_min
+VO2              = −4.60 + 0.182258·v + 0.000104·v²
+%VO2max          = 0.8 + 0.1894393·e^(−0.012778·t) + 0.2989558·e^(−0.1932605·t)
+VO2max           = VO2 / %VO2max
+```
 
-**Compared to Riegel:**
-- Predicting from short distances (5K): Cameron tends to be more conservative (slower prediction) — acknowledges that 5K speed has a larger anaerobic component
-- Predicting from moderate distances (10K): Cameron tends to be slightly more optimistic — 10K is already a strong predictor of marathon aerobic capacity
-- Both formulas are estimates; real performance depends on training specificity, conditions, and individual physiology
+Accuracy: ±3–5 ml/kg/min vs. laboratory testing. Best with efforts between **5 and 60 minutes** at near-maximal pace.
 
-### Other Useful Methods
+---
 
-Calcpace also provides other useful methods:
+### Other Utilities
 
 ```ruby
-converter = Calcpace.new
-converter.convert_to_seconds('01:00:00') # => 3600
-converter.convert_to_clocktime(3600) # => '01:00:00'
-converter.convert_to_clocktime(100000) # => '1 03:46:40'
-converter.check_time('01:00:00') # => nil
+calc.convert_to_seconds('01:00:00')  # => 3600
+calc.convert_to_clocktime(3600)      # => "01:00:00"
+calc.check_time('01:00:00')          # => nil (valid)
 ```
 
-### Errors
+---
 
-The gem now raises specific custom error classes for invalid inputs, allowing for more precise error handling. These errors inherit from `Calcpace::Error`.
+### Errors
 
-- `Calcpace::NonPositiveInputError`: Raised when a numeric input is not positive.
-- `Calcpace::InvalidTimeFormatError`: Raised when a time string is not in the expected `HH:MM:SS` or `MM:SS` format.
+All errors inherit from `Calcpace::Error`:
 
-For example:
+- `Calcpace::NonPositiveInputError` — numeric input is zero or negative
+- `Calcpace::InvalidTimeFormatError` — time string not in `HH:MM:SS` or `MM:SS` format
 
-```ruby
-begin
-  calculate.pace(945, -1)
-rescue Calcpace::NonPositiveInputError => e
-  puts e.message # => "Distance must be a positive number"
-end
-
-begin
-  calculate.checked_time('string', 10)
-rescue Calcpace::InvalidTimeFormatError => e
-  puts e.message # => "It must be a valid time in the XX:XX:XX or XX:XX format"
-end
-```
+---
 
 ### Testing
 
-To run the tests, clone the repository and run:
-
 ```bash
 bundle exec rake
 ```
 
-### Supported Ruby Versions
-
-The tests are run using Ruby versions from 2.7.8 to 3.4.2, as specified in the `.github/workflows/test.yml` file.
+Requires Ruby >= 3.2.0.
 
 ## Contributing
 
-We welcome contributions to Calcpace! To contribute, clone this repository and submit a pull request. Please ensure that your code adheres to our style and includes tests where appropriate.
+Clone the repo and submit a pull request. Please include tests.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+[MIT License](https://opensource.org/licenses/MIT)

data/calcpace.gemspec

@@ -8,8 +8,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ['João Gilberto Saraiva']
   spec.email         = ['joaogilberto@tuta.io']
 
-  spec.summary       = 'A Ruby gem for pace, distance, and time calculations.'
-  spec.description   = 'Ruby gem for pace, distance, time, and speed calculations. Supports multiple units and formats.'
+  spec.summary       = 'Pace, distance, GPS track analysis, and VO2max calculations for runners and cyclists.'
+  spec.description   = 'Ruby gem for running and cycling calculations: pace, time, distance, ' \
+                       'unit conversions (30+ units), race predictions (Riegel & Cameron), ' \
+                       'GPS track analysis (Haversine, elevation gain, per-km splits), ' \
+                       'and VO2max estimation (Daniels & Gilbert).'
   spec.homepage      = 'https://github.com/0jonjo/calcpace'
   spec.metadata['source_code_uri'] = spec.homepage
   spec.license = 'MIT'

data/lib/calcpace/track_calculator.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+# Module for GPS track calculations
+#
+# This module provides pure mathematical methods for computing distances,
+# elevation changes, and pace splits from arrays of GPS coordinate points.
+# It does not perform any file I/O or GPX parsing — callers are responsible
+# for supplying arrays of hashes with the required keys.
+#
+# @example Calculate total distance of a track
+#   calc = Calcpace.new
+#   points = [
+#     { lat: -23.5505, lon: -46.6333 },
+#     { lat: -23.5510, lon: -46.6340 },
+#     { lat: -23.5520, lon: -46.6350 }
+#   ]
+#   calc.track_distance(points) #=> 0.17 (km)
+#
+# @example Calculate elevation gain and loss
+#   points = [
+#     { lat: -23.5505, lon: -46.6333, ele: 760.0 },
+#     { lat: -23.5510, lon: -46.6340, ele: 763.5 },
+#     { lat: -23.5515, lon: -46.6347, ele: 758.0 }
+#   ]
+#   calc.elevation_gain(points) #=> { gain: 3.5, loss: 5.5 }
+module TrackCalculator
+  # Mean radius of the Earth in kilometers (IAU standard)
+  EARTH_RADIUS_KM = 6371.0
+
+  # Computes the great-circle distance between two GPS coordinates using
+  # the Haversine formula.
+  #
+  # The Haversine formula calculates the shortest distance over the Earth's
+  # surface between two points defined by latitude and longitude. It assumes
+  # a spherical Earth (error < 0.3% vs. WGS84 ellipsoid), which is accurate
+  # enough for running and cycling purposes.
+  #
+  # Formula:
+  #   a = sin²(Δlat/2) + cos(lat1) × cos(lat2) × sin²(Δlon/2)
+  #   c = 2 × atan2(√a, √(1−a))
+  #   d = R × c
+  #
+  # @param lat1 [Numeric] latitude of first point in decimal degrees
+  # @param lon1 [Numeric] longitude of first point in decimal degrees
+  # @param lat2 [Numeric] latitude of second point in decimal degrees
+  # @param lon2 [Numeric] longitude of second point in decimal degrees
+  # @return [Float] distance in kilometers
+  # @raise [ArgumentError] if any coordinate is outside valid range (lat ±90, lon ±180)
+  #
+  # @example Distance between two points in São Paulo
+  #   haversine_distance(-23.5505, -46.6333, -23.5510, -46.6340)
+  #   #=> 0.089 (km)
+  def haversine_distance(lat1, lon1, lat2, lon2)
+    validate_coordinates(lat1, lon1)
+    validate_coordinates(lat2, lon2)
+    haversine_km(lat1, lon1, lat2, lon2)
+  end
+
+  # Calculates the total distance of a GPS track by summing Haversine distances
+  # between consecutive points.
+  #
+  # @param points [Array<Hash>] array of points with :lat and :lon keys (String or Symbol)
+  # @return [Float] total distance in kilometers, rounded to 2 decimal places
+  # @raise [ArgumentError] if any point has coordinates outside valid range
+  #
+  # @example
+  #   points = [
+  #     { lat: -23.5505, lon: -46.6333 },
+  #     { lat: -23.5510, lon: -46.6340 },
+  #     { lat: -23.5520, lon: -46.6350 }
+  #   ]
+  #   track_distance(points) #=> 0.17
+  def track_distance(points)
+    return 0.0 if points.nil? || points.size < 2
+
+    total = points.each_cons(2).sum do |a, b|
+      haversine_distance(fetch_coord(a, :lat), fetch_coord(a, :lon),
+                         fetch_coord(b, :lat), fetch_coord(b, :lon))
+    end
+
+    total.round(2)
+  end
+
+  # Calculates cumulative elevation gain and loss along a GPS track.
+  #
+  # Only consecutive pairs where both points have an :ele value are considered.
+  # Points missing :ele are silently skipped.
+  #
+  # @param points [Array<Hash>] array of points with optional :ele key (meters)
+  # @return [Hash] hash with :gain and :loss keys, both Floats rounded to 1 decimal
+  #
+  # @example
+  #   points = [
+  #     { lat: 0, lon: 0, ele: 100.0 },
+  #     { lat: 0, lon: 0, ele: 105.0 },
+  #     { lat: 0, lon: 0, ele: 102.0 }
+  #   ]
+  #   elevation_gain(points) #=> { gain: 5.0, loss: 3.0 }
+  def elevation_gain(points)
+    gain = 0.0
+    loss = 0.0
+    return { gain: gain, loss: loss } if points.nil? || points.size < 2
+
+    points.each_cons(2) do |a, b|
+      gain, loss = accumulate_elevation(gain, loss, fetch_ele(a), fetch_ele(b))
+    end
+
+    { gain: gain.round(1), loss: loss.round(1) }
+  end
+
+  # Calculates pace splits at regular distance intervals along a GPS track.
+  #
+  # Accumulates Haversine distance between consecutive points until the target
+  # split distance is reached, then records elapsed time and pace for that split.
+  # Any remaining distance at the end is included as a partial split.
+  #
+  # @param points [Array<Hash>] array of points with :lat, :lon, and :time keys.
+  #   :time must respond to #to_f (Unix timestamp) or be a Time object.
+  # @param split_km [Numeric] split interval in kilometers (default: 1.0)
+  # @return [Array<Hash>] array of split hashes, each with:
+  #   - :km [Float] cumulative distance at split end
+  #   - :elapsed [Integer] elapsed seconds from start of track to end of split
+  #   - :pace [String] pace for this split in MM:SS format
+  # @raise [ArgumentError] if split_km is not positive
+  # @raise [ArgumentError] if any point is missing a :time key
+  #
+  # @example 5 km track with 1 km splits
+  #   calc.track_splits(points, 1.0)
+  #   #=> [
+  #         { km: 1.0, elapsed: 312, pace: "05:12" },
+  #         { km: 2.0, elapsed: 624, pace: "05:12" },
+  #         ...
+  #       ]
+  def track_splits(points, split_km = 1.0)
+    raise ArgumentError, 'split_km must be positive' unless split_km.is_a?(Numeric) && split_km.positive?
+    return [] if points.nil? || points.size < 2
+
+    validate_points_have_time(points)
+    collect_splits(points, split_km)
+  end
+
+  private
+
+  def haversine_km(lat1, lon1, lat2, lon2)
+    dlat = deg_to_rad(lat2 - lat1)
+    dlon = deg_to_rad(lon2 - lon1)
+    a = haversine_a(dlat, dlon, lat1, lat2)
+    c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
+    EARTH_RADIUS_KM * c
+  end
+
+  def haversine_a(dlat, dlon, lat1, lat2)
+    (Math.sin(dlat / 2)**2) +
+      (Math.cos(deg_to_rad(lat1)) * Math.cos(deg_to_rad(lat2)) *
+      (Math.sin(dlon / 2)**2))
+  end
+
+  def deg_to_rad(degrees)
+    degrees * Math::PI / 180.0
+  end
+
+  def validate_coordinates(lat, lon)
+    unless lat.is_a?(Numeric) && lat >= -90 && lat <= 90
+      raise ArgumentError, "Invalid latitude: #{lat}. Must be between -90 and 90."
+    end
+
+    return if lon.is_a?(Numeric) && lon >= -180 && lon <= 180
+
+    raise ArgumentError, "Invalid longitude: #{lon}. Must be between -180 and 180."
+  end
+
+  def accumulate_elevation(gain, loss, ele_a, ele_b)
+    return [gain, loss] if ele_a.nil? || ele_b.nil?
+
+    diff = ele_b - ele_a
+    if diff.positive?
+      [gain + diff, loss]
+    else
+      [gain, loss + diff.abs]
+    end
+  end
+
+  def fetch_coord(point, key)
+    point[key] || point[key.to_s]
+  end
+
+  def fetch_ele(point)
+    val = point[:ele] || point['ele']
+    val&.to_f
+  end
+
+  def validate_points_have_time(points)
+    points.each_with_index do |pt, i|
+      next if pt[:time] || pt['time']
+
+      raise ArgumentError, "Point at index #{i} is missing :time key required for splits"
+    end
+  end
+
+  def point_time(point)
+    t = point[:time] || point['time']
+    t.respond_to?(:to_f) ? t.to_f : t
+  end
+
+  def interpolate_time(point_a, point_b, segment_km, distance_into_segment)
+    return point_time(point_a) if segment_km.zero?
+
+    t_a = point_time(point_a)
+    t_b = point_time(point_b)
+    t_a + ((t_b - t_a) * (distance_into_segment / segment_km))
+  end
+
+  def seconds_to_pace(seconds, km)
+    return '00:00' if km.zero?
+
+    pace_seconds = (seconds.to_f / km).round
+    format('%<min>02d:%<sec>02d', min: pace_seconds / 60, sec: pace_seconds % 60)
+  end
+
+  def collect_splits(points, split_km)
+    state = { splits: [], start_time: point_time(points.first),
+              split_start_time: point_time(points.first),
+              accumulated_km: 0.0, split_number: 1 }
+
+    points.each_cons(2) { |a, b| process_segment(a, b, split_km, state) }
+    append_partial_split(points.last, split_km, state)
+    state[:splits]
+  end
+
+  def process_segment(point_a, point_b, split_km, state)
+    segment_km = haversine_distance(fetch_coord(point_a, :lat), fetch_coord(point_a, :lon),
+                                    fetch_coord(point_b, :lat), fetch_coord(point_b, :lon))
+    state[:accumulated_km] += segment_km
+
+    while state[:accumulated_km] >= split_km * state[:split_number]
+      record_split(point_a, point_b, segment_km, split_km, state)
+    end
+  end
+
+  def record_split(point_a, point_b, segment_km, split_km, state)
+    offset = (split_km * state[:split_number]) - (state[:accumulated_km] - segment_km)
+    boundary_time = interpolate_time(point_a, point_b, segment_km, offset)
+    state[:splits] << build_split_entry(boundary_time, split_km, state)
+    state[:split_start_time] = boundary_time
+    state[:split_number] += 1
+  end
+
+  def build_split_entry(boundary_time, split_km, state)
+    split_elapsed = (boundary_time - state[:split_start_time]).round
+    {
+      km: (split_km * state[:split_number]).round(2),
+      elapsed: (boundary_time - state[:start_time]).round,
+      pace: seconds_to_pace(split_elapsed, split_km)
+    }
+  end
+
+  def append_partial_split(last_point, split_km, state)
+    remaining_km = state[:accumulated_km] - (split_km * (state[:split_number] - 1))
+    return unless remaining_km > 0.001
+
+    last_time = point_time(last_point)
+    state[:splits] << {
+      km: state[:accumulated_km].round(2),
+      elapsed: (last_time - state[:start_time]).round,
+      pace: seconds_to_pace((last_time - state[:split_start_time]).round, remaining_km)
+    }
+  end
+end

data/lib/calcpace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Calcpace
-  VERSION = '1.9.1'
+  VERSION = '1.9.3'
 end

data/lib/calcpace/vo2max_estimator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Module for estimating VO2max from a race performance
+#
+# Uses the Daniels & Gilbert formula (1979), which relates running velocity
+# and exercise duration to oxygen consumption as a percentage of VO2max.
+#
+# Formula:
+#   velocity (m/min)  = distance_m / time_min
+#   VO2               = -4.60 + 0.182258 * v + 0.000104 * v²
+#   %VO2max           = 0.8 + 0.1894393·e^(-0.012778·t) + 0.2989558·e^(-0.1932605·t)
+#   VO2max            = VO2 / %VO2max
+#
+# Accuracy: ±3–5 ml/kg/min vs laboratory testing. Best results with efforts
+# between 5 and 60 minutes at race pace (i.e. near-maximal effort).
+module Vo2maxEstimator
+  VO2MAX_LABELS = [
+    { min: 70, label: 'Elite' },
+    { min: 60, label: 'Excellent' },
+    { min: 50, label: 'Very Good' },
+    { min: 40, label: 'Good' },
+    { min: 30, label: 'Fair' },
+    { min: 0,  label: 'Beginner' }
+  ].freeze
+
+  # Estimates VO2max from a race performance using Daniels & Gilbert formula
+  #
+  # @param distance_km [Numeric] race distance in kilometres (must be > 0)
+  # @param time [String, Integer] finish time as "HH:MM:SS" / "MM:SS", or total seconds (must be > 0)
+  # @return [Float] estimated VO2max in ml/kg/min, rounded to one decimal place
+  # @raise [Calcpace::NonPositiveInputError] if distance or time are not positive
+  # @raise [Calcpace::InvalidTimeFormatError] if time string is not in HH:MM:SS or MM:SS format
+  #
+  # @example 10 km in 40:00 → ~51.9 ml/kg/min
+  #   calc = Calcpace.new
+  #   calc.estimate_vo2max(10.0, '00:40:00') #=> 51.9
+  def estimate_vo2max(distance_km, time)
+    distance_m = distance_km.to_f * 1000
+    time_min   = parse_time_minutes(time)
+
+    check_positive(distance_m, 'Distance')
+    check_positive(time_min,   'Time')
+
+    velocity    = distance_m / time_min
+    vo2         = vo2_at_velocity(velocity)
+    pct_vo2max  = percent_vo2max(time_min)
+
+    (vo2 / pct_vo2max).round(1)
+  end
+
+  # Returns a descriptive label for a given VO2max value
+  #
+  # @param value [Numeric] VO2max in ml/kg/min
+  # @return [String] label: "Beginner", "Fair", "Good", "Very Good", "Excellent", or "Elite"
+  # @raise [ArgumentError] if value is not positive
+  #
+  # @example
+  #   calc.vo2max_label(51.9) #=> "Very Good"
+  def vo2max_label(value)
+    check_positive(value.to_f, 'VO2max value')
+
+    VO2MAX_LABELS.find { |entry| value.to_f >= entry[:min] }[:label]
+  end
+
+  private
+
+  def vo2_at_velocity(velocity)
+    -4.60 + (0.182258 * velocity) + (0.000104 * (velocity**2))
+  end
+
+  def percent_vo2max(time_min)
+    0.8 +
+      (0.1894393 * Math.exp(-0.012778 * time_min)) +
+      (0.2989558 * Math.exp(-0.1932605 * time_min))
+  end
+
+  def parse_time_minutes(time)
+    return time.to_f / 60.0 if time.is_a?(Numeric)
+
+    check_time(time.to_s)
+    convert_to_seconds(time.to_s) / 60.0
+  end
+end

data/lib/calcpace.rb

@@ -10,6 +10,8 @@ require_relative 'calcpace/pace_calculator'
 require_relative 'calcpace/pace_converter'
 require_relative 'calcpace/race_predictor'
 require_relative 'calcpace/race_splits'
+require_relative 'calcpace/track_calculator'
+require_relative 'calcpace/vo2max_estimator'
 
 # Calcpace - A Ruby gem for pace, distance, and time calculations
 #
@@ -42,6 +44,8 @@ class Calcpace
   include PaceConverter
   include RacePredictor
   include RaceSplits
+  include TrackCalculator
+  include Vo2maxEstimator
 
   # Creates a new Calcpace instance
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.9.1
+  version: 1.9.3
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -9,8 +9,9 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Ruby gem for pace, distance, time, and speed calculations. Supports multiple
-  units and formats.
+description: 'Ruby gem for running and cycling calculations: pace, time, distance,
+  unit conversions (30+ units), race predictions (Riegel & Cameron), GPS track analysis
+  (Haversine, elevation gain, per-km splits), and VO2max estimation (Daniels & Gilbert).'
 email:
 - joaogilberto@tuta.io
 executables: []
@@ -40,7 +41,9 @@ files:
 - lib/calcpace/pace_converter.rb
 - lib/calcpace/race_predictor.rb
 - lib/calcpace/race_splits.rb
+- lib/calcpace/track_calculator.rb
 - lib/calcpace/version.rb
+- lib/calcpace/vo2max_estimator.rb
 homepage: https://github.com/0jonjo/calcpace
 licenses:
 - MIT
@@ -64,5 +67,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: A Ruby gem for pace, distance, and time calculations.
+summary: Pace, distance, GPS track analysis, and VO2max calculations for runners and
+  cyclists.
 test_files: []