fit4ruby 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 49de464c7356d1b55144fac48b0f6150371e29a9
-  data.tar.gz: 4b5e2057123c3e4a62c6f2335182cfd6cf8aa8ea
+  metadata.gz: 3b1343b7cebb0656f6a7f59aa5b1eb067e684504
+  data.tar.gz: c547627b2a01e6ed635cec1da6618f49e8bc5385
 SHA512:
-  metadata.gz: b8688224199cac6c1b024711d680bb98b33cb761e46d36af2d83e61aa04701a9f182fc70f5dd442f4a8311c6be43f7a6bf1ccf063034fd31e751191dfff8c2a2
-  data.tar.gz: 4c0bdd82555fb57d705d8992c21aa48a01b689d9596b61199894a89604d24dd4e159e55e86fcdd8b1327b4070270b688a78e0628e2caaad929f0308af4f88c4a
+  metadata.gz: cd337bb5e3d842f4720679ae934cd7c490f92c549569af97a14755e78f8275541faeec5bd44e3b2a858e3a4c647d7c747a54c2d4b2624afbd0e81fe6753cd1c4
+  data.tar.gz: bc9a7c8f43d5f239a768df8f18ebbe1989c835ac5c460f68ca71ef7f35b2390b2756ffd8f954b3de805880ea3c58a17a4d7612c0399d3ac4d6bcdf3c38410ada

data/README.md

@@ -8,6 +8,93 @@ This libary is still work in progress and probably not yet ready to be
 used in your application. However, you are welcome to try it and send
 me comments and patches.
 
+Usage
+-----
+
+You can create an Activity.
+
+```
+require 'fit4ruby'
+
+a = Fit4Ruby::Activity.new
+a.total_timer_time = 30 * 60
+a.new_user_profile({ :age => 33, :height => 1.78, :weight => 73.0,
+                     :gender => 'male', :activity_class => 4.0,
+                     :max_hr => 178 })
+
+a.new_event({ :event => 'timer', :event_type => 'start_time' })
+a.new_device_info({ :device_index => 0 })
+a.new_device_info({ :device_index => 1, :battery_status => 'ok' })
+ts = Time.now
+0.upto(a.total_timer_time / 60) do |mins|
+  ts += 60
+  a.new_record({
+    :timestamp => ts,
+    :position_lat => 51.5512 - mins * 0.0008,
+    :position_long => 11.647 + mins * 0.002,
+    :distance => 200.0 * mins,
+    :altitude => 100 + mins * 0.5,
+    :speed => 3.1,
+    :vertical_oscillation => 9 + mins * 0.02,
+    :stance_time => 235.0 * mins * 0.01,
+    :stance_time_percent => 32.0,
+    :heart_rate => 140 + mins,
+    :cadence => 75,
+    :activity_type => 'running',
+    :fractional_cadence => (mins % 2) / 2.0
+  })
+
+  if mins > 0 && mins % 5 == 0
+    a.new_lap({ :timestamp => ts })
+  end
+end
+a.new_session({ :timestamp => ts })
+a.new_event({ :timestamp => ts, :event => 'recovery_time',
+              :event_type => 'marker',
+              :data => 2160 })
+a.new_event({ :timestamp => ts, :event => 'vo2max',
+              :event_type => 'marker', :data => 52 })
+a.new_event({ :timestamp => ts, :event => 'timer',
+              :event_type => 'stop_all' })
+a.new_device_info({ :timestamp => ts, :device_index => 0 })
+ts += 1
+a.new_device_info({ :timestamp => ts, :device_index => 1,
+                    :battery_status => 'low' })
+ts += 120
+a.new_event({ :timestamp => ts, :event => 'recovery_hr',
+              :event_type => 'marker', :data => 132 })
+```
+
+Now you can have the accumulated data for laps and sessions computed.
+
+```
+a.aggregate
+```
+
+Save it to a file.
+
+```
+Fit4Ruby.write('TEST.FIT', a)
+```
+
+Or read an Activity from a file.
+
+```
+a = Fit4Ruby.read('TEST.FIT')
+```
+
+Then you can access the data in the file.
+
+```
+a.records.each do |r|
+  puts "Latitude: #{r['position_lat']}"
+  puts "Longitude: #{r['position_long']}"
+end
+```
+
+Please see lib/fit4ruby/GlobalFitMessages.rb for the data fields that
+are supported for the various FIT record types.
+
 License
 -------
 

data/Rakefile

@@ -4,8 +4,11 @@ $:.unshift File.join(File.dirname(__FILE__))
 lib = File.expand_path('../lib', __FILE__)
 $:.unshift lib unless $:.include?(lib)
 
+require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require 'rake/clean'
+require 'yard'
+YARD::Rake::YardocTask.new
 
 Dir.glob( 'tasks/*.rake').each do |fn|
   begin 

data/lib/fit4ruby/Activity.rb

@@ -23,12 +23,18 @@ require 'fit4ruby/PersonalRecords'
 
 module Fit4Ruby
 
+  # This is the most important class of this library. It holds references to
+  # all other data structures. Each of the objects it references are direct
+  # equivalents of the message record structures used in the FIT file.
   class Activity < FitDataRecord
 
     attr_accessor :file_id, :file_creator, :device_infos, :user_profiles,
                   :sessions, :laps, :records, :events, :personal_records
 
-    def initialize
+    # Create a new Activity object.
+    # @param field_values [Hash] A Hash that provides initial values for
+    #        certain fields of the FitDataRecord.
+    def initialize(field_values = {})
       super('activity')
       @num_sessions = 0
 
@@ -46,8 +52,12 @@ module Fit4Ruby
       @cur_lap_records = []
 
       @lap_counter = 1
+
+      set_field_values(field_values)
     end
 
+    # Perform some basic logical checks on the object and all references sub
+    # objects. Any errors will be reported via the Log object.
     def check
       unless @timestamp && @timestamp >= Time.parse('1990-01-01')
         Log.error "Activity has no valid timestamp"
@@ -63,22 +73,30 @@ module Fit4Ruby
       @sessions.each { |s| s.check(self) }
     end
 
+    # Convenience method that aggregates all the distances from the included
+    # sessions.
     def total_distance
       d = 0.0
       @sessions.each { |s| d += s.total_distance }
       d
     end
 
+    # Call this method to update the aggregated data fields stored in Lap and
+    # Session objects.
     def aggregate
+      @laps.each { |l| l.aggregate }
       @sessions.each { |s| s.aggregate }
     end
 
+    # Convenience method that averages the speed over all sessions.
     def avg_speed
       speed = 0.0
       @sessions.each { |s| speed += s.avg_speed }
       speed / @sessions.length
     end
 
+    # Returns the predicted recovery time needed after this activity.
+    # @return recovery time in seconds.
     def recovery_time
       @events.each do |e|
         return e.data if e.event == 'recovery_time'
@@ -87,6 +105,8 @@ module Fit4Ruby
       nil
     end
 
+    # Returns the computed VO2max value. This value is computed by the device
+    # based on multiple previous activities.
     def vo2max
       @events.each do |e|
         return e.data if e.event == 'vo2max'
@@ -95,6 +115,10 @@ module Fit4Ruby
       nil
     end
 
+    # Write the Activity data to a file.
+    # @param io [IO] File reference
+    # @param id_mapper [FitMessageIdMapper] Maps global FIT record types to
+    #        local ones.
     def write(io, id_mapper)
       @file_id.write(io, id_mapper)
       @file_creator.write(io, id_mapper)
@@ -106,42 +130,91 @@ module Fit4Ruby
       super
     end
 
+    # Add a new FileId to the Activity. It will replace any previously added
+    # FileId object.
+    # @param field_values [Hash] A Hash that provides initial values for
+    #        certain fields of the FitDataRecord.
+    # @return [FileId]
     def new_file_id(field_values = {})
       new_fit_data_record('file_id', field_values)
     end
 
+    # Add a new FileCreator to the Activity. It will replace any previously
+    # added FileCreator object.
+    # @param field_values [Hash] A Hash that provides initial values for
+    #        certain fields of the FitDataRecord.
+    # @return [FileCreator]
     def new_file_creator(field_values = {})
       new_fit_data_record('file_creator', field_values)
     end
 
+    # Add a new DeviceInfo to the Activity.
+    # @param field_values [Hash] A Hash that provides initial values for
+    #        certain fields of the FitDataRecord.
+    # @return [DeviceInfo]
     def new_device_info(field_values = {})
       new_fit_data_record('device_info', field_values)
     end
 
+    # Add a new UserProfile to the Activity.
+    # @param field_values [Hash] A Hash that provides initial values for
+    #        certain fields of the FitDataRecord.
+    # @return [UserProfile]
     def new_user_profile(field_values = {})
       new_fit_data_record('user_profile', field_values)
     end
 
+    # Add a new Event to the Activity.
+    # @param field_values [Hash] A Hash that provides initial values for
+    #        certain fields of the FitDataRecord.
+    # @return [Event]
     def new_event(field_values = {})
       new_fit_data_record('event', field_values)
     end
 
+    # Add a new Session to the Activity. All previously added Lap objects are
+    # associated with this Session unless they have been associated with
+    # another Session before. If there are any Record objects that have not
+    # yet been associated with a Lap, a new lap will be created and the
+    # Record objects will be associated with this Lap. The Lap will be
+    # associated with the newly created Session.
+    # @param field_values [Hash] A Hash that provides initial values for
+    #        certain fields of the FitDataRecord.
+    # @return [Session]
     def new_session(field_values = {})
       new_fit_data_record('session', field_values)
     end
 
+    # Add a new Lap to the Activity. All previoulsy added Record objects are
+    # associated with this Lap unless they have been associated with another
+    # Lap before.
+    # @param field_values [Hash] A Hash that provides initial values for
+    #        certain fields of the FitDataRecord.
+    # @return [Lap]
     def new_lap(field_values = {})
       new_fit_data_record('lap', field_values)
     end
 
+    # Add a new PersonalRecord to the Activity.
+    # @param field_values [Hash] A Hash that provides initial values for
+    #        certain fields of the FitDataRecord.
+    # @return [PersonalRecord]
     def new_personal_record(field_values = {})
       new_fit_data_record('personal_record', field_values)
     end
 
+    # Add a new Record to the Activity.
+    # @param field_values [Hash] A Hash that provides initial values for
+    #        certain fields of the FitDataRecord.
+    # @return [Record]
     def new_record(field_values = {})
       new_fit_data_record('record', field_values)
     end
 
+    # Check if the current Activity is equal to the passed Activity.
+    # @param a [Activity] Activity to compare this Activity with.
+    # @return [TrueClass/FalseClass] true if both Activities are equal,
+    # otherwise false.
     def ==(a)
       super(a) && @file_id == a.file_id &&
         @file_creator == a.file_creator &&
@@ -150,6 +223,12 @@ module Fit4Ruby
         @sessions == a.sessions && personal_records == a.personal_records
     end
 
+    # Create a new FitDataRecord.
+    # @param record_type [String] Type that identifies the FitDataRecord
+    #        derived class to create.
+    # @param field_values [Hash] A Hash that provides initial values for
+    #        certain fields of the FitDataRecord.
+    # @return FitDataRecord
     def new_fit_data_record(record_type, field_values = {})
       case record_type
       when 'file_id'
@@ -165,20 +244,14 @@ module Fit4Ruby
       when 'session'
         unless @cur_lap_records.empty?
           # Ensure that all previous records have been assigned to a lap.
-          @lap_counter += 1
-          @cur_session_laps << (lap = Lap.new(@cur_lap_records, field_values))
-          @laps << lap
-          @cur_lap_records = []
+          record = create_new_lap(field_values)
         end
         @num_sessions += 1
         @sessions << (record = Session.new(@cur_session_laps, @lap_counter,
                                            field_values))
         @cur_session_laps = []
       when 'lap'
-        @lap_counter += 1
-        @cur_session_laps << (record = Lap.new(@cur_lap_records, field_values))
-        @laps << record
-        @cur_lap_records = []
+        record = create_new_lap(field_values)
       when 'record'
         @cur_lap_records << (record = Record.new(field_values))
         @records << record
@@ -191,6 +264,18 @@ module Fit4Ruby
       record
     end
 
+    private
+
+    def create_new_lap(field_values)
+      lap = Lap.new(@cur_lap_records, @laps.last, field_values)
+      @lap_counter += 1
+      @cur_session_laps << lap
+      @laps << lap
+      @cur_lap_records = []
+
+      lap
+    end
+
   end
 
 end

data/lib/fit4ruby/Converters.rb

@@ -14,9 +14,32 @@ module Fit4Ruby
 
   module Converters
 
-    def speedToPace(speed)
-      if speed > 0.01
-        pace = 1000.0 / (speed * 60.0)
+    def conversion_factor(from_unit, to_unit)
+      factors = {
+        'm' => { 'km' => 0.001, 'in' => 39.3701, 'ft' => 3.28084,
+                 'mi' => 0.000621371 },
+        'mm' => { 'cm' => 0.1, 'in' => 0.0393701 },
+        'm/s' => { 'km/h' => 0.277778 },
+        'min/km' => { 'min/mi' => 1.60934 },
+        'kg' => { 'lbs' => 0.453592 }
+      }
+      return 1.0 if from_unit == to_unit
+      unless factors.include?(from_unit)
+        Log.fatal "No conversion factors defined for unit " +
+                  "'#{from_unit}' to '#{to_unit}'"
+      end
+
+      factor = factors[from_unit][to_unit]
+      if factor.nil?
+        Log.fatal "No conversion factor from '#{from_unit}' to '#{to_unit}' " +
+                  "defined."
+      end
+      factor
+    end
+
+    def speedToPace(speed, distance = 1000.0)
+      if speed && speed > 0.01
+        pace = distance / (speed * 60.0)
         int, dec = pace.divmod 1
         "#{int}:#{'%02d' % (dec * 60)}"
       else

data/lib/fit4ruby/FitDataRecord.rb

@@ -17,14 +17,17 @@ module Fit4Ruby
 
   class FitDataRecord
 
+    include Converters
+
     def initialize(record_id)
       @message = GlobalFitMessages.find_by_name(record_id)
 
       # Create instance variables that correspond to every field of the
-      # corresponding FIT # data record.
+      # corresponding FIT data record.
       @message.fields.each do |field_number, field|
         create_instance_variable(field.name)
       end
+      @meta_field_units = {}
       @timestamp = Time.now
     end
 
@@ -43,6 +46,29 @@ module Fit4Ruby
       instance_variable_set('@' + name, value)
     end
 
+    def get(name)
+      ivar_name = '@' + name
+      return nil unless instance_variable_defined?(ivar_name)
+
+      instance_variable_get('@' + name)
+    end
+
+    def get_as(name, to_unit)
+      value = respond_to?(name) ? send(name) : get(name)
+      return nil if value.nil?
+
+      if @meta_field_units.include?(name)
+        unit = @meta_field_units[name]
+      else
+        field = @message.find_by_name(name)
+        unless (unit = field.opts[:unit])
+          Log.fatal "Field #{name} has no unit"
+        end
+      end
+
+      value * conversion_factor(unit, to_unit)
+    end
+
     def ==(fdr)
       @message.fields.each do |field_number, field|
         ivar_name = '@' + field.name

data/lib/fit4ruby/GlobalFitMessage.rb

@@ -114,6 +114,9 @@ module Fit4Ruby
         when 'date_time'
           value = time_to_fit_time(value)
         end
+        if value.is_a?(Float) && @opts[:scale].nil?
+          Log.error "Field #{@name} must not be a Float value"
+        end
 
         value
       end
@@ -141,6 +144,10 @@ module Fit4Ruby
       @fields[number] = Field.new(type, name, opts)
     end
 
+    def find_by_name(field_name)
+      @fields.values.find { |f| f.name == field_name }
+    end
+
     def write(io, local_message_type)
       header = FitRecordHeader.new
       header.normal = 0
@@ -195,7 +202,7 @@ module Fit4Ruby
     end
 
     def find_by_name(name)
-      @messages.each_value{ |m| return m if m.name == name }
+      @messages.values.find { |m| m.name == name }
     end
 
     def field(number, type, name, opts = {})

data/lib/fit4ruby/GlobalFitMessages.rb

@@ -43,7 +43,7 @@ module Fit4Ruby
     field 17, 'uint8', 'max_heart_rate', :unit => 'bpm'
     field 18, 'uint8', 'avg_running_cadence', :unit => 'strides/min'
     field 19, 'uint8', 'max_running_cadence', :unit => 'strides/min'
-    field 22, 'uint16', 'total_ascend', :unit => 'm'
+    field 22, 'uint16', 'total_ascent', :unit => 'm'
     field 23, 'uint16', 'total_descent', :unit => 'm'
     field 24, 'uint8', 'total_training_effect', :scale => 10
     field 25, 'uint16', 'first_lap_index'
@@ -162,6 +162,17 @@ module Fit4Ruby
     field 25, 'enum', 'undocumented_field_25'
     field 253, 'uint32', 'timestamp', :type => 'date_time'
 
+    message 33, 'totals'
+    field 0, 'uint32', 'timer_time', :unit => 's'
+    field 1, 'uint32', 'distance', :unit => 'm'
+    field 2, 'uint32', 'calories', :unit => 'kcal'
+    field 3, 'enum', 'sport', :dict => 'sport'
+    field 4, 'uint32', 'elapsed_time', :unit => 's'
+    field 5, 'uint16', 'sessions'
+    field 6, 'uint32', 'active_time', :unit => 's'
+    field 253, 'uint32', 'timestamp', :type => 'date_time'
+    field 254, 'uint16', 'message_index'
+
     message 34, 'activity'
     field 0, 'uint32', 'total_timer_time', :type => 'duration',  :scale => 1000
     field 1, 'uint16', 'num_sessions'

data/lib/fit4ruby/Lap.rb

@@ -11,16 +11,35 @@
 #
 
 require 'fit4ruby/FitDataRecord'
+require 'fit4ruby/RecordAggregator'
 
 module Fit4Ruby
 
   class Lap < FitDataRecord
 
+    include RecordAggregator
+
     attr_reader :records
 
-    def initialize(records, field_values)
+    def initialize(records, previous_lap, field_values)
       super('lap')
+      @meta_field_units['avg_stride_length'] = 'm'
       @records = records
+      @previous_lap = previous_lap
+
+      if previous_lap && previous_lap.records && previous_lap.records.last
+        # Set the start time of the new lap to the timestamp of the last record
+        # of the previous lap.
+        @start_time = previous_lap.records.last.timestamp
+      elsif records.first
+        # Or to the timestamp of the first record.
+        @start_time = records.first.timestamp
+      end
+
+      if records.last
+        @total_elapsed_time = records.last.timestamp - @start_time
+      end
+
       set_field_values(field_values)
     end
 
@@ -42,49 +61,11 @@ module Fit4Ruby
       end
     end
 
-    def aggregate
-      return if @records.empty?
-
-      r = @records[0]
-      @start_time = r.timestamp
-      @start_position_lat = r.position_lat
-      @start_position_long = r.position_long
-
-      r = @records[-1]
-      @end_position_lat = r.position_lat
-      @end_position_long = r.position_long
-      @total_elapsed_time = r.timestamp - @start_time
-      @total_timer_time = @total_elapsed_time
-      @avg_speed = ((@total_distance.to_f / @total_elapsed_time) * 1000).to_i
-
-      @max_speed = 0
-      first_distance, last_distance = nil, nil
-      @records.each do |r|
-        first_distance = r.distance if first_distance.nil? && r.distance
-        last_distance = r.distance if r.distance
-        @max_speed = r.speed if r.speed && @max_speed < r.speed
-
-        if r.position_lat
-          if (@swc_lat.nil? || r.position_lat < @swc_lat)
-            @swc_lat = r.position_lat
-          end
-          if (@nec_lat.nil? || r.position_lat > @nec_lat)
-            @nec_lat = r.position_lat
-          end
-        end
-        if r.position_long
-          if (@swc_long.nil? || r.position_long < @swc_long)
-            @swc_long = r.position_long
-          end
-          if (@nec_long.nil? || r.position_long > @nec_long)
-            @nec_long = r.position_long
-          end
-        end
-
-      end
+    # Compute the average stride length for this Session.
+    def avg_stride_length
+      return nil unless @total_strides
 
-      @total_distance = last_distance && first_distance ?
-        last_distance - first_distance : 0
+      @total_distance / (@total_strides * 2.0)
     end
 
   end

data/lib/fit4ruby/Record.rb

@@ -14,13 +14,32 @@ require 'fit4ruby/FitDataRecord'
 
 module Fit4Ruby
 
+  # The Record corresponds to the record FIT message. A Record is a basic set
+  # of primary measurements that are associated with a certain timestamp.
   class Record < FitDataRecord
 
+    # Create a new Record object.
+    # @param field_values [Hash] Hash that provides initial values for certain
+    #        fields.
     def initialize(field_values = {})
       super('record')
+      @meta_field_units['pace'] = 'min/km'
+      @meta_field_units['run_cadence'] = 'spm'
       set_field_values(field_values)
     end
 
+    def run_cadence
+      if @cadence && @fractional_cadence
+        (@cadence + @fractional_cadence) * 2
+      elsif @cadence
+        @cadence * 2
+      else
+        nil
+      end
+    end
+
+    # Convert the 'speed' field into a running pace. The pace is measured in
+    # minutes per Kilometer.
     def pace
       1000.0 / (@speed * 60.0)
     end

data/lib/fit4ruby/RecordAggregator.rb

@@ -0,0 +1,173 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = RecordAggregator.rb -- Fit4Ruby - FIT file processing library for Ruby
+#
+# Copyright (c) 2014 by Chris Schlaeger <cs@taskjuggler.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of version 2 of the GNU General Public License as
+# published by the Free Software Foundation.
+#
+
+module Fit4Ruby
+
+  module RecordAggregator
+
+    def aggregate
+      return if @records.empty?
+
+      # TODO: Add support for pause events.
+      @total_timer_time = @total_elapsed_time
+
+      aggregate_geo_region
+      aggregate_ascent_descent
+      aggregate_speed_distance
+      aggregate_heart_rate
+      aggregate_strides
+      aggregate_vertical_oscillation
+      aggregate_stance_time
+    end
+
+    def aggregate_geo_region
+      r = @records.first
+      @start_position_lat = r.position_lat
+      @start_position_long = r.position_long
+
+      r = @records.last
+      @end_position_lat = r.position_lat
+      @end_position_long = r.position_long
+
+      @records.each do |r|
+        if r.position_lat
+          if (@swc_lat.nil? || r.position_lat < @swc_lat)
+            @swc_lat = r.position_lat
+          end
+          if (@nec_lat.nil? || r.position_lat > @nec_lat)
+            @nec_lat = r.position_lat
+          end
+        end
+        if r.position_long
+          if (@swc_long.nil? || r.position_long < @swc_long)
+            @swc_long = r.position_long
+          end
+          if (@nec_long.nil? || r.position_long > @nec_long)
+            @nec_long = r.position_long
+          end
+        end
+      end
+    end
+
+    def aggregate_ascent_descent
+      @total_ascent = @total_descent = 0
+      altitude = nil
+
+      @records.each do |r|
+        if altitude
+          if r.altitude < altitude
+            @total_descent += (altitude - r.altitude)
+          else
+            @total_ascent += (r.altitude - altitude)
+          end
+        end
+        altitude = r.altitude
+      end
+    end
+
+    def aggregate_speed_distance
+      @max_speed = 0
+      first_distance, last_distance = nil, nil
+
+      @records.each do |r|
+        @max_speed = r.speed if r.speed && @max_speed < r.speed
+
+        first_distance = r.distance if first_distance.nil? && r.distance
+        last_distance = r.distance if r.distance
+      end
+
+      @total_distance = last_distance && first_distance ?
+        last_distance - first_distance : 0
+      @avg_speed = @total_distance.to_f / @total_elapsed_time
+    end
+
+    def aggregate_heart_rate
+      total_heart_beats = 0
+      @max_heart_rate = 0
+      last_timestamp = @start_time
+
+      @records.each do |r|
+        if r.heart_rate
+          delta_t = last_timestamp ? r.timestamp - last_timestamp : nil
+          total_heart_beats += (r.heart_rate / 60.0) * delta_t if delta_t
+          if r.heart_rate > @max_heart_rate
+            @max_heart_rate = r.heart_rate
+          end
+        end
+        last_timestamp = r.timestamp
+      end
+      @avg_heart_rate = (total_heart_beats.to_f / @total_elapsed_time * 60).to_i
+    end
+
+    def aggregate_strides
+      @total_strides = 0
+      @max_running_cadence = 0
+      last_timestamp = @start_time
+
+      @records.each do |r|
+        delta_t = last_timestamp ? r.timestamp - last_timestamp : nil
+
+        if delta_t && (run_cadence = r.run_cadence)
+          @total_strides += (run_cadence / 60.0) * delta_t
+        end
+        if run_cadence && run_cadence > @max_running_cadence
+          @max_running_cadence = run_cadence.to_i
+        end
+
+        last_timestamp = r.timestamp
+      end
+      @avg_running_cadence, @avg_fractional_cadence =
+        (@total_strides.to_f / @total_timer_time * (60 / 2)).divmod(1)
+      @total_strides = @total_strides.to_i
+    end
+
+    def aggregate_vertical_oscillation
+      total_vertical_oscillation = 0.0
+      vertical_oscillation_count = 0
+
+      @records.each do |r|
+        if r.vertical_oscillation
+          total_vertical_oscillation += r.vertical_oscillation
+          vertical_oscillation_count += 1
+        end
+      end
+
+      @avg_vertical_oscillation = total_vertical_oscillation /
+        vertical_oscillation_count
+    end
+
+    def aggregate_stance_time
+      total_stance_time = 0.0
+      total_stance_time_percent = 0.0
+      stance_time_count = 0
+      stance_time_percent_count = 0
+
+      @records.each do |r|
+        if r.stance_time
+          total_stance_time += r.stance_time
+          stance_time_count += 1
+        end
+        if r.stance_time_percent
+          total_stance_time_percent += r.stance_time_percent
+          stance_time_percent_count += 1
+        end
+      end
+
+      @avg_stance_time = total_stance_time / stance_time_count
+      @avg_stance_time_percent = total_stance_time_percent /
+        stance_time_percent_count
+    end
+
+  end
+
+end
+

data/lib/fit4ruby/Session.rb

@@ -12,23 +12,45 @@
 
 require 'fit4ruby/Converters'
 require 'fit4ruby/FitDataRecord'
+require 'fit4ruby/RecordAggregator'
 
 module Fit4Ruby
 
+  # The Session objects correspond to the session FIT messages. They hold
+  # accumlated data for a set of Lap objects.
   class Session < FitDataRecord
 
-    include Converters
+    include RecordAggregator
 
     attr_reader :laps
 
+    # Create a new Session object.
+    # @param laps [Array of Laps] Laps to associate with the Session.
+    # @param first_lap_index [Fixnum] Index of the first Lap in this Session.
+    # @param field_values [Hash] Hash that provides initial values for certain
+    #        fields.
     def initialize(laps, first_lap_index, field_values)
       super('session')
+      @meta_field_units['avg_stride_length'] = 'm'
       @laps = laps
+      @records = []
+      @laps.each { |lap| @records += lap.records }
       @first_lap_index = first_lap_index
       @num_laps = @laps.length
+
+      if @records.first
+        # Or to the timestamp of the first record.
+        @start_time = @records.first.timestamp
+        if @records.last
+          @total_elapsed_time = @records.last.timestamp - @start_time
+        end
+      end
+
       set_field_values(field_values)
     end
 
+    # Perform some basic consistency and logical checks on the object. Errors
+    # are reported via the Log object.
     def check(activity)
       unless @first_lap_index
         Log.error 'first_lap_index is not set'
@@ -47,33 +69,16 @@ module Fit4Ruby
       @laps.each { |l| l.check }
     end
 
-    def aggregate
-      @total_distance = 0
-      @total_elapsed_time = 0
-      @laps.each do |lap|
-        lap.aggregate
-        @total_distance += lap.total_distance if lap.total_distance
-        @total_elapsed_time += lap.total_elapsed_time if lap.total_elapsed_time
-      end
-      if (l = @laps[0])
-        @start_time = l.start_time
-        @start_position_lat = l.start_position_lat
-        @start_position_long = l.start_position_long
-      end
-      if (l = @laps[-1])
-        @end_position_lat = l.end_position_lat
-        @end_position_long = l.end_position_long
-      end
-
-      if @total_distance && @total_elapsed_time
-        @avg_speed = @total_distance / @total_elapsed_time
-      end
+    # Return true if the session contains geographical location data.
+    def has_geo_data?
+      @swc_long && @swc_lat && @nec_long && nec_lat
     end
 
+    # Compute the average stride length for this Session.
     def avg_stride_length
       return nil unless @total_strides
 
-      @total_distance / @total_strides
+      @total_distance / (@total_strides * 2.0)
     end
 
   end

data/lib/fit4ruby/UserProfile.rb

@@ -14,8 +14,12 @@ require 'fit4ruby/FitDataRecord'
 
 module Fit4Ruby
 
+  # This class corresponds to the user_profile FIT message.
   class UserProfile < FitDataRecord
 
+    # Create a new UserProfile object.
+    # @param field_values [Hash] Hash that provides initial values for certain
+    #        fields.
     def initialize(field_values = {})
       super('user_profile')
       set_field_values(field_values)

data/lib/fit4ruby/version.rb

@@ -1,3 +1,4 @@
 module Fit4Ruby
-  VERSION = '0.0.2'
+  # The version number of the library.
+  VERSION = '0.0.3'
 end

data/spec/FitFile_spec.rb

@@ -32,7 +32,7 @@ describe Fit4Ruby do
         :position_lat => 51.5512 - mins * 0.0008,
         :position_long => 11.647 + mins * 0.002,
         :distance => 200.0 * mins,
-        :altitude => 100 + mins * 0.5,
+        :altitude => (100 + mins * 0.5).to_i,
         :speed => 3.1,
         :vertical_oscillation => 9 + mins * 0.02,
         :stance_time => 235.0 * mins * 0.01,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fit4ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Chris Schlaeger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-10 00:00:00.000000000 Z
+date: 2014-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bindata
@@ -106,6 +106,7 @@ files:
 - lib/fit4ruby/Log.rb
 - lib/fit4ruby/PersonalRecords.rb
 - lib/fit4ruby/Record.rb
+- lib/fit4ruby/RecordAggregator.rb
 - lib/fit4ruby/Session.rb
 - lib/fit4ruby/UserProfile.rb
 - lib/fit4ruby/version.rb
@@ -140,3 +141,4 @@ specification_version: 4
 summary: Library to read GARMIN FIT files.
 test_files:
 - spec/FitFile_spec.rb
+has_rdoc: