geodetic 0.3.1 → 0.4.0

data/docs/reference/path.md

@@ -0,0 +1,269 @@
+# Path Reference
+
+`Geodetic::Path` represents a directed, ordered sequence of unique coordinates. It models routes, trails, boundaries, and any linear geographic feature where the order of waypoints matters.
+
+A Path has a start (first coordinate) and an end (last coordinate). No duplicate coordinates are allowed — each waypoint appears exactly once, enabling unambiguous navigation with `next` and `prev`.
+
+Path includes Ruby's `Enumerable` module, so all standard iteration methods (`map`, `select`, `any?`, `to_a`, etc.) are available.
+
+---
+
+## Constructor
+
+```ruby
+# Empty path
+path = Path.new
+
+# From an array of coordinates
+path = Path.new(coordinates: [a, b, c, d])
+```
+
+Raises `ArgumentError` if any coordinate appears more than once.
+
+---
+
+## Attributes
+
+| Attribute     | Type  | Description |
+|---------------|-------|-------------|
+| `coordinates` | Array | The ordered list of waypoints (read-only) |
+
+---
+
+## Navigation
+
+| Method              | Returns     | Description |
+|---------------------|-------------|-------------|
+| `first`             | Coordinate  | Starting waypoint |
+| `last`              | Coordinate  | Ending waypoint |
+| `next(coordinate)`  | Coordinate  | Waypoint after the given one, or `nil` at end |
+| `prev(coordinate)`  | Waypoint before the given one, or `nil` at start |
+| `size`              | Integer     | Number of waypoints |
+| `empty?`            | Boolean     | True if the path has no waypoints |
+| `segments`          | Array       | Array of `Segment` objects for each consecutive pair |
+
+---
+
+## Membership
+
+| Method | Description |
+|--------|-------------|
+| `include?(coord)` | True if the coordinate is a waypoint in the path |
+| `includes?(coord)` | Alias for `include?` |
+| `contains?(coord, tolerance: 10.0)` | True if the coordinate lies on any segment within tolerance (meters) |
+| `inside?(coord, tolerance: 10.0)` | Alias for `contains?` |
+| `excludes?(coord, tolerance: 10.0)` | Opposite of `contains?` |
+| `exclude?(coord)` | Alias for `excludes?` |
+| `outside?(coord)` | Alias for `excludes?` |
+
+`includes?` checks waypoints only. `contains?` checks whether a coordinate lies on the line between any two consecutive waypoints, using a bearing comparison with a tolerance derived from the segment length.
+
+---
+
+## Equality
+
+```ruby
+path1 == path2
+```
+
+Two paths are equal if they have the same coordinates in the same order.
+
+---
+
+## Spatial Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `nearest_waypoint(target)` | Coordinate | The waypoint closest to the target |
+| `closest_coordinate_to(target)` | Coordinate | The closest point on the path (projected onto segments) |
+| `distance_to(other)` | Distance | Distance from the closest point on the path to the target |
+| `bearing_to(other)` | Bearing | Bearing from the closest point on the path to the target |
+| `closest_points_to(other)` | Hash | Closest pair between path and an Area or another Path |
+
+The `other` parameter for `distance_to`, `bearing_to`, and `closest_coordinate_to` can be a coordinate, a Feature, an Area, or another Path.
+
+### Closest Points
+
+`closest_points_to` returns a hash with:
+
+```ruby
+{
+  path_point: Coordinate,  # closest point on this path
+  area_point: Coordinate,  # closest point on the other geometry
+  distance:   Distance     # distance between the two points
+}
+```
+
+Accepts `Areas::Circle`, `Areas::Polygon`, `Areas::BoundingBox`, or another `Path`.
+
+---
+
+## Computed Properties
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `total_distance` | Distance | Sum of all segment distances |
+| `segment_distances` | Array | Distance for each segment |
+| `segment_bearings` | Array | Bearing for each segment |
+| `reverse` | Path | New path with coordinates in reverse order |
+
+---
+
+## Subpath and Split
+
+### `between(from, to)`
+
+Extracts a subpath between two waypoints (inclusive). Both must exist in the path, and `from` must precede `to`.
+
+```ruby
+sub = route.between(wall_street, union_square)
+```
+
+### `split_at(coordinate)`
+
+Splits the path at a waypoint, returning two paths that share the split point.
+
+```ruby
+left, right = route.split_at(city_hall)
+# left ends with city_hall, right starts with city_hall
+```
+
+---
+
+## Interpolation
+
+### `at_distance(distance)`
+
+Returns the coordinate at a given distance along the path from the start. Accepts a `Distance` object or a numeric value in meters.
+
+```ruby
+halfway = route.at_distance(route.total_distance.meters / 2.0)
+quarter = route.at_distance(Distance.new(route.total_distance.meters * 0.25))
+```
+
+Returns the last coordinate if the distance exceeds the total path length.
+
+---
+
+## Bounding Box
+
+### `bounds`
+
+Returns an `Areas::BoundingBox` representing the axis-aligned bounding box of all waypoints.
+
+```ruby
+bbox = route.bounds
+bbox.nw  # => northwest corner
+bbox.se  # => southeast corner
+bbox.includes?(some_point)  # => true/false
+```
+
+---
+
+## To Polygon
+
+### `to_polygon`
+
+Closes the path into an `Areas::Polygon` by connecting the last coordinate to the first. Requires at least 3 coordinates. Raises `ArgumentError` if the closing segment would intersect any interior segment of the path.
+
+```ruby
+triangle = Path.new(coordinates: [a, b, c])
+poly = triangle.to_polygon
+poly.includes?(some_point)
+```
+
+---
+
+## Intersection
+
+### `intersects?(other_path)`
+
+Returns true if any segment of this path crosses any segment of the other path. Uses orientation-based intersection testing.
+
+```ruby
+route.intersects?(crosstown)  # => true/false
+```
+
+---
+
+## Non-Mutating Operators
+
+These return new Path objects; the original is unchanged.
+
+| Operator | Accepts | Description |
+|----------|---------|-------------|
+| `+ coordinate` | Coordinate | New path with coordinate appended |
+| `+ path` | Path | New path with all coordinates of the other path appended |
+| `- coordinate` | Coordinate | New path with coordinate removed |
+| `- path` | Path | New path with all of the other path's coordinates removed |
+
+```ruby
+combined = downtown_path + uptown_path
+trimmed  = full_route - detour_path
+```
+
+Raises `ArgumentError` if `+` would create duplicates, or if `-` references coordinates not in the path.
+
+---
+
+## Mutating Operators
+
+These modify the path in place and return `self` for chaining.
+
+| Method | Accepts | Description |
+|--------|---------|-------------|
+| `<< other` | Coordinate or Path | Append to end |
+| `>> other` | Coordinate or Path | Prepend to start |
+| `prepend(other)` | Coordinate or Path | Same as `>>` |
+| `insert(coord, after: ref)` | Coordinate | Insert after a reference waypoint |
+| `insert(coord, before: ref)` | Coordinate | Insert before a reference waypoint |
+| `delete(coord)` | Coordinate | Remove a waypoint |
+| `remove(coord)` | Coordinate | Alias for `delete` |
+
+```ruby
+path = Path.new
+path << a << b << c          # build incrementally
+path >> start_point           # prepend
+path << other_path            # append an entire path
+path.insert(detour, after: b) # insert between waypoints
+path.delete(b)                # remove a waypoint
+```
+
+---
+
+## Enumerable
+
+Path includes `Enumerable`. The `each` method iterates over coordinates in order.
+
+```ruby
+route.map { |c| c.lat }
+route.select { |c| c.lat > 40.72 }
+route.max_by { |c| c.lat }
+route.to_a
+```
+
+---
+
+## Display
+
+| Method | Returns |
+|--------|---------|
+| `to_s` | `"Path(7): 40.70... -> 40.71... -> ..."` |
+| `inspect` | `"#<Geodetic::Path size=7 first=... last=...>"` |
+
+---
+
+## Feature Integration
+
+A Path can be used as the geometry of a `Feature`. When a Feature wraps a Path, `distance_to` and `bearing_to` use the Path's geometric projection to find the closest approach point.
+
+```ruby
+hiking_route = Feature.new(
+  label:    "Manhattan Walking Tour",
+  geometry: route,
+  metadata: { type: "walking" }
+)
+
+hiking_route.distance_to(statue_of_liberty).to_km
+hiking_route.bearing_to(statue_of_liberty).to_compass
+```

data/docs/reference/segment.md

@@ -0,0 +1,181 @@
+# Segment Reference
+
+`Geodetic::Segment` represents a directed line segment between two points on the Earth's surface. It is the fundamental geometric primitive underlying `Path` segments, `Polygon` edges, and closest-approach calculations.
+
+A Segment has a `start_point` and an `end_point`, both stored as `Coordinate::LLA`. Properties like `length`, `bearing`, and `midpoint` are computed lazily and cached.
+
+---
+
+## Great Circle Arcs
+
+On a sphere, any two points that are not antipodal (diametrically opposite) define a great circle, and that great circle produces two arcs between them: the **minor arc** (the shorter path) and the **major arc** (the longer way around the globe).
+
+Segment always uses the **minor arc**. All operations — `length`, `bearing`, `interpolate`, `project`, `contains?` — follow the shortest path between the two endpoints via Vincenty geodesic calculations.
+
+For **antipodal points** (exactly opposite sides of the Earth, roughly 20,000 km apart), the great circle is degenerate: there are infinitely many paths of equal length and the bearing is undefined.
+
+In practice, real-world segments rarely approach even a quarter of the Earth's circumference (~10,000 km), so the minor arc assumption holds for virtually all use cases.
+
+---
+
+## Constructor
+
+```ruby
+a = Geodetic::Coordinate::LLA.new(lat: 40.7484, lng: -73.9857, alt: 0)
+b = Geodetic::Coordinate::LLA.new(lat: 40.7580, lng: -73.9855, alt: 0)
+
+seg = Geodetic::Segment.new(a, b)
+```
+
+Accepts any coordinate type that responds to `to_lla`. Endpoints are converted to LLA on construction.
+
+---
+
+## Attributes
+
+| Attribute     | Type | Description |
+|---------------|------|-------------|
+| `start_point` | LLA  | The starting point of the segment |
+| `end_point`   | LLA  | The ending point of the segment |
+
+---
+
+## Properties
+
+All properties are lazily computed and cached after first access.
+
+| Method         | Returns  | Description |
+|----------------|----------|-------------|
+| `length`       | Distance | Great-circle distance between endpoints |
+| `distance`     | Distance | Alias for `length` |
+| `length_meters`| Float    | Length in meters (convenience accessor) |
+| `bearing`      | Bearing  | Forward azimuth from start to end |
+| `midpoint`     | LLA      | Point at the halfway mark |
+
+```ruby
+seg.length           # => #<Geodetic::Distance 1067.45 m>
+seg.distance         # => #<Geodetic::Distance 1067.45 m> (alias)
+seg.length_meters    # => 1067.45
+seg.bearing          # => #<Geodetic::Bearing 1.0°>
+seg.midpoint         # => LLA at the midpoint
+```
+
+---
+
+## Geometry
+
+### `reverse`
+
+Returns a new Segment with start and end points swapped.
+
+```ruby
+rev = seg.reverse
+rev.start_point == seg.end_point  # => true
+```
+
+### `interpolate(fraction)`
+
+Returns the LLA coordinate at a given fraction (0.0 to 1.0) along the segment.
+
+```ruby
+seg.interpolate(0.0)   # => start_point
+seg.interpolate(0.5)   # => midpoint
+seg.interpolate(1.0)   # => end_point
+seg.interpolate(0.25)  # => quarter-way along
+```
+
+---
+
+## Projection
+
+### `project(point)`
+
+Projects a point onto the segment, returning the closest point on the segment and the distance in meters.
+
+```ruby
+foot, distance_m = seg.project(target_point)
+```
+
+- If the perpendicular foot falls within the segment, returns the foot and the perpendicular distance.
+- If the foot falls before the start, returns `start_point`.
+- If the foot falls past the end, returns `end_point`.
+- Handles zero-length segments and target-at-endpoint edge cases.
+
+This is the core geometric operation used by `Path#closest_coordinate_to`, `Path#closest_points_to`, and `Path#at_distance`.
+
+---
+
+## Membership
+
+| Method | Description |
+|--------|-------------|
+| `includes?(point)` | True if the point is a vertex (start or end point) |
+| `contains?(point, tolerance: 10.0)` | True if the point lies on the segment within tolerance (meters) |
+| `excludes?(point, tolerance: 10.0)` | Opposite of `contains?` |
+
+`includes?` checks vertices only. `contains?` checks whether a point lies anywhere along the line between the two endpoints using a bearing comparison with a tolerance derived from the segment length.
+
+```ruby
+seg.includes?(seg.start_point)     # => true
+seg.includes?(seg.midpoint)        # => false
+
+seg.contains?(seg.midpoint)        # => true
+seg.contains?(far_away_point)      # => false
+```
+
+---
+
+## Intersection
+
+### `intersects?(other_segment)`
+
+Tests whether two segments cross each other using cross-product orientation tests on a flat lat/lng approximation. Handles both proper intersections and collinear overlap.
+
+```ruby
+seg1 = Geodetic::Segment.new(a, b)
+seg2 = Geodetic::Segment.new(c, d)
+
+seg1.intersects?(seg2)  # => true/false
+```
+
+Used internally by `Path#intersects?` and `Path#to_polygon` for self-intersection validation.
+
+---
+
+## Conversion
+
+| Method   | Returns | Description |
+|----------|---------|-------------|
+| `to_path`| Path    | A two-point Path from start to end |
+| `to_a`   | Array   | `[start_point, end_point]` |
+
+```ruby
+seg.to_path   # => #<Geodetic::Path size=2 ...>
+seg.to_a      # => [start_point, end_point]
+```
+
+---
+
+## Equality and Display
+
+```ruby
+seg1 == seg2   # true if same start and end points
+
+seg.to_s       # => "Segment(40.748400, ... -> 40.758000, ...)"
+seg.inspect    # => "#<Geodetic::Segment start=... end=... length=1067.45 m>"
+```
+
+Two segments are equal if they have the same start and end points. Direction matters: `Segment.new(a, b) != Segment.new(b, a)`.
+
+---
+
+## Relationship to Path and Polygon
+
+`Path#segments` returns an array of Segment objects:
+
+```ruby
+route = Path.new(coordinates: [a, b, c, d])
+route.segments  # => [Segment(a→b), Segment(b→c), Segment(c→d)]
+```
+
+Polygon edges are implicit segments formed by consecutive boundary points. Segment's `project`, `intersects?`, and `contains?` methods power the geometric operations in both Path and Polygon.

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"