geodetic 0.3.2 → 0.4.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 ---
@@ -343,7 +335,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 +344,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 +356,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 +382,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 +411,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 +428,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 +441,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 +461,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

data/lib/geodetic/segment.rb

@@ -0,0 +1,172 @@
+# 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
+
+    # --- Conversion ---
+
+    def to_path
+      Path.new(coordinates: [@start_point, @end_point])
+    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

data/lib/geodetic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Geodetic
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

data/lib/geodetic.rb

@@ -7,6 +7,7 @@ require_relative "geodetic/bearing"
 require_relative "geodetic/geoid_height"
 require_relative "geodetic/coordinate"
 require_relative "geodetic/areas"
+require_relative "geodetic/segment"
 require_relative "geodetic/path"
 require_relative "geodetic/feature"
 

data/mkdocs.yml

@@ -136,6 +136,7 @@ nav:
       - Datums: reference/datums.md
       - Geoid Height: reference/geoid-height.md
       - Areas: reference/areas.md
+      - Segment: reference/segment.md
       - Path: reference/path.md
       - Feature: reference/feature.md
       - Serialization: reference/serialization.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: geodetic
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -57,6 +57,7 @@ files:
 - docs/reference/geoid-height.md
 - docs/reference/map-rendering.md
 - docs/reference/path.md
+- docs/reference/segment.md
 - docs/reference/serialization.md
 - examples/01_basic_conversions.rb
 - examples/02_all_coordinate_systems.rb
@@ -71,13 +72,20 @@ files:
 - examples/05_map_rendering/icons/park.png
 - examples/05_map_rendering/nyc_landmarks.png
 - examples/06_path_operations.rb
+- examples/07_segments_and_shapes.rb
 - examples/README.md
 - fiddle_pointer_buffer_pool.md
 - lib/geodetic.rb
 - lib/geodetic/areas.rb
+- lib/geodetic/areas/bounding_box.rb
 - lib/geodetic/areas/circle.rb
+- lib/geodetic/areas/hexagon.rb
+- lib/geodetic/areas/octagon.rb
+- lib/geodetic/areas/pentagon.rb
 - lib/geodetic/areas/polygon.rb
 - lib/geodetic/areas/rectangle.rb
+- lib/geodetic/areas/regular_polygon.rb
+- lib/geodetic/areas/triangle.rb
 - lib/geodetic/bearing.rb
 - lib/geodetic/coordinate.rb
 - lib/geodetic/coordinate/bng.rb
@@ -104,6 +112,7 @@ files:
 - lib/geodetic/feature.rb
 - lib/geodetic/geoid_height.rb
 - lib/geodetic/path.rb
+- lib/geodetic/segment.rb
 - lib/geodetic/version.rb
 - mkdocs.yml
 - sig/geodetic.rbs