= Gooby -- Google APIs + Ruby 

Version: 0.9.1

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 
0.9.1 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 Forerunner 201 XML files.  Both file formats will contain 
your own Global Positioning System (GPS) data.

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 is primarily intended for running.
Therefore the names of the classes and 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 
swimming Google Maps can also be created with Gooby.  Please let me know how
you use Gooby!

All Gooby 0.9.1 functionality is intended to be invoked from a command line.  
Web and Rails integration will be done in a later release.

See the Goals/Requirements and Usage sections below for the complete list of
Gooby functionality.

= General

Author::   Chris Joakim <chris@joakimsoftware.com>
Requires:: Ruby 1.8.0 or later
License::  Copyright 2007 by Chris Joakim.
           GNU General Public License (GPL) license.
           See http://www.gnu.org/copyleft/gpl.html
		
== License

Gooby is available under GNU General Public License (GPL) license.

== Download

The latest version of gooby can be found at
* http://rubyforge/

== Installation

Gooby is packaged and installed as a Gem.

=== Running the Gooby Test Suite

To execute the test suite, run the following command from the main 'gooby'
directory:

> ruby tests/tc_gooby.rb 

Gooby regression test files are in the 'tests' directory.  File 'tc_gooby.rb'
is the main test file, which invokes the other more granular test files.
The philosophy of the Gooby project is to use the Ruby 'test/unit' framework,
and to have one test file for each source code file in the 'lib' directory.

== 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/20041113_richmond_marathon.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/phoenix_marathon.html
   http://www.joakimsoftware.com/gmap/run_2007_02_24_15_01_35.html


=== Road Map / TODO List

*  BUG - Larger maps appear properly in Safari and Firefox browser, but not on
   Windows Explorer.

*  Incomplete, WIP - Google Map generation from your data/geo_data.txt file.

*  Incomplete, WIP - Support sources of GPS data other than Garmin Forerunner 
   XML from Forerunner Logbook.  Training Center and Forerunner 205 data is 
   expected in March 2007.   

*  BUG - TestGenerator adds two space lines to top-of-file upon test code
   regeneration.

*  Add more regression tests.

*  Add Rails support for realtime dynamic map/content generation.

*  Add other Google APIs (earth, search, sitemaps, froogle, etc).

== Support

Please see http://rubyforge.org/projects/gooby/.

----

= Usage

All Gooby 1.0 functionality is intended to be invoked from a command line.  
See the /bin directory for commented examples.

# Example 1: "Splitting" a huge exported Garmin Forerunner Logbook XML file
# into its individual <Run> files, sending output files to the /temp directory.

> ruby bin/forerunner_xml_splitter.rb /temp data/forerunner_2007.xml

---

# Eaxmple 2: Parsing exported Garmin Forerunner XML into CSV format

> ruby bin/forerunner_xml_parser.rb data/phx.xml > data/phx.csv

---

# Eaxmple 3: Generating a Google Map HTML page from your CSV file.
# Remember to edit 'gooby_options.yaml' with your Google Map key and other
# configuration settings (title, map size, etc).

> ruby  bin/gen_gmap.rb  data/phx.csv > samples/phoenix_marathon.html
   

== Goals / Requirements 
          
=== Functional Requirements

f1.   Provide the ability to parse exported XML data from a Garmin Forerunner
      GPS receiver, specifically model 201.  Parse the XML into less-verbose 
      and more-editable CSV format.

f2.   Provide the ability to "split" a large Garmin 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.

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 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).

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.

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.

f8.   Provide adequate user documentation and scripts, so that someone other 
      than the author can actually use Gooby.

f9.   Provide sample files - xml, csv, images.

Currently out-of-scope but intended for a future release:
---------------------------------------------------------

f50.  Rails framework integration.

f51.  Other Google APIs, such as Google Earth.

f52.  Parsing of other XML GPS formats other than Garmin Forerunner.

=== Technical Requirements

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.

t3.   Implement a reasonably complete set of regression tests using the 
      'test/unit' framework.

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.

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.

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.

t8.   Implement a Ruby-standard packaging mechanism, so that users can easily
      download and install Gooby.

== Warranty

This software is provided "as is" and without any express or implied warranties, 
including, without limitation, the implied warranties of merchantibility and 
fitness for a particular purpose.
