geodetic 0.3.2 → 0.5.0

data/lib/geodetic/path.rb

@@ -32,7 +32,7 @@ module Geodetic
     end
 
     def segments
-      @coordinates.each_cons(2).to_a
+      @coordinates.each_cons(2).map { |a, b| Segment.new(a, b) }
     end
 
     def size
@@ -66,7 +66,7 @@ module Geodetic
     def contains?(coordinate, tolerance: DEFAULT_TOLERANCE_METERS)
       return true if include?(coordinate)
 
-      segments.any? { |a, b| on_segment?(a, b, coordinate, tolerance) }
+      segments.any? { |seg| seg.contains?(coordinate, tolerance: tolerance) }
     end
 
     alias inside? contains?
@@ -146,17 +146,11 @@ module Geodetic
 
       accumulated = 0.0
 
-      segments.each do |a, b|
-        seg_len = a.distance_to(b).meters
+      segments.each do |seg|
+        seg_len = seg.length_meters
         if accumulated + seg_len >= target_m
           fraction = (target_m - accumulated) / seg_len
-          a_lla = a.is_a?(Coordinate::LLA) ? a : a.to_lla
-          b_lla = b.is_a?(Coordinate::LLA) ? b : b.to_lla
-          return Coordinate::LLA.new(
-            lat: a_lla.lat + (b_lla.lat - a_lla.lat) * fraction,
-            lng: a_lla.lng + (b_lla.lng - a_lla.lng) * fraction,
-            alt: a_lla.alt + (b_lla.alt - a_lla.alt) * fraction
-          )
+          return seg.interpolate(fraction)
         end
         accumulated += seg_len
       end
@@ -170,7 +164,7 @@ module Geodetic
       lats = @coordinates.map { |c| c.is_a?(Coordinate::LLA) ? c.lat : c.to_lla.lat }
       lngs = @coordinates.map { |c| c.is_a?(Coordinate::LLA) ? c.lng : c.to_lla.lng }
 
-      Areas::Rectangle.new(
+      Areas::BoundingBox.new(
         nw: Coordinate::LLA.new(lat: lats.max, lng: lngs.min, alt: 0),
         se: Coordinate::LLA.new(lat: lats.min, lng: lngs.max, alt: 0)
       )
@@ -179,12 +173,10 @@ module Geodetic
     def to_polygon
       raise ArgumentError, "need at least 3 coordinates for a polygon" if size < 3
 
-      # Check that closing last→first doesn't cross any interior segment
-      closing_a = @coordinates.last
-      closing_b = @coordinates.first
+      closing = Segment.new(@coordinates.last, @coordinates.first)
       interior = segments[1...-1] || []
 
-      if interior.any? { |a, b| segments_intersect?(closing_a, closing_b, a, b) }
+      if interior.any? { |seg| closing.intersects?(seg) }
         raise ArgumentError, "closing segment intersects the path"
       end
 
@@ -194,9 +186,9 @@ module Geodetic
     def intersects?(other_path)
       raise ArgumentError, "expected a Path" unless other_path.is_a?(Path)
 
-      segments.each do |a1, b1|
-        other_path.segments.each do |a2, b2|
-          return true if segments_intersect?(a1, b1, a2, b2)
+      segments.each do |seg1|
+        other_path.segments.each do |seg2|
+          return true if seg1.intersects?(seg2)
         end
       end
 
@@ -208,11 +200,11 @@ module Geodetic
     end
 
     def segment_distances
-      segments.map { |a, b| a.distance_to(b) }
+      segments.map(&:length)
     end
 
     def segment_bearings
-      segments.map { |a, b| a.bearing_to(b) }
+      segments.map(&:bearing)
     end
 
     # --- Non-mutating operators ---
@@ -272,6 +264,46 @@ module Geodetic
 
     alias remove delete
 
+    # --- Translation ---
+
+    def *(other)
+      raise ArgumentError, "expected a Vector, got #{other.class}" unless other.is_a?(Vector)
+
+      self.class.new(coordinates: @coordinates.map { |c| other.destination_from(c) })
+    end
+
+    alias translate *
+
+    # --- Geometric conversions ---
+
+    def to_corridor(width:)
+      raise ArgumentError, "need at least 2 coordinates for a corridor" if size < 2
+
+      half = (width.is_a?(Distance) ? width.meters : width.to_f) / 2.0
+      segs = segments
+      bearings = segs.map { |s| s.bearing.degrees }
+
+      left_side  = []
+      right_side = []
+
+      @coordinates.each_with_index do |coord, i|
+        lla = coord.is_a?(Coordinate::LLA) ? coord : coord.to_lla
+
+        if i == 0
+          perp = bearings[0]
+        elsif i == @coordinates.length - 1
+          perp = bearings[-1]
+        else
+          perp = mean_bearing(bearings[i - 1], bearings[i])
+        end
+
+        left_side  << offset_point(lla, perp - 90.0, half)
+        right_side << offset_point(lla, perp + 90.0, half)
+      end
+
+      Areas::Polygon.new(boundary: left_side + right_side.reverse)
+    end
+
     # --- Display ---
 
     def to_s
@@ -288,6 +320,12 @@ module Geodetic
     def append!(other)
       if other.is_a?(Path)
         other.coordinates.each { |c| append!(c) }
+      elsif other.is_a?(Segment)
+        [other.start_point, other.end_point].each { |c| append!(c) }
+      elsif other.is_a?(Vector)
+        dest = other.destination_from(@coordinates.last)
+        check_duplicate!(dest)
+        @coordinates << dest
       else
         check_duplicate!(other)
         @coordinates << other
@@ -343,7 +381,8 @@ module Geodetic
       best_dist = waypoint.distance_to(target).meters
 
       if idx > 0
-        candidate, candidate_dist = project_onto_segment(@coordinates[idx - 1], waypoint, target)
+        seg = Segment.new(@coordinates[idx - 1], waypoint)
+        candidate, candidate_dist = seg.project(target)
         if candidate_dist < best_dist
           best = candidate
           best_dist = candidate_dist
@@ -351,7 +390,8 @@ module Geodetic
       end
 
       if idx < @coordinates.length - 1
-        candidate, candidate_dist = project_onto_segment(waypoint, @coordinates[idx + 1], target)
+        seg = Segment.new(waypoint, @coordinates[idx + 1])
+        candidate, candidate_dist = seg.project(target)
         if candidate_dist < best_dist
           best = candidate
           best_dist = candidate_dist
@@ -362,24 +402,22 @@ module Geodetic
     end
 
     def closest_points_to_boundary(boundary_coords)
-      boundary_segments = boundary_coords.each_cons(2).to_a
+      boundary_segs = boundary_coords.each_cons(2).map { |a, b| Segment.new(a, b) }
 
       best = { path_point: nil, area_point: nil, distance: Distance.new(Float::INFINITY) }
 
-      # For each path segment, project each boundary vertex onto it
-      # For each boundary segment, project each path waypoint onto it
-      segments.each do |seg_a, seg_b|
+      segments.each do |seg|
         boundary_coords.each do |bpt|
-          candidate, dist = project_onto_segment(seg_a, seg_b, bpt)
+          candidate, dist = seg.project(bpt)
           if dist < best[:distance].meters
             best = { path_point: candidate, area_point: bpt, distance: Distance.new(dist) }
           end
         end
       end
 
-      boundary_segments.each do |bseg_a, bseg_b|
+      boundary_segs.each do |bseg|
         @coordinates.each do |wpt|
-          candidate, dist = project_onto_segment(bseg_a, bseg_b, wpt)
+          candidate, dist = bseg.project(wpt)
           if dist < best[:distance].meters
             best = { path_point: wpt, area_point: candidate, distance: Distance.new(dist) }
           end
@@ -390,23 +428,16 @@ module Geodetic
     end
 
     def closest_points_to_circle(circle)
-      # Find closest point on path to the circle's centroid
       path_point = closest_point_to_coordinate(circle.centroid)
       dist_to_center = path_point.distance_to(circle.centroid).meters
 
-      # The closest point on the circle is along the line from
-      # centroid toward the path point, offset by the radius
       if dist_to_center < 1e-6
-        # Path passes through the center — pick any point on the circle
         area_point = circle.centroid
         dist = circle.radius
       elsif dist_to_center <= circle.radius
-        # Path is inside the circle
         area_point = path_point
         dist = 0.0
       else
-        # Interpolate from centroid toward path_point by radius distance
-        bearing = circle.centroid.bearing_to(path_point).degrees
         fraction = circle.radius / dist_to_center
         c_lla = circle.centroid
         p_lla = path_point.is_a?(Coordinate::LLA) ? path_point : path_point.to_lla
@@ -426,7 +457,7 @@ module Geodetic
       case area
       when Areas::Polygon
         area.boundary
-      when Areas::Rectangle
+      when Areas::BoundingBox
         [area.nw,
          Coordinate::LLA.new(lat: area.nw.lat, lng: area.se.lng, alt: 0),
          area.se,
@@ -443,10 +474,10 @@ module Geodetic
         resolve_geometry(other.geometry)
       when Path
         other.coordinates
-      when Areas::Polygon, Areas::Rectangle
+      when Areas::Polygon, Areas::BoundingBox
         area_boundary(other)
       when Areas::Circle
-        other  # handled specially in distance_to/bearing_to/closest_coordinate_to
+        other
       else
         other.respond_to?(:centroid) ? other.centroid : other
       end
@@ -456,69 +487,13 @@ module Geodetic
       case other
       when Feature
         resolve_area(other.geometry)
-      when Areas::Circle, Areas::Polygon, Areas::Rectangle, Path
+      when Areas::Circle, Areas::Polygon, Areas::BoundingBox, Path
         other
       else
         raise ArgumentError, "expected an Area or Path, got #{other.class}"
       end
     end
 
-    # Projects target onto segment A→B using triangle geometry.
-    # Returns [closest_coordinate, distance_to_target].
-    #
-    # Given triangle A-T with known:
-    #   - bearing A→B (segment heading)
-    #   - bearing A→T
-    #   - distance A→T
-    #
-    # The angle between A→B and A→T gives us:
-    #   - along-segment distance = dist_AT * cos(angle)
-    #   - perpendicular distance = dist_AT * sin(angle)
-    #
-    # If the foot of the perpendicular falls between A and B,
-    # that foot is the closest point. Otherwise the nearer
-    # endpoint wins.
-    def project_onto_segment(a, b, target)
-      seg_dist   = a.distance_to(b).meters
-      dist_a_t   = a.distance_to(target).meters
-
-      # Degenerate: zero-length segment or target at endpoint
-      return [a, dist_a_t] if seg_dist < 1e-6
-      return [a, 0.0] if dist_a_t < 1e-6
-
-      bearing_ab = a.bearing_to(b).degrees
-      bearing_at = a.bearing_to(target).degrees
-
-      # Angle between the segment direction and the line to target
-      angle = (bearing_at - bearing_ab).abs
-      angle = 360.0 - angle if angle > 180.0
-      angle_rad = angle * Geodetic::RAD_PER_DEG
-
-      # Distance along the segment from A to the foot of the perpendicular
-      along = dist_a_t * Math.cos(angle_rad)
-
-      # If the foot falls before A or beyond B, the closest point is an endpoint
-      if along <= 0.0
-        return [a, dist_a_t]
-      elsif along >= seg_dist
-        dist_b_t = b.distance_to(target).meters
-        return [b, dist_b_t]
-      end
-
-      # Interpolate along the segment to find the foot
-      fraction = along / seg_dist
-      a_lla = a.is_a?(Coordinate::LLA) ? a : a.to_lla
-      b_lla = b.is_a?(Coordinate::LLA) ? b : b.to_lla
-
-      foot = Coordinate::LLA.new(
-        lat: a_lla.lat + (b_lla.lat - a_lla.lat) * fraction,
-        lng: a_lla.lng + (b_lla.lng - a_lla.lng) * fraction,
-        alt: a_lla.alt + (b_lla.alt - a_lla.alt) * fraction
-      )
-
-      [foot, foot.distance_to(target).meters]
-    end
-
     def resolve_point_from(other)
       case other
       when Feature
@@ -532,62 +507,6 @@ module Geodetic
       end
     end
 
-    def on_segment?(a, b, point, tolerance)
-      seg_dist = a.distance_to(b).meters
-      return a == point || b == point if seg_dist < 1e-6
-
-      dist_a_p = a.distance_to(point).meters
-      dist_p_b = point.distance_to(b).meters
-
-      # Point must be closer to both endpoints than the segment length
-      return false if dist_a_p > seg_dist || dist_p_b > seg_dist
-
-      # Bearing from A->P should match bearing from P->B within a
-      # delta derived from the tolerance and segment distance
-      delta = Math.atan(tolerance / seg_dist) * Geodetic::DEG_PER_RAD
-
-      bearing_ap = a.bearing_to(point).degrees
-      bearing_pb = point.bearing_to(b).degrees
-
-      (bearing_ap - bearing_pb).abs <= delta
-    end
-
-    # Checks if two segments (a1→b1) and (a2→b2) intersect using
-    # cross-product orientation tests on a flat lat/lng approximation.
-    def segments_intersect?(a1, b1, a2, b2)
-      p1 = to_flat(a1); q1 = to_flat(b1)
-      p2 = to_flat(a2); q2 = to_flat(b2)
-
-      d1 = cross_sign(p2, q2, p1)
-      d2 = cross_sign(p2, q2, q1)
-      d3 = cross_sign(p1, q1, p2)
-      d4 = cross_sign(p1, q1, q2)
-
-      return true if d1 != d2 && d3 != d4
-
-      if d1 == 0 && on_collinear?(p2, q2, p1) then return true end
-      if d2 == 0 && on_collinear?(p2, q2, q1) then return true end
-      if d3 == 0 && on_collinear?(p1, q1, p2) then return true end
-      if d4 == 0 && on_collinear?(p1, q1, q2) then return true end
-
-      false
-    end
-
-    def to_flat(coord)
-      c = coord.is_a?(Coordinate::LLA) ? coord : coord.to_lla
-      [c.lat, c.lng]
-    end
-
-    def cross_sign(a, b, c)
-      val = (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0])
-      val > 1e-12 ? 1 : (val < -1e-12 ? -1 : 0)
-    end
-
-    def on_collinear?(a, b, p)
-      p[0] >= [a[0], b[0]].min && p[0] <= [a[0], b[0]].max &&
-        p[1] >= [a[1], b[1]].min && p[1] <= [a[1], b[1]].max
-    end
-
     def dup_path
       self.class.new(coordinates: @coordinates.dup)
     end
@@ -595,5 +514,18 @@ module Geodetic
     def dup_path_without(coordinate)
       self.class.new(coordinates: @coordinates.reject { |c| c == coordinate })
     end
+
+    def offset_point(lla, bearing_deg, distance_m)
+      Vector.new(distance: distance_m, bearing: bearing_deg).destination_from(lla)
+    end
+
+    def mean_bearing(b1, b2)
+      r1 = b1 * RAD_PER_DEG
+      r2 = b2 * RAD_PER_DEG
+      Math.atan2(
+        Math.sin(r1) + Math.sin(r2),
+        Math.cos(r1) + Math.cos(r2)
+      ) * DEG_PER_RAD
+    end
   end
 end

data/lib/geodetic/segment.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Geodetic
+  class Segment
+    attr_reader :start_point, :end_point
+
+    def initialize(start_point, end_point)
+      @start_point = start_point.is_a?(Coordinate::LLA) ? start_point : start_point.to_lla
+      @end_point   = end_point.is_a?(Coordinate::LLA)   ? end_point   : end_point.to_lla
+    end
+
+    # --- Properties ---
+
+    def length
+      @length ||= @start_point.distance_to(@end_point)
+    end
+
+    alias distance length
+
+    def length_meters
+      length.meters
+    end
+
+    def bearing
+      @bearing ||= @start_point.bearing_to(@end_point)
+    end
+
+    def midpoint
+      @midpoint ||= interpolate(0.5)
+    end
+
+    alias centroid midpoint
+
+    # --- Geometry ---
+
+    def reverse
+      self.class.new(@end_point, @start_point)
+    end
+
+    def interpolate(fraction)
+      Coordinate::LLA.new(
+        lat: @start_point.lat + (@end_point.lat - @start_point.lat) * fraction,
+        lng: @start_point.lng + (@end_point.lng - @start_point.lng) * fraction,
+        alt: @start_point.alt + (@end_point.alt - @start_point.alt) * fraction
+      )
+    end
+
+    # Projects a point onto this segment.
+    # Returns [closest_point_on_segment, distance_in_meters].
+    def project(point)
+      target = point.is_a?(Coordinate::LLA) ? point : point.to_lla
+      seg_len = length_meters
+      dist_a_t = @start_point.distance_to(target).meters
+
+      return [@start_point, dist_a_t] if seg_len < 1e-6
+      return [@start_point, 0.0] if dist_a_t < 1e-6
+
+      bearing_ab = bearing.degrees
+      bearing_at = @start_point.bearing_to(target).degrees
+
+      angle = (bearing_at - bearing_ab).abs
+      angle = 360.0 - angle if angle > 180.0
+      angle_rad = angle * Geodetic::RAD_PER_DEG
+
+      along = dist_a_t * Math.cos(angle_rad)
+
+      if along <= 0.0
+        return [@start_point, dist_a_t]
+      elsif along >= seg_len
+        dist_b_t = @end_point.distance_to(target).meters
+        return [@end_point, dist_b_t]
+      end
+
+      foot = interpolate(along / seg_len)
+      [foot, foot.distance_to(target).meters]
+    end
+
+    # Tests if a point lies on this segment within a tolerance (meters).
+    def contains?(point, tolerance: 10.0)
+      target = point.is_a?(Coordinate::LLA) ? point : point.to_lla
+      seg_len = length_meters
+
+      return @start_point == target || @end_point == target if seg_len < 1e-6
+
+      dist_a_p = @start_point.distance_to(target).meters
+      dist_p_b = target.distance_to(@end_point).meters
+
+      # Exact endpoint match
+      return true if dist_a_p < 1e-6 || dist_p_b < 1e-6
+
+      return false if dist_a_p > seg_len || dist_p_b > seg_len
+
+      delta = Math.atan(tolerance / seg_len) * Geodetic::DEG_PER_RAD
+      bearing_ap = @start_point.bearing_to(target).degrees
+      bearing_pb = target.bearing_to(@end_point).degrees
+
+      (bearing_ap - bearing_pb).abs <= delta
+    end
+
+    # True if the point is a vertex (start or end point).
+    def includes?(point)
+      target = point.is_a?(Coordinate::LLA) ? point : point.to_lla
+      @start_point == target || @end_point == target
+    end
+
+    def excludes?(point, tolerance: 10.0)
+      !contains?(point, tolerance: tolerance)
+    end
+
+    # Tests if this segment intersects another segment.
+    def intersects?(other)
+      p1 = flat(@start_point); q1 = flat(@end_point)
+      p2 = flat(other.start_point); q2 = flat(other.end_point)
+
+      d1 = cross_sign(p2, q2, p1)
+      d2 = cross_sign(p2, q2, q1)
+      d3 = cross_sign(p1, q1, p2)
+      d4 = cross_sign(p1, q1, q2)
+
+      return true if d1 != d2 && d3 != d4
+
+      return true if d1 == 0 && on_collinear?(p2, q2, p1)
+      return true if d2 == 0 && on_collinear?(p2, q2, q1)
+      return true if d3 == 0 && on_collinear?(p1, q1, p2)
+      return true if d4 == 0 && on_collinear?(p1, q1, q2)
+
+      false
+    end
+
+    # --- Arithmetic ---
+
+    def +(other)
+      to_path + other
+    end
+
+    def *(other)
+      raise ArgumentError, "expected a Vector, got #{other.class}" unless other.is_a?(Vector)
+
+      self.class.new(
+        other.destination_from(@start_point),
+        other.destination_from(@end_point)
+      )
+    end
+
+    alias translate *
+
+    # --- Conversion ---
+
+    def to_path
+      Path.new(coordinates: [@start_point, @end_point])
+    end
+
+    def to_vector
+      Vector.from_segment(self)
+    end
+
+    def to_a
+      [@start_point, @end_point]
+    end
+
+    # --- Equality / Display ---
+
+    def ==(other)
+      other.is_a?(Segment) &&
+        @start_point == other.start_point &&
+        @end_point == other.end_point
+    end
+
+    def to_s
+      "Segment(#{@start_point} -> #{@end_point})"
+    end
+
+    def inspect
+      "#<Geodetic::Segment start=#{@start_point.inspect} end=#{@end_point.inspect} length=#{length}>"
+    end
+
+    private
+
+    def flat(coord)
+      [coord.lat, coord.lng]
+    end
+
+    def cross_sign(a, b, c)
+      val = (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0])
+      val > 1e-12 ? 1 : (val < -1e-12 ? -1 : 0)
+    end
+
+    def on_collinear?(a, b, p)
+      p[0] >= [a[0], b[0]].min && p[0] <= [a[0], b[0]].max &&
+        p[1] >= [a[1], b[1]].min && p[1] <= [a[1], b[1]].max
+    end
+  end
+end