geodetic 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13b2b50f8ff03c2093abf1a2454f3db38942f9c32918eb23aab30b6c45a4146b
-  data.tar.gz: 2b3d5a7f325e2766196d2997e9c1781f0425abe016edeeb2fe4f155fc6a43f13
+  metadata.gz: f295df82e85611a9a7a7dd56593ae029d6ad096cc5c96021d5b59b4f4b001cc2
+  data.tar.gz: 6da1bc3461fd4f372b53f5458d322f8c14d1feb8a2afa93a2375cb5641674674
 SHA512:
-  metadata.gz: 1d0378c9df0e04f9bb3de688303abae35857c4fbc594a26094a983417baa55004ef7f7f4cef7c8db7511b8fc769d0a368420e7601cb04e12eaf887b324e51e61
-  data.tar.gz: c20dd6fa952579d8d035e1afd146d7337caa087efd71df4db17dcc3918b8cb4c561237f1cb5820167d9f84a64209da48a1dd38d0b46a5bccf0e3ce6959aa06d3
+  metadata.gz: 1a0b72935abf28bbcb41182f800d1bdb52466530565f13d75fec5f3eec14c0dac7680f8220f09c51cf4d60ed3b87fc53a3675ceb972f1cec17ca06cbd096d717
+  data.tar.gz: 754e5b64d8e1d333dafd270a6e21434d46102ea57e43fbba16b83bcecd9eb69eb4e834a51554c10eb59433f6d434930bf2664fca0d9c22b37cf7378e90cc106e

data/CHANGELOG.md

@@ -11,6 +11,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [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-Rectangle, 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`
+  - **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

@@ -19,6 +19,7 @@
 - <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>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>
@@ -541,9 +542,49 @@ rect.sw             # => computed SW corner
 rect.includes?(point)  # => true/false
 ```
 
+### 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::Rectangle
+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 +641,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/index.md

@@ -15,6 +15,7 @@
 <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>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>
@@ -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.
-- **Features** -- `Geodetic::Feature` wraps any coordinate or area with a label and metadata hash, delegating `distance_to` and `bearing_to` to the underlying geometry.
+- **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/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`, `Rectangle`), or a `Path`. The `metadata` hash is optional and defaults to `{}`.
 
 ---
 
@@ -36,8 +36,9 @@ 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`
+- **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.
 
 ---
 

data/docs/reference/path.md

@@ -0,0 +1,269 @@
+# Path Reference
+
+`Geodetic::Path` represents a directed, ordered sequence of unique coordinates. It models routes, trails, boundaries, and any linear geographic feature where the order of waypoints matters.
+
+A Path has a start (first coordinate) and an end (last coordinate). No duplicate coordinates are allowed — each waypoint appears exactly once, enabling unambiguous navigation with `next` and `prev`.
+
+Path includes Ruby's `Enumerable` module, so all standard iteration methods (`map`, `select`, `any?`, `to_a`, etc.) are available.
+
+---
+
+## Constructor
+
+```ruby
+# Empty path
+path = Path.new
+
+# From an array of coordinates
+path = Path.new(coordinates: [a, b, c, d])
+```
+
+Raises `ArgumentError` if any coordinate appears more than once.
+
+---
+
+## Attributes
+
+| Attribute     | Type  | Description |
+|---------------|-------|-------------|
+| `coordinates` | Array | The ordered list of waypoints (read-only) |
+
+---
+
+## Navigation
+
+| Method              | Returns     | Description |
+|---------------------|-------------|-------------|
+| `first`             | Coordinate  | Starting waypoint |
+| `last`              | Coordinate  | Ending waypoint |
+| `next(coordinate)`  | Coordinate  | Waypoint after the given one, or `nil` at end |
+| `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], ...]` |
+
+---
+
+## Membership
+
+| Method | Description |
+|--------|-------------|
+| `include?(coord)` | True if the coordinate is a waypoint in the path |
+| `includes?(coord)` | Alias for `include?` |
+| `contains?(coord, tolerance: 10.0)` | True if the coordinate lies on any segment within tolerance (meters) |
+| `inside?(coord, tolerance: 10.0)` | Alias for `contains?` |
+| `excludes?(coord, tolerance: 10.0)` | Opposite of `contains?` |
+| `exclude?(coord)` | Alias for `excludes?` |
+| `outside?(coord)` | Alias for `excludes?` |
+
+`includes?` checks waypoints only. `contains?` checks whether a coordinate lies on the line between any two consecutive waypoints, using a bearing comparison with a tolerance derived from the segment length.
+
+---
+
+## Equality
+
+```ruby
+path1 == path2
+```
+
+Two paths are equal if they have the same coordinates in the same order.
+
+---
+
+## Spatial Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `nearest_waypoint(target)` | Coordinate | The waypoint closest to the target |
+| `closest_coordinate_to(target)` | Coordinate | The closest point on the path (projected onto segments) |
+| `distance_to(other)` | Distance | Distance from the closest point on the path to the target |
+| `bearing_to(other)` | Bearing | Bearing from the closest point on the path to the target |
+| `closest_points_to(other)` | Hash | Closest pair between path and an Area or another Path |
+
+The `other` parameter for `distance_to`, `bearing_to`, and `closest_coordinate_to` can be a coordinate, a Feature, an Area, or another Path.
+
+### Closest Points
+
+`closest_points_to` returns a hash with:
+
+```ruby
+{
+  path_point: Coordinate,  # closest point on this path
+  area_point: Coordinate,  # closest point on the other geometry
+  distance:   Distance     # distance between the two points
+}
+```
+
+Accepts `Areas::Circle`, `Areas::Polygon`, `Areas::Rectangle`, or another `Path`.
+
+---
+
+## Computed Properties
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `total_distance` | Distance | Sum of all segment distances |
+| `segment_distances` | Array | Distance for each segment |
+| `segment_bearings` | Array | Bearing for each segment |
+| `reverse` | Path | New path with coordinates in reverse order |
+
+---
+
+## Subpath and Split
+
+### `between(from, to)`
+
+Extracts a subpath between two waypoints (inclusive). Both must exist in the path, and `from` must precede `to`.
+
+```ruby
+sub = route.between(wall_street, union_square)
+```
+
+### `split_at(coordinate)`
+
+Splits the path at a waypoint, returning two paths that share the split point.
+
+```ruby
+left, right = route.split_at(city_hall)
+# left ends with city_hall, right starts with city_hall
+```
+
+---
+
+## Interpolation
+
+### `at_distance(distance)`
+
+Returns the coordinate at a given distance along the path from the start. Accepts a `Distance` object or a numeric value in meters.
+
+```ruby
+halfway = route.at_distance(route.total_distance.meters / 2.0)
+quarter = route.at_distance(Distance.new(route.total_distance.meters * 0.25))
+```
+
+Returns the last coordinate if the distance exceeds the total path length.
+
+---
+
+## Bounding Box
+
+### `bounds`
+
+Returns an `Areas::Rectangle` representing the axis-aligned bounding box of all waypoints.
+
+```ruby
+bbox = route.bounds
+bbox.nw  # => northwest corner
+bbox.se  # => southeast corner
+bbox.includes?(some_point)  # => true/false
+```
+
+---
+
+## To Polygon
+
+### `to_polygon`
+
+Closes the path into an `Areas::Polygon` by connecting the last coordinate to the first. Requires at least 3 coordinates. Raises `ArgumentError` if the closing segment would intersect any interior segment of the path.
+
+```ruby
+triangle = Path.new(coordinates: [a, b, c])
+poly = triangle.to_polygon
+poly.includes?(some_point)
+```
+
+---
+
+## Intersection
+
+### `intersects?(other_path)`
+
+Returns true if any segment of this path crosses any segment of the other path. Uses orientation-based intersection testing.
+
+```ruby
+route.intersects?(crosstown)  # => true/false
+```
+
+---
+
+## Non-Mutating Operators
+
+These return new Path objects; the original is unchanged.
+
+| Operator | Accepts | Description |
+|----------|---------|-------------|
+| `+ coordinate` | Coordinate | New path with coordinate appended |
+| `+ path` | Path | New path with all coordinates of the other path appended |
+| `- coordinate` | Coordinate | New path with coordinate removed |
+| `- path` | Path | New path with all of the other path's coordinates removed |
+
+```ruby
+combined = downtown_path + uptown_path
+trimmed  = full_route - detour_path
+```
+
+Raises `ArgumentError` if `+` would create duplicates, or if `-` references coordinates not in the path.
+
+---
+
+## Mutating Operators
+
+These modify the path in place and return `self` for chaining.
+
+| Method | Accepts | Description |
+|--------|---------|-------------|
+| `<< other` | Coordinate or Path | Append to end |
+| `>> other` | Coordinate or Path | Prepend to start |
+| `prepend(other)` | Coordinate or Path | Same as `>>` |
+| `insert(coord, after: ref)` | Coordinate | Insert after a reference waypoint |
+| `insert(coord, before: ref)` | Coordinate | Insert before a reference waypoint |
+| `delete(coord)` | Coordinate | Remove a waypoint |
+| `remove(coord)` | Coordinate | Alias for `delete` |
+
+```ruby
+path = Path.new
+path << a << b << c          # build incrementally
+path >> start_point           # prepend
+path << other_path            # append an entire path
+path.insert(detour, after: b) # insert between waypoints
+path.delete(b)                # remove a waypoint
+```
+
+---
+
+## Enumerable
+
+Path includes `Enumerable`. The `each` method iterates over coordinates in order.
+
+```ruby
+route.map { |c| c.lat }
+route.select { |c| c.lat > 40.72 }
+route.max_by { |c| c.lat }
+route.to_a
+```
+
+---
+
+## Display
+
+| Method | Returns |
+|--------|---------|
+| `to_s` | `"Path(7): 40.70... -> 40.71... -> ..."` |
+| `inspect` | `"#<Geodetic::Path size=7 first=... last=...>"` |
+
+---
+
+## Feature Integration
+
+A Path can be used as the geometry of a `Feature`. When a Feature wraps a Path, `distance_to` and `bearing_to` use the Path's geometric projection to find the closest approach point.
+
+```ruby
+hiking_route = Feature.new(
+  label:    "Manhattan Walking Tour",
+  geometry: route,
+  metadata: { type: "walking" }
+)
+
+hiking_route.distance_to(statue_of_liberty).to_km
+hiking_route.bearing_to(statue_of_liberty).to_compass
+```