gooby 0.9.3 → 0.9.4

data/README

@@ -1,19 +1,29 @@
 = Gooby -- Google APIs + Ruby 
 
-Version: 0.9.3
+Version: 0.9.4
+
+RubyForge Release Notes:
+
+Gooby = Google APIs + Ruby.
+This release adds support for Garmin TrainingCenter TCX XML files, created by 
+the newer Garmin devices such as models 205 and 305.  For an example of a Google Map
+created with Gooby, see http://www.joakimsoftware.com/gmap/phoenix_marathon.html
+
+---
 
 This package contains 'Gooby', a set of Ruby code to assist you with using and
-producing content for the various Google APIs.  The initial focus of version 
-Gooby is on the Google Maps API, version 2.0.  
+producing content for the various Google APIs.  The initial focus of Gooby is 
+on the Google Maps API, version 2.0.  
 
-Google Maps can be produced using Gooby from either CSV files, or from exported
-and parsed Garmin ForerunnerLogbook XML files.  Both file formats will contain 
-your own Global Positioning System (GPS) data.  
+Google Maps can be produced using Gooby from your data in CSV format, 
+as created in one of the following three ways.
+1)  From exported and parsed Garmin ForerunnerLogbook XML files.
+2)  From exported and parsed Garmin TrainingCenter TCX(XML) files.
+3)  From your own manually edited Global Positioning System (GPS) data.
+    See any of the 'data/*.csv' files in the distribution for an example
+    of the CSV format. 
 
-Support for Garmin TrainingCenter *.tcx files will be in the next release.
-The exported XML file formats from Garmin ForerunnerLogbook and Garmin
-TrainingCenter are different, yet altering the Gooby parsing code shouldn't
-require a major effort.
+Support for Garmin TrainingCenter *.tcx files was added in the 0.9.4 release.
 
 Google maps are applicable really to any outdoor activity for which GPS data 
 can be obtained.  The focus of Gooby is on running, because the author is a 
@@ -23,11 +33,11 @@ methods are running oriented (ex. - Run, Track, Trackpoint, pace, distance,
 etc).
 
 Other activities, such as cycling, hiking, walking, driving, and even golfing
-are also well suited for Gooby.  Given a waterproof GPS receiver, sailing and 
+are also well suited for Gooby.  Given a waterproof GPS receiver, sailing, and 
 swimming Google Maps can also be created with Gooby.  Please let me know how
 you use Gooby!
 
-All Gooby 0.9.3 functionality is intended to be invoked from a command line.  
+All Gooby 0.9.4 functionality is intended to be invoked from a command line.  
 Web and Rails integration may be done in a later release.
 
 See the Goals/Requirements and Usage sections below for the complete list of
@@ -124,6 +134,12 @@ See file 'bin/example_usage.rb' in the gem distribution.  Most of this file
 is shown below.  You will probably have to change the input filenames (yaml, 
 xml, csv) to your own filenames on your computer.
 
+Of course, you'll also have to obtain a Google Maps key for your web site.
+It's free, and has to be included in every page which displays a map.  See
+the 'gmap_key' entry in 'gooby_options.yaml', which embeds your key value 
+into the generated html page.  Also see the Google Maps API site - 
+http://www.google.com/apis/maps/
+
 	require 'gooby'
 
 	include REXML
@@ -141,66 +157,103 @@ xml, csv) to your own filenames on your computer.
 	v = options.get(n)
 	puts "option '#{n}' = #{v}"
 
-	# Split a large ForerunnerLogbook XML file into individual r 'run' files.
+	# Split a large Garmin ForerunnerLogbook XML file into individual 'run' files.
 	# In this example, '/temp' is the output directory.
-	gooby.split_forerunner_xml('data/forerunner_2007.xml', '/temp')
+	gooby.split_garmin_forerunner_logbook_xml('data/forerunner_2007.xml', '/temp') 
+
+	# Split a large Garmin TrainingCenter TCX(XML) file into individual 'activity' files.
+	gooby.split_garmin_training_center_xml('data/2007_03_04.tcx', '/temp') 
 
-	# Parse a ForerunnerLogbook XML file, or 'split' subset, into CSV.
+	# Parse a Garmin ForerunnerLogbook XML file, or previously 'split' subset, into CSV.
 	# You may want to redirect this output to a file.
-	gooby.parse_forerunner_xml 'data/run_2007_01_01_16_38_27.xml' 
+	gooby.parse_garmin_forerunner_logbook_xml 'data/run_2007_01_01_16_38_27.xml' 
+
+	# Parse a TrainingCenter TCX(XML) file, or previously 'split' subset, into CSV.
+	gooby.parse_garmin_training_center_xml 'data/activity_2007_03_04_15_22_36.xml'  
 
 	# Generate a Google Map from your CSV file data, and the Options per
-	# your yaml file.  
-	gooby.generate_google_map('data/phx.csv', options)
+	# your yaml file.  You may also wish to redirect this output to a file.
+	gooby.generate_google_map('data/phx.csv', options)  
    
 
 == Goals / Requirements 
           
 === Functional Requirements
 
-f1.   Provide the ability to parse exported XML data from a Garmin Forerunner
-      GPS receiver, specifically model 201.  Garmin ForerunnerLogbook is the
-      software used to export this XML.  Parse the XML into less-verbose and
-      more-editable CSV format.
+f1.   Provide the ability to parse exported XML GPS data files from the Garmin
+      ForerunnerLogbook software.  ForerunnerLogbook is used in conjunction
+      with the Garmin Forerunner 201 GPS receiver.  Parse the XML into less-
+      verbose and more readable and editable CSV format.
+
+      status = complete
+
+f2.   Provide the ability to parse exported XML GPS data files from the Garmin
+      TrainingCenter software.  TrainingCenter is used in conjunction with
+      newer Garmin GPS receivers, such as model 205 and 305.  Parse the TCX
+      file (XML format) into less-verbose and more readable and editable CSV
+      format.
+
+      status = complete
+	
+f3.   Provide the ability to "split" a large Garmin ForerunnerLogbook XML file
+      containing many "runs" into individual "run_" files.  The individual 
+      files can then be processed separately, and can optionally be stored in 
+      your personal records directory or source control system.
 
-f2.   Provide the ability to "split" a large Garmin ForerunnerLogbook XML file
-      containing many "runs" into individual run files.  The individual files 
-      can then be processed separately, and can optionally be stored in your 
-      personal records directory or source control system.
+      status = complete
 
-f3.   Provide the ability to generate Google Map HTML content from your GPS 
-      data in CSV or other simple text format, using the Google Map API v2.0.
-      The generated content should be viewable in most current web browsers,
-      including Apple Safari 2 and Windows Internet Explorer 6.
+f4.   Provide the ability to "split" a large Garmin TrainingCenter TCX/XML file
+      containing many "activities" into individual "activity_" files.  The 
+      individual files can then be processed separately, and can optionally be
+      stored in your personal records directory or source control system.
 
-f4.   Provide the ability to define your own points-of-interest (POI), route
+      status = complete
+	
+f5.   Provide the ability to generate Google Map HTML content from your GPS 
+      data in CSV text format, using the Google Map API v2.0.  The generated 
+      content should be viewable in most current web browsers, including Apple
+      Safari 2, Firefox 1.5, and Windows Internet Explorer 6.
+
+      status = complete
+
+f6.   Provide the ability to define your own points-of-interest (POI), route
       segments, and routes as a collection of GPS data in a simple text file.
       Allow "routes" to be composed from "reusable route segments", and 
       annotated with your own POI. 
 
-f5.   Provide the ability to generate Google Maps (requirement f3) from your
-      collection of GPS data (requirement f4).
+      status = in-progress
+
+f7.   Provide the ability to generate Google Maps (requirement f5) from your
+      collection of GPS data (requirement f6).
 
-f6.   Provide the ability (i.e. - an Internet web page) for a user to easily
+      status = in-progress
+
+f8.   Provide the ability (i.e. - an Internet web page) for a user to easily
       obtain GPS coordinates for their particular POI, segments, and routes.
 
-f7.   Provide the ability to alter appropriate Gooby behavior via a simple
+      status = complete.
+
+f9.   Provide the ability to alter appropriate Gooby behavior via a simple
       configuration file (i.e. - gooby_options.yaml) rather than modifying 
       the source code.  Specific configuration requirements are:
       a.  Allow the user to specify roughly how many points appear on a map.
       b.  Allow the user to specify a distance unit-of-measure in either
           miles, kilometers, or yards.
 
-f8.   Provide adequate user documentation and scripts, so that someone other 
+      status = in-progress
+
+f10   Provide adequate user documentation and scripts, so that someone other 
       than the author can actually use Gooby.
 
-f9.   Provide sample files - xml, csv, images.
+      status = in-progress
+
+f11.  Provide sample files - xml, csv, images.
+
+      status = complete
 
 Currently out-of-scope but intended for a future release:
 ---------------------------------------------------------
 
-f50.  Parsing of other XML GPS formats other than Garmin Forerunner.
-
 f51.  Other Google APIs, such as Google Earth.
 
 f52.  Rails framework integration.
@@ -213,7 +266,7 @@ t2.   Strive to implement the code in the "standard Ruby way", and to try to
       discover exactly what that is during the development of Gooby.
 
 t3.   Implement a reasonably complete set of regression tests using the 
-      'test/unit' framework.
+      'test/unit' framework.  80/20 rule.
 
 t4.   Implement a way to generate/regenerate regression tests so that as the
       tested classes/modules evolve, the corresponding test class will 
@@ -229,11 +282,11 @@ t5.   Enable adequate runtime diagnostics; including:
 t6.   Use the RubyForge CVS repository as the SCM after initial development;
       use local SCM during the initial development.
  
-t7.   Implement a Ruby-standard directory structure - code, tests, data, 
-      documentation, etc.
+t7.   Implement a Ruby-standard directory structure - bin, data, lib, tests,
+      etc.
 
 t8.   Implement a Ruby-standard packaging mechanism, so that users can easily
-      download and install Gooby.
+      download and install Gooby (i.e. - package Gooby as a gem).
 
 == Warranty
 

data/bin/example_usage.rb

@@ -7,6 +7,9 @@ to your own filenames on your computer.
 
 =end
 
+# The following prefixes ../lib to the active ruby load path
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
 require 'gooby'
 
 include REXML
@@ -24,15 +27,21 @@ n = 'gmap_approx_max_points'
 v = options.get(n)
 puts "option '#{n}' = #{v}"
 
-# Split a large ForerunnerLogbook XML file into individual r 'run' files.
+# Split a large Garmin ForerunnerLogbook XML file into individual 'run' files.
 # In this example, '/temp' is the output directory.
-gooby.split_forerunner_xml('data/forerunner_2007.xml', '/temp')
+gooby.split_garmin_forerunner_logbook_xml('data/forerunner_2007.xml', '/temp') if true
+
+# Split a large Garmin TrainingCenter TCX(XML) file into individual 'activity' files.
+gooby.split_garmin_training_center_xml('data/2007_03_04.tcx', '/temp') if true
 
-# Parse a ForerunnerLogbook XML file, or 'split' subset, into CSV.
+# Parse a Garmin ForerunnerLogbook XML file, or previously 'split' subset, into CSV.
 # You may want to redirect this output to a file.
-gooby.parse_forerunner_xml 'data/run_2007_01_01_16_38_27.xml' 
+gooby.parse_garmin_forerunner_logbook_xml 'data/run_2007_01_01_16_38_27.xml'  if true
+
+# Parse a TrainingCenter TCX(XML) file, or previously 'split' subset, into CSV.
+gooby.parse_garmin_training_center_xml 'data/activity_2007_03_04_15_22_36.xml'  if true
 
 # Generate a Google Map from your CSV file data, and the Options per
-# your yaml file.  
-gooby.generate_google_map('data/phx.csv', options)
+# your yaml file.  You may also wish to redirect this output to a file.
+gooby.generate_google_map('data/phx.csv', options)  if false
   

data/bin/tcx_ex.rb

@@ -0,0 +1,35 @@
+=begin rdoc
+
+This file contains examples of how to use Gooby.
+
+You will probably have to change the input filenames (yaml, xml, csv)
+to your own filenames on your computer.
+
+=end
+
+# The following prefixes ../lib to the active ruby load path
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+puts '$LOAD_PATH is now:'
+puts $LOAD_PATH
+
+require 'gooby'
+
+include REXML
+
+# First, create a GoobyCommand object.
+gooby = Gooby::GoobyCommand.new
+
+# Next, create an Options object from the given yaml file - see the sample 
+# 'gooby_options.yaml' file in the distribution.
+options_file = 'gooby_options.yaml'
+options = gooby.options(options_file)
+
+# Optionally display some of its values.
+n = 'gmap_approx_max_points'
+v = options.get(n)
+puts "option '#{n}' = #{v}"
+
+# Split a large ForerunnerLogbook XML file into individual 'run' files.
+# In this example, '/temp' is the output directory.
+gooby.split_garmin_training_center_xml('data/2007_03_04.tcx', '/temp')
+