gooby 1.0.0 → 1.1.0

data/README

@@ -1,22 +1,20 @@
 = Gooby = Google APIs + Ruby 
 
-Version: 1.0.0 - 2007/03/21
+Version: 1.1.0 - 2007/06/10
 
-Gooby = Google APIs + Ruby.  Release 1.0.0 generates Google maps from GPS data
+Gooby = Google APIs + Ruby.  Release 1.1.0 generates Google maps from GPS data
 exported by your Garmin Forerunner GPS unit, or manually edited CSV file.
-Please see the README file.  Feedback is requested.  Sample maps at:
-http://www.joakimsoftware.com/gmap/20050430_nashville_marathon.html
-http://www.joakimsoftware.com/gmap/20060115_phoenix_marathon.html
-http://www.joakimsoftware.com/gmap/20050305_corporate_cup_hm.html
-http://www.joakimsoftware.com/gmap/20070310_corporate_cup_hm.html
-http://www.joakimsoftware.com/gmap/phoenix_marathon.html
+Please see the README file.  Feedback is requested.  
 
-In April 2007, see the 'quick-ETL' project, which will enable you to load
-your GPS data to a relational database.
+Sample maps at:
+http://www.joakim-systems.com:8219/gmap/
+http://www.joakim-systems.com:8219/gmap/ccc_half_2005
+http://www.joakim-systems.com:8219/gmap/nashville_marathon_2005
+http://www.joakim-systems.com:8219/gmap/phoenix_marathon_2006
 
 ---
 
-This package contains 'Gooby', a set of Ruby code to assist you with using and
+This gem contains 'Gooby', a set of Ruby code to assist you with using and
 producing content for the various Google APIs.  The initial focus of Gooby is 
 on the Google Maps API, version 2.0.  
 
@@ -31,25 +29,16 @@ as created in one of the following three ways.
 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 
 marathon runner, and the Garmin Forerunner (I use both models 201 and 205) 
-is primarily intended for running.  Therefore the names of the classes and 
-methods are running oriented (ex. - Run, Track, Trackpoint, Pace, Distance, 
-etc).
+is primarily intended for running.  Other activities, such as cycling, hiking, 
+walking, driving, and even golfing are also well suited for Gooby.  Please let
+me know how you use Gooby!  Feedback is requested.
 
-Other activities, such as cycling, hiking, walking, driving, and even golfing
-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!  Feedback is requested.
-
-All Gooby functionality is intended to be invoked from a command line.  
-Web and Rails integration may be done in a later release.  See the example
-usage section below.
-
-See the Goals/Requirements and Usage sections below for the complete list of
-Gooby functionality.
+All Gooby functionality is intended to be invoked from a command line.  Web
+and Rails integration may be done in a later release.  
 
 = General
 
-Author::   Chris Joakim <chris@joakimsoftware.com>
+Author::   Chris Joakim <chris@joakim-systems.com>
 Requires:: Ruby 1.8.0 or later
 License::  Copyright 2007 by Chris Joakim.
            GNU General Public License (GPL) license.
@@ -68,51 +57,81 @@ The latest version of gooby can be found at
 
 Gooby is packaged and installed as a ruby 'gem'.  Download the latest gem to 
 your computer, then run the following command from your download directory.
-The -t flag will cause the Gooby regression test suite to be executed.
-
-gem install gooby-1.0.0.gem
-or
-gem install gooby-1.0.0.gem -t
-
-== Running the Gooby Test Suite
-
-To execute the test suite, run the following command from the main 'gooby'
-directory:
 
-> ruby tests/ts_gooby.rb 
+gem install gooby-1.1.0.gem
 
 == Online Resources
 
 *  The Gooby home page http://rubyforge.org/projects/gooby/.
    RubyForge provides CVS hosting for the project.
 
-   Sample Gooby-generated Google Maps are at www.joakimsoftware.com, below:
-
-   http://www.joakimsoftware.com/gmap/gps_point_capture.html
-
-   http://www.joakimsoftware.com/gmap/20050305_corporate_cup_hm.html
-   http://www.joakimsoftware.com/gmap/20050430_nashville_marathon.html
-   http://www.joakimsoftware.com/gmap/20060115_phoenix_marathon.html
-   http://www.joakimsoftware.com/gmap/20070310_corporate_cup_hm.html
-   http://www.joakimsoftware.com/gmap/phoenix_marathon.html
+   Sample Gooby-generated Google Maps are at www.joakim-systems.com, below:
+
+   http://www.joakim-systems.com:8219/gmap/
+   http://www.joakim-systems.com:8219/gmap/ccc_half_2005
+   http://www.joakim-systems.com:8219/gmap/nashville_marathon_2005
+   http://www.joakim-systems.com:8219/gmap/phoenix_marathon_2006
+   http://www.joakim-systems.com:8219/gmap/gps_data_capture
+
+== This Release - 1.1.0
+
+*  Greatly simplify usage and command-line argument handling.
+   See the shell scripts and ruby files in the /bin directory for examples.
+
+   Special thanks to Davis Kitchel for his several suggestions that resulted
+   in the following enhancements:
+
+*  Gooby is a Garmin XML parser!  The 'marketing' focus on Gooby prior to now
+   has been on Google Map generation.  However, some users simply use it as
+   a Garmin XML to CSV parser, then use the parsed data for their own various
+   needs without creating a Google map.  This release recognizes that simple
+   parsing of Garmin data is a significant and "core" use of Gooby.
+
+*  Reformatted the parsed CSV files and added more fields to each output 
+   line, including a unique identifier (primary key), run_id, and lap-specific
+   info such as lap number, lap distance, and lap elapsed time.
+
+*  Renamed and enhanced yaml file 'gooby_config.yaml'.  Previously, this had
+   been Google-map biased.  This release allows you to define your own
+   "points of interest" (poi) in the yaml file.  Furthermore, you can define
+   "courses" or "subcourses" which consist of a given series of points-of-
+   interest.  See 'gooby_config.yaml' for examples.
+
+*  Added proximity-based "been_there" reporting logic (method 'been_there' of
+   class GoobyCommand).  This functionality allows you to scan your CVS data
+   file(s) where you have been on user-specified "courses", within a given
+   proximity.  Your courses are defined in the yaml file (see the above item).
+   Proximity is specified in "degrees difference" between the course point
+   definition coordinates, and the actual observed GPS coordinates.  Degrees
+   difference is defined as the absolute value of lat1 - lat2, plus the
+   absolute value of lng1 - lng2.  
+
+   For an example report, see file 'been_there.txt' in the /samples directory.
+
+   This functionality essentially lets you retroactively "click the Lap button"
+   on your Garmin GPS receiver and examine split-times between given points.
+   Typical usage is to examine "hill climb", "time trial", or "speedwork" 
+   zones within your runs or rides. 
+ 
+*  Optional support for loading your GPS data into a MySQL database.  See the
+   generate and load scripts in the /sql directory.  
 
+   Note that Gooby data does NOT need to be loaded into a database; the CSV 
+   format is preferred.  However, users may find it useful to store this data 
+   in a database for their required processing.
 
 === Road Map / TODO List
 
 *  IE or Google Bug - The Google Map v2 JavaScript has not run properly in
    Internet Explorer at times.  Script error after loading the map background,
    but before the map route is drawn.
- 
-*  Incomplete - Google Map generation from your data/geo_data.txt file.
-   You can, however, provide your own data as a CSV file per the current
-   map generation design.
 
-*  Add more regression tests.
+*  Add Rails support for realtime dynamic map/content generation.
+
+*  Parse cadence and heartbeat information from Garmin export file for cyclists.
 
 *  Add other Google APIs (earth, search, sitemaps, froogle, etc).
 
-*  Add Rails support for realtime dynamic map/content generation.
-
 == Support
 
 Please see http://rubyforge.org/projects/gooby/ to submit a request or report
@@ -122,164 +141,109 @@ a bug, on the Tracker page.
 
 = Usage
 
-See files 'bin/example_usage.sh' and 'bin/example_usage.rb' in the gem 
-distribution. Most of the *.rb file is shown below.  You will probably have to
-change the input filenames (yaml, xml, csv) to your own filenames on your 
-computer.
+See the shell scripts and corresponding ruby files in the /bin directory for examples.
+The following in-line text shows both the shell and ruby code.
+
+Function 1 - Garmin XML/TCX file splitting:
+-------------------------------------------
+	shell:
+	
+	ruby /devtools/workspace/RF_Gooby/bin/gooby_splitter.rb  garmin201  /devtools/workspace/RF_Gooby/data/raw/forerunner_201_2007.xml  /temp/splits
+	ruby /devtools/workspace/RF_Gooby/bin/gooby_splitter.rb  garmin205  /devtools/workspace/RF_Gooby/data/raw/forerunner_205_2007.tcx  /temp/splits
 
-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/
+    ruby:
 
+	require 'rubygems' 
 	require 'gooby'
 	include REXML
 
-	# First, create a GoobyCommand object.
-	gooby = Gooby::GoobyCommand.new
+	config_filename = '/devtools/workspace/RF_Gooby/config/gooby_config.yaml'
 
-	# 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)
+	gooby = Gooby::GoobyCommand.new(config_filename)
+	gooby.display_version
+	gooby.split_garmin_export_file(ARGV)
 
-	# Optionally display some of its values.
-	n = 'gmap_approx_max_points'
-	v = options.get(n)
-	puts "option '#{n}' = #{v}"
 
-	# Split a large Garmin ForerunnerLogbook XML file into individual 'run' files.
-	# In this example, '/temp' is the output directory.
-	gooby.split_garmin_forerunner_logbook_xml('data/forerunner_2007.xml', '/temp') if true
+Function 2 - Garmin XML/TCX file parsing:
+-----------------------------------------
+    shell:
 
-	# Split a large Garmin TrainingCenter TCX(XML) file into individual 'activity' files.
-	gooby.split_garmin_training_center_xml('data/2007_03_10.tcx', '/temp') if true
+	ruby /devtools/workspace/RF_Gooby/bin/gooby_parser.rb  garmin201  /devtools/workspace/RF_Gooby/data/raw/forerunner_201_2007.xml  > 
+        	/devtools/workspace/RF_Gooby/data/2007_g201.csv
+	ruby /devtools/workspace/RF_Gooby/bin/gooby_parser.rb  garmin205  /devtools/workspace/RF_Gooby/data/raw/forerunner_205_2007.tcx  >
+        /devtools/workspace/RF_Gooby/data/2007_g205.csv
+	ruby /devtools/workspace/RF_Gooby/bin/gooby_parser.rb  garmin201  /devtools/workspace/RF_Gooby/data/20060115_phoenix_marathon.xml  >
+        /devtools/workspace/RF_Gooby/data/20060115_phoenix_marathon.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_garmin_forerunner_logbook_xml 'data/run_2007_01_01_16_38_27.xml'  if true
+	ruby:
 
-	# 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.  You may also wish to redirect this output to a file.
-	gooby.generate_google_map('data/phx.csv', options)  if true 
-   
-
-== Goals / Requirements 
-          
-=== Functional Requirements
-
-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
+	require 'rubygems' 
+	require 'gooby'
+	include REXML
 
-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.
+	config_filename = '/devtools/workspace/RF_Gooby/config/gooby_config.yaml'
 
-      status = complete
+	gooby = Gooby::GoobyCommand.new(config_filename)
+	gooby.parse_garmin_xml_file(ARGV)
 	
-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.
-
-      status = complete
-
-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.
 
-      status = complete
+Function 3 - "been_there":
+--------------------------
+	shell:
 	
-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 (i.e. - an Internet web page) for a user to easily
-      obtain GPS coordinates for their particular POI, segments, and routes.
-
-      See http://www.joakimsoftware.com/gmap/gps_point_capture.html and also
-      file gps_point_capture.html in the gem.  Modify this file for your site
-      as necessary.
-
-      status = complete
-
-f7.   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.
-
-      status = complete
-
-f8.   Provide adequate user documentation and scripts, so that someone other 
-      than the author can actually use Gooby.
+	ruby /devtools/workspace/RF_Gooby/bin/gooby_been_there.rb > /devtools/workspace/RF_Gooby/samples/been_there.txt
 
-      status = complete, see example_usage.sh and example_usage.rb
-
-f9.  Provide sample files - xml, csv, images.
-
-      status = complete
+	ruby:
+	
+	require 'rubygems' 
+	require 'gooby'
+	include REXML
 
-Currently out-of-scope; but may be implemented at a future date.
-----------------------------------------------------------------
+	config_filename = '/devtools/workspace/RF_Gooby/config/gooby_config.yaml'
 
-f40.  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. 
+	gooby = Gooby::GoobyCommand.new(config_filename)
 
-f41.  Provide the ability to generate Google Maps (requirement f5) from your
-      collection of GPS data (requirement f40).
+	# first read the csv file(s) parsed from your Garmin export tcx/xml files.
+	csv_list = Array.new
+	csv_list << "/devtools/workspace/RF_Gooby/data/2007_g201.csv"  # csv file produced from Garmin 201
+	csv_list << "/devtools/workspace/RF_Gooby/data/2007_g205.csv"  # csv file produced from Garmin 205
 
-f51.  Other Google APIs, such as Google Earth.
+	#  read_csv_files has an optional second arg to display the specified formatted record number (i.e. - (csv_list,3) ).
+	gooby.read_csv_files(csv_list, 3)   
 
-f52.  Rails framework integration.
+	gooby.been_there('333', 0.0025)  # course 333 doesn't exist
 
+	# first arg to 'been_there' is the course number, second arg is the 'proximity' specified as
+	# 'degrees difference'.  Degrees difference is defined as the absolute value of lat1 - lat2, 
+	# plus the absolute value of lng1 - lng2.  Your courses and points of interest (poi) are defined
+	# in the yaml file.
 
-=== Technical Requirements
+	gooby.been_there('1', 0.0025) 
+	gooby.been_there('2', 0.0025) 
+	gooby.been_there('3', 0.0025) 
+	gooby.been_there('4', 0.0025) 
+	gooby.been_there('10', 0.0025)
 
-t1.   Conform to consistent coding and naming standards throughout the code.
 
-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.
+Function 4 - Google Map Generation:
+-----------------------------------
 
-t3.   Implement a reasonably complete set of regression tests using the 
-      'test/unit' framework.  80/20 rule.
+	shell:
+	
+	ruby /devtools/workspace/RF_Gooby/bin/gooby_gen_gmap.rb  /devtools/workspace/RF_Gooby/data/20050430_nashville_marathon.csv  >
+        /devtools/workspace/RF_Gooby/samples/20050430_nashville_marathon.html 
 
-t4.   Implement a way to generate/regenerate regression tests so that as the
-      tested classes/modules evolve, the corresponding test class will 
-      similarly automatically evolve.  New test method "stubs" will be 
-      created, obsolete methods will be flagged, and current test method
-      implementations will be retained.  Writing tests shouldn't hurt.
+	ruby:
 
-t5.   Enable adequate runtime diagnostics; including:
-      a.  Configurible logging mechanism, similar to Java's log4j.
-      b.  Leverage Ruby profiling functionality.
-      c.  Leverage Ruby tracing functionality.
+	require 'rubygems' 
+	require 'gooby'
+	include REXML
 
-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 - bin, data, lib, tests,
-      etc.
+	config_filename = '/devtools/workspace/RF_Gooby/config/gooby_config.yaml'
 
-t8.   Implement a Ruby-standard packaging mechanism, so that users can easily
-      download and install Gooby (i.e. - package Gooby as a gem).
+	gooby = Gooby::GoobyCommand.new(config_filename)
+	gooby.generate_google_map(ARGV)
+		
 
 == Warranty
 

data/bin/example_usage.txt

@@ -0,0 +1,55 @@
+
+The following are sample command line arguments demonstrating the usage of Gooby.
+Three programs are involved - gooby_splitter.rb, gooby_parser.rb, and gooby_gen_gmap.rb.
+
+Please see each of these three files for programatic use of Gooby.
+
+--------------------
+
+gooby_splitter.rb splits a large Garmin Export file into several individual run or activity
+files.  The output *.xml file names are based on start time of the run or activity per 
+the GPS data.
+         
+> ruby bin/gooby_splitter.rb  garmin205  data/raw/20070602.tcx  /temp/splits
+
+  command line args:
+  the first arg, format, should be one of: garmin201, garmin205, garmin305, etc.
+  the second arg is the input filename - which is a garmin export file.
+  the third arg is the output directory where the split files are written to.
+
+--------------------
+  
+gooby_parser.rb parses one of the *.xml files produced by the above gooby_splitter.rb, into a CSV file.
+The CSV file is a simpler and more useful format for most needs.  This CSV file is used
+by the gooby_gen_gmap.rb program, described below.
+
+You should redirect the output of gooby_parser.rb to the file of your choice.
+
+> ruby bin/gooby_parser.rb  garmin201 data/20050305_corporate_cup_hm.xml    > data/20050305_corporate_cup_hm.csv
+> ruby bin/gooby_parser.rb  garmin201 data/20050430_nashville_marathon.xml  > data/20050430_nashville_marathon.csv
+> ruby bin/gooby_parser.rb  garmin201 data/20060115_phoenix_marathon.xml    > data/20060115_phoenix_marathon.csv
+> ruby bin/gooby_parser.rb  garmin205 data/activity_2007_05_05_12_28_32.xml > data/20070505_Davidson_5K.csv
+> ruby bin/gooby_parser.rb  garmin205 data/activity_2007_06_02_11_06_06.xml > data/20070602_11Miler.csv
+
+  command line args:
+  the first arg, format, should be one of: garmin201, garmin205, garmin305, etc.
+  the second arg, input xml filename, was produced by the Gooby 'gooby_splitter.rb' program.
+  
+--------------------
+
+gooby_gen_gmap.rb generates a HTML file which represents a Google Map for the given CSV data.
+The CSV file was produced by the above gooby_parser.rb program.  Note that you can also 
+manually edit your own CSV file with your data, and pass this file to gooby_gen_gmap.rb.
+
+You should redirect the output of gooby_gen_gmap.rb to the file of your choice.
+
+> ruby bin/gooby_gen_gmap.rb data/20050305_corporate_cup_hm.csv   > samples/20050305_corporate_cup_hm.html
+> ruby bin/gooby_gen_gmap.rb data/20050430_nashville_marathon.csv > samples/20050430_nashville_marathon.html
+> ruby bin/gooby_gen_gmap.rb data/20060115_phoenix_marathon.csv   > samples/20060115_phoenix_marathon.html
+> ruby bin/gooby_gen_gmap.rb data/20070505_Davidson_5K.csv        > samples/20070505_Davidson_5K.html
+> ruby bin/gooby_gen_gmap.rb data/20070602_11miler.csv            > samples/20070602_11miler.html
+
+  command line args:
+  the first arg, csv filename, was produced by the Gooby 'gooby_parser.rb' program, or manually edited.
+  
+