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 <[email protected]>

Requires

Ruby 1.8.0 or later

License

Copyright 2007 by Chris Joakim. GNU General Public License (GPL) license. See 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

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

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