geodetic 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f295df82e85611a9a7a7dd56593ae029d6ad096cc5c96021d5b59b4f4b001cc2
-  data.tar.gz: 6da1bc3461fd4f372b53f5458d322f8c14d1feb8a2afa93a2375cb5641674674
+  metadata.gz: 495ba0272532d5591ecbb37869857675af00014d6863849c79c6fbef35e590c3
+  data.tar.gz: dcb68a4385f7a888fbfb37b421d2f82c66aae077bda8557ce2a7b60c57e38b35
 SHA512:
-  metadata.gz: 1a0b72935abf28bbcb41182f800d1bdb52466530565f13d75fec5f3eec14c0dac7680f8220f09c51cf4d60ed3b87fc53a3675ceb972f1cec17ca06cbd096d717
-  data.tar.gz: 754e5b64d8e1d333dafd270a6e21434d46102ea57e43fbba16b83bcecd9eb69eb4e834a51554c10eb59433f6d434930bf2664fca0d9c22b37cf7378e90cc106e
+  metadata.gz: 8f276d8924aad177efc94aee0037f1fbd4e1cb655668ed54ff5ba0e471c16dd91687966577505057e31a144ea545adf3d8843535ca0705fca69fc5e5bf9a3637
+  data.tar.gz: f2d8102549b1502099d149453f5b18d8143b5799e3d3f5c2c4f947c86b7e2de1355e74916ae3b0d7376652fdb547ebd48488bff2eba18d60211da4ff0ff030a3

data/CHANGELOG.md

@@ -11,6 +11,88 @@ 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
+
+- **`Geodetic::Segment` class** — directed two-point line segment, the fundamental geometric primitive underlying Path and Polygon
+  - **Properties**: `length`/`distance` (returns Distance), `length_meters`, `bearing` (returns Bearing), `midpoint`/`centroid` (returns LLA) — all lazily computed and cached
+  - **Projection**: `project(point)` returns the closest point on the segment and perpendicular distance
+  - **Interpolation**: `interpolate(fraction)` returns the LLA at any fraction along the segment
+  - **Membership**: `includes?(point)` (vertex-only check), `contains?(point, tolerance:)` (on-segment check), `excludes?`
+  - **Intersection**: `intersects?(other_segment)` using cross-product orientation tests
+  - **Conversion**: `reverse`, `to_path`, `to_a`, `==`, `to_s`, `inspect`
+- **`Geodetic::Areas::Triangle`** — polygon subclass with four construction modes
+  - Isosceles: `Triangle.new(center:, width:, height:, bearing:)`
+  - Equilateral by circumradius: `Triangle.new(center:, radius:, bearing:)`
+  - Equilateral by side length: `Triangle.new(center:, side:, bearing:)`
+  - Arbitrary vertices: `Triangle.new(vertices: [p1, p2, p3])`
+  - Predicates: `equilateral?`, `isosceles?`, `scalene?` based on actual side lengths (5m tolerance)
+  - Methods: `vertices`, `side_lengths`, `base`, `to_bounding_box`
+- **`Geodetic::Areas::Rectangle`** — polygon subclass defined by a centerline Segment and perpendicular width
+  - `Rectangle.new(segment:, width:)` — accepts a Segment object or a two-element array of coordinates
+  - `width:` accepts numeric (meters) or a Distance instance
+  - Derived properties: `center`, `height`, `bearing` from the centerline; `corners`, `square?`, `to_bounding_box`
+- **`Geodetic::Areas::Pentagon`**, **`Hexagon`**, **`Octagon`** — regular polygon subclasses from center + radius + bearing
+- **Polygon self-intersection validation** — `Polygon.new` validates that no edge crosses another; pass `validate: false` to skip (used by subclasses with generated geometry)
+- **Polygon `segments` method** — returns `Array<Segment>` for each edge; `edges` and `border` are aliases
+- **Segments and shapes example** (`examples/07_segments_and_shapes.rb`) — 10-section demo covering Segment operations, Triangle/Rectangle construction and predicates, regular polygons, containment, bounding boxes, and Feature integration
+- Documentation: `docs/reference/segment.md` (Segment reference with Great Circle Arcs section), updated `docs/reference/areas.md` with all polygon subclasses
+
+### Changed
+
+- **Refactored `Path`** to use Segment objects — removed ~140 lines of private segment methods (`project_onto_segment`, `on_segment?`, `segments_intersect?`, `cross_sign`, `on_collinear?`, `to_flat`); all segment operations now delegate to Segment
+- **Refactored `Polygon`** — `segments` is now the primary method (was `edges`); `edges` and `border` are aliases
+- **Updated `Feature`** to support Segment as a geometry type via `centroid` (alias for `midpoint`)
+- Updated README, `docs/index.md`, `docs/reference/areas.md`, `docs/reference/segment.md`, `examples/README.md`, and mkdocs nav
+
+### Removed
+
+- `Areas::Rectangle = Areas::BoundingBox` alias — Rectangle is now its own class (Polygon subclass)
+
 ## [0.3.2] - 2026-03-09
 
 ### Added
@@ -19,11 +101,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Navigation**: `first`, `last`, `next`, `prev`, `segments`, `size`, `empty?`
   - **Membership**: `include?`/`includes?` (waypoint check), `contains?`/`inside?` (on-segment check with configurable tolerance)
   - **Spatial**: `nearest_waypoint`, `closest_coordinate_to`, `distance_to`, `bearing_to` using geometric projection onto segments
-  - **Closest points**: `closest_points_to` for Path-to-Path, Path-to-Polygon, Path-to-Rectangle, and Path-to-Circle
+  - **Closest points**: `closest_points_to` for Path-to-Path, Path-to-Polygon, Path-to-BoundingBox, and Path-to-Circle
   - **Computed**: `total_distance`, `segment_distances`, `segment_bearings`, `reverse`
   - **Subpath/split**: `between(from, to)` extracts a subpath; `split_at(coord)` divides into two paths sharing the split point
   - **Interpolation**: `at_distance(distance)` finds the coordinate at a given distance along the path
-  - **Bounding box**: `bounds` returns an `Areas::Rectangle`
+  - **Bounding box**: `bounds` returns an `Areas::BoundingBox`
   - **Polygon conversion**: `to_polygon` closes the path (validates no self-intersection)
   - **Intersection**: `intersects?(other_path)` detects crossing segments
   - **Equality**: `==` compares coordinates in order

data/README.md

@@ -18,9 +18,12 @@
 - <strong>Distance Calculations</strong> - Vincenty great-circle and straight-line with unit tracking<br>
 - <strong>Bearing Calculations</strong> - Forward azimuth, back azimuth, compass directions, elevation angles<br>
 - <strong>Geoid Height Support</strong> - EGM96, EGM2008, GEOID18, GEOID12B models<br>
-- <strong>Geographic Areas</strong> - Circle, Polygon, and Rectangle with point-in-area tests<br>
+- <strong>Geographic Areas</strong> - Circle, Polygon, BoundingBox, Triangle, Rectangle, Pentagon, Hexagon, Octagon<br>
+- <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>
@@ -426,7 +429,7 @@ lla = gh36.to_lla
 gh36.neighbors  # => { N: GH36, S: GH36, E: GH36, W: GH36, NE: ..., NW: ..., SE: ..., SW: ... }
 
 # Bounding rectangle of the geohash cell
-area = gh36.to_area    # => Areas::Rectangle
+area = gh36.to_area    # => Areas::BoundingBox
 area.includes?(gh36.to_lla)  # => true
 
 # Precision info
@@ -453,7 +456,7 @@ lla = gh.to_lla
 gh.neighbors  # => { N: GH, S: GH, E: GH, W: GH, NE: ..., NW: ..., SE: ..., SW: ... }
 
 # Bounding rectangle of the geohash cell
-area = gh.to_area    # => Areas::Rectangle
+area = gh.to_area    # => Areas::BoundingBox
 area.includes?(gh.to_lla)  # => true
 
 # Precision info
@@ -480,7 +483,7 @@ lla = ham.to_lla
 ham.neighbors  # => { N: HAM, S: HAM, E: HAM, W: HAM, NE: ..., NW: ..., SE: ..., SW: ... }
 
 # Bounding rectangle of the grid square
-area = ham.to_area    # => Areas::Rectangle
+area = ham.to_area    # => Areas::BoundingBox
 area.includes?(ham.to_lla)  # => true
 
 # Precision info
@@ -507,7 +510,7 @@ lla = olc.to_lla
 olc.neighbors  # => { N: OLC, S: OLC, E: OLC, W: OLC, NE: ..., NW: ..., SE: ..., SW: ... }
 
 # Bounding rectangle of the plus code cell
-area = olc.to_area    # => Areas::Rectangle
+area = olc.to_area    # => Areas::BoundingBox
 area.includes?(olc.to_lla)  # => true
 
 # Precision info
@@ -532,16 +535,52 @@ points = [
 polygon = Areas::Polygon.new(boundary: points)
 polygon.centroid    # => computed centroid as LLA
 
-# Rectangle area (accepts any coordinate type)
+# BoundingBox area (accepts any coordinate type)
 nw = Coordinates::LLA.new(lat: 41.0, lng: -75.0)
 se = Coordinates::LLA.new(lat: 40.0, lng: -74.0)
-rect = Areas::Rectangle.new(nw: nw, se: se)
+rect = Areas::BoundingBox.new(nw: nw, se: se)
 rect.centroid       # => LLA at center
 rect.ne             # => computed NE corner
 rect.sw             # => computed SW corner
 rect.includes?(point)  # => true/false
 ```
 
+### Segments
+
+`Segment` represents a directed line segment between two points. It provides the geometric primitives that `Path` and `Polygon` build on.
+
+```ruby
+a = Coordinate::LLA.new(lat: 40.7484, lng: -73.9857, alt: 0)
+b = Coordinate::LLA.new(lat: 40.7580, lng: -73.9855, alt: 0)
+
+seg = Segment.new(a, b)
+
+# Properties (lazily computed, cached)
+seg.length           # => Distance
+seg.distance         # => Distance (alias for length)
+seg.bearing          # => Bearing
+seg.midpoint         # => LLA at halfway point
+
+# Projection — closest point on segment to a target
+foot, dist_m = seg.project(target_point)
+
+# Interpolation — point at fraction along segment
+seg.interpolate(0.25)  # => LLA at quarter-way
+
+# Membership
+seg.includes?(a)              # => true  (vertex check only)
+seg.includes?(seg.midpoint)   # => false
+seg.contains?(seg.midpoint)   # => true  (on-segment check)
+
+# Intersection
+seg.intersects?(other_seg)  # => true/false
+
+# Conversion
+seg.reverse    # => Segment with swapped endpoints
+seg.to_path    # => two-point Path
+seg.to_a       # => [start_point, end_point]
+```
+
 ### Paths
 
 `Path` is a directed, ordered sequence of unique coordinates representing routes, trails, or boundaries.
@@ -572,7 +611,7 @@ route.closest_points_to(other_path)  # path-to-path
 sub = route.between(a, b)        # extract subpath
 left, right = route.split_at(c)  # split at waypoint
 route.at_distance(Distance.km(2)) # interpolate along path
-route.bounds                     # => Areas::Rectangle
+route.bounds                     # => Areas::BoundingBox
 route.to_polygon                 # close into polygon
 route.intersects?(other_path)    # crossing detection
 route.contains?(point)           # on-segment check
@@ -612,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
@@ -642,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/coordinate-systems/gars.md

@@ -173,11 +173,11 @@ Neighbors preserve the same precision as the original code. Latitude is clamped
 
 ## Area
 
-The `to_area` method returns the GARS cell as a `Geodetic::Areas::Rectangle`.
+The `to_area` method returns the GARS cell as a `Geodetic::Areas::BoundingBox`.
 
 ```ruby
 area = coord.to_area
-# => Geodetic::Areas::Rectangle
+# => Geodetic::Areas::BoundingBox
 
 area.includes?(coord.to_lla)    # => true (midpoint is inside the cell)
 area.nw                         # => LLA (northwest corner)

data/docs/coordinate-systems/georef.md

@@ -154,11 +154,11 @@ Neighbors preserve the same precision as the original code. Latitude is clamped
 
 ## Area
 
-The `to_area` method returns the GEOREF cell as a `Geodetic::Areas::Rectangle`.
+The `to_area` method returns the GEOREF cell as a `Geodetic::Areas::BoundingBox`.
 
 ```ruby
 area = coord.to_area
-# => Geodetic::Areas::Rectangle
+# => Geodetic::Areas::BoundingBox
 
 area.includes?(coord.to_lla)    # => true (midpoint is inside the cell)
 area.nw                         # => LLA (northwest corner)

data/docs/coordinate-systems/gh.md

@@ -142,11 +142,11 @@ Neighbors preserve the same precision as the original geohash. Longitude wraps c
 
 ## Area
 
-The `to_area` method returns the geohash cell as a `Geodetic::Areas::Rectangle`.
+The `to_area` method returns the geohash cell as a `Geodetic::Areas::BoundingBox`.
 
 ```ruby
 area = coord.to_area
-# => Geodetic::Areas::Rectangle
+# => Geodetic::Areas::BoundingBox
 
 area.includes?(coord.to_lla)    # => true (midpoint is inside the cell)
 area.nw                         # => LLA (northwest corner)

data/docs/coordinate-systems/gh36.md

@@ -137,11 +137,11 @@ Neighbor computation propagates carries when the adjustment wraps beyond the mat
 
 ## Area
 
-The `to_area` method returns the geohash cell as a `Geodetic::Areas::Rectangle`.
+The `to_area` method returns the geohash cell as a `Geodetic::Areas::BoundingBox`.
 
 ```ruby
 area = coord.to_area
-# => Geodetic::Areas::Rectangle
+# => Geodetic::Areas::BoundingBox
 
 area.includes?(coord.to_lla)    # => true (midpoint is inside the cell)
 area.nw                         # => LLA (northwest corner)

data/docs/coordinate-systems/h3.md

@@ -36,8 +36,8 @@ Geodetic searches these paths automatically:
 
 | Feature | GH/OLC/GARS/GEOREF/HAM | H3 |
 |---------|------------------------|-----|
-| Cell shape | Rectangle | Hexagon (6 vertices) |
-| `to_area` returns | `Areas::Rectangle` | `Areas::Polygon` |
+| Cell shape | BoundingBox | Hexagon (6 vertices) |
+| `to_area` returns | `Areas::BoundingBox` | `Areas::Polygon` |
 | `neighbors` returns | Hash with 8 cardinal keys | Array of 6 cells |
 | Code format | String | 64-bit integer (hex string) |
 | Dependency | None (pure Ruby) | `libh3` (C library via fiddle) |

data/docs/coordinate-systems/ham.md

@@ -150,11 +150,11 @@ Neighbors preserve the same precision as the original locator. Latitude is clamp
 
 ## Area
 
-The `to_area` method returns the grid square as a `Geodetic::Areas::Rectangle`.
+The `to_area` method returns the grid square as a `Geodetic::Areas::BoundingBox`.
 
 ```ruby
 area = coord.to_area
-# => Geodetic::Areas::Rectangle
+# => Geodetic::Areas::BoundingBox
 
 area.includes?(coord.to_lla)    # => true (midpoint is inside the cell)
 area.nw                         # => LLA (northwest corner)

data/docs/coordinate-systems/olc.md

@@ -155,11 +155,11 @@ Neighbors preserve the same precision as the original code. Latitude is clamped
 
 ## Area
 
-The `to_area` method returns the plus code cell as a `Geodetic::Areas::Rectangle`.
+The `to_area` method returns the plus code cell as a `Geodetic::Areas::BoundingBox`.
 
 ```ruby
 area = coord.to_area
-# => Geodetic::Areas::Rectangle
+# => Geodetic::Areas::BoundingBox
 
 area.includes?(coord.to_lla)    # => true (midpoint is inside the cell)
 area.nw                         # => LLA (northwest corner)

data/docs/index.md

@@ -14,7 +14,8 @@
 <li><strong>Distance Calculations</strong> - Vincenty great-circle and straight-line with unit tracking<br>
 <li><strong>Bearing Calculations</strong> - Forward azimuth, back azimuth, compass directions, elevation angles<br>
 <li><strong>Geoid Height Support</strong> - EGM96, EGM2008, GEOID18, GEOID12B models<br>
-<li><strong>Geographic Areas</strong> - Circle, Polygon, and Rectangle with point-in-area tests<br>
+<li><strong>Geographic Areas</strong> - Circle, Polygon, BoundingBox, Triangle, Rectangle, Pentagon, Hexagon, Octagon<br>
+<li><strong>Segments</strong> - Directed two-point line segments with projection, intersection, and interpolation<br>
 <li><strong>Paths</strong> - Directed coordinate sequences with navigation, interpolation, closest approach, intersection, and area conversion<br>
 <li><strong>Features</strong> - Named geometry wrapper with metadata and delegated distance/bearing<br>
 <li><strong>Validated Setters</strong> - Type coercion and range validation on all coordinate attributes<br>
@@ -57,7 +58,8 @@ Geodetic supports full bidirectional conversion between all 18 coordinate system
 
 - **16 geodetic datums** -- WGS84, GRS 1980, Clarke 1866, Airy 1830, Bessel 1841, and more. All conversion methods accept an optional datum parameter, defaulting to WGS84.
 - **Geoid height calculations** -- Convert between ellipsoidal and orthometric heights using models such as EGM96, EGM2008, GEOID18, and GEOID12B.
-- **Geographic areas** -- `Geodetic::Areas::Circle`, `Geodetic::Areas::Polygon`, and `Geodetic::Areas::Rectangle` for point-in-area testing.
+- **Geographic areas** -- `Geodetic::Areas::Circle`, `Geodetic::Areas::Polygon`, `Geodetic::Areas::BoundingBox`, plus polygon subclasses (`Triangle`, `Rectangle`, `Pentagon`, `Hexagon`, `Octagon`) for point-in-area testing.
+- **Segments** -- `Geodetic::Segment` is a directed two-point line segment with projection, intersection detection, interpolation, and membership testing. It is the geometric primitive underlying Path and Polygon operations.
 - **Paths** -- `Geodetic::Path` is a directed, ordered sequence of unique coordinates supporting navigation, segment analysis, interpolation, closest approach (geometric projection), containment testing, bounding boxes, polygon conversion, and path intersection detection.
 - **Features** -- `Geodetic::Feature` wraps any coordinate, area, or path with a label and metadata hash, delegating `distance_to` and `bearing_to` to the underlying geometry.
 

data/docs/reference/areas.md

@@ -1,6 +1,6 @@
 # Areas Reference
 
-The `Geodetic::Areas` module provides three geometric area classes for point-in-area testing: `Circle`, `Polygon`, and `Rectangle`. All operate on `Geodetic::Coordinate::LLA` points.
+The `Geodetic::Areas` module provides geometric area classes for point-in-area testing: `Circle`, `Polygon`, `BoundingBox`, and polygon subclasses (`Triangle`, `Rectangle`, `Pentagon`, `Hexagon`, `Octagon`). All operate on `Geodetic::Coordinate::LLA` points.
 
 ---
 
@@ -107,18 +107,38 @@ Returns `true` if the given LLA point falls outside the polygon. The logical inv
 polygon.excludes?(point)  # => true or false
 ```
 
+#### `segments` / `edges` / `border`
+
+Returns an array of `Segment` objects for each edge of the polygon.
+
+```ruby
+polygon.segments  # => [Segment(p1→p2), Segment(p2→p3), Segment(p3→p1)]
+```
+
+### Self-Intersection Validation
+
+By default the constructor validates that no edge crosses another edge. Pass `validate: false` to skip this check (used by subclasses that generate known-good geometry).
+
+```ruby
+Geodetic::Areas::Polygon.new(boundary: points)                  # validates
+Geodetic::Areas::Polygon.new(boundary: points, validate: false)  # skips
+```
+
 ### Alias Summary
 
 | Primary Method | Aliases |
 |---------------|---------|
 | `includes?` | `include?`, `inside?` |
 | `excludes?` | `exclude?`, `outside?` |
+| `segments` | `edges`, `border` |
 
 ---
 
-## Geodetic::Areas::Rectangle
+## Geodetic::Areas::BoundingBox
 
-Defines an axis-aligned rectangle by its northwest and southeast corners.
+Defines an axis-aligned bounding box by its northwest and southeast corners. Edges are always oriented East-West and North-South.
+
+> **Note:** `Rectangle` is a separate class (`Polygon` subclass) constructed from a `Segment` centerline. It is not related to `BoundingBox`.
 
 ### Constructor
 
@@ -126,7 +146,7 @@ Defines an axis-aligned rectangle by its northwest and southeast corners.
 nw = Geodetic::Coordinate::LLA.new(lat: 41.0, lng: -75.0)
 se = Geodetic::Coordinate::LLA.new(lat: 40.0, lng: -74.0)
 
-rectangle = Geodetic::Areas::Rectangle.new(nw: nw, se: se)
+bbox = Geodetic::Areas::BoundingBox.new(nw: nw, se: se)
 ```
 
 The constructor accepts any coordinate type that responds to `to_lla` -- coordinates are automatically converted to LLA.
@@ -134,7 +154,7 @@ The constructor accepts any coordinate type that responds to `to_lla` -- coordin
 ```ruby
 nw_wm = Geodetic::Coordinate::WebMercator.from_lla(nw)
 se_wm = Geodetic::Coordinate::WebMercator.from_lla(se)
-rectangle = Geodetic::Areas::Rectangle.new(nw: nw_wm, se: se_wm)
+bbox = Geodetic::Areas::BoundingBox.new(nw: nw_wm, se: se_wm)
 ```
 
 Raises `ArgumentError` if the NW corner has a lower latitude than the SE corner, or if the NW corner has a higher longitude than the SE corner.
@@ -152,27 +172,27 @@ All attributes are read-only.
 ### Computed Corners
 
 ```ruby
-rectangle.ne    # => LLA (nw.lat, se.lng)
-rectangle.sw    # => LLA (se.lat, nw.lng)
+bbox.ne    # => LLA (nw.lat, se.lng)
+bbox.sw    # => LLA (se.lat, nw.lng)
 ```
 
 ### Methods
 
 #### `includes?(a_point)` / `include?(a_point)` / `inside?(a_point)`
 
-Returns `true` if the given point falls within (or on the boundary of) the rectangle. Accepts any coordinate type that responds to `to_lla`.
+Returns `true` if the given point falls within (or on the boundary of) the bounding box. Accepts any coordinate type that responds to `to_lla`.
 
 ```ruby
 point = Geodetic::Coordinate::LLA.new(lat: 40.5, lng: -74.5)
-rectangle.includes?(point)  # => true
+bbox.includes?(point)  # => true
 ```
 
 #### `excludes?(a_point)` / `exclude?(a_point)` / `outside?(a_point)`
 
-Returns `true` if the given point falls outside the rectangle.
+Returns `true` if the given point falls outside the bounding box.
 
 ```ruby
-rectangle.excludes?(point)  # => true or false
+bbox.excludes?(point)  # => true or false
 ```
 
 ### Alias Summary
@@ -182,14 +202,120 @@ rectangle.excludes?(point)  # => true or false
 | `includes?` | `include?`, `inside?` |
 | `excludes?` | `exclude?`, `outside?` |
 
-### Integration with GH36
+### Integration with Spatial Hashes
 
-`Geodetic::Coordinate::GH36#to_area` returns a `Rectangle` representing the geohash cell's bounding box:
+Spatial hash coordinate systems (`GH`, `GH36`, `HAM`, `OLC`, `GEOREF`, `GARS`) return a `BoundingBox` from `to_area`:
 
 ```ruby
 gh36 = Geodetic::Coordinate::GH36.new("bdrdC26BqH")
 area = gh36.to_area
-# => Geodetic::Areas::Rectangle
+# => Geodetic::Areas::BoundingBox
 
 area.includes?(gh36.to_lla)  # => true (midpoint is inside the cell)
 ```
+
+---
+
+## Polygon Subclasses
+
+All polygon subclasses inherit from `Polygon` and share its `includes?`/`excludes?`, `segments`, `centroid`, and `boundary` methods. Each adds shape-specific constructors and attributes.
+
+### Geodetic::Areas::Triangle
+
+A three-sided polygon with four construction modes.
+
+#### Constructors
+
+```ruby
+center = Geodetic::Coordinate::LLA.new(lat: 40.7484, lng: -73.9857, alt: 0)
+
+# Isosceles — width and height from a center point
+tri = Geodetic::Areas::Triangle.new(center: center, width: 400, height: 600, bearing: 0)
+
+# Equilateral by circumradius
+tri = Geodetic::Areas::Triangle.new(center: center, radius: 500, bearing: 45)
+
+# Equilateral by side length
+tri = Geodetic::Areas::Triangle.new(center: center, side: 600)
+
+# Arbitrary 3 vertices
+tri = Geodetic::Areas::Triangle.new(vertices: [p1, p2, p3])
+```
+
+#### Attributes and Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `sides` | Integer | Always 3 |
+| `vertices` | Array<LLA> | The three vertices |
+| `center` | LLA | Center point (or centroid for arbitrary vertices) |
+| `width` | Float | Base width in meters (0 for arbitrary vertices) |
+| `height` | Float | Height in meters (0 for arbitrary vertices) |
+| `bearing` | Float | Bearing in degrees (0 for arbitrary vertices) |
+| `base` | Float/nil | Same as width; nil for arbitrary vertices |
+| `side_lengths` | Array<Float> | Three side lengths in meters |
+| `equilateral?` | Boolean | All sides equal (within 5m tolerance) |
+| `isosceles?` | Boolean | Exactly two sides equal |
+| `scalene?` | Boolean | No two sides equal |
+| `to_bounding_box` | BoundingBox | Axis-aligned bounding box enclosing the triangle |
+
+---
+
+### Geodetic::Areas::Rectangle
+
+A four-sided polygon defined by a centerline `Segment` and a perpendicular width. The centerline is the fundamental representation — center, height, and bearing are all derived from it.
+
+#### Constructor
+
+```ruby
+a = Geodetic::Coordinate::LLA.new(lat: 40.7400, lng: -73.9900, alt: 0)
+b = Geodetic::Coordinate::LLA.new(lat: 40.7500, lng: -73.9900, alt: 0)
+
+# From a Segment object
+seg = Geodetic::Segment.new(a, b)
+rect = Geodetic::Areas::Rectangle.new(segment: seg, width: 200)
+
+# From an array of two coordinates
+rect = Geodetic::Areas::Rectangle.new(segment: [a, b], width: 200)
+
+# Width accepts a Distance instance (converted to meters)
+rect = Geodetic::Areas::Rectangle.new(segment: seg, width: seg.distance)
+rect.square?  #=> true
+```
+
+The `segment:` parameter defines the centerline of the rectangle. Height equals the segment length, bearing equals the segment direction, and center equals the segment midpoint. Width is the perpendicular extent, specified in meters or as a `Distance` instance.
+
+#### Attributes and Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `sides` | Integer | Always 4 |
+| `centerline` | Segment | The centerline segment |
+| `width` | Float | Perpendicular width in meters |
+| `center` | LLA | Midpoint of the centerline |
+| `height` | Float | Length of the centerline in meters |
+| `bearing` | Float | Direction of the centerline in degrees |
+| `corners` | Array<LLA> | Four corners: front-left, front-right, back-right, back-left |
+| `square?` | Boolean | True when width equals height |
+| `to_bounding_box` | BoundingBox | Axis-aligned bounding box enclosing the rectangle |
+
+---
+
+### Geodetic::Areas::Pentagon / Hexagon / Octagon
+
+Regular polygons constructed from a center point and circumradius.
+
+```ruby
+center = Geodetic::Coordinate::LLA.new(lat: 40.7484, lng: -73.9857, alt: 0)
+
+pent = Geodetic::Areas::Pentagon.new(center: center, radius: 500, bearing: 0)
+hex  = Geodetic::Areas::Hexagon.new(center: center, radius: 500, bearing: 0)
+oct  = Geodetic::Areas::Octagon.new(center: center, radius: 500, bearing: 0)
+```
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `sides` | Integer | 5, 6, or 8 respectively |
+| `center` | LLA | Center point |
+| `radius` | Float | Circumradius in meters |
+| `bearing` | Float | Rotation bearing in degrees |