gpx 0.1

data/lib/gpx/magellan_track_log.rb

@@ -0,0 +1,134 @@
+#--
+# Copyright (c) 2006  Doug Fales 
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+module GPX
+
+   # This class will parse the lat/lon and time data from a Magellan track log,
+   # which is a NMEA formatted CSV list of points.
+
+   class MagellanTrackLog
+      #PMGNTRK
+      # This message is to be used to transmit Track information (basically a list of previous position fixes) 
+      # which is often displayed on the plotter or map screen of the unit.  The first field in this message 
+      # is the Latitude, followed by N or S.  The next field is the Longitude followed by E or W.  The next 
+      # field is the altitude followed by “F” for feet or “M” for meters.  The next field is 
+      # the UTC time of the fix.  The next field consists of a status letter of “A” to indicated that 
+      # the data is valid, or “V” to indicate that the data is not valid.  The last character field is 
+      # the name of the track, for those units that support named tracks.  The last field contains the UTC date 
+      # of the fix.  Note that this field is (and its preceding comma) is only produced by the unit when the 
+      # command PMGNCMD,TRACK,2 is given.  It is not present when a simple command of PMGNCMD,TRACK is issued.
+
+      #NOTE: The Latitude and Longitude Fields are shown as having two decimal
+      # places. As many additional decimal places may be added as long as the total
+      # length of the message does not exceed 82 bytes.
+
+      # $PMGNTRK,llll.ll,a,yyyyy.yy,a,xxxxx,a,hhmmss.ss,A,c----c,ddmmyy*hh<CR><LF>
+      require 'csv' 
+
+      LAT       = 1
+      LAT_HEMI  = 2
+      LON       = 3
+      LON_HEMI  = 4
+      ELE       = 5 
+      ELE_UNITS = 6
+      TIME      = 7
+      INVALID_FLAG = 8
+      DATE      = 10
+
+      FEET_TO_METERS = 0.3048
+
+      class << self
+
+         # Takes the name of a magellan file, converts the contents to GPX, and
+         # writes the result to gpx_filename.
+         def  convert_to_gpx(magellan_filename, gpx_filename)
+
+            segment = Segment.new
+
+            CSV.open(magellan_filename, "r") do |row| 
+               next if(row.size < 10 or row[INVALID_FLAG] == 'V')
+
+               lat_deg  = row[LAT][0..1]
+               lat_min  = row[LAT][2...-1]
+               lat_hemi = row[LAT_HEMI]
+
+               lat = lat_deg.to_f + (lat_min.to_f / 60.0)
+               lat = (-lat) if(lat_hemi == 'S')
+
+               lon_deg      = row[LON][0..2]
+               lon_min  = row[LON][3..-1]
+               lon_hemi = row[LON_HEMI]
+
+               lon = lon_deg.to_f + (lon_min.to_f / 60.0)
+               lon = (-lon) if(lon_hemi == 'W')
+
+
+               ele = row[ELE]
+               ele_units = row[ELE_UNITS]
+               ele = ele.to_f
+               if(ele_units == 'F')
+                  ele *= FEET_TO_METERS
+               end
+
+               hrs  = row[TIME][0..1].to_i
+               mins = row[TIME][2..3].to_i
+               secs = row[TIME][4..5].to_i
+               day  = row[DATE][0..1].to_i
+               mon  = row[DATE][2..3].to_i
+               yr   = 2000 + row[DATE][4..5].to_i
+
+               time = Time.gm(yr, mon, day, hrs, mins, secs)
+
+               #must create point
+               pt = TrackPoint.new(:lat => lat, :lon => lon, :time => time, :elevation => ele)
+               segment.append_point(pt)
+
+            end 
+
+            trk = Track.new
+            trk.append_segment(segment)
+            gpx_file = GPXFile.new(:tracks => [trk])
+            gpx_file.write(gpx_filename)
+
+         end
+
+         # Tests to see if the given file is a magellan NMEA track log.
+         def is_magellan_file?(filename)
+            i = 0
+            File.open(filename, "r") do |f|
+               f.each do |line|
+                  i +=  1
+                  if line =~ /^\$PMGNTRK/
+                     return true 
+                  elsif line =~ /<\?xml/
+                     return false
+                  elsif(i > 10)
+                     return false 
+                  end
+               end
+            end
+            return false
+         end
+      end
+
+   end
+end

data/lib/gpx/point.rb

@@ -0,0 +1,103 @@
+#--
+# Copyright (c) 2006  Doug Fales 
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+include Math
+module GPX
+   # The base class for all points.  Trackpoint and Waypoint both descend from this base class.
+   class Point < Base
+      D_TO_R = PI/180.0;
+      attr_accessor :lat, :lon, :time, :elevation
+
+      # When you need to manipulate individual points, you can create a Point
+      # object with a latitude, a longitude, an elevation, and a time.  In
+      # addition, you can pass a REXML element to this initializer, and the
+      # relevant info will be parsed out.
+      def initialize(opts = {:lat => 0.0, :lon => 0.0, :elevation => 0.0, :time => Time.now } )
+         if (opts[:element]) 
+            elem = opts[:element]
+            @lat, @lon = elem.attributes["lat"].to_f, elem.attributes["lon"].to_f
+            @latr, @lonr = (D_TO_R * @lat), (D_TO_R * @lon)
+            #'-'? yyyy '-' mm '-' dd 'T' hh ':' mm ':' ss ('.' s+)? (zzzzzz)?
+            @time = (Time.xmlschema(elem.elements["time"].text) rescue nil)
+            @elevation = elem.elements["ele"].text.to_f if elem.elements["ele"]
+         else
+            @lat = opts[:lat]
+            @lon = opts[:lon]
+            @elevation = opts[:elevation]
+            @time = opts[:time]
+         end
+
+      end
+
+
+      # Returns the latitude and longitude (in that order), separated by the
+      # given delimeter.  This is useful for passing a point into another API
+      # (i.e. the Google Maps javascript API).
+      def lat_lon(delim = ', ')
+        "#{lat}#{delim}#{lon}"
+      end
+
+      # Returns the longitude and latitude (in that order), separated by the
+      # given delimeter.  This is useful for passing a point into another API
+      # (i.e. the Google Maps javascript API).
+      def lon_lat(delim = ', ')
+        "#{lon}#{delim}#{lat}"
+      end
+
+      # Latitude in radians.
+      def latr
+         @latr ||= (@lat * D_TO_R)
+      end
+
+      # Longitude in radians.
+      def lonr
+         @lonr ||= (@lon * D_TO_R)
+      end
+
+      # Set the latitude (in degrees).
+      def lat=(latitude)
+         @latr = (latitude * D_TO_R)
+         @lat = latitude
+      end
+
+      # Set the longitude (in degrees).
+      def lon=(longitude)
+         @lonr = (longitude * D_TO_R)
+         @lon = longitude
+      end
+
+      # Convert this point to a REXML::Element.
+      def to_xml(elem_name = 'trkpt')
+         pt = Element.new('trkpt')
+         pt.attributes['lat'] = lat
+         pt.attributes['lon'] = lon
+         time_elem = Element.new('time')
+         time_elem.text = time.xmlschema
+         pt.elements << time_elem
+         elev = Element.new('ele')
+         elev.text = elevation
+         pt.elements << elev
+         pt
+      end
+
+   end
+end

data/lib/gpx/route.rb

@@ -0,0 +1,65 @@
+#--
+# Copyright (c) 2006  Doug Fales 
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+module GPX
+
+   # A Route in GPX is very similar to a Track, but it is created by a user
+   # from a series of Waypoints, whereas a Track is created by the GPS device
+   # automatically logging your progress at regular intervals.  
+   class Route < Base
+
+      attr_reader :points, :name, :gpx_file
+
+      # Initialize a Route from a REXML::Element.
+      def initialize(opts = {})
+         rte_element = opts[:element]
+         @gpx_file = opts[:gpx_file]
+         @name = rte_element.elements["child::name"].text
+         @points = []
+         XPath.each(rte_element, "child::rtept") do |point|
+            @points << Point.new(:element => point)
+         end
+
+      end
+
+      # Delete points outside of a given area.
+      def crop(area)
+         points.delete_if{ |pt| not area.contains? pt }
+      end
+
+      # Delete points within the given area.
+      def delete_area(area)
+         points.delete_if{ |pt| area.contains? pt }
+      end
+
+      # Convert this Route to a REXML::Element.
+      def to_xml
+         rte = Element.new('rte')
+         name_elem = Element.new('name')
+         name_elem.text = name
+         rte.elements << name_elem
+         points.each { |rte_pt| rte.elements << rte_pt.to_xml('rtept') }
+         rte
+      end
+
+   end
+end

data/lib/gpx/segment.rb

@@ -0,0 +1,217 @@
+#--
+# Copyright (c) 2006  Doug Fales 
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+module GPX
+
+   # A segment is the basic container in a GPX file.  A Segment contains points
+   # (in this lib, they're called TrackPoints).  A Track contains Segments.  An
+   # instance of Segment knows its highest point, lowest point, earliest and
+   # latest points, distance, and bounds.
+   class Segment < Base
+
+      attr_reader :earliest_point, :latest_point, :bounds, :highest_point, :lowest_point, :distance
+      attr_accessor :points, :track 
+
+      # If a REXML::Element object is passed-in, this will initialize a new
+      # Segment based on its contents.  Otherwise, a blank Segment is created.
+      def initialize(opts = {})
+         @track = opts[:track]
+         @points = []
+         @earliest_point = nil
+         @latest_point = nil
+         @highest_point = nil
+         @lowest_point = nil
+         @distance = 0.0
+         @bounds = Bounds.new
+         if(opts[:element])
+            segment_element = opts[:element]
+            last_pt = nil
+            unless segment_element.is_a?(Text)
+               XPath.each(segment_element, "child::trkpt") do |trkpt| 
+                  pt = TrackPoint.new(:element => trkpt, :segment => self)  
+                  @earliest_point = pt if(@earliest_point.nil? or pt.time < @earliest_point.time)
+                  @latest_point   = pt if(@latest_point.nil? or pt.time > @latest_point.time)
+                  unless pt.elevation.nil?
+                     @lowest_point   = pt if(@lowest_point.nil? or pt.elevation < @lowest_point.elevation)
+                     @highest_point  = pt if(@highest_point.nil? or pt.elevation > @highest_point.elevation)
+                  end
+                  @bounds.min_lat = pt.lat if pt.lat < @bounds.min_lat
+                  @bounds.min_lon = pt.lon if pt.lon < @bounds.min_lon
+                  @bounds.max_lat = pt.lat if pt.lat > @bounds.max_lat
+                  @bounds.max_lon = pt.lon if pt.lon > @bounds.max_lon
+
+                  @distance += haversine_distance(last_pt, pt) unless last_pt.nil?
+
+                  @points << pt
+                  last_pt  = pt
+               end
+            end
+         end
+      end
+
+      # Tack on a point to this Segment.  All meta-data will be updated.
+      def append_point(pt)
+         last_pt = @points[-1]
+         @earliest_point = pt if(@earliest_point.nil? or pt.time < @earliest_point.time)
+         @latest_point   = pt if(@latest_point.nil? or pt.time > @latest_point.time)
+         @lowest_point   = pt if(@lowest_point.nil? or pt.elevation < @lowest_point.elevation)
+         @highest_point  = pt if(@highest_point.nil? or pt.elevation > @highest_point.elevation)
+         @bounds.min_lat = pt.lat if pt.lat < @bounds.min_lat
+         @bounds.min_lon = pt.lon if pt.lon < @bounds.min_lon
+         @bounds.max_lat = pt.lat if pt.lat > @bounds.max_lat
+         @bounds.max_lon = pt.lon if pt.lon > @bounds.max_lon
+         @distance += haversine_distance(last_pt, pt) unless last_pt.nil?
+         @points << pt
+      end
+
+      # Returns true if the given time is within this Segment.
+      def contains_time?(time)
+         (time >= @earliest_point.time and time <= @latest_point.time)
+      end
+
+      # Finds the closest point in time to the passed-in time argument.  Useful
+      # for matching up time-based objects (photos, video, etc) with a
+      # geographic location.
+      def closest_point(time)
+         find_closest(points, time)
+      end
+
+      # Deletes all points within this Segment that lie outside of the given
+      # area (which should be a Bounds object).
+      def crop(area)
+         delete_if { |pt| not area.contains?(pt) }
+      end
+
+      # Deletes all points in this Segment that lie within the given area.
+      def delete_area(area)
+         delete_if{ |pt| area.contains?(pt) }
+      end
+
+      # A handy method that deletes points based on a block that is passed in.
+      # If the passed-in block returns true when given a point, then that point
+      # is deleted.  For example:
+      #         delete_if{ |pt| area.contains?(pt) }
+      def delete_if
+         reset_meta_data
+         keep_points = []
+         last_pt = nil
+         points.each do |pt| 
+            unless yield(pt)
+               keep_points << pt
+               update_meta_data(pt, last_pt)
+               last_pt = pt
+            end
+         end
+         @points = keep_points
+      end
+
+      # Returns true if this Segment has no points.
+      def empty?
+         (points.nil? or (points.size == 0))
+      end
+
+      # Converts this Segment to a REXML::Element object.
+      def to_xml
+         seg = Element.new('trkseg')
+         points.each { |pt| seg.elements << pt.to_xml }
+         seg
+      end
+
+      # Prints out a nice summary of this Segment.
+      def to_s
+         result = "Track Segment\n"
+         result << "\tSize: #{points.size} points\n"
+         result << "\tDistance: #{distance} km\n"
+         result << "\tEarliest Point: #{earliest_point.time.to_s} \n"
+         result << "\tLatest Point: #{latest_point.time.to_s} \n"
+         result << "\tLowest Point: #{lowest_point.elevation} \n"
+         result << "\tHighest Point: #{highest_point.elevation}\n "
+         result << "\tBounds: #{bounds.to_s}"
+         result
+      end
+
+      protected
+      def find_closest(pts, time)
+         return pts.first if pts.size == 1
+         midpoint = pts.size/2
+         if pts.size == 2
+            diff_1 = pts[0].time - time
+            diff_2 = pts[1].time - time
+            return (diff_1 < diff_2 ? pts[0] : pts[1])
+         end
+         if time >= pts[midpoint].time and time <= pts[midpoint+1].time
+
+            return pts[midpoint]
+
+         elsif(time <= pts[midpoint].time)
+            return find_closest(pts[0..midpoint], time)
+         else
+            return find_closest(pts[(midpoint+1)..-1], time)
+         end
+      end
+
+      RADIUS = 6371; # earth's mean radius in km
+
+      # Calculate the Haversine distance between two points. This is the method
+      # the library uses to calculate the cumulative distance of GPX files. 
+      def haversine_distance(p1, p2)
+         d_lat = p2.latr - p1.latr;
+         d_lon = p2.lonr - p1.lonr;
+         a = Math.sin(d_lat/2) * Math.sin(d_lat/2) + Math.cos(p1.latr) * Math.cos(p2.latr) * Math.sin(d_lon/2) * Math.sin(d_lon/2);
+         c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
+         d = RADIUS * c;
+         return d;
+      end
+
+      # Calculate the plain Pythagorean difference between two points.  Not currently used.
+      def pythagorean_distance(p1, p2)
+         Math.sqrt((p2.latr - p1.latr)**2 + (p2.lonr - p1.lonr)**2)
+      end
+
+      # Calculates the distance between two points using the Law of Cosines formula.  Not currently used.
+      def law_of_cosines_distance(p1, p2)
+         (Math.acos(Math.sin(p1.latr)*Math.sin(p2.latr) + Math.cos(p1.latr)*Math.cos(p2.latr)*Math.cos(p2.lonr-p1.lonr)) * RADIUS)
+      end
+
+      def reset_meta_data
+         @earliest_point = nil
+         @latest_point = nil
+         @highest_point = nil
+         @lowest_point = nil
+         @distance = 0.0
+         @bounds = Bounds.new
+      end
+
+      def update_meta_data(pt, last_pt)
+         @earliest_point = pt if(@earliest_point.nil? or pt.time < @earliest_point.time)
+         @latest_point   = pt if(@latest_point.nil? or pt.time > @latest_point.time)
+         unless pt.elevation.nil?
+            @lowest_point   = pt if(@lowest_point.nil? or pt.elevation < @lowest_point.elevation)
+            @highest_point  = pt if(@highest_point.nil? or pt.elevation > @highest_point.elevation)
+         end
+         @bounds.add(pt)
+         @distance += haversine_distance(last_pt, pt) unless last_pt.nil?
+      end
+
+   end
+
+end