where_was_i 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f76b6b51ae66a959ee39162517a749fe40397d2c
-  data.tar.gz: 639a75c546b03ef5c17c13f7b15db1112b231e7a
+  metadata.gz: af13af41cb05d18d3084de41b04c6876dccffbe5
+  data.tar.gz: 3aa33bfa697733a7ed454e882797c4cd52e747c8
 SHA512:
-  metadata.gz: 3f1280bc1b60fd733398f0c011c6bfbb57e72eca637ade33681628232234d4f1916c1ec2f638c78015a2f29d645dc64a97a830af27640f49ec6448f6b1b52ad2
-  data.tar.gz: 74209c3e5c8ab8296bcf86f78942a6e81f2253eeb7ef5aaa4158377056d54f6896af66f7bdff457cf1c252e1ae11d602f958297db1e1c95df7a254ee26066963
+  metadata.gz: 282b3e85109110fd42920f84c7b37763995a879e1a6b7729745e41ce64ef569556d7c43d83fee7c011aac7704d382ab5c33f1322727643b9a080376dba89d58e
+  data.tar.gz: 381154a92ce76bb626110d56768fb2a7250402c2069d4b1a84e812c0956dfe59cdc4a899c65f1cfe9a8e9508378f2b265abe410d88723b854df1e3f13d773c42

data/README.md

@@ -2,15 +2,55 @@
 
 Given a GPX data file and a time reference, infer a location.
 
+[API documentation](http://rubydoc.info/github/alexdean/where_was_i/master/frames) is available on rubydoc.org.
+
+## Examples
+
 ```ruby
 w = WhereWasI::Gpx.new(gpx_file: '/home/alex/track.gpx')
 w.at('2014-01-01T00:00:00Z')
 #=> {lat: 48.0, lon: 98.0, elevation: 1000}
 ```
 
-`at` will return `nil` if the supplied time is not covered by the GPX data.
+By default, `at` will return `nil` if the supplied time is not covered by the GPX data.
+This includes times before the earliest data or after the last data, or times that
+fall in-between GPX segments. (Like if your GPS receiver was turned off for a few
+minutes.)
+
 ```ruby
 w = WhereWasI::Gpx.new(gpx_file: '/home/alex/track.gpx')
 w.at('2014-01-02T00:00:00Z')
 #=> nil
 ```
+
+## Inter-segment Behavior
+
+For times that fall outside any segments, you can opt to guess about a location
+in a few different ways, instead of returning `nil`.
+
+### Interpolation
+
+If you would like to interpolate a location using the ending and beginning
+locations of the nearest segments, do the following:
+
+```ruby
+w = WhereWasI::Gpx.new(
+  gpx_file: '/home/alex/track.gpx',
+  intersegment_behavior: :interpolate
+)
+w.at('2014-01-02T00:00:00Z')
+```
+
+### Nearest
+
+Interpolating will give impossible results if a large distance exists between
+two segments. In those cases, simply selecting the location of segment begin/end
+which is nearest in time may be preferable.
+
+```ruby
+w = WhereWasI::Gpx.new(
+  gpx_file: '/home/alex/track.gpx',
+  intersegment_behavior: :nearest
+)
+w.at('2014-01-02T00:00:00Z')
+```

data/lib/where_was_i/gpx.rb

@@ -4,16 +4,21 @@ module WhereWasI
 
   # Use a GPX file as a data source for location inferences.
   class Gpx
-    attr_reader :tracks
+    attr_reader :tracks, :intersegment_behavior
+
+    Infinity = 1.0/0
 
     # @param [String] gpx_file Path to a GPX file.
     # @param [String] gpx_data GPX XML data string.
+    # @param [nil,Symbol] intersegment_behavior How to handle times that fall between track segments.
+    #   nil: return nil
+    #   :interpolate: Interpolate a location from the ends of the nearest segments
     #
     # @example with a gpx file
     #   g = WhereWasI::Gpx.new(gpx_file: '/path/to/data.gpx')
     # @example with gpx data
     #   g = WhereWasI::Gpx.new(gpx_data: '<?xml version="1.0"><gpx ...')
-    def initialize(gpx_file:nil, gpx_data:nil)
+    def initialize(gpx_file:nil, gpx_data:nil, intersegment_behavior:nil)
       if gpx_file
         @gpx_data = open(gpx_file)
       elsif gpx_data
@@ -22,6 +27,12 @@ module WhereWasI
         raise ArgumentError, "Must supply gpx_file or gpx_data."
       end
 
+      valid_values = [nil, :interpolate, :nearest]
+      if !valid_values.include?(intersegment_behavior)
+        raise ArgumentError, "intersegment_behavior must be one of: #{valid_values.inspect}"
+      end
+      @intersegment_behavior = intersegment_behavior
+
       @tracks_added = false
     end
 
@@ -47,21 +58,97 @@ module WhereWasI
         end
         @tracks << track
       end
+
+      @intersegments = []
+      @tracks.each_with_index do |track,i|
+        next if i == 0
+
+        this_track = track
+        prev_track = @tracks[i-1]
+
+        inter_track = Track.new
+        inter_track.add_point(
+          lat: prev_track.end_location[0],
+          lon: prev_track.end_location[1],
+          elevation: prev_track.end_location[2],
+          time: prev_track.end_time
+        )
+        inter_track.add_point(
+          lat: this_track.start_location[0],
+          lon: this_track.start_location[1],
+          elevation: this_track.start_location[2],
+          time: this_track.start_time
+        )
+        @intersegments << inter_track
+      end
+
       @tracks_added = true
     end
 
     # infer a location from track data and a time
     #
-    # @param [Time,String] time
+    # @param [Time,String,Fixnum] time
     # @return [Hash]
     # @see Track#at
     def at(time)
       add_tracks if ! @tracks_added
+
+      if time.is_a?(String)
+        time = Time.parse(time)
+      end
+      time = time.to_i
+
       location = nil
+
       @tracks.each do |track|
         location = track.at(time)
         break if location
       end
+
+      if ! location
+        case @intersegment_behavior
+        when :interpolate then
+          @intersegments.each do |track|
+            location = track.at(time)
+            break if location
+          end
+        when :nearest then
+          # hash is sorted in ascending time order.
+          # all start/end points for all segments
+          points = {}
+          @tracks.each do |t|
+            points[t.start_time.to_i] = t.start_location
+            points[t.end_time.to_i] = t.end_location
+          end
+
+          last_diff = Infinity
+          last_time = -1
+          points.each do |p_time,p_location|
+            this_diff = (p_time.to_i - time).abs
+
+            # as long as the differences keep getting smaller, we keep going
+            # as soon as we see a larger one, we step back one and use that value.
+            if this_diff > last_diff
+              l = points[last_time]
+              location = Track.array_to_hash(points[last_time])
+              break
+            else
+              last_diff = this_diff
+              last_time = p_time
+            end
+          end
+
+          # if we got here, time is > the end of the last segment
+          location = Track.array_to_hash(points[last_time])
+        end
+      end
+
+      # each segment has a begin and end time.
+      # which one is this time closest to?
+      # array of times in order. compute abs diff between time and each point.
+      # put times in order. abs diff to each, until we get a larger value or we run out of points. then back up one and use that.
+      # {time => [lat, lon, elev], time => [lat, lon, elev]}
+
       location
     end
   end

data/lib/where_was_i/track.rb

@@ -5,7 +5,15 @@ module WhereWasI
 
   # a series of sequential [lat, lon, elevation] points
   class Track
-    attr_reader :start_time, :end_time
+    attr_reader :start_time, :end_time, :start_location, :end_location
+
+    def self.array_to_hash(a)
+      {
+        lat: a[0],
+        lon: a[1],
+        elevation: a[2]
+      }
+    end
 
     def initialize
       @points = {}
@@ -20,9 +28,19 @@ module WhereWasI
     def add_point(lat:, lon:, elevation:, time:)
       time = Time.parse(time) if ! time.is_a?(Time)
 
-      @start_time = time if @start_time.nil? || time < @start_time
-      @end_time   = time if @end_time.nil?   || time > @end_time
-      @points[time.to_i] = [lat, lon, elevation]
+      current = [lat, lon, elevation]
+
+      if @start_time.nil? || time < @start_time
+        @start_time     = time
+        @start_location = current
+      end
+
+      if @end_time.nil?   || time > @end_time
+        @end_time     = time
+        @end_location = current
+      end
+
+      @points[time.to_i] = current
 
       true
     end
@@ -48,23 +66,23 @@ module WhereWasI
     #
     # @example
     #  track.at(time) => {lat:48, lon:98, elevation: 2100}
-    # @param time [String,Time]
+    # @param time [String,Time,Fixnum]
     # @return [Hash,nil]
     def at(time)
-      return nil if ! in_time_range?(time)
-      if ! time.is_a?(Time)
-        time = Time.parse(time).to_i
+      if time.is_a?(String)
+        time = Time.parse(time)
       end
-      time = time.to_i
+      if time.is_a?(Fixnum)
+        time = Time.at(time)
+      end
+      raise ArgumentError, "time must be a Time,String, or Fixnum" if ! time.is_a?(Time)
+
+      return nil if ! in_time_range?(time)
 
       @interp ||= Interpolate::Points.new(@points)
-      data = @interp.at(time)
+      data = @interp.at(time.to_i)
 
-      {
-        lat: data[0],
-        lon: data[1],
-        elevation: data[2]
-      }
+      self.class.array_to_hash(data)
     end
   end
 

data/lib/where_was_i/version.rb

@@ -1,3 +1,3 @@
 module WhereWasI
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 end

data/spec/lib/where_was_i/gpx_spec.rb

@@ -47,5 +47,51 @@ RSpec.describe WhereWasI::Gpx do
       expect(subject.at('2014-06-17T12:00:00Z')).to eq nil
     end
 
+    it "should do inter-track interpolation" do
+      subject = WhereWasI::Gpx.new(gpx_file: test_filename, intersegment_behavior: :interpolate)
+      expect(subject.at('2014-06-17T12:00:00Z')).to eq({
+        elevation: 187.56424463380702,
+        lat: 48.75755751944594,
+        lon: -87.60709448942973
+      })
+    end
+
+    describe "nearest behavior" do
+      let(:subject) {WhereWasI::Gpx.new(gpx_file: test_filename, intersegment_behavior: :nearest)}
+
+      it "should return start of first segment for a time earlier than the first segment" do
+        expect(subject.intersegment_behavior).to eq :nearest
+        expect(subject.at('2014-06-16T16:00:00Z')).to eq({
+          lat: 48.833804307505488,
+          lon: -87.519973134621978,
+          elevation: 186.150000000000006
+        })
+      end
+
+      it "should return the end of the last segment for a time after the end of the last segment" do
+        expect(subject.at('2014-06-17T15:00:00Z')).to eq({
+          lat: 48.747312789782882,
+          lon: -87.618932314217091,
+          elevation: 188.080000000000013
+        })
+      end
+
+      it "should return the closest segment beginning when between segments but nearer to a begin" do
+        expect(subject.at('2014-06-16T17:00:00Z')).to eq({
+          lat: 48.833690145984292,
+          lon: -87.520155273377895,
+          elevation: 183.75
+        })
+      end
+
+      it "should return the closest segment ending when between segments but nearer to an end" do
+        expect(subject.at('2014-06-17T13:00:00Z')).to eq({
+          lat: 48.747263001278043,
+          lon: -87.618850255385041,
+          elevation: 188.080000000000013
+        })
+      end
+    end
+
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: where_was_i
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Alex Dean
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-14 00:00:00.000000000 Z
+date: 2014-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri