GpsTrail 0.3

data/lib/baseconverter.rb

@@ -0,0 +1,12 @@
+class BaseConverter
+  @@converters = Array.new
+
+  def BaseConverter.inherited(sub)
+    @@converters.push(sub.to_s)
+  end
+  
+  def BaseConverter.converters
+    @@converters    
+  end  
+    
+end

data/lib/converters/forerunner301.rb

@@ -0,0 +1,54 @@
+require 'rexml/document'
+require 'journey'
+require 'point'
+require 'sample'
+require 'fileutil'
+require 'template'
+
+include REXML
+
+class Forerunner301 < BaseConverter
+
+  @@device_name = "Forerunner301"  
+
+  def convert(xml_doc)
+    convert_to_domain_model(xml_doc)     
+  end    
+      
+  def convert_to_domain_model(doc)
+    journeys = Array.new
+    doc.elements.each("//Run/") do |journey_xml|       
+      journeys.push(process_journey(journey_xml))
+    end
+    journeys.sort
+  end  
+
+  def process_journey(journey_xml)
+    journey = Journey.new('Run')
+    
+    journey_xml.each_element("Lap/Track/Trackpoint") do |trackpoint|
+      process_trackpoint(journey, trackpoint)
+    end  
+    
+    journey
+  end
+  
+  def process_trackpoint(journey, trackpoint)
+    position = trackpoint.get_elements("Position")[0]
+    
+    if(position)
+      time = trackpoint.get_elements("Time")[0].get_text    
+      lat = position.get_elements("LatitudeDegrees")[0].get_text
+      long = position.get_elements("LongitudeDegrees")[0].get_text
+      alt = position.get_elements("AltitudeMeters")[0].get_text
+      point = Point.new(lat.to_s.to_f, long.to_s.to_f, alt.to_s.to_f)      
+      sample = Sample.new(time, point)
+      journey.add_sample(sample)
+    end      
+  end
+  
+  def to_s
+    @@device_name
+  end  
+  
+end

data/lib/fileutil.rb

@@ -0,0 +1,10 @@
+class FileUtil
+
+  # Illegal characters in Windows filenames (XP SP2) are:
+  # \ / : * ? " < > |
+
+  def FileUtil.convert_to_win_filename!(filename)
+    filename.gsub(/[\\\/:*?"<>|]/, '-')
+  end
+  
+end  

data/lib/folder_template.kml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://earth.google.com/kml/2.0">
+<Document>
+   <name>Forerunner 301</name>
+   <visibility>0</visibility>
+   <open>1</open>
+   <Folder>
+       <name>Forerunner 301</name>
+       <open>1</open>
+       <Folder>
+         <name>${journey_type}</name>
+            <open>1</open>
+         ${placemarks}        
+      </Folder>
+   </Folder>
+</Document>
+</kml>

data/lib/gpstrail.rb

@@ -0,0 +1,113 @@
+#
+# == Synonpsis
+# 
+# GpsTrail lets you view your GPS trips in Google Earth.
+#
+# == Usage
+# 
+# ruby gpstrail.rb [ -ld] | [ -h | -- help] [ -d gpsdevice] [ -f file ]
+# 
+# -ld
+#   List the supported GPS devices 
+# -d
+#   Specify a listed device
+# -f
+#   Specify the file containing the output from the specified device
+#
+# == Example
+# 
+# ruby gpstrail.rb -d Forerunner301 -f "C:\Sport\history.hst"
+
+require 'find'
+require 'rexml/document'
+require 'journey'
+require 'point'
+require 'sample'
+require 'fileutil'
+require 'template'
+require 'baseconverter'
+require 'rdoc/usage'
+require 'optparse'
+require 'ostruct'
+
+include REXML
+
+class GpsTrail
+
+  def process(file_to_process, converter)
+    start_time = Time.now
+    puts "Processing #{file_to_process}\nPlease wait..."
+    STDOUT.flush
+    xml_doc = Document.new(File.open(file_to_process))     
+    journeys = converter.convert(xml_doc)     
+    
+    placemarks_kml = ""
+    journeys.each do |journey|
+      placemarks_kml += create_placemark_kml(journey) 
+    end
+    
+    map = {"placemarks" => placemarks_kml, "journey_type" => "Run"}
+    kml = Template.load_and_substitute('folder_template.kml', map)
+    
+    kml_file_name = File.join(ENV['HOMEPATH'], "gpstrail.kml")
+    kml_file = File.new(kml_file_name, "w")
+    kml_file.puts(kml)
+    kml_file.close    
+    
+    total_time = Time.now - start_time
+    puts "Output written to #{kml_file_name}"
+    puts "Processed #{journeys.size} journeys in #{total_time}s"
+  end    
+  
+  def create_placemark_kml(journey)       
+    look_at_lat, look_at_long = journey.find_center
+    coords = create_coords_list(journey)
+    
+    map = { "look_at_long" => look_at_long.to_s, "look_at_lat" => look_at_lat.to_s, 
+            "range" => journey.find_distance_of_longest_vector.to_s, 
+            "tilt" => 45.to_s, "heading" => 0.to_s, "coordinates" => coords,
+            "name" => journey.start_time.to_s}
+    
+    Template.load_and_substitute('line_template.kml', map)
+  end
+  
+  def create_coords_list(journey)
+    coords = ""
+    journey.samples.each do |sample|
+      point = sample.point
+      coords += point.long.to_s + "," + point.lat.to_s + ",0\n"
+    end  
+    coords
+  end
+    
+  def load_converters
+    Find.find("./converters") do |filename|
+      load filename if filename =~ /rb$/
+    end
+       
+    BaseConverter.converters
+  end    
+    
+end
+
+$: << 'converters'
+options = OpenStruct.new
+
+opts = OptionParser.new
+opts.on("-h", "--help") {RDoc::usage}
+opts.on("-ld") do 
+  puts "Device List:\n" 
+  GpsTrail.new.load_converters.each {|converter| puts "\t#{converter}" }
+  options.devices_listed = true
+end
+opts.on("-d" "=dev_name")  {|dn| options.device_name = dn}
+opts.on("-f", "=file_name")  {|fn| options.file_name = fn}
+opts.parse(ARGV) rescue RDoc::usage
+
+if(options == OpenStruct.new)
+  RDoc::usage    
+elsif(options.device_name && options.file_name)
+  require options.device_name
+  dev = Object.const_get(options.device_name).new
+  GpsTrail.new.process(options.file_name, dev)
+end

data/lib/journey.rb

@@ -0,0 +1,70 @@
+class Journey
+  include Enumerable
+  
+  attr_reader :samples, :type
+  
+  def initialize(type)
+    @samples = Array.new
+    @type = type
+    @max_long_index, @min_long_index = 0, 0
+    @max_lat_index, @min_lat_index = 0, 0   
+  end   
+  
+  def add_sample(sample)
+    @samples.push(sample)
+    new_long = sample.long
+    new_lat = sample.lat
+    
+    @max_long_index = @samples.length-1 if new_long > @samples[@max_long_index].long
+    @min_long_index = @samples.length-1 if new_long < @samples[@min_long_index].long
+    @max_lat_index = @samples.length-1 if new_lat > @samples[@max_lat_index].lat
+    @min_lat_index = @samples.length-1 if new_lat < @samples[@min_lat_index].lat
+  end
+  
+  def [](index)
+    @samples[index]
+  end  
+  
+  def find_center
+    lat = (@samples[@max_lat_index].lat + @samples[@min_lat_index].lat) / 2
+    long = (@samples[@max_long_index].long +  @samples[@min_long_index].long) / 2
+    [lat, long]
+  end
+  
+  def find_distance_of_longest_vector
+    max_long_point = @samples[@max_long_index].point
+    min_long_point = @samples[@min_long_index].point
+    long_distance = max_long_point.distance_from(min_long_point)
+    
+    max_lat_point = @samples[@max_lat_index].point
+    min_lat_point = @samples[@min_lat_index].point
+    lat_distance = max_lat_point.distance_from(min_lat_point)
+    [lat_distance, long_distance].max
+  end
+  
+  def size
+    @samples.size
+  end    
+  
+  def each
+    samples.each {|sample| yield sample}
+  end
+  
+  def <=>(other)
+    self.start_time <=> other.start_time
+  end
+  
+  def start_time
+    samples[0].time
+  end
+  
+  def to_s
+    time = @samples[0].time
+    journey = "#{journey_type} at #{time}:\n"
+    @samples.each do |sample| 
+      journey += sample.to_s + "\n"
+    end
+    journey
+  end
+  
+end

data/lib/line_template.kml

@@ -0,0 +1,28 @@
+<Placemark>
+ <name>${name}</name>
+ <LookAt>
+   <longitude>${look_at_long}</longitude>
+   <latitude>${look_at_lat}</latitude>
+   <range>${range}</range>
+   <tilt>${tilt}</tilt>
+   <heading>${heading}</heading>
+ </LookAt>
+ <visibility>0</visibility>
+ <open>0</open>
+ <Style>
+   <LineStyle>
+     <color>ff00ffff</color>
+   </LineStyle>
+   <PolyStyle>
+     <color>7f00ff00</color>
+   </PolyStyle>
+ </Style>
+ <LineString>
+  <extrude>0</extrude>
+  <tessellate>1</tessellate>
+  <altitudeMode>absolute</altitudeMode>
+  <coordinates>
+   ${coordinates}
+  </coordinates>
+ </LineString>
+</Placemark>

data/lib/point.rb

@@ -0,0 +1,51 @@
+# A Point specifies a latitude, longitude and elevation
+# Note that the elevation is not considered in distance calculations
+class Point
+  
+  AVG_CIRCUMFERANCE_OF_EARTH = 6372795
+  attr_reader :lat, :long, :elevation
+
+  def initialize(lat, long, elevation=0.0)
+    if(lat.nil? or long.nil?)
+      raise ArgumentError
+    end      
+  
+    @lat       = lat 
+    @long      = long
+    @elevation = elevation
+  end
+      
+  def to_s
+    "Lat: #@lat Long: #@long Elevation: #@elevation"
+  end      
+  
+  # Return the distance between one point and another in metres.
+  # Note that distance_from does not take elevation into account.
+  # The formula used is based on great circle distance formula from spherical 
+  # goemetry, but as the Earth is not a sphere a small error may result (up to 0.5%). 
+  # The formula used is that listed on http://en.wikipedia.org/wiki/Great-circle_distance 
+  def distance_from(other)
+    lat1, lat2 = Point.degrees_to_radians(@lat), Point.degrees_to_radians(other.lat)  
+    long1, long2 = Point.degrees_to_radians(@long), Point.degrees_to_radians(other.long)   
+    long_diff = (long1 - long2).abs
+  
+    dvd1 = (Math.cos(lat2) * Math.sin(long_diff))**2
+    dvd2 = ((Math.cos(lat1)*Math.sin(lat2)) - (Math.sin(lat1)*Math.cos(lat2)*Math.cos(long_diff)))**2
+    dividend = Math.sqrt(dvd1 + dvd2)
+    
+    dvr1 = Math.sin(lat1)*Math.sin(lat2)
+    dvr2 = Math.cos(lat1)*Math.cos(lat2)*Math.cos(long_diff)
+    divisor = dvr1 + dvr2
+    
+    arctan_arg = dividend / divisor
+    
+    angular_diff = Math.atan(arctan_arg)
+    
+    angular_diff * AVG_CIRCUMFERANCE_OF_EARTH  
+  end
+  
+  def Point.degrees_to_radians(degrees)
+    degrees * ((2*Math::PI)/360)
+  end
+      
+end      

data/lib/sample.rb

@@ -0,0 +1,26 @@
+class Sample
+
+  attr_reader :time, :point
+  
+  def initialize(time, point)
+    if(time.nil? or point.nil?)
+      raise ArgumentError
+    end
+    
+    @time = time
+    @point = point
+  end
+  
+  def to_s
+    @time.to_s + " " + @point.to_s 
+  end
+
+  def lat
+    point.lat
+  end
+  
+  def long
+    point.long
+  end
+  
+end

data/lib/template.rb

@@ -0,0 +1,18 @@
+class Template
+
+  def Template.substitute(template, key_value_map)  
+    result = template
+    key_value_map.each do |key, value|
+      result = result.gsub("${#{key}}", value)
+    end
+    result
+  end
+  
+  def Template.load_and_substitute(template_name, key_value_map)
+      f = File.new(template_name)
+      template = f.readlines.to_s
+      f.close
+      Template.substitute(template, key_value_map)
+  end
+  
+end

data/readme

@@ -0,0 +1,43 @@
+# == Overview
+#
+# 	GpsTrail lets you view your GPS trips in Google Earth.
+#  
+# == How To Use
+#
+#  	1. Open Garmin Training Center
+#  	2. Click File -> Export History... -> Save
+#  	3. Run converter.rb and specify the location of the file you just saved
+#  	4. In Windows Explorer, navigate to the output directory 
+#     (e.g. C:\Documents and Settings\Paul) and double click on forerunner301.kml 
+#  
+#  	Note: You'll need a Ruby interpreter installed on your Windows system in order
+#  	to run the converter. If you don't have one, download the installer from
+#  	http://rubyinstaller.rubyforge.org/wiki/wiki.pl
+#
+# == Known Issues (in the order I intend to fix them)
+#
+#  	- Currently only exports Runs (not Bike rides, Multisport or Other)
+#  	- The KML file could become prohibitively large
+#     - Try KMZ rather than KML
+#     - Offer an option to create a single Google Earth file per trip
+#  	- The message specifying the output file could be improved
+#  	- Sometimes trips aren't perfectly centered in the Google Earth frame
+#	- Some paths could be tidied (e.g. tc_template.rb)
+#    
+# == Contact
+#
+#	Comments and suggestions welcome at paul.p.carey@gmail.com
+#
+# == Copyright 2006 Paul Carey
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.

data/test/tc_fileutil.rb

@@ -0,0 +1,13 @@
+require 'test/unit'
+require 'fileutil'
+
+class FileUtilTest < Test::Unit::TestCase
+  
+  def test_convert_to_win_filename
+    chars = %W(\\ / : * ? \" < > |)
+    chars.each do |char|
+      assert_equal("1-1", FileUtil.convert_to_win_filename!("1#{char}1"))
+    end       
+  end
+  
+end

data/test/tc_journey.rb

@@ -0,0 +1,37 @@
+require 'test/unit'
+require 'journey'
+require 'point'
+require 'sample'
+
+class JourneyTest < Test::Unit::TestCase
+
+  def setup
+    now = Time.now
+    later = now + 60 
+    p1 = Point.new(54.0, 2.0, 70)
+    p2 = Point.new(55.0, -1.0, 80)  
+    @s1 = Sample.new(now, p1)
+    @s2 = Sample.new(later, p2)
+    
+    @j1 = Journey.new('run')
+    @j1.add_sample(@s1)
+    @j1.add_sample(@s2)  
+  end
+  
+  def test_journey_type
+    assert_equal('run', @j1.type)
+  end
+
+  def test_run
+    assert_equal(2, @j1.size)
+    assert_equal(@s1, @j1[0])
+    assert_equal(@s2, @j1[1])    
+  end
+  
+  def test_find_center
+    lat, long = @j1.find_center
+    assert_equal(54.5, lat)
+    assert_equal(0.5, long)
+  end
+  
+end

data/test/tc_point.rb

@@ -0,0 +1,40 @@
+require 'test/unit'
+require 'point'
+
+class PointTest < Test::Unit::TestCase
+
+  def test_valid_point
+    p1 = Point.new(2.3, 4.5, 50)
+    assert_equal(2.3, p1.lat)
+    assert_equal(4.5, p1.long)
+    assert_equal(50, p1.elevation)
+  end
+  
+  def test_variable_length_constructor
+    p1 = Point.new(5, 10)
+    assert_equal(0, p1.elevation)
+  end
+  
+  def test_nil_atts_passed_to_constructor
+    assert_raise(ArgumentError) {Point.new(nil, 1, 1)}
+    assert_raise(ArgumentError) {Point.new(1, nil, 1)}
+  end
+  
+  def test_degrees_to_radians
+    assert_in_delta(0.0174532925, Point.degrees_to_radians(1), 0.00001)  
+  end
+  
+  def test_distance1
+    bna = Point.new(36.12, -86.67)
+    lax = Point.new(33.94, -118.4)
+    distance = bna.distance_from(lax)
+    assert_in_delta(2887000, distance, 10000)
+  end
+  
+  def test_distance2
+    dublin = Point.new(53.21, -6.15)
+    lusaka = Point.new(-15.28, 28.16)
+    assert_in_delta(8300000, dublin.distance_from(lusaka), 10000)
+  end    
+  
+end

data/test/tc_sample.rb

@@ -0,0 +1,28 @@
+require 'test/unit'
+require 'point'
+require 'sample'
+
+class SampleTest < Test::Unit::TestCase
+
+  def setup
+    @now = Time.now
+    @p1 = Point.new(54, 6.8, 70)  
+  end
+
+  def test_valid_sample
+    s1 = Sample.new(@now, @p1)
+    assert_equal(@now, s1.time)
+    assert_equal(@p1, s1.point)
+  end
+  
+  def test_nil_time
+    assert_raise(ArgumentError) { Sample.new(nil, @p1) }
+  end
+  
+  def test_nil_point
+    assert_raise(ArgumentError) do 
+      Sample.new(@now, nil)
+    end
+  end  
+
+end

data/test/tc_template.kml

@@ -0,0 +1 @@
+How ${pronoun} doin'?

data/test/tc_template.rb

@@ -0,0 +1,32 @@
+require 'test/unit'
+require 'template'
+
+class TemplateTest < Test::Unit::TestCase
+
+  def test_no_substitution
+    s = "hello name"
+    result = Template.substitute(s, Hash.new)
+    assert_equal("hello name", result)
+  end
+  
+  def test_single_substitution
+    s = "hello ${name}"
+    m = { 'name' => 'paul'}
+    result = Template.substitute(s, m)
+    assert_equal("hello paul", result)
+  end
+  
+  def test_multiple_substitution
+    s = "Hello ${name}. This is <${de_ity}> speaking. It's good to meet you ${name}."
+    m = { 'name' => 'Paul', 'de_ity' => 'God'}
+    result = Template.substitute(s, m)
+    assert_equal("Hello Paul. This is <God> speaking. It's good to meet you Paul.", result)
+  end  
+  
+  def test_substitution_from_file
+    m = { 'pronoun' => 'you'}  
+    result = Template.load_and_substitute('../test/tc_template.kml', m)
+    assert_equal("How you doin'?", result)
+  end 
+
+end

data/test/ts_gpstrail.rb

@@ -0,0 +1,7 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "test")
+require 'test/unit'
+require 'tc_point'
+require 'tc_journey'
+require 'tc_sample'
+require 'tc_template'
+require 'tc_forerunner'

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: GpsTrail
+version: !ruby/object:Gem::Version 
+  version: "0.3"
+date: 2006-02-28 00:00:00 +00:00
+summary: GpsTrail lets you view your Forerunner 301 trips in Google Earth
+require_paths: 
+- lib
+email: paul.p.carey@gmail.com
+homepage: 
+rubyforge_project: 
+description: 
+autorequire: converter
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Paul Carey
+files: 
+- lib/baseconverter.rb
+- lib/converters
+- lib/fileutil.rb
+- lib/folder_template.kml
+- lib/gpstrail.rb
+- lib/journey.rb
+- lib/line_template.kml
+- lib/point.rb
+- lib/sample.rb
+- lib/template.rb
+- lib/converters/forerunner301.rb
+- test/tc_fileutil.rb
+- test/tc_journey.rb
+- test/tc_point.rb
+- test/tc_sample.rb
+- test/tc_template.kml
+- test/tc_template.rb
+- test/ts_gpstrail.rb
+- readme
+test_files: 
+- test/ts_gpstrail.rb
+rdoc_options: []
+
+extra_rdoc_files: 
+- readme
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+