geodetic 0.3.2 → 0.5.0

data/docs/reference/arithmetic.md

@@ -0,0 +1,368 @@
+# Geodetic Arithmetic Reference
+
+Geodetic provides operator overloading that lets you compose geometric objects naturally. The `+` operator builds geometry from parts, while `*` (and its alias `translate`) applies a vector displacement to shift objects.
+
+---
+
+## Design Principles
+
+1. **Type determines result** — the types of the operands, not their values, determine the return type. `Coordinate + Coordinate` always returns a Segment, never conditionally a different type.
+
+2. **Left operand is the anchor** — in asymmetric operations, the left operand provides the reference point. `P1 + V` creates a segment starting at P1; `V + P1` creates a segment ending at P1.
+
+3. **Consistent translation** — `*` always means "translate by this vector," returning the same type as the receiver. A translated Segment is still a Segment; a translated Path is still a Path.
+
+---
+
+## The + Operator: Building Geometry
+
+The `+` operator composes smaller geometric objects into larger ones. The result type depends on the combination of operand types.
+
+### Coordinate + Coordinate → Segment
+
+Two points define a directed line segment.
+
+```ruby
+seattle = Geodetic::Coordinate::LLA.new(lat: 47.62, lng: -122.35, alt: 0)
+portland = Geodetic::Coordinate::LLA.new(lat: 45.52, lng: -122.68, alt: 0)
+
+seg = seattle + portland  # => Geodetic::Segment
+seg.start_point           # => seattle
+seg.end_point             # => portland
+seg.length                # => Distance (~235 km)
+seg.bearing               # => Bearing (~188°)
+```
+
+Works across any coordinate system — the Segment converts both points to LLA internally:
+
+```ruby
+utm = portland.to_utm
+seg = seattle + utm       # => Segment (seattle → portland via LLA)
+```
+
+Order matters: `seattle + portland` is a different segment than `portland + seattle`.
+
+### Coordinate + Coordinate + Coordinate → Path
+
+Chaining builds a path. The first `+` produces a Segment; the second `+` extends it into a Path.
+
+```ruby
+path = seattle + portland + sf  # => Geodetic::Path (3 points)
+path.size                       # => 3
+path.first                      # => seattle
+path.last                       # => sf
+```
+
+Further chaining continues to extend the Path:
+
+```ruby
+path = seattle + portland + sf + la + nyc  # => Path (5 points)
+```
+
+### Coordinate + Segment → Path
+
+A point plus a segment produces a three-point path: the point, then the segment's endpoints.
+
+```ruby
+seg = portland + sf
+path = seattle + seg  # => Path: seattle → portland → sf
+path.size             # => 3
+```
+
+### Segment + Coordinate → Path
+
+Extending a segment with a point:
+
+```ruby
+seg = seattle + portland
+path = seg + sf       # => Path: seattle → portland → sf
+```
+
+### Segment + Segment → Path
+
+Two segments concatenate into a four-point path:
+
+```ruby
+seg1 = seattle + portland
+seg2 = sf + la
+path = seg1 + seg2    # => Path: seattle → portland → sf → la
+```
+
+### Coordinate + Distance → Circle
+
+A point plus a distance defines a circle.
+
+```ruby
+radius = Geodetic::Distance.km(5)
+circle = seattle + radius
+# => Areas::Circle centered at seattle, 5000m radius
+```
+
+### Distance + Coordinate → Circle
+
+Commutative — same result:
+
+```ruby
+circle = Geodetic::Distance.km(5) + seattle
+# => Areas::Circle centered at seattle, 5000m radius
+```
+
+### Coordinate + Vector → Segment
+
+A point plus a vector solves the Vincenty direct problem, producing a segment from the origin to the destination.
+
+```ruby
+v = Geodetic::Vector.new(distance: 100_000, bearing: 45.0)
+seg = seattle + v
+# => Segment from seattle to a point 100km northeast
+seg.length_meters  # => ~100000.0
+seg.bearing        # => ~45°
+```
+
+This is different from translation (`*`): `+` gives you the journey (a Segment), while `*` gives you just the destination (a Coordinate).
+
+### Vector + Coordinate → Segment
+
+The vector reversed determines the start point; the coordinate is the endpoint.
+
+```ruby
+v = Geodetic::Vector.new(distance: 10_000, bearing: 90.0)
+seg = v + seattle
+# => Segment from (10km west of seattle) to seattle
+```
+
+### Segment + Vector → Path
+
+Extends the segment from its endpoint in the vector's direction.
+
+```ruby
+seg = seattle + portland
+v = Geodetic::Vector.new(distance: 50_000, bearing: 180.0)
+path = seg + v
+# => Path: seattle → portland → (50km south of portland)
+```
+
+### Vector + Segment → Path
+
+Prepends a new start point. The vector is reversed from the segment's start to find it.
+
+```ruby
+v = Geodetic::Vector.new(distance: 50_000, bearing: 90.0)
+seg = seattle + portland
+path = v + seg
+# => Path: (50km west of seattle) → seattle → portland
+```
+
+### Path + Vector → Path
+
+Extends the path from its last point in the vector's direction.
+
+```ruby
+path = seattle + portland + sf
+v = Geodetic::Vector.new(distance: 100_000, bearing: 180.0)
+path2 = path + v
+# => Path: seattle → portland → sf → (100km south of sf)
+```
+
+### Path + Coordinate → Path
+
+Appends a waypoint (already existed before arithmetic was added):
+
+```ruby
+path = seattle + portland
+path2 = path + sf  # => Path: seattle → portland → sf
+```
+
+### Path + Path → Path
+
+Concatenates two paths (already existed):
+
+```ruby
+west_coast = seattle + portland + sf
+east_coast = nyc + dc
+cross_country = west_coast + east_coast
+```
+
+---
+
+## Complete + Operator Table
+
+| Left | + Right | Result | Description |
+|------|---------|--------|-------------|
+| Coordinate | Coordinate | Segment | Two-point directed segment |
+| Coordinate | Vector | Segment | Origin to Vincenty destination |
+| Coordinate | Distance | Circle | Point + radius |
+| Coordinate | Segment | Path | Point then segment endpoints |
+| Segment | Coordinate | Path | Extend with waypoint |
+| Segment | Segment | Path | Concatenate segments |
+| Segment | Vector | Path | Extend from endpoint |
+| Vector | Coordinate | Segment | Reverse start to coordinate |
+| Vector | Segment | Path | Prepend via reverse |
+| Vector | Vector | Vector | Component-wise addition |
+| Distance | Coordinate | Circle | Radius + center |
+| Path | Coordinate | Path | Append waypoint |
+| Path | Path | Path | Concatenate |
+| Path | Segment | Path | Append segment points |
+| Path | Vector | Path | Extend from last point |
+
+---
+
+## The * Operator: Translation
+
+The `*` operator translates (shifts) a geometric object by a vector displacement. Every point in the object is moved by the same vector. The result is always the same type as the receiver.
+
+The named method `translate` is an alias for `*`.
+
+### Coordinate * Vector → Coordinate
+
+Returns the destination point — the pure result of moving the point.
+
+```ruby
+v = Geodetic::Vector.new(distance: 10_000, bearing: 0.0)
+p2 = seattle * v           # => LLA (10km north of seattle)
+p2 = seattle.translate(v)  # => same
+```
+
+Compare with `+`: `seattle + v` returns a **Segment** (the journey); `seattle * v` returns a **Coordinate** (just the destination).
+
+### Segment * Vector → Segment
+
+Both endpoints are translated by the same vector. Length and bearing are preserved.
+
+```ruby
+seg = Geodetic::Segment.new(seattle, portland)
+v = Geodetic::Vector.new(distance: 100_000, bearing: 90.0)
+
+shifted = seg * v
+shifted = seg.translate(v)
+
+shifted.length_meters  # => same as original
+shifted.start_point    # => 100km east of seattle
+shifted.end_point      # => 100km east of portland
+```
+
+### Path * Vector → Path
+
+All waypoints are translated. The shape and distances between points are preserved.
+
+```ruby
+route = seattle + portland + sf
+v = Geodetic::Vector.new(distance: 50_000, bearing: 0.0)
+
+shifted = route * v           # => Path shifted 50km north
+shifted = route.translate(v)  # => same
+shifted.size                  # => 3
+```
+
+### Circle * Vector → Circle
+
+The centroid is translated. The radius is preserved.
+
+```ruby
+circle = Geodetic::Areas::Circle.new(centroid: seattle, radius: 5000)
+v = Geodetic::Vector.new(distance: 10_000, bearing: 180.0)
+
+shifted = circle * v           # => Circle 10km south, same 5km radius
+shifted = circle.translate(v)  # => same
+shifted.radius                 # => 5000.0
+```
+
+### Polygon * Vector → Polygon
+
+All boundary vertices are translated. The shape is preserved.
+
+```ruby
+a = LLA.new(lat: 40.0, lng: -74.0, alt: 0)
+b = LLA.new(lat: 40.0, lng: -73.0, alt: 0)
+c = LLA.new(lat: 41.0, lng: -73.5, alt: 0)
+poly = Geodetic::Areas::Polygon.new(boundary: [a, b, c])
+
+v = Geodetic::Vector.new(distance: 100_000, bearing: 0.0)
+shifted = poly * v           # => Polygon shifted 100km north
+shifted = poly.translate(v)  # => same
+```
+
+---
+
+## Complete * Operator Table
+
+| Object | * Vector | Result | Effect |
+|--------|----------|--------|--------|
+| Coordinate | Vector | Coordinate | Translate point |
+| Segment | Vector | Segment | Translate both endpoints |
+| Path | Vector | Path | Translate all waypoints |
+| Circle | Vector | Circle | Translate centroid, preserve radius |
+| Polygon | Vector | Polygon | Translate all vertices |
+
+The `*` operator only accepts a `Vector` on the right side. Any other type raises `ArgumentError`.
+
+---
+
+## Corridors
+
+`Path#to_corridor(width:)` converts a path into a polygon by offsetting each waypoint perpendicular to the path bearing on both sides.
+
+```ruby
+route = seattle + portland + sf
+corridor = route.to_corridor(width: 1000)          # 1km wide
+corridor = route.to_corridor(width: Distance.km(1)) # also accepts Distance
+# => Areas::Polygon with 2*N boundary vertices
+```
+
+At interior waypoints, the perpendicular direction uses the mean bearing of the two adjacent segments to avoid self-intersection at bends.
+
+Requires at least 2 coordinates. The `width:` parameter accepts meters (Numeric) or a `Distance` object.
+
+---
+
+## Combining + and *
+
+The operators compose naturally:
+
+```ruby
+# Build a route, then shift it
+v = Geodetic::Vector.new(distance: 50_000, bearing: 90.0)
+route = (seattle + portland + sf) * v  # shifted 50km east
+
+# Build a circle, then translate it
+circle = (seattle + Distance.km(5)) * v
+
+# Chain: point + vector gives segment, then extend
+seg = seattle + Geodetic::Vector.new(distance: 100_000, bearing: 45.0)
+path = seg + portland  # 3-point path
+
+# Translate a corridor
+corridor = route.to_corridor(width: 500)
+shifted_corridor = corridor * v
+```
+
+---
+
+## Key Distinctions
+
+### + vs * with Vector
+
+This is the most important distinction to understand:
+
+| Expression | Result | Meaning |
+|-----------|--------|---------|
+| `P + V` | Segment | The **journey** — where you started and where you arrived |
+| `P * V` | Coordinate | The **destination** — just where you end up |
+
+`P + V` gives you a Segment because building geometry is the purpose of `+`. The segment records both the origin and the destination.
+
+`P * V` gives you a Coordinate because translation is the purpose of `*`. You're moving the point, not creating a composite object.
+
+### Commutativity
+
+Most `+` operations are **not** commutative — order determines the structure:
+
+- `P1 + P2` starts at P1; `P2 + P1` starts at P2
+- `P + V` creates a segment starting at P; `V + P` creates a segment ending at P
+
+The exceptions are:
+
+- `P + Distance` and `Distance + P` both produce the same Circle
+- `V1 + V2` and `V2 + V1` produce the same Vector (component addition is commutative)
+
+Translation (`*`) is always `object * vector` — the vector must be on the right.

data/docs/reference/feature.md

@@ -14,7 +14,7 @@ Feature.new(
 )
 ```
 
-The `geometry` parameter accepts any coordinate class, any area class (`Circle`, `Polygon`, `Rectangle`), or a `Path`. The `metadata` hash is optional and defaults to `{}`.
+The `geometry` parameter accepts any coordinate class, any area class (`Circle`, `Polygon`, `BoundingBox`), or a `Path`. The `metadata` hash is optional and defaults to `{}`.
 
 ---
 
@@ -35,7 +35,7 @@ All three attributes have both reader and writer methods.
 A Feature's geometry can be any of:
 
 - **Coordinate** — any of the 18 coordinate classes (`LLA`, `ECEF`, `UTM`, etc.)
-- **Area** — `Areas::Circle`, `Areas::Polygon`, or `Areas::Rectangle`
+- **Area** — `Areas::Circle`, `Areas::Polygon`, or `Areas::BoundingBox`
 - **Path** — a `Geodetic::Path` representing a route or trail
 
 When the geometry is an area, `distance_to` and `bearing_to` use the area's `centroid` as the reference point. When the geometry is a Path, `distance_to` and `bearing_to` use geometric projection to find the closest approach point on the path.

data/docs/reference/path.md

@@ -40,7 +40,7 @@ Raises `ArgumentError` if any coordinate appears more than once.
 | `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       | Pairs of consecutive coordinates `[[a,b], [b,c], ...]` |
+| `segments`          | Array       | Array of `Segment` objects for each consecutive pair |
 
 ---
 
@@ -94,7 +94,7 @@ The `other` parameter for `distance_to`, `bearing_to`, and `closest_coordinate_t
 }
 ```
 
-Accepts `Areas::Circle`, `Areas::Polygon`, `Areas::Rectangle`, or another `Path`.
+Accepts `Areas::Circle`, `Areas::Polygon`, `Areas::BoundingBox`, or another `Path`.
 
 ---
 
@@ -149,7 +149,7 @@ Returns the last coordinate if the distance exceeds the total path length.
 
 ### `bounds`
 
-Returns an `Areas::Rectangle` representing the axis-aligned bounding box of all waypoints.
+Returns an `Areas::BoundingBox` representing the axis-aligned bounding box of all waypoints.
 
 ```ruby
 bbox = route.bounds

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.