geodetic 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13b2b50f8ff03c2093abf1a2454f3db38942f9c32918eb23aab30b6c45a4146b
-  data.tar.gz: 2b3d5a7f325e2766196d2997e9c1781f0425abe016edeeb2fe4f155fc6a43f13
+  metadata.gz: f85da37953a9e974422502d62fbf82279fcf4f0ff71594ada2bb150e07cc75d1
+  data.tar.gz: a986282c09df583d9de453034f36e1a15c0d29cc016f586f09239f4f642d6fae
 SHA512:
-  metadata.gz: 1d0378c9df0e04f9bb3de688303abae35857c4fbc594a26094a983417baa55004ef7f7f4cef7c8db7511b8fc769d0a368420e7601cb04e12eaf887b324e51e61
-  data.tar.gz: c20dd6fa952579d8d035e1afd146d7337caa087efd71df4db17dcc3918b8cb4c561237f1cb5820167d9f84a64209da48a1dd38d0b46a5bccf0e3ce6959aa06d3
+  metadata.gz: 2d72a9b0e9e1a0688f25659dbff3d35e8b1c001c72468d2d2bd5c64ffe9fd2f16315dbbe4ec429c545115268e7486db81b26c4f6c9d625de3a8089b82cbcf8df
+  data.tar.gz: 031eb9604c27d9683c74bf3483b913a5ddb065ed78bd5375f23297f39b923f5a6212498c236982a310afe25fa5ca300df0dfaaa60d8632ad02950c75c2662e15

data/CHANGELOG.md

@@ -11,6 +11,72 @@ 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
+
+- **`Geodetic::Path` class** — directed, ordered sequence of unique coordinates for modeling routes, trails, and boundaries
+  - **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-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::BoundingBox`
+  - **Polygon conversion**: `to_polygon` closes the path (validates no self-intersection)
+  - **Intersection**: `intersects?(other_path)` detects crossing segments
+  - **Equality**: `==` compares coordinates in order
+  - **Enumerable**: includes `Enumerable` via `each` — supports `map`, `select`, `any?`, `to_a`, etc.
+  - **Non-mutating operators**: `+` and `-` accept both coordinates and paths
+  - **Mutating operators**: `<<`, `>>`, `prepend`, `insert(after:/before:)`, `delete`/`remove` — all accept paths as well as coordinates
+- **Path operations example** (`examples/06_path_operations.rb`) — 19-section demo covering all Path capabilities with a Manhattan walking route
+- Documentation: `docs/reference/path.md` (Path reference)
+
+### Changed
+
+- Updated `Geodetic::Feature` to support Path as a geometry type — delegates `distance_to` and `bearing_to` using geometric projection
+- Updated README, `docs/index.md`, `docs/reference/feature.md`, `examples/README.md`, and mkdocs nav to include Path class
+
 ## [0.3.1] - 2026-03-09
 
 ### Added

data/README.md

@@ -18,7 +18,9 @@
 - <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>
 - <strong>Serialization</strong> - to_s(precision), to_a, from_string, from_array, DMS format<br>
@@ -425,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
@@ -452,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
@@ -479,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
@@ -506,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
@@ -531,19 +533,95 @@ 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.
+
+```ruby
+route = Path.new(coordinates: [battery_park, wall_street, brooklyn_bridge, city_hall])
+
+# Navigation
+route.first                      # => starting waypoint
+route.next(wall_street)          # => brooklyn_bridge
+route.total_distance.to_km       # => "3.42 km"
+
+# Build incrementally
+trail = Path.new
+trail << start << middle << finish
+trail >> new_start               # prepend
+
+# Combine paths
+combined = downtown + uptown     # concatenate
+trimmed  = combined - detour     # remove coordinates
+
+# Closest approach (geometric projection, not just waypoints)
+route.closest_coordinate_to(off_path_point)
+route.distance_to(target)
+route.closest_points_to(other_path)  # path-to-path
+
+# Spatial operations
+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::BoundingBox
+route.to_polygon                 # close into polygon
+route.intersects?(other_path)    # crossing detection
+route.contains?(point)           # on-segment check
+
+# Enumerable
+route.map { |c| c.lat }
+route.select { |c| c.lat > 40.72 }
+```
+
 ### Features
 
-`Feature` wraps a geometry (any coordinate or area) with a label and a metadata hash. It delegates `distance_to` and `bearing_to` to its geometry, using the centroid for area geometries.
+`Feature` wraps a geometry (any coordinate, area, or path) with a label and a metadata hash. It delegates `distance_to` and `bearing_to` to its geometry, using the centroid for area geometries.
 
 ```ruby
 liberty = Feature.new(
@@ -600,6 +678,7 @@ The [`examples/`](examples/) directory contains runnable demo scripts showing pr
 | [`03_distance_calculations.rb`](examples/03_distance_calculations.rb) | Distance class features, unit conversions, and arithmetic |
 | [`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 |
 
 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,9 @@
 <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>
 <li><strong>Serialization</strong> - to_s(precision), to_a, from_string, from_array, DMS format<br>
@@ -56,8 +58,10 @@ 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.
-- **Features** -- `Geodetic::Feature` wraps any coordinate or area with a label and metadata hash, delegating `distance_to` and `bearing_to` to the underlying geometry.
+- **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.
 
 ## Design Principles
 

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 or any area class (`Circle`, `Polygon`, `Rectangle`). 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,9 +35,10 @@ 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 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.
 
 ---