geodetic 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f85da37953a9e974422502d62fbf82279fcf4f0ff71594ada2bb150e07cc75d1
-  data.tar.gz: a986282c09df583d9de453034f36e1a15c0d29cc016f586f09239f4f642d6fae
+  metadata.gz: 495ba0272532d5591ecbb37869857675af00014d6863849c79c6fbef35e590c3
+  data.tar.gz: dcb68a4385f7a888fbfb37b421d2f82c66aae077bda8557ce2a7b60c57e38b35
 SHA512:
-  metadata.gz: 2d72a9b0e9e1a0688f25659dbff3d35e8b1c001c72468d2d2bd5c64ffe9fd2f16315dbbe4ec429c545115268e7486db81b26c4f6c9d625de3a8089b82cbcf8df
-  data.tar.gz: 031eb9604c27d9683c74bf3483b913a5ddb065ed78bd5375f23297f39b923f5a6212498c236982a310afe25fa5ca300df0dfaaa60d8632ad02950c75c2662e15
+  metadata.gz: 8f276d8924aad177efc94aee0037f1fbd4e1cb655668ed54ff5ba0e471c16dd91687966577505057e31a144ea545adf3d8843535ca0705fca69fc5e5bf9a3637
+  data.tar.gz: f2d8102549b1502099d149453f5b18d8143b5799e3d3f5c2c4f947c86b7e2de1355e74916ae3b0d7376652fdb547ebd48488bff2eba18d60211da4ff0ff030a3

data/CHANGELOG.md

@@ -11,6 +11,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [0.5.0] - 2026-03-10
+
+### Added
+
+- **`Geodetic::Vector` class** — geodetic displacement pairing a Distance (magnitude) with a Bearing (direction)
+  - **Construction**: `Vector.new(distance:, bearing:)` with automatic coercion from numeric values
+  - **Components**: `north`, `east` — decomposed meters; `magnitude` — distance in meters
+  - **Factory methods**: `Vector.from_components(north:, east:)`, `Vector.from_segment(segment)`
+  - **Vincenty direct**: `destination_from(origin)` solves the direct geodetic problem on the WGS84 ellipsoid
+  - **Arithmetic**: `+`, `-` (component-wise), `*`, `/` (scalar), `-@` (unary minus); `Numeric * Vector` via coerce
+  - **Products**: `dot(other)`, `cross(other)`, `angle_between(other)`
+  - **Properties**: `zero?`, `normalize`, `reverse`/`inverse`
+  - **Comparable**: ordered by distance (magnitude)
+  - Near-zero results (< 1e-9 m) snap to clean zero vector
+- **Geodetic arithmetic with `+` operator** — build geometry from coordinates, vectors, and distances:
+  - `Coordinate + Coordinate` → Segment
+  - `Coordinate + Coordinate + Coordinate` → Path (via Segment + Coordinate → Path)
+  - `Coordinate + Segment` → Path
+  - `Segment + Coordinate` → Path
+  - `Segment + Segment` → Path
+  - `Coordinate + Distance` → Circle
+  - `Distance + Coordinate` → Circle (commutative)
+  - `Coordinate + Vector` → Segment (Vincenty direct)
+  - `Vector + Coordinate` → Segment (reverse start to coordinate)
+  - `Segment + Vector` → Path (extend from endpoint)
+  - `Vector + Segment` → Path (prepend via reverse)
+  - `Path + Vector` → Path (extend from last point)
+- **Translation with `*` operator and `translate` method** — uniform displacement across all geometric types:
+  - `Coordinate * Vector` → Coordinate (translated point)
+  - `Segment * Vector` → Segment (translated endpoints)
+  - `Path * Vector` → Path (translated waypoints)
+  - `Circle * Vector` → Circle (translated centroid, preserved radius)
+  - `Polygon * Vector` → Polygon (translated vertices)
+- **`Segment#to_vector`** — extract a Vector from a Segment's length and bearing
+- **`Path#to_corridor(width:)`** — convert a path into a Polygon corridor of a given width; uses mean bearing at interior waypoints to avoid self-intersection; accepts meters or a Distance object
+- **Geodetic arithmetic example** (`examples/08_geodetic_arithmetic.rb`) — 11-section demo covering all arithmetic operators, Vector class, translation, corridors, and composed operations
+- Documentation: `docs/reference/vector.md` (Vector reference), `docs/reference/arithmetic.md` (Geodetic Arithmetic reference)
+
+### Changed
+
+- Updated README with Vector, Geodetic Arithmetic, and Corridors sections; added to key features list
+- Updated `examples/README.md` with example 08 description
+
 ## [0.4.0] - 2026-03-10
 
 ### Added

data/README.md

@@ -22,6 +22,8 @@
 - <strong>Segments</strong> - Directed two-point line segments with projection, intersection, and interpolation<br>
 - <strong>Paths</strong> - Directed coordinate sequences with navigation, interpolation, closest approach, intersection, and area conversion<br>
 - <strong>Features</strong> - Named geometry wrapper with metadata and delegated distance/bearing<br>
+- <strong>Vectors</strong> - Geodetic displacement (distance + bearing) with full arithmetic and Vincenty direct<br>
+- <strong>Geodetic Arithmetic</strong> - Compose geometry with operators: P1 + P2 → Segment, + P3 → Path, + Distance → Circle, * Vector → translate<br>
 - <strong>Validated Setters</strong> - Type coercion and range validation on all coordinate attributes<br>
 - <strong>Serialization</strong> - to_s(precision), to_a, from_string, from_array, DMS format<br>
 - <strong>Multiple Datums</strong> - WGS84, Clarke 1866, GRS 1980, Airy 1830, and more<br>
@@ -649,6 +651,78 @@ park.distance_to(liberty).to_km     # => "12.47 km"
 
 All three attributes (`label`, `geometry`, `metadata`) are mutable.
 
+### Vectors
+
+`Vector` pairs a `Distance` (magnitude) with a `Bearing` (direction) to represent a geodetic displacement. It solves the Vincenty direct problem to compute destination points.
+
+```ruby
+v = Geodetic::Vector.new(distance: 10_000, bearing: 90.0)
+v = Geodetic::Vector.new(distance: Distance.km(10), bearing: Bearing.new(90))
+
+v.north          # => north component in meters
+v.east           # => east component in meters
+v.magnitude      # => distance in meters
+v.reverse        # => same distance, opposite bearing
+v.normalize      # => unit vector (1 meter)
+```
+
+**Vector arithmetic:**
+
+```ruby
+v1 + v2          # => Vector (component-wise addition)
+v1 - v2          # => Vector (component-wise subtraction)
+v * 3            # => Vector (scale distance)
+v / 2            # => Vector (scale distance)
+-v               # => Vector (reverse bearing)
+v.dot(v2)        # => Float (dot product)
+v.cross(v2)      # => Float (2D cross product)
+```
+
+**Factory methods:**
+
+```ruby
+Vector.from_components(north: 1000, east: 500)
+Vector.from_segment(segment)
+segment.to_vector
+```
+
+### Geodetic Arithmetic
+
+Operators build geometry from coordinates, vectors, and distances:
+
+```ruby
+# Building geometry with +
+p1 + p2                    # => Segment
+p1 + p2 + p3              # => Path
+p1 + segment              # => Path
+segment + p3              # => Path
+segment + segment          # => Path
+p1 + distance              # => Circle
+p1 + vector                # => Segment (to destination)
+segment + vector           # => Path (extend from endpoint)
+vector + segment           # => Path (prepend via reverse)
+path + vector              # => Path (extend from last point)
+vector + coordinate        # => Segment
+distance + coordinate      # => Circle
+
+# Translation with * or .translate
+p1 * vector                # => Coordinate (translated point)
+segment * vector           # => Segment (translated endpoints)
+path * vector              # => Path (translated waypoints)
+circle * vector            # => Circle (translated centroid)
+polygon * vector           # => Polygon (translated vertices)
+```
+
+### Corridors
+
+Convert a path into a polygon corridor of a given width:
+
+```ruby
+route = seattle + portland + sf
+corridor = route.to_corridor(width: 1000)        # 1km wide polygon
+corridor = route.to_corridor(width: Distance.km(1))
+```
+
 ### Web Mercator Tile Coordinates
 
 ```ruby
@@ -679,6 +753,8 @@ The [`examples/`](examples/) directory contains runnable demo scripts showing pr
 | [`04_bearing_calculations.rb`](examples/04_bearing_calculations.rb) | Bearing class, compass directions, elevation angles, and chain bearings |
 | [`05_map_rendering/`](examples/05_map_rendering/) | Render landmarks on a raster map with Feature objects, polygon areas, bearing arrows, and icons using [libgd-gis](https://rubygems.org/gems/libgd-gis) |
 | [`06_path_operations.rb`](examples/06_path_operations.rb) | Path class: construction, navigation, mutation, path arithmetic, closest approach, containment, Enumerable, equality, subpaths, split, interpolation, bounding boxes, polygon conversion, intersection, path-to-path/area closest points, and Feature integration |
+| [`07_segments_and_shapes.rb`](examples/07_segments_and_shapes.rb) | Segment and polygon subclasses: Triangle, Rectangle, Pentagon, Hexagon, Octagon with containment, edges, and bounding boxes |
+| [`08_geodetic_arithmetic.rb`](examples/08_geodetic_arithmetic.rb) | Geodetic arithmetic: building geometry with + (Segments, Paths, Circles), Vector class (Vincenty direct, components, arithmetic, dot/cross products), translation with * (Coordinates, Segments, Paths, Circles, Polygons), and corridors |
 
 Run any example with:
 

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.