gpx/README

= GPX Gem

Copyright (C) 2006  Doug Fales
Doug Fales mailto:doug@falesafeconsulting.com

== What It Does

This library reads GPX files and provides an API for reading and manipulating
the data as objects.  For more info on the GPX format, see
http://www.topografix.com/gpx.asp.

In addition to parsing GPX files, this library is capable of converting
Magellan NMEA files to GPX, and writing new GPX files.  It can crop and delete
rectangular areas within a file, and it also calculates some meta-data about
the tracks and points in a file (such as distance, duration, average speed,
etc).

== Examples

Reading a GPX file, and cropping its contents to a given area:
         <tt>gpx =  GPX::GPXFile.new(:gpx_file => filename)   # Read GPX file</tt>
         <tt>bounds = GPX::Bounds.new(params)                 # Create a rectangular area to crop</tt>
         <tt>gpx.crop(bounds)                                 # Crop it</tt>
         <tt>gpx.write(filename)                              # Save it</tt>

Converting a Magellan track log to GPX:
      <tt>if GPX::MagellanTrackLog::is_magellan_file?(filename)</tt>
      <tt>   GPX::MagellanTrackLog::convert_to_gpx(filename, "#{filename}.gpx")</tt>
      <tt>end</tt>


== Notes

This library was written to bridge the gap between my Garmin Geko
and my website, WalkingBoss.org (RIP).  For that reason, it has always been more of a
work-in-progress than an attempt at full GPX compliance.  The track side of the
library has seen much more use than the route/waypoint side, so if you're doing
something with routes or waypoints, you may need to tweak some things.  

Since this code uses XML to read an entire GPX file into memory, it is not
the fastest possible solution for working with GPX data, especially if you are
working with tracks from several days or weeks.  

Finally, it should be noted that none of the distance/speed calculation or
crop/delete code has been tested under International Date Line-crossing
conditions.  That particular part of the code will likely be unreliable if
you're zig-zagging across 180 degrees longitude routinely.