geodetic 0.3.2 → 0.5.0

data/docs/reference/vector.md

@@ -0,0 +1,256 @@
+# Vector Reference
+
+`Geodetic::Vector` represents a geodetic displacement — a combination of distance (magnitude) and bearing (direction). It is the fundamental type for expressing "how far and which way" between two points on Earth.
+
+A Vector solves the **Vincenty direct problem**: given an origin point, a bearing, and a distance, compute the destination point on the WGS84 ellipsoid.
+
+---
+
+## Constructor
+
+```ruby
+# From numeric values (meters and degrees)
+v = Geodetic::Vector.new(distance: 10_000, bearing: 90.0)
+
+# From Distance and Bearing objects
+v = Geodetic::Vector.new(
+  distance: Geodetic::Distance.km(10),
+  bearing:  Geodetic::Bearing.new(90.0)
+)
+```
+
+Numeric arguments are automatically coerced: `distance` wraps into `Distance.new(value)` and `bearing` wraps into `Bearing.new(value)`.
+
+---
+
+## Attributes
+
+| Attribute  | Type     | Description |
+|------------|----------|-------------|
+| `distance` | Distance | The magnitude of the vector |
+| `bearing`  | Bearing  | The direction of the vector (0-360 degrees from north) |
+
+---
+
+## Components
+
+A Vector decomposes into north/east components in meters, treating bearing as an angle measured clockwise from north.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `north` | Float | North component: `distance * cos(bearing)` |
+| `east`  | Float | East component: `distance * sin(bearing)` |
+
+```ruby
+v = Geodetic::Vector.new(distance: 1000, bearing: 45.0)
+v.north  # => 707.107 (meters north)
+v.east   # => 707.107 (meters east)
+```
+
+A due-north vector has a full north component and zero east component. A due-east vector has zero north and full east.
+
+---
+
+## Factory Methods
+
+### `Vector.from_components(north:, east:)`
+
+Reconstruct a Vector from north/east components in meters.
+
+```ruby
+v = Geodetic::Vector.from_components(north: 1000, east: 0)
+v.bearing.degrees  # => 0.0 (due north)
+v.distance.meters  # => 1000.0
+```
+
+Near-zero magnitudes (< 1e-9 meters) snap to a clean zero vector to avoid floating-point artifacts.
+
+### `Vector.from_segment(segment)`
+
+Create a Vector from an existing Segment's length and bearing.
+
+```ruby
+seg = Geodetic::Segment.new(seattle, portland)
+v = Geodetic::Vector.from_segment(seg)
+v.distance.meters  # => same as seg.length_meters
+v.bearing.degrees  # => same as seg.bearing.degrees
+```
+
+Also available as `segment.to_vector`.
+
+---
+
+## Vincenty Direct
+
+### `destination_from(origin)`
+
+Given an origin coordinate, compute the destination point by traveling the vector's distance along the vector's bearing. Uses the full Vincenty direct formula on the WGS84 ellipsoid.
+
+```ruby
+v = Geodetic::Vector.new(distance: 100_000, bearing: 45.0)
+dest = v.destination_from(seattle)  # => LLA 100km northeast of Seattle
+```
+
+Accepts any coordinate type — non-LLA inputs are converted automatically. A zero-distance vector returns the origin unchanged.
+
+**Round-trip accuracy:**
+
+```ruby
+v = Geodetic::Vector.new(distance: 50_000, bearing: 135.0)
+dest = v.destination_from(origin)
+origin.distance_to(dest).meters  # => 50000.0 (within ~1 meter)
+```
+
+---
+
+## Arithmetic
+
+Vector arithmetic uses north/east component decomposition. The result is always a new Vector.
+
+### Vector + Vector
+
+Component-wise addition. Combines two displacements into a single resultant vector.
+
+```ruby
+north = Geodetic::Vector.new(distance: 1000, bearing: 0.0)
+east  = Geodetic::Vector.new(distance: 1000, bearing: 90.0)
+result = north + east
+result.bearing.degrees  # => 45.0
+result.distance.meters  # => 1414.21
+```
+
+### Vector - Vector
+
+Component-wise subtraction.
+
+```ruby
+v1 = Geodetic::Vector.new(distance: 1000, bearing: 45.0)
+result = v1 - v1
+result.zero?  # => true
+```
+
+### Vector * Scalar
+
+Scales the distance. Negative scalars reverse the bearing.
+
+```ruby
+v = Geodetic::Vector.new(distance: 1000, bearing: 45.0)
+(v * 3).distance.meters   # => 3000.0, bearing 45
+(v * -1).bearing.degrees  # => 225.0 (reversed)
+```
+
+`Scalar * Vector` also works via `coerce`:
+
+```ruby
+2 * v  # => Vector with double the distance
+```
+
+### Vector / Scalar
+
+Scales the distance down. Raises `ZeroDivisionError` for zero. Negative divisors reverse the bearing.
+
+```ruby
+v = Geodetic::Vector.new(distance: 3000, bearing: 90.0)
+(v / 3).distance.meters  # => 1000.0
+```
+
+### Unary Minus
+
+Same distance, reversed bearing.
+
+```ruby
+v = Geodetic::Vector.new(distance: 1000, bearing: 45.0)
+(-v).bearing.degrees  # => 225.0
+```
+
+### Identity: V + (-V)
+
+Opposite vectors cancel to zero:
+
+```ruby
+v = Geodetic::Vector.new(distance: 1000, bearing: 45.0)
+result = v + (-v)
+result.zero?  # => true
+```
+
+---
+
+## Products
+
+### `dot(other)`
+
+Scalar dot product using north/east components. Returns a Float.
+
+```ruby
+north = Geodetic::Vector.new(distance: 100, bearing: 0.0)
+east  = Geodetic::Vector.new(distance: 100, bearing: 90.0)
+
+north.dot(north)  # => 10000.0 (parallel)
+north.dot(east)   # => 0.0 (perpendicular)
+```
+
+### `cross(other)`
+
+2D cross product (scalar). Returns a Float. Positive means `other` is to the left of `self`.
+
+```ruby
+north.cross(east)  # => 10000.0
+east.cross(north)  # => -10000.0
+```
+
+### `angle_between(other)`
+
+Returns a Bearing representing the angular difference.
+
+```ruby
+north = Geodetic::Vector.new(distance: 100, bearing: 0.0)
+east  = Geodetic::Vector.new(distance: 100, bearing: 90.0)
+north.angle_between(east).degrees  # => 90.0
+```
+
+---
+
+## Properties
+
+| Method      | Returns  | Description |
+|-------------|----------|-------------|
+| `magnitude` | Float    | Distance in meters |
+| `zero?`     | Boolean  | True if distance is zero |
+| `normalize` | Vector   | Unit vector (1 meter) in the same bearing |
+| `reverse`   | Vector   | Same distance, opposite bearing (alias for `-self`) |
+| `inverse`   | Vector   | Alias for `reverse` |
+
+```ruby
+v = Geodetic::Vector.new(distance: 5000, bearing: 135.0)
+v.magnitude            # => 5000.0
+v.normalize.magnitude  # => 1.0
+v.reverse.bearing.degrees  # => 315.0
+```
+
+---
+
+## Comparison
+
+Vectors include `Comparable`, ordered by distance (magnitude). Two vectors are equal (`==`) only if both distance and bearing match.
+
+```ruby
+short = Geodetic::Vector.new(distance: 100, bearing: 0.0)
+long  = Geodetic::Vector.new(distance: 200, bearing: 0.0)
+short < long  # => true
+
+# Same magnitude, different bearing
+a = Geodetic::Vector.new(distance: 100, bearing: 0.0)
+b = Geodetic::Vector.new(distance: 100, bearing: 90.0)
+(a <=> b) == 0  # => true (same magnitude)
+a == b          # => false (different bearing)
+```
+
+---
+
+## Display
+
+```ruby
+v = Geodetic::Vector.new(distance: 1000, bearing: 90.0)
+v.to_s     # => "Vector(1000.00 m, 90.0000°)"
+v.inspect  # => "#<Geodetic::Vector distance=#<Geodetic::Distance ...> bearing=#<Geodetic::Bearing ...>>"
+```

data/examples/02_all_coordinate_systems.rb

@@ -253,13 +253,13 @@ def demo_coordinate_systems
   puts "   Lat/Lng error is from MGRS 1-meter grid precision truncation."
   puts
 
-  # ========== Rectangle Area ==========
-  puts "RECTANGLE AREA"
+  # ========== BoundingBox Area ==========
+  puts "BOUNDING BOX AREA"
   puts "-" * 50
 
   nw = LLA.new(lat: 47.65, lng: -122.40)
   se = LLA.new(lat: 47.60, lng: -122.30)
-  rect = Areas::Rectangle.new(nw: nw, se: se)
+  rect = Areas::BoundingBox.new(nw: nw, se: se)
   puts "   NW: (#{rect.nw.lat}, #{rect.nw.lng})"
   puts "   SE: (#{rect.se.lat}, #{rect.se.lng})"
   puts "   NE: (#{rect.ne.lat}, #{rect.ne.lng})"
@@ -268,10 +268,10 @@ def demo_coordinate_systems
   puts "   Space Needle inside? #{rect.includes?(lla_coord)}"
   puts "   London inside? #{rect.includes?(london_lla)}"
 
-  # Rectangle from non-LLA coordinates
+  # BoundingBox from non-LLA coordinates
   nw_wm = WebMerc.from_lla(nw)
   se_wm = WebMerc.from_lla(se)
-  rect_wm = Areas::Rectangle.new(nw: nw_wm, se: se_wm)
+  rect_wm = Areas::BoundingBox.new(nw: nw_wm, se: se_wm)
   puts "   From WebMercator: NW=(#{rect_wm.nw.lat.round(4)}, #{rect_wm.nw.lng.round(4)})"
   puts
 
@@ -292,7 +292,7 @@ def demo_coordinate_systems
   puts "Geohash-36 (GH36)"
   puts "Geoid Height Support"
   puts
-  puts "Areas: Circle, Polygon, Rectangle"
+  puts "Areas: Circle, Polygon, BoundingBox"
   puts
   puts "All coordinate systems support complete bidirectional conversions!"
   puts "Total coordinate systems implemented: 13"

data/examples/06_path_operations.rb

@@ -59,10 +59,8 @@ puts
 
 puts "--- 3. Segment Analysis ---"
 
-route.segments.each_with_index do |(a, b), i|
-  dist    = a.distance_to(b)
-  bearing = a.bearing_to(b)
-  puts "  Segment #{i + 1}: #{dist.to_km} #{bearing.to_compass(points: 8)} (#{bearing.to_s(1)})"
+route.segments.each_with_index do |seg, i|
+  puts "  Segment #{i + 1}: #{seg.length.to_km} #{seg.bearing.to_compass(points: 8)} (#{seg.bearing.to_s(1)})"
 end
 
 puts <<~TOTAL

data/examples/07_segments_and_shapes.rb

@@ -0,0 +1,258 @@
+#!/usr/bin/env ruby
+
+# Demonstration of Segment and polygon subclasses (Triangle, Rectangle,
+# Pentagon, Hexagon, Octagon). Shows construction, properties, predicates,
+# containment testing, segment access, bounding boxes, and Feature integration.
+
+require_relative "../lib/geodetic"
+
+include Geodetic
+LLA = Coordinate::LLA
+
+# ── Notable locations around the National Mall, Washington DC ─────
+
+lincoln     = LLA.new(lat: 38.8893, lng: -77.0502, alt: 0)
+washington  = LLA.new(lat: 38.8895, lng: -77.0353, alt: 0)
+capitol     = LLA.new(lat: 38.8899, lng: -77.0091, alt: 0)
+white_house = LLA.new(lat: 38.8977, lng: -77.0365, alt: 0)
+jefferson   = LLA.new(lat: 38.8814, lng: -77.0365, alt: 0)
+pentagon    = LLA.new(lat: 38.8719, lng: -77.0563, alt: 0)
+
+puts "=== Segments and Shapes Demo ==="
+puts
+
+# ── 1. Segment Basics ────────────────────────────────────────────
+
+puts "--- 1. Segment ---"
+puts
+
+seg = Segment.new(lincoln, washington)
+
+puts <<~SEG
+  Lincoln Memorial -> Washington Monument
+  Length:   #{seg.length.to_s}  (#{seg.length_meters.round(1)} m)
+  Distance: #{seg.distance.to_s}  (alias for length)
+  Bearing:  #{seg.bearing.to_s}  (#{seg.bearing.to_compass})
+  Midpoint: #{seg.midpoint.to_s(4)}
+  Centroid: #{seg.centroid.to_s(4)}  (alias for midpoint)
+SEG
+puts
+
+# ── 2. Segment Operations ───────────────────────────────────────
+
+puts "--- 2. Segment Operations ---"
+puts
+
+quarter = seg.interpolate(0.25)
+puts "  Quarter-way point:  #{quarter.to_s(4)}"
+puts "  Reverse bearing:    #{seg.reverse.bearing.to_s}"
+puts
+
+foot, dist_m = seg.project(white_house)
+puts "  Project White House onto Lincoln-Washington segment:"
+puts "  Foot:     #{foot.to_s(4)}"
+puts "  Distance: #{dist_m.round(1)} m from segment"
+puts
+
+puts "  White House is a vertex?   #{seg.includes?(white_house)}"
+puts "  Lincoln is a vertex?       #{seg.includes?(lincoln)}"
+puts "  Midpoint on segment?       #{seg.contains?(seg.midpoint)}"
+puts "  White House on segment?    #{seg.contains?(white_house)}"
+puts
+
+# ── 3. Segment Intersection ─────────────────────────────────────
+
+puts "--- 3. Segment Intersection ---"
+puts
+
+mall_ns = Segment.new(white_house, jefferson)
+mall_ew = Segment.new(lincoln, capitol)
+
+puts "  N-S segment: White House -> Jefferson Memorial"
+puts "  E-W segment: Lincoln Memorial -> Capitol"
+puts "  Intersects?  #{mall_ew.intersects?(mall_ns)}"
+puts
+
+parallel = Segment.new(
+  LLA.new(lat: 38.892, lng: -77.050, alt: 0),
+  LLA.new(lat: 38.892, lng: -77.010, alt: 0)
+)
+puts "  Parallel segment (north of Mall):"
+puts "  Intersects E-W?  #{mall_ew.intersects?(parallel)}"
+puts
+
+# ── 4. Triangle ──────────────────────────────────────────────────
+
+puts "--- 4. Triangle ---"
+puts
+
+puts "  Isosceles (center + width + height):"
+tri = Areas::Triangle.new(center: washington, width: 400, height: 600, bearing: 0)
+puts "    Sides:       #{tri.sides}"
+puts "    Width:       #{tri.width} m"
+puts "    Height:      #{tri.height} m"
+puts "    Bearing:     #{tri.bearing}\u00B0"
+puts "    Equilateral? #{tri.equilateral?}"
+puts "    Isosceles?   #{tri.isosceles?}"
+puts "    Scalene?     #{tri.scalene?}"
+puts "    Side lengths: #{tri.side_lengths.map { |l| "#{l.round(1)} m" }.join(', ')}"
+puts "    Center inside?  #{tri.includes?(washington)}"
+puts
+
+puts "  Equilateral by side (500m):"
+eq_tri = Areas::Triangle.new(center: washington, side: 500, bearing: 30)
+puts "    Equilateral? #{eq_tri.equilateral?}"
+puts "    Side lengths: #{eq_tri.side_lengths.map { |l| "#{l.round(1)} m" }.join(', ')}"
+puts
+
+puts "  Equilateral by radius (300m):"
+r_tri = Areas::Triangle.new(center: washington, radius: 300, bearing: 0)
+puts "    Equilateral? #{r_tri.equilateral?}"
+puts "    Width:  #{r_tri.width.round(1)} m"
+puts "    Height: #{r_tri.height.round(1)} m"
+puts
+
+puts "  Arbitrary 3 vertices:"
+arb_tri = Areas::Triangle.new(vertices: [lincoln, washington, white_house])
+puts "    Scalene?     #{arb_tri.scalene?}"
+puts "    Side lengths: #{arb_tri.side_lengths.map { |l| "#{l.round(1)} m" }.join(', ')}"
+puts "    Washington inside? #{arb_tri.includes?(washington)}"
+puts
+
+# ── 5. Rectangle ────────────────────────────────────────────────
+
+puts "--- 5. Rectangle ---"
+puts
+
+puts "  From a Segment (Lincoln -> Washington) + width:"
+centerline = Segment.new(lincoln, washington)
+rect = Areas::Rectangle.new(segment: centerline, width: 200)
+
+puts "    Width:     #{rect.width} m"
+puts "    Height:    #{rect.height.round(1)} m"
+puts "    Bearing:   #{rect.bearing.round(1)}\u00B0"
+puts "    Center:    #{rect.center.to_s(4)}"
+puts "    Square?    #{rect.square?}"
+puts "    Sides:     #{rect.sides}"
+puts "    Corners:   #{rect.corners.size}"
+puts "    Centerline start: #{rect.centerline.start_point.to_s(4)}"
+puts "    Centerline end:   #{rect.centerline.end_point.to_s(4)}"
+puts
+
+puts "  From an array of two points + width:"
+rect2 = Areas::Rectangle.new(segment: [white_house, jefferson], width: 300)
+puts "    Width:   #{rect2.width} m"
+puts "    Height:  #{rect2.height.round(1)} m"
+puts "    Bearing: #{rect2.bearing.round(1)}\u00B0"
+puts "    Square?  #{rect2.square?}"
+puts
+
+puts "  Square rectangle (width = segment distance):"
+short_seg = Segment.new(lincoln, seg.interpolate(0.1))
+sq = Areas::Rectangle.new(segment: short_seg, width: short_seg.distance)
+puts "    Width:   #{sq.width.round(1)} m"
+puts "    Height:  #{sq.height.round(1)} m"
+puts "    Square?  #{sq.square?}"
+puts
+
+# ── 6. Pentagon, Hexagon, Octagon ────────────────────────────────
+
+puts "--- 6. Regular Polygons ---"
+puts
+
+[
+  ["Pentagon", Areas::Pentagon.new(center: washington, radius: 500, bearing: 0)],
+  ["Hexagon",  Areas::Hexagon.new(center: washington, radius: 500, bearing: 0)],
+  ["Octagon",  Areas::Octagon.new(center: washington, radius: 500, bearing: 0)]
+].each do |name, shape|
+  puts "  #{name}:"
+  puts "    Sides:    #{shape.sides}"
+  puts "    Radius:   #{shape.radius} m"
+  puts "    Vertices: #{shape.boundary.size - 1} (boundary has #{shape.boundary.size} points, closed)"
+  puts "    Centroid: #{shape.centroid.to_s(4)}"
+  puts "    Center inside?  #{shape.includes?(washington)}"
+  puts "    Pentagon inside? #{shape.includes?(pentagon)}"
+  puts
+end
+
+# ── 7. Polygon Segments ─────────────────────────────────────────
+
+puts "--- 7. Polygon Segments ---"
+puts
+
+puts "  Rectangle segments (edges/border):"
+rect.segments.each_with_index do |s, i|
+  puts "    Edge #{i + 1}: #{s.length_meters.round(1)} m, bearing #{s.bearing.to_s}"
+end
+puts "    Connected? #{rect.segments.each_cons(2).all? { |a, b| a.end_point == b.start_point }}"
+puts
+
+puts "  Triangle segments:"
+tri.segments.each_with_index do |s, i|
+  puts "    Side #{i + 1}: #{s.length_meters.round(1)} m"
+end
+puts
+
+# ── 8. Bounding Boxes ───────────────────────────────────────────
+
+puts "--- 8. Bounding Boxes ---"
+puts
+
+[
+  ["Triangle",  tri],
+  ["Rectangle", rect]
+].each do |name, shape|
+  bbox = shape.to_bounding_box
+  puts "  #{name}:"
+  puts "    NW: #{bbox.nw.to_s(4)}"
+  puts "    SE: #{bbox.se.to_s(4)}"
+
+  shape_center = shape.respond_to?(:center) ? shape.center : shape.centroid
+  puts "    Center inside bbox? #{bbox.includes?(shape_center)}"
+  puts
+end
+
+# ── 9. Containment ──────────────────────────────────────────────
+
+puts "--- 9. Containment Testing ---"
+puts
+
+hex = Areas::Hexagon.new(center: washington, radius: 500)
+
+test_points = {
+  "Washington Monument" => washington,
+  "Lincoln Memorial"    => lincoln,
+  "White House"         => white_house,
+  "Pentagon"            => pentagon
+}
+
+puts "  Hexagon (500m radius around Washington Monument):"
+test_points.each do |name, point|
+  dist = washington.distance_to(point)
+  puts "    #{name.ljust(22)} inside? #{hex.includes?(point).to_s.ljust(5)}  (#{dist.to_s} away)"
+end
+puts
+
+# ── 10. Feature Integration ─────────────────────────────────────
+
+puts "--- 10. Feature Integration ---"
+puts
+
+seg_feature = Feature.new(label: "National Mall Axis", geometry: centerline)
+tri_feature = Feature.new(label: "Warning Zone", geometry: tri, metadata: { type: "restricted" })
+rect_feature = Feature.new(label: "Search Area", geometry: rect, metadata: { priority: "high" })
+
+puts "  Segment feature: #{seg_feature}"
+puts "  Triangle feature: #{tri_feature}"
+puts "  Rectangle feature: #{rect_feature}"
+puts
+
+puts "  Distance from each feature to the Pentagon:"
+[seg_feature, tri_feature, rect_feature].each do |f|
+  dist = f.distance_to(pentagon)
+  bearing = f.bearing_to(pentagon)
+  puts "    #{f.label.ljust(20)} #{dist.to_s.rjust(12)}  bearing #{bearing.to_s} (#{bearing.to_compass})"
+end
+puts
+
+puts "=== Done ==="