geodetic 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f295df82e85611a9a7a7dd56593ae029d6ad096cc5c96021d5b59b4f4b001cc2
-  data.tar.gz: 6da1bc3461fd4f372b53f5458d322f8c14d1feb8a2afa93a2375cb5641674674
+  metadata.gz: f85da37953a9e974422502d62fbf82279fcf4f0ff71594ada2bb150e07cc75d1
+  data.tar.gz: a986282c09df583d9de453034f36e1a15c0d29cc016f586f09239f4f642d6fae
 SHA512:
-  metadata.gz: 1a0b72935abf28bbcb41182f800d1bdb52466530565f13d75fec5f3eec14c0dac7680f8220f09c51cf4d60ed3b87fc53a3675ceb972f1cec17ca06cbd096d717
-  data.tar.gz: 754e5b64d8e1d333dafd270a6e21434d46102ea57e43fbba16b83bcecd9eb69eb4e834a51554c10eb59433f6d434930bf2664fca0d9c22b37cf7378e90cc106e
+  metadata.gz: 2d72a9b0e9e1a0688f25659dbff3d35e8b1c001c72468d2d2bd5c64ffe9fd2f16315dbbe4ec429c545115268e7486db81b26c4f6c9d625de3a8089b82cbcf8df
+  data.tar.gz: 031eb9604c27d9683c74bf3483b913a5ddb065ed78bd5375f23297f39b923f5a6212498c236982a310afe25fa5ca300df0dfaaa60d8632ad02950c75c2662e15

data/CHANGELOG.md

@@ -11,6 +11,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [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 +58,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,7 +18,8 @@
 - <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>Validated Setters</strong> - Type coercion and range validation on all coordinate attributes<br>
@@ -426,7 +427,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 +454,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 +481,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 +508,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 +533,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 +609,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

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 |

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