geodetic 0.0.1

data/examples/04_bearing_calculations.rb

@@ -0,0 +1,236 @@
+#!/usr/bin/env ruby
+
+# Demonstration of bearing calculations and the Bearing class
+# Shows great-circle bearings, compass directions, elevation angles,
+# cross-system bearings, and Bearing class features.
+
+require_relative "../lib/geodetic"
+
+Bearing = Geodetic::Bearing
+
+# ── Notable locations ────────────────────────────────────────────
+
+seattle  = GCS::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
+portland = GCS::LLA.new(lat: 45.5152, lng: -122.6784, alt: 0.0)
+sf       = GCS::LLA.new(lat: 37.7749, lng: -122.4194, alt: 0.0)
+nyc      = GCS::LLA.new(lat: 40.7128, lng: -74.0060,  alt: 0.0)
+london   = GCS::LLA.new(lat: 51.5074, lng: -0.1278,   alt: 0.0)
+
+puts "=== Bearing Calculations Demo ==="
+puts
+
+# ── Basic bearing_to ──────────────────────────────────────────────
+
+puts "--- Great-Circle Bearings (Forward Azimuth) ---"
+puts
+
+b = seattle.bearing_to(portland)
+puts <<~HEREDOC
+  Seattle -> Portland:
+    #{b.to_s}          (default: 4 decimals)
+    #{b.to_s(2)}            (2 decimals)
+    #{b.to_s(0)}               (integer)
+    #{b.to_compass(points: 16)} (16-point compass)
+    #{b.to_radians.round(4)} radians
+    Back azimuth: #{b.reverse.to_s}
+HEREDOC
+
+b = seattle.bearing_to(nyc)
+puts "Seattle -> NYC:      #{b.to_s}  (#{b.to_compass(points: 8)})"
+
+b = seattle.bearing_to(london)
+puts "Seattle -> London:   #{b.to_s}  (#{b.to_compass(points: 8)})"
+
+b = seattle.bearing_to(sf)
+puts "Seattle -> SF:       #{b.to_s}  (#{b.to_compass(points: 8)})"
+puts
+
+# ── Compass directions at different resolutions ──────────────────
+
+puts "--- Compass Resolution Comparison ---"
+puts
+
+targets = { "Portland" => portland, "SF" => sf, "NYC" => nyc, "London" => london }
+
+puts "  %-10s %12s  %4s  %4s  %4s" % ["Target", "Degrees", "4pt", "8pt", "16pt"]
+puts "  " + "-" * 42
+
+targets.each do |name, target|
+  b = seattle.bearing_to(target)
+  puts "  %-10s %12s  %4s  %4s  %4s" % [
+    name, b.to_s, b.to_compass(points: 4),
+    b.to_compass(points: 8), b.to_compass(points: 16)
+  ]
+end
+puts
+
+# ── Elevation angles ─────────────────────────────────────────────
+
+puts "--- Elevation Angles ---"
+puts
+
+ground  = GCS::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
+hilltop = GCS::LLA.new(lat: 47.6205, lng: -122.3493, alt: 5000.0)
+plane   = GCS::LLA.new(lat: 47.6300, lng: -122.3400, alt: 10000.0)
+nearby  = GCS::LLA.new(lat: 47.6210, lng: -122.3490, alt: 100.0)
+
+puts "  From ground (0m) to directly above (5000m):"
+puts "    Elevation: #{ground.elevation_to(hilltop).round(2)}°  (nearly straight up)"
+puts
+puts "  From ground to airplane (10km alt, ~1km away):"
+puts "    Elevation: #{ground.elevation_to(plane).round(2)}°"
+puts "    Bearing:   #{ground.bearing_to(plane).to_s}"
+puts
+puts "  From ground to nearby hilltop (100m alt, ~60m away):"
+puts "    Elevation: #{ground.elevation_to(nearby).round(2)}°"
+puts "    Bearing:   #{ground.bearing_to(nearby).to_s}"
+puts
+
+# ── Chain bearings ────────────────────────────────────────────────
+
+puts "--- Chain Bearings (Consecutive Legs) ---"
+puts "Route: Seattle -> Portland -> SF -> NYC -> London"
+puts
+
+bearings = GCS.bearing_between(seattle, portland, sf, nyc, london)
+legs = [
+  "Seattle -> Portland",
+  "Portland -> SF",
+  "SF -> NYC",
+  "NYC -> London"
+]
+
+legs.each_with_index do |label, i|
+  b = bearings[i]
+  puts "  %-22s %12s  %-3s  (reverse: %s)" % [
+    label, b.to_s, b.to_compass(points: 8), b.reverse.to_s
+  ]
+end
+puts
+
+# ── Cross-system bearings ────────────────────────────────────────
+
+puts "--- Cross-System Bearings ---"
+puts
+
+utm_seattle   = seattle.to_utm
+mgrs_portland = GCS::MGRS.from_lla(portland)
+wm_sf         = GCS::WebMercator.from_lla(sf)
+
+b = utm_seattle.bearing_to(mgrs_portland)
+puts "  UTM(Seattle) -> MGRS(Portland):      #{b.to_s}  (#{b.to_compass})"
+
+b = mgrs_portland.bearing_to(wm_sf)
+puts "  MGRS(Portland) -> WebMercator(SF):   #{b.to_s}  (#{b.to_compass})"
+
+b = wm_sf.bearing_to(utm_seattle)
+puts "  WebMercator(SF) -> UTM(Seattle):     #{b.to_s}  (#{b.to_compass})"
+
+gh36_nyc = GCS::GH36.new(nyc)
+b = gh36_nyc.bearing_to(utm_seattle)
+puts "  GH36(NYC) -> UTM(Seattle):           #{b.to_s}  (#{b.to_compass})"
+puts
+
+# ── Local bearings (ENU/NED) ─────────────────────────────────────
+
+puts "--- Local Tangent Plane Bearings (ENU / NED) ---"
+puts
+
+enu_origin = GCS::ENU.new(e: 0.0, n: 0.0, u: 0.0)
+enu_ne     = GCS::ENU.new(e: 100.0, n: 100.0, u: 0.0)
+enu_south  = GCS::ENU.new(e: 0.0, n: -200.0, u: 50.0)
+
+puts "  ENU local_bearing_to:"
+puts "    Origin -> NE point (100,100):  #{enu_origin.local_bearing_to(enu_ne).round(2)}°"
+puts "    Origin -> South point (0,-200): #{enu_origin.local_bearing_to(enu_south).round(2)}°"
+puts
+
+ned_origin = GCS::NED.new(n: 0.0, e: 0.0, d: 0.0)
+ned_above  = GCS::NED.new(n: 100.0, e: 0.0, d: -100.0)
+ned_below  = GCS::NED.new(n: 100.0, e: 0.0, d: 100.0)
+
+puts "  NED local_bearing_to / local_elevation_angle_to:"
+puts "    Origin -> N+Up:    bearing #{ned_origin.local_bearing_to(ned_above).round(2)}°, elevation #{ned_origin.local_elevation_angle_to(ned_above).round(2)}°"
+puts "    Origin -> N+Down:  bearing #{ned_origin.local_bearing_to(ned_below).round(2)}°, elevation #{ned_origin.local_elevation_angle_to(ned_below).round(2)}°"
+puts
+
+# ── Bearing class features ───────────────────────────────────────
+
+puts "=== Bearing Class Features ==="
+puts
+
+# ── Construction and normalization ────────────────────────────────
+
+puts "--- Construction (auto-normalizes to 0-360) ---"
+puts
+
+[0, 90, -90, 450, 720, -180].each do |deg|
+  puts "  Bearing.new(%-4d) => %s" % [deg, Bearing.new(deg).to_s]
+end
+puts
+
+# ── Reverse (back azimuth) ───────────────────────────────────────
+
+puts "--- Reverse (Back Azimuth) ---"
+puts
+
+[0, 45, 90, 180, 270, 315].each do |deg|
+  b = Bearing.new(deg)
+  puts "  %-10s reverse => %s" % [b.to_s, b.reverse.to_s]
+end
+puts
+
+# ── Arithmetic ───────────────────────────────────────────────────
+
+puts "--- Arithmetic ---"
+puts
+
+b = Bearing.new(350)
+puts "  b = #{b.to_s}"
+puts "  b + 20 = #{(b + 20).to_s}  (wraps past 360)"
+puts "  b - 10 = #{(b - 10).to_s}"
+puts
+
+b1 = Bearing.new(90)
+b2 = Bearing.new(45)
+puts "  Bearing(90) - Bearing(45) = #{(b1 - b2)}  (Float, angular difference)"
+puts "  Bearing(45) - Bearing(90) = #{(b2 - b1)}  (negative difference)"
+puts
+
+# ── Comparison ───────────────────────────────────────────────────
+
+puts "--- Comparison ---"
+puts
+
+puts "  Bearing(90) == Bearing(90)?   #{Bearing.new(90) == Bearing.new(90)}"
+puts "  Bearing(90) == Bearing(450)?  #{Bearing.new(90) == Bearing.new(450)}"
+puts "  Bearing(45) < Bearing(90)?    #{Bearing.new(45) < Bearing.new(90)}"
+puts "  Bearing(270) > 180?           #{Bearing.new(270) > 180}"
+puts
+
+# ── Combined distance and bearing ────────────────────────────────
+
+puts "=== Combined Distance + Bearing ==="
+puts
+
+puts "  %-22s %10s  %12s  %6s" % ["Leg", "Distance", "Bearing", "Dir"]
+puts "  " + "-" * 54
+
+route = [
+  ["Seattle", seattle],
+  ["Portland", portland],
+  ["SF", sf],
+  ["NYC", nyc],
+  ["London", london]
+]
+
+route.each_cons(2) do |(name_a, coord_a), (name_b, coord_b)|
+  d = coord_a.distance_to(coord_b)
+  b = coord_a.bearing_to(coord_b)
+  label = "#{name_a} -> #{name_b}"
+  km_str = "%.1f km" % d.to_km.to_f
+  puts "  %-22s %10s  %12s  %6s" % [label, km_str, b.to_s, b.to_compass(points: 8)]
+end
+puts
+
+puts "=== Done ==="

data/lib/geodetic/areas/circle.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative '../coordinates/lla'
+
+module Geodetic
+  module Areas
+    class Circle
+      attr_reader :centroid, :radius
+
+      def initialize(centroid:, radius:)
+        @centroid = centroid  # LLA point
+        @radius   = radius   # in units of meters
+      end
+
+      def includes?(a_point)
+        @centroid.distance_to(a_point).meters <= @radius
+      end
+
+      def excludes?(a_point)
+        !includes?(a_point)
+      end
+
+      alias_method :include?, :includes?
+      alias_method :exclude?, :excludes?
+      alias_method :inside?,  :includes?
+      alias_method :outside?, :excludes?
+    end
+  end
+end

data/lib/geodetic/areas/polygon.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative '../coordinates/lla'
+
+module Geodetic
+  module Areas
+    class Polygon
+      attr_reader :boundary, :centroid
+
+      def initialize(boundary:)
+        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
+
+        centroid_lng /= (6.0 * area)
+        centroid_lat /= (6.0 * area)
+
+        @centroid = Coordinates::LLA.new(lat: centroid_lat, lng: centroid_lng, alt: 0.0)
+      end
+
+      def includes?(a_point)
+        turn_angle = 0.0
+
+        (@boundary.length - 2).times do |index|
+          return true if @boundary[index] == a_point
+
+          d_turn_angle  = a_point.bearing_to(@boundary[index + 1]) - a_point.bearing_to(@boundary[index])
+          d_turn_angle += (d_turn_angle > 0.0 ? -360.0 : 360.0) if d_turn_angle.abs > 180.0
+          turn_angle   += d_turn_angle
+        end
+
+        turn_angle.abs > 180.0
+      end
+
+      def excludes?(a_point)
+        !includes?(a_point)
+      end
+
+      alias_method :include?, :includes?
+      alias_method :exclude?, :excludes?
+      alias_method :inside?,  :includes?
+      alias_method :outside?, :excludes?
+    end
+  end
+end

data/lib/geodetic/areas/rectangle.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative '../coordinates/lla'
+
+module Geodetic
+  module Areas
+    class Rectangle
+      attr_reader :nw, :se, :centroid
+
+      # Define an axis-aligned rectangle by its NW and SE corners.
+      # Accepts any coordinate that responds to to_lla.
+      #
+      #   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?(Coordinates::LLA) ? nw : nw.to_lla
+        @se = se.is_a?(Coordinates::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 = Coordinates::LLA.new(
+          lat: (@nw.lat + @se.lat) / 2.0,
+          lng: (@nw.lng + @se.lng) / 2.0,
+          alt: 0.0
+        )
+      end
+
+      def ne
+        Coordinates::LLA.new(lat: @nw.lat, lng: @se.lng, alt: 0.0)
+      end
+
+      def sw
+        Coordinates::LLA.new(lat: @se.lat, lng: @nw.lng, alt: 0.0)
+      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
+      end
+
+      def excludes?(a_point)
+        !includes?(a_point)
+      end
+
+      alias_method :include?, :includes?
+      alias_method :exclude?, :excludes?
+      alias_method :inside?,  :includes?
+      alias_method :outside?, :excludes?
+    end
+  end
+end

data/lib/geodetic/areas.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "areas/circle"
+require_relative "areas/polygon"
+require_relative "areas/rectangle"

data/lib/geodetic/bearing.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Geodetic
+  class Bearing
+    include Comparable
+
+    COMPASS_16 = %w[N NNE NE ENE E ESE SE SSE S SSW SW WSW W WNW NW NNW].freeze
+    COMPASS_8  = %w[N NE E SE S SW W NW].freeze
+    COMPASS_4  = %w[N E S W].freeze
+
+    attr_reader :degrees
+
+    def initialize(degrees)
+      @degrees = degrees.to_f % 360.0
+    end
+
+    def to_f
+      @degrees
+    end
+
+    def to_i
+      @degrees.to_i
+    end
+
+    def to_radians
+      @degrees * RAD_PER_DEG
+    end
+
+    # Back azimuth (reverse bearing)
+    def reverse
+      Bearing.new(@degrees + 180.0)
+    end
+
+    # Compass direction string.
+    # points: 4 (N/E/S/W), 8 (N/NE/E/...), or 16 (N/NNE/NE/ENE/...)
+    def to_compass(points: 16)
+      case points
+      when 4  then COMPASS_4[(((@degrees + 45.0) % 360.0) / 90.0).to_i]
+      when 8  then COMPASS_8[(((@degrees + 22.5) % 360.0) / 45.0).to_i]
+      when 16 then COMPASS_16[(((@degrees + 11.25) % 360.0) / 22.5).to_i]
+      else raise ArgumentError, "points must be 4, 8, or 16"
+      end
+    end
+
+    def to_s(precision = 4)
+      precision = precision.to_i
+      if precision == 0
+        "#{@degrees.round}°"
+      else
+        format("%.#{precision}f°", @degrees)
+      end
+    end
+
+    def inspect
+      "#<Geodetic::Bearing #{to_s} (#{to_compass})>"
+    end
+
+    def <=>(other)
+      case other
+      when Bearing then @degrees <=> other.degrees
+      when Numeric then @degrees <=> other.to_f
+      end
+    end
+
+    # Bearing - Bearing => Float (angular difference)
+    # Bearing - Numeric => Bearing (subtract degrees)
+    def -(other)
+      case other
+      when Bearing then @degrees - other.degrees
+      when Numeric then Bearing.new(@degrees - other)
+      else raise ArgumentError, "Cannot subtract #{other.class} from Bearing"
+      end
+    end
+
+    # Bearing + Numeric => Bearing
+    def +(other)
+      case other
+      when Numeric then Bearing.new(@degrees + other)
+      else raise ArgumentError, "Cannot add #{other.class} to Bearing"
+      end
+    end
+
+    def coerce(other)
+      case other
+      when Numeric then [other, @degrees]
+      else raise TypeError, "#{other.class} can't be coerced into Bearing"
+      end
+    end
+
+    def zero?
+      @degrees == 0.0
+    end
+  end
+end