geodetic 0.3.2 → 0.4.0

data/lib/geodetic/areas/polygon.rb

@@ -7,29 +7,26 @@ module Geodetic
     class Polygon
       attr_reader :boundary, :centroid
 
-      def initialize(boundary:)
+      def initialize(boundary:, validate: true)
         raise ArgumentError, "A Polygon requires more than #{boundary.length} points on its boundary" unless boundary.length > 2
 
         @boundary = boundary.dup
         @boundary << boundary[0] unless boundary.first == boundary.last
 
-        centroid_lat = 0.0
-        centroid_lng = 0.0
-        area = 0.0
-
-        0.upto(@boundary.length - 2) do |i|
-          cross = @boundary[i].lng * @boundary[i + 1].lat - @boundary[i + 1].lng * @boundary[i].lat
-          area += 0.5 * cross
-          centroid_lng += (@boundary[i].lng + @boundary[i + 1].lng) * cross
-          centroid_lat += (@boundary[i].lat + @boundary[i + 1].lat) * cross
-        end
+        validate_no_self_intersection! if validate
 
-        centroid_lng /= (6.0 * area)
-        centroid_lat /= (6.0 * area)
+        compute_centroid
+      end
 
-        @centroid = Coordinate::LLA.new(lat: centroid_lat, lng: centroid_lng, alt: 0.0)
+      # Returns Segment objects for each edge of the polygon.
+      # Returns Segment objects for each side of the polygon.
+      def segments
+        @segments ||= @boundary.each_cons(2).map { |a, b| Segment.new(a, b) }
       end
 
+      alias edges segments
+      alias border segments
+
       def includes?(a_point)
         turn_angle = 0.0
 
@@ -52,6 +49,49 @@ module Geodetic
       alias_method :exclude?, :excludes?
       alias_method :inside?,  :includes?
       alias_method :outside?, :excludes?
+
+      private
+
+      def compute_centroid
+        centroid_lat = 0.0
+        centroid_lng = 0.0
+        area = 0.0
+
+        0.upto(@boundary.length - 2) do |i|
+          cross = @boundary[i].lng * @boundary[i + 1].lat - @boundary[i + 1].lng * @boundary[i].lat
+          area += 0.5 * cross
+          centroid_lng += (@boundary[i].lng + @boundary[i + 1].lng) * cross
+          centroid_lat += (@boundary[i].lat + @boundary[i + 1].lat) * cross
+        end
+
+        if area.abs < 1e-12
+          # Degenerate polygon (collinear or self-intersecting) — fall back to mean
+          centroid_lat = @boundary[0...-1].sum(&:lat) / (@boundary.length - 1).to_f
+          centroid_lng = @boundary[0...-1].sum(&:lng) / (@boundary.length - 1).to_f
+        else
+          centroid_lng /= (6.0 * area)
+          centroid_lat /= (6.0 * area)
+        end
+
+        @centroid = Coordinate::LLA.new(lat: centroid_lat, lng: centroid_lng, alt: 0.0)
+      end
+
+      def validate_no_self_intersection!
+        segs = @boundary.each_cons(2).map { |a, b| Segment.new(a, b) }
+
+        segs.each_with_index do |seg_i, i|
+          segs.each_with_index do |seg_j, j|
+            # Skip same edge and adjacent edges (they share a vertex)
+            next if j <= i + 1
+            # Skip first-last pair (they share the closing vertex)
+            next if i == 0 && j == segs.length - 1
+
+            if seg_i.intersects?(seg_j)
+              raise ArgumentError, "edge #{i} intersects edge #{j} — polygon boundary must not self-intersect"
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/geodetic/areas/rectangle.rb

@@ -1,55 +1,105 @@
 # frozen_string_literal: true
 
-require_relative '../coordinate/lla'
+require_relative "polygon"
 
 module Geodetic
   module Areas
-    class Rectangle
-      attr_reader :nw, :se, :centroid
+    class Rectangle < Polygon
+      attr_reader :centerline, :width
 
-      # Define an axis-aligned rectangle by its NW and SE corners.
-      # Accepts any coordinate that responds to to_lla.
+      # Construct a rectangle from a centerline Segment and a width (meters).
       #
-      #   Rectangle.new(
-      #     nw: LLA.new(lat: 41.0, lng: -75.0),
-      #     se: LLA.new(lat: 40.0, lng: -74.0)
-      #   )
-      def initialize(nw:, se:)
-        @nw = nw.is_a?(Coordinate::LLA) ? nw : nw.to_lla
-        @se = se.is_a?(Coordinate::LLA) ? se : se.to_lla
-
-        raise ArgumentError, "NW corner must have higher latitude than SE corner" if @nw.lat < @se.lat
-        raise ArgumentError, "NW corner must have lower longitude than SE corner" if @nw.lng > @se.lng
-
-        @centroid = Coordinate::LLA.new(
-          lat: (@nw.lat + @se.lat) / 2.0,
-          lng: (@nw.lng + @se.lng) / 2.0,
-          alt: 0.0
-        )
+      #   Rectangle.new(segment: a_segment, width: 200)
+      #   Rectangle.new(segment: [point_a, point_b], width: 200)
+      #
+      # The segment defines the centerline — height = segment.length,
+      # bearing = segment.bearing, center = segment.midpoint.
+      # Width is the perpendicular extent on each side of the centerline.
+      #
+      def initialize(segment:, width:)
+        @centerline = segment.is_a?(Segment) ? segment : Segment.new(*segment)
+        @width = width.is_a?(Distance) ? width.meters : width.to_f
+
+        raise ArgumentError, "width must be positive" unless @width > 0
+
+        super(boundary: generate_vertices, validate: false)
+      end
+
+      def sides
+        4
+      end
+
+      # Center is the midpoint of the centerline.
+      def center
+        @centerline.midpoint
+      end
+
+      # Height is the length of the centerline in meters.
+      def height
+        @centerline.length_meters
       end
 
-      def ne
-        Coordinate::LLA.new(lat: @nw.lat, lng: @se.lng, alt: 0.0)
+      # Bearing is the direction of the centerline in degrees.
+      def bearing
+        @centerline.bearing.degrees
       end
 
-      def sw
-        Coordinate::LLA.new(lat: @se.lat, lng: @nw.lng, alt: 0.0)
+      # Returns the 4 corner coordinates [front-left, front-right, back-right, back-left]
+      # relative to the bearing direction.
+      def corners
+        boundary[0..3]
       end
 
-      def includes?(a_point)
-        lla = a_point.respond_to?(:to_lla) ? a_point.to_lla : a_point
-        lla.lat >= @se.lat && lla.lat <= @nw.lat &&
-          lla.lng >= @nw.lng && lla.lng <= @se.lng
+      # True when width equals height (within tolerance).
+      def square?
+        (@width - height).abs < 1e-6
       end
 
-      def excludes?(a_point)
-        !includes?(a_point)
+      # Returns the axis-aligned bounding box that encloses this rectangle.
+      def to_bounding_box
+        lats = corners.map(&:lat)
+        lngs = corners.map(&:lng)
+
+        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)
+        )
+      end
+
+      private
+
+      def generate_vertices
+        half_w = @width / 2.0
+        bearing_deg = @centerline.bearing.degrees
+        front = @centerline.end_point
+        back  = @centerline.start_point
+
+        # Perpendicular bearing: +90 for right, -90 for left
+        [
+          offset_point(front, -half_w, bearing_deg + 90),  # front-left
+          offset_point(front,  half_w, bearing_deg + 90),  # front-right
+          offset_point(back,   half_w, bearing_deg + 90),  # back-right
+          offset_point(back,  -half_w, bearing_deg + 90)   # back-left
+        ]
       end
 
-      alias_method :include?, :includes?
-      alias_method :exclude?, :excludes?
-      alias_method :inside?,  :includes?
-      alias_method :outside?, :excludes?
+      # Offset a point by a signed distance along a bearing using flat-earth projection.
+      def offset_point(origin, distance_m, bearing_deg)
+        bearing_rad = bearing_deg * Geodetic::RAD_PER_DEG
+        lat_rad = origin.lat * Geodetic::RAD_PER_DEG
+
+        m_per_deg_lat = 111_320.0
+        m_per_deg_lng = 111_320.0 * Math.cos(lat_rad)
+
+        north = distance_m * Math.cos(bearing_rad) / m_per_deg_lat
+        east  = distance_m * Math.sin(bearing_rad) / m_per_deg_lng
+
+        Coordinate::LLA.new(
+          lat: origin.lat + north,
+          lng: origin.lng + east,
+          alt: origin.alt
+        )
+      end
     end
   end
 end

data/lib/geodetic/areas/regular_polygon.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "polygon"
+
+module Geodetic
+  module Areas
+    # Base class for regular polygons (equal sides, equal angles).
+    # Subclasses set SIDES and inherit vertex generation.
+    class RegularPolygon < Polygon
+      attr_reader :center, :radius, :bearing
+
+      def initialize(center:, radius:, bearing: 0)
+        @center  = center.is_a?(Coordinate::LLA) ? center : center.to_lla
+        @radius  = radius.to_f
+        @bearing = bearing.to_f
+
+        raise ArgumentError, "radius must be positive" unless @radius > 0
+
+        super(boundary: generate_vertices, validate: false)
+      end
+
+      def sides
+        self.class::SIDES
+      end
+
+      private
+
+      def generate_vertices
+        n = self.class::SIDES
+        step = 360.0 / n
+
+        n.times.map do |i|
+          angle = @bearing + step * i
+          destination(@center, @radius, angle)
+        end
+      end
+
+      # Compute a destination point given start, distance (meters), and bearing (degrees).
+      # Uses a simplified flat-earth projection adequate for polygon-scale distances.
+      def destination(origin, distance_m, bearing_deg)
+        bearing_rad = bearing_deg * Geodetic::RAD_PER_DEG
+        lat_rad = origin.lat * Geodetic::RAD_PER_DEG
+
+        # Approximate meters per degree at this latitude
+        m_per_deg_lat = 111_320.0
+        m_per_deg_lng = 111_320.0 * Math.cos(lat_rad)
+
+        dlat = distance_m * Math.cos(bearing_rad) / m_per_deg_lat
+        dlng = distance_m * Math.sin(bearing_rad) / m_per_deg_lng
+
+        Coordinate::LLA.new(
+          lat: origin.lat + dlat,
+          lng: origin.lng + dlng,
+          alt: origin.alt
+        )
+      end
+    end
+  end
+end

data/lib/geodetic/areas/triangle.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "polygon"
+
+module Geodetic
+  module Areas
+    class Triangle < Polygon
+      attr_reader :center, :width, :height, :bearing
+
+      SIDE_TOLERANCE = 5.0 # meters — accounts for flat-earth projection error
+
+      # Four construction modes:
+      #
+      #   Isosceles:             Triangle.new(center:, width:, height:, bearing:)
+      #   Equilateral by radius: Triangle.new(center:, radius:, bearing:)
+      #   Equilateral by side:   Triangle.new(center:, side:, bearing:)
+      #   Arbitrary 3 vertices:  Triangle.new(vertices: [p1, p2, p3])
+      #
+      def initialize(center: nil, width: nil, height: nil, radius: nil, side: nil, bearing: 0, vertices: nil)
+        if vertices
+          raise ArgumentError, "vertices: cannot be combined with other shape arguments" if center || width || height || radius || side
+
+          verts = validate_vertices(vertices)
+          @center  = compute_center(verts)
+          @bearing = 0.0
+          @width   = 0.0
+          @height  = 0.0
+          super(boundary: verts)
+        else
+          raise ArgumentError, "center is required" unless center
+
+          @center  = center.is_a?(Coordinate::LLA) ? center : center.to_lla
+          @bearing = bearing.to_f
+          resolve_dimensions(width, height, radius, side)
+
+          raise ArgumentError, "width must be positive" unless @width > 0
+          raise ArgumentError, "height must be positive" unless @height > 0
+
+          super(boundary: generate_vertices, validate: false)
+        end
+      end
+
+      def sides
+        3
+      end
+
+      # Returns the three vertices.
+      def vertices
+        boundary[0..2]
+      end
+
+      # Base length (same as width). Returns nil for arbitrary vertex triangles.
+      def base
+        @width > 0 ? @width : nil
+      end
+
+      # True when all three side lengths are equal (within tolerance).
+      def equilateral?
+        a, b, c = side_lengths
+        (a - b).abs < SIDE_TOLERANCE &&
+          (b - c).abs < SIDE_TOLERANCE
+      end
+
+      # True when exactly two side lengths are equal (within tolerance).
+      def isosceles?
+        a, b, c = side_lengths
+        pairs = [
+          (a - b).abs < SIDE_TOLERANCE,
+          (b - c).abs < SIDE_TOLERANCE,
+          (a - c).abs < SIDE_TOLERANCE
+        ]
+        equal_count = pairs.count(true)
+        equal_count == 1
+      end
+
+      # True when no two side lengths are equal (within tolerance).
+      def scalene?
+        !equilateral? && !isosceles?
+      end
+
+      # Returns the three side lengths in meters as [ab, bc, ca].
+      def side_lengths
+        v = vertices
+        [
+          v[0].distance_to(v[1]).meters,
+          v[1].distance_to(v[2]).meters,
+          v[2].distance_to(v[0]).meters
+        ]
+      end
+
+      # Returns the axis-aligned bounding box that encloses this triangle.
+      def to_bounding_box
+        lats = vertices.map(&:lat)
+        lngs = vertices.map(&:lng)
+
+        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)
+        )
+      end
+
+      private
+
+      def validate_vertices(verts)
+        raise ArgumentError, "exactly 3 vertices required" unless verts.size == 3
+
+        verts.map { |v| v.is_a?(Coordinate::LLA) ? v : v.to_lla }
+      end
+
+      def compute_center(verts)
+        Coordinate::LLA.new(
+          lat: verts.sum(&:lat) / 3.0,
+          lng: verts.sum(&:lng) / 3.0,
+          alt: verts.sum(&:alt) / 3.0
+        )
+      end
+
+      def resolve_dimensions(width, height, radius, side)
+        given = { width: width, height: height, radius: radius, side: side }
+                  .compact
+
+        if given.key?(:radius)
+          raise ArgumentError, "radius cannot be combined with width, height, or side" if given.size > 1
+
+          r = radius.to_f
+          raise ArgumentError, "radius must be positive" unless r > 0
+
+          @width  = r * Math.sqrt(3)
+          @height = r * 1.5
+
+        elsif given.key?(:side)
+          raise ArgumentError, "side cannot be combined with width or height" if given.size > 1
+
+          s = side.to_f
+          raise ArgumentError, "side must be positive" unless s > 0
+
+          @width  = s
+          @height = s * Math.sqrt(3) / 2.0
+
+        elsif given.key?(:width) && given.key?(:height)
+          raise ArgumentError, "width/height cannot be combined with radius or side" if given.size > 2
+
+          @width  = width.to_f
+          @height = height.to_f
+
+        else
+          raise ArgumentError, "provide width: + height:, radius:, side:, or vertices:"
+        end
+      end
+
+      def generate_vertices
+        half_w = @width / 2.0
+        half_h = @height / 2.0
+
+        [
+          vertex(-half_w, -half_h),  # base-left
+          vertex( half_w, -half_h),  # base-right
+          vertex(    0.0,  half_h)   # apex
+        ]
+      end
+
+      def vertex(x_offset, y_offset)
+        bearing_rad = @bearing * Geodetic::RAD_PER_DEG
+        lat_rad = @center.lat * Geodetic::RAD_PER_DEG
+
+        m_per_deg_lat = 111_320.0
+        m_per_deg_lng = 111_320.0 * Math.cos(lat_rad)
+
+        north = y_offset * Math.cos(bearing_rad) - x_offset * Math.sin(bearing_rad)
+        east  = y_offset * Math.sin(bearing_rad) + x_offset * Math.cos(bearing_rad)
+
+        Coordinate::LLA.new(
+          lat: @center.lat + north / m_per_deg_lat,
+          lng: @center.lng + east / m_per_deg_lng,
+          alt: @center.alt
+        )
+      end
+    end
+  end
+end

data/lib/geodetic/areas.rb

@@ -2,4 +2,10 @@
 
 require_relative "areas/circle"
 require_relative "areas/polygon"
+require_relative "areas/bounding_box"
+require_relative "areas/regular_polygon"
+require_relative "areas/triangle"
 require_relative "areas/rectangle"
+require_relative "areas/pentagon"
+require_relative "areas/hexagon"
+require_relative "areas/octagon"

data/lib/geodetic/coordinate/gh36.rb

@@ -89,7 +89,7 @@ module Geodetic
         bb = self.class.send(:decode_bounds, @geohash)
         nw = LLA.new(lat: bb[:max_lat], lng: bb[:min_lng], alt: 0.0)
         se = LLA.new(lat: bb[:min_lat], lng: bb[:max_lng], alt: 0.0)
-        Areas::Rectangle.new(nw: nw, se: se)
+        Areas::BoundingBox.new(nw: nw, se: se)
       end
 
       # Uses formula-based precision instead of bounds-based

data/lib/geodetic/coordinate/h3.rb

@@ -11,7 +11,7 @@
 #
 # Key differences from other spatial hashes:
 #   - Cells are hexagons (6 vertices), not rectangles
-#   - to_area returns Areas::Polygon, not Areas::Rectangle
+#   - to_area returns Areas::Polygon, not Areas::BoundingBox
 #   - neighbors returns an Array (6 cells), not a directional Hash
 #   - "precision" maps to H3 resolution (0-15), not string length
 #

data/lib/geodetic/coordinate/spatial_hash.rb

@@ -309,12 +309,12 @@ module Geodetic
         end
       end
 
-      # Returns the cell as an Areas::Rectangle
+      # Returns the cell as an Areas::BoundingBox
       def to_area
         bb = decode_bounds(code_value)
         nw = LLA.new(lat: bb[:max_lat], lng: bb[:min_lng], alt: 0.0)
         se = LLA.new(lat: bb[:min_lat], lng: bb[:max_lng], alt: 0.0)
-        Areas::Rectangle.new(nw: nw, se: se)
+        Areas::BoundingBox.new(nw: nw, se: se)
       end
 
       # Returns precision in meters as {lat:, lng:}