tcxread 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e42a89981c1614dec069270cb1315ee64d0c6a172de5c44a5370b5f5c8bd584f
-  data.tar.gz: dcee18bb770a1aa020d5ad8f67370f775a6f8d25139c39eb8576e76c463c1efd
+  metadata.gz: 7b17178126aaf26d70869aa047a6054ca4128ac454c75b3fbd0903ce935222dc
+  data.tar.gz: f27e41c68c87672a7acd2791b4a147c8a0bf09a2da1707a8722091a965508b89
 SHA512:
-  metadata.gz: 72c0b8ba80f7cd524c91417123353e6d9523551050c513d55447ae1c6d73ff8add6af60cc6ec319d26af8aa237e7bcb40771f587653ffe92766f57be7d538194
-  data.tar.gz: 42a2ea64072c68e786e002a5dd0fa32c4547ac0503a4eb207537c3d9442148ca958fe9038b44b826033fa94ca4ddf80feaff92f8904745bfdad7aaba96c591ae
+  metadata.gz: 9281010f7900f5bf0a579c648690329e0f5680ecb9cc91e56733a2718ce15ac75cdfa15eabb4fc4f97b99d6cd26dfbbb53c627124775261fa1083797f9c1d4c1
+  data.tar.gz: c61eee523a2b34730e40cddce7cd2eb58193bcb9585b84c0d08252f66cd8f4e90f49b6bf77dcbebdf13d8e96336fd5365787a3e670fda68b26cab214a540cd26

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2024 Iztok Fister Jr.
+
+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,83 @@
+<h1 align="center">
+     tcxread -- A parser for TCX files written in Ruby
+</h1>
+
+<p align="center">
+     <a href="https://badge.fury.io/rb/tcxread">
+          <img alt="Gem Version" src="https://badge.fury.io/rb/tcxread.svg">
+     </a>
+     <a href="https://github.com/firefly-cpp/tcxread/blob/master/LICENSE">
+          <img alt="License" src="https://img.shields.io/github/license/firefly-cpp/tcxread.svg">
+     </a>
+     <a href=https://repology.org/project/ruby:tcxread/versions>
+          <img alt="Packaging status" src="https://repology.org/badge/tiny-repos/ruby:tcxread.svg">
+     </a>
+     <img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/w/firefly-cpp/tcxread.svg">
+     <img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/firefly-cpp/tcxread">
+</p>
+
+<p align="center">
+     <a href="#-installation">📦 Installation</a> •
+     <a href="#-basic-run-example">🚀 Basic run example</a> •
+     <a href="#-datasets">💾 Datasets</a> •
+     <a href="#-further-read">📖 Further read</a> •
+     <a href="#-related-packagesframeworks">🔗 Related packages/frameworks</a> •
+     <a href="#-license">🔑 License</a>
+</p>
+
+tcxread is a Ruby package designed to simplify the process of reading and processing .tcx files, commonly used by Garmin devices and other GPS-enabled fitness devices to store workout data.
+
+## 📦 Installation
+
+```sh
+$ gem install tcxread
+```
+
+## 🚀 Basic run example
+
+```ruby
+require 'tcxread'
+
+data = TCXRead.new('23.tcx')
+
+puts "Distance meters: #{data.total_distance_meters}, " \
+     "Time seconds: #{data.total_time_seconds}, " \
+     "Calories: #{data.total_calories}, " \
+     "Total ascent: #{data.total_ascent}, " \
+     "Total descent: #{data.total_descent}, " \
+     "Max altitude: #{data.max_altitude}, " \
+     "Average heart rate: #{data.average_heart_rate}, " \
+     "Average watts: #{data.average_watts}, " \
+     "Max watts: #{data.max_watts}, " \
+     "Average speed: #{data.average_speed_all}, " \
+     "Average speed (moving): #{data.average_speed_moving}, " \
+     "Average cadence (moving): #{data.average_cadence_biking}, " \
+     "Average cadence: #{data.average_cadence_all}"
+
+```
+
+## 💾 Datasets
+
+Datasets available and used in the examples on the following links: [DATASET1](http://iztok-jr-fister.eu/static/publications/Sport5.zip), [DATASET2](http://iztok-jr-fister.eu/static/css/datasets/Sport.zip), [DATASET3](https://github.com/firefly-cpp/tcx-test-files).
+
+## 📖 Further read
+
+[1] [Awesome Computational Intelligence in Sports](https://github.com/firefly-cpp/awesome-computational-intelligence-in-sports)
+
+## 🔗 Related packages/frameworks
+
+[1] [tcxreader: Python reader/parser for Garmin's TCX file format.](https://github.com/alenrajsp/tcxreader)
+
+[2] [sport-activities-features: A minimalistic toolbox for extracting features from sports activity files written in Python](https://github.com/firefly-cpp/sport-activities-features)
+
+[3] [TCXReader.jl: Julia package designed for parsing TCX files](https://github.com/firefly-cpp/TCXReader.jl)
+
+[4] [TCXWriter: A Tiny Library for writing/creating TCX files on Arduino](https://github.com/firefly-cpp/tcxwriter)
+
+## 🔑 License
+
+This package is distributed under the MIT License. This license can be found online at <http://www.opensource.org/licenses/MIT>.
+
+## Disclaimer
+
+This framework is provided as-is, and there are no guarantees that it fits your purposes or that it is bug-free. Use it at your own risk!

data/lib/tcxread.rb

@@ -1,11 +1,10 @@
 require "nokogiri"
 
-# TCXRead is a class that parses TCX (Training Center XML) files to extract
-# workout data such as activities, laps, tracks, trackpoints, and integral metrics.
 class TCXRead
   attr_reader :total_distance_meters, :total_time_seconds, :total_calories,
               :total_ascent, :total_descent, :max_altitude, :average_heart_rate,
-              :max_watts, :average_watts, :average_cadence
+              :max_watts, :average_watts, :average_cadence_all, :average_cadence_biking,
+              :average_speed_all, :average_speed_moving
 
   def initialize(file_path)
     @file_path = file_path
@@ -19,17 +18,16 @@ class TCXRead
     @total_descent = 0
     @max_altitude = 0
     @average_heart_rate = 0
-    # use NA if no watts exist in the TCX file
     @max_watts = 'NA'
     @average_watts = 'NA'
-    @average_cadence = 0
+    @average_cadence_all = 0
+    @average_cadence_biking = 0
+    @average_speed_all = 0
+    @average_speed_moving = 0
 
     parse
   end
 
-  # Parses the TCX file and extracts data.
-  #
-  # @return [Hash] a hash containing the parsed activities.
   def parse
     activities = parse_activities
     if activities.any?
@@ -39,7 +37,12 @@ class TCXRead
       @total_ascent, @total_descent, @max_altitude = calculate_ascent_descent_and_max_altitude_from_activities(activities)
       @average_heart_rate = calculate_average_heart_rate_from_activities(activities)
       @max_watts, @average_watts = calculate_watts_from_activities(activities)
-      @average_cadence = calculate_average_cadence_from_activities(activities)
+      cadence_results = calculate_average_cadence_from_activities(activities)
+      @average_cadence_all = cadence_results[:average_cadence_all]
+      @average_cadence_biking = cadence_results[:average_cadence_biking]
+      speed_results = calculate_average_speed_from_activities(activities)
+      @average_speed_all = speed_results[:average_speed_all]
+      @average_speed_moving = speed_results[:average_speed_moving]
     end
 
     { activities: activities }
@@ -47,9 +50,6 @@ class TCXRead
 
   private
 
-  # Parses the activities from the TCX file.
-  #
-  # @return [Array<Hash>] an array of hashes, each representing an activity.
   def parse_activities
     activities = []
     @doc.xpath('//xmlns:Activities/xmlns:Activity').each do |activity|
@@ -76,10 +76,6 @@ class TCXRead
     activities
   end
 
-  # Parses the laps for a given activity.
-  #
-  # @param activity [Nokogiri::XML::Element] the activity element from the TCX file.
-  # @return [Array<Hash>] an array of hashes, each representing a lap.
   def parse_laps(activity)
     laps = []
     activity.xpath('xmlns:Lap').each do |lap|
@@ -100,10 +96,6 @@ class TCXRead
     laps
   end
 
-  # Parses the tracks for a given lap.
-  #
-  # @param lap [Nokogiri::XML::Element] the lap element from the TCX file.
-  # @return [Array<Array<Hash>>] an array of arrays, each representing a track containing trackpoints.
   def parse_tracks(lap)
     tracks = []
     lap.xpath('xmlns:Track').each do |track|
@@ -125,10 +117,6 @@ class TCXRead
     tracks
   end
 
-  # Parses the position for a given trackpoint.
-  #
-  # @param trackpoint [Nokogiri::XML::Element] the trackpoint element from the TCX file.
-  # @return [Hash, nil] a hash representing the position (latitude and longitude) or nil if no position is available.
   def parse_position(trackpoint)
     position = trackpoint.at_xpath('xmlns:Position')
     return nil unless position
@@ -139,10 +127,6 @@ class TCXRead
     }
   end
 
-  # Calculates the total ascent, total descent, and maximum altitude from the laps.
-  #
-  # @param laps [Array<Hash>] an array of lap hashes.
-  # @return [Array<Float>] an array containing total ascent, total descent, and maximum altitude.
   def calculate_ascent_descent_and_max_altitude(laps)
     total_ascent = 0.0
     total_descent = 0.0
@@ -170,10 +154,6 @@ class TCXRead
     [total_ascent, total_descent, max_altitude]
   end
 
-  # Calculates the total ascent, total descent, and maximum altitude from the activities.
-  #
-  # @param activities [Array<Hash>] an array of activity hashes.
-  # @return [Array<Float>] an array containing total ascent, total descent, and maximum altitude.
   def calculate_ascent_descent_and_max_altitude_from_activities(activities)
     total_ascent = 0.0
     total_descent = 0.0
@@ -188,10 +168,6 @@ class TCXRead
     [total_ascent, total_descent, max_altitude]
   end
 
-  # Calculates the average heart rate from the laps.
-  #
-  # @param laps [Array<Hash>] an array of lap hashes.
-  # @return [Float] the average heart rate.
   def calculate_average_heart_rate(laps)
     total_heart_rate = 0
     heart_rate_count = 0
@@ -209,10 +185,6 @@ class TCXRead
     heart_rate_count > 0 ? total_heart_rate.to_f / heart_rate_count : 0.0
   end
 
-  # Calculates the average heart rate from the activities.
-  #
-  # @param activities [Array<Hash>] an array of activity hashes.
-  # @return [Float] the average heart rate.
   def calculate_average_heart_rate_from_activities(activities)
     total_heart_rate = 0
     heart_rate_count = 0
@@ -232,10 +204,6 @@ class TCXRead
     heart_rate_count > 0 ? total_heart_rate.to_f / heart_rate_count : 0.0
   end
 
-  # Calculates the maximum and average watts from the activities.
-  #
-  # @param activities [Array<Hash>] an array of activity hashes.
-  # @return [Array<Float, Float>] an array containing maximum watts and average watts. Returns 'NA' for both if no watts data is available.
   def calculate_watts_from_activities(activities)
     max_watts = 0
     total_watts = 0
@@ -265,26 +233,72 @@ class TCXRead
     [max_watts, average_watts]
   end
 
-  # Calculates the average cadence from the activities.
-  #
-  # @param activities [Array<Hash>] an array of activity hashes.
-  # @return [Float] the average cadence.
   def calculate_average_cadence_from_activities(activities)
-    total_cadence = 0
-    cadence_count = 0
+    total_cadence_all = 0
+    total_cadence_biking = 0
+    cadence_count_all = 0
+    cadence_count_biking = 0
 
     activities.each do |activity|
       activity[:laps].each do |lap|
         lap[:tracks].flatten.each do |trackpoint|
           cadence = trackpoint[:cadence]
+          total_cadence_all += cadence
+          cadence_count_all += 1
+
           if cadence > 0
-            total_cadence += cadence
-            cadence_count += 1
+            total_cadence_biking += cadence
+            cadence_count_biking += 1
           end
         end
       end
     end
 
-    cadence_count > 0 ? total_cadence.to_f / cadence_count : 0.0
+    average_cadence_all = cadence_count_all > 0 ? total_cadence_all.to_f / cadence_count_all : 0.0
+    average_cadence_biking = cadence_count_biking > 0 ? total_cadence_biking.to_f / cadence_count_biking : 0.0
+
+    {
+      average_cadence_all: average_cadence_all,
+      average_cadence_biking: average_cadence_biking
+    }
+  end
+
+  # Calculates the average speed from the activities.
+  #
+  # @param activities [Array<Hash>] an array of activity hashes.
+  # @return [Hash] a hash containing average speed including zeros and average speed while moving.
+  def calculate_average_speed_from_activities(activities)
+    total_speed_all = 0
+    total_speed_moving = 0
+    speed_count_all = 0
+    speed_count_moving = 0
+
+    activities.each do |activity|
+      activity[:laps].each do |lap|
+        lap[:tracks].flatten.each do |trackpoint|
+          distance = trackpoint[:distance_meters]
+          time_seconds = lap[:total_time_seconds]
+          speed = distance / time_seconds if time_seconds > 0
+
+          if speed
+            total_speed_all += speed
+            speed_count_all += 1
+
+            if speed > 0
+              total_speed_moving += speed
+              speed_count_moving += 1
+            end
+          end
+        end
+      end
+    end
+
+    average_speed_all = speed_count_all > 0 ? total_speed_all.to_f / speed_count_all : 0.0
+    average_speed_moving = speed_count_moving > 0 ? total_speed_moving.to_f / speed_count_moving : 0.0
+
+    {
+      average_speed_all: average_speed_all,
+      average_speed_moving: average_speed_moving
+    }
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tcxread
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - firefly-cpp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-29 00:00:00.000000000 Z
+date: 2024-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -31,6 +31,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - lib/tcxread.rb
 homepage: https://github.com/firefly-cpp/tcxread
 licenses: