geodetic 0.5.0 → 0.5.2

data/docs/reference/conversions.md

@@ -250,7 +250,7 @@ portland = Geodetic::Coordinate::LLA.new(lat: 45.5152, lng: -122.6784, alt: 0.0)
 sf = Geodetic::Coordinate::LLA.new(lat: 37.7749, lng: -122.4194, alt: 0.0)
 
 # Radial distances from receiver
-seattle.distance_to(portland)          # => Distance (235393.17 m)
+seattle.distance_to(portland)          # => Distance (235385.71 m)
 seattle.distance_to(portland, sf)      # => [Distance, Distance] (Array)
 
 # Consecutive chain distances
@@ -274,7 +274,7 @@ Both `distance_to` and `straight_line_distance_to` accept any coordinate type. C
 ```ruby
 utm = seattle.to_utm
 mgrs = Geodetic::Coordinate::MGRS.from_lla(portland)
-utm.distance_to(mgrs)    # => Distance (235393.17 m)
+utm.distance_to(mgrs)    # => Distance (235385.71 m)
 ```
 
 ### ENU and NED (Relative Systems)
@@ -308,7 +308,7 @@ sf = Geodetic::Coordinate::LLA.new(lat: 37.7749, lng: -122.4194, alt: 0.0)
 
 # Forward azimuth
 b = seattle.bearing_to(portland)       # => Bearing
-b.degrees                              # => 188.2...
+b.degrees                              # => 186.25...
 b.to_compass(points: 8)               # => "S"
 b.reverse                             # => Bearing (back azimuth)
 

data/docs/reference/feature.md

@@ -65,7 +65,7 @@ liberty.distance_to(LLA.new(lat: 40.7484, lng: -73.9857, alt: 0))
 Returns a `Geodetic::Bearing` from this feature to another feature, coordinate, or area. Uses the same centroid resolution as `distance_to`.
 
 ```ruby
-liberty.bearing_to(empire).degrees      # => 36.99
+liberty.bearing_to(empire).degrees      # => 36.95
 liberty.bearing_to(empire).to_compass   # => "NE"
 ```
 

data/docs/reference/geojson.md

@@ -0,0 +1,388 @@
+# GeoJSON Export Reference
+
+`Geodetic::GeoJSON` builds a [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) FeatureCollection from any combination of Geodetic objects. It provides an accumulator pattern for collecting geometry, then exporting as a Hash, JSON string, or file.
+
+Every geometry type also gains a `to_geojson` instance method that returns a GeoJSON-compatible Ruby Hash.
+
+---
+
+## GeoJSON Class
+
+### Constructor
+
+```ruby
+gj = Geodetic::GeoJSON.new                       # empty collection
+gj = Geodetic::GeoJSON.new(seattle, portland)     # initialize with objects
+gj = Geodetic::GeoJSON.new([seattle, portland])   # also accepts an array
+```
+
+### Accumulating Objects
+
+Use `<<` to add a single object or an array of objects. Returns `self` for chaining.
+
+```ruby
+gj = Geodetic::GeoJSON.new
+
+gj << seattle                          # single coordinate
+gj << [portland, sf, la]               # array of coordinates
+gj << Geodetic::Segment.new(a, b)     # segment
+gj << route                           # path
+gj << polygon                         # area
+gj << circle                          # circle (approximated)
+gj << bbox                            # bounding box
+gj << feature                         # feature (preserves properties)
+```
+
+Any Geodetic object with a `to_geojson` method can be added. Non-Feature objects are auto-wrapped as GeoJSON Features with empty `properties`. Feature objects carry their `label` and `metadata` into the GeoJSON output.
+
+### Query
+
+| Method   | Returns | Description |
+|----------|---------|-------------|
+| `size`   | Integer | Number of collected objects |
+| `length` | Integer | Alias for `size` |
+| `empty?` | Boolean | True if no objects collected |
+| `each`   | Enumerator | Iterate over collected objects |
+
+`GeoJSON` includes `Enumerable`, so `map`, `select`, `reject`, `count`, `to_a`, and all other Enumerable methods are available.
+
+```ruby
+gj.size                      # => 5
+gj.empty?                    # => false
+gj.map { |obj| obj.class }  # => [LLA, LLA, Path, ...]
+```
+
+### Removing Objects
+
+| Method        | Description |
+|---------------|-------------|
+| `delete(obj)` | Remove a specific object from the collection |
+| `clear`       | Remove all objects |
+
+Both return `self` for chaining.
+
+```ruby
+gj.delete(portland)
+gj.clear
+```
+
+### Export
+
+| Method                     | Returns | Description |
+|----------------------------|---------|-------------|
+| `to_h`                     | Hash    | GeoJSON FeatureCollection as a Ruby Hash |
+| `to_json`                  | String  | Compact JSON string |
+| `to_json(pretty: true)`    | String  | Pretty-printed JSON string |
+| `save(path)`               | nil     | Write compact JSON to file |
+| `save(path, pretty: true)` | nil     | Write pretty-printed JSON to file |
+
+```ruby
+gj.to_h
+# => {"type" => "FeatureCollection", "features" => [...]}
+
+gj.to_json
+# => '{"type":"FeatureCollection","features":[...]}'
+
+gj.to_json(pretty: true)
+# => formatted JSON with indentation
+
+gj.save("my_map.geojson")
+gj.save("my_map.geojson", pretty: true)
+```
+
+The `to_json` and `save` methods use Ruby's built-in `json` library (a default gem, always available). No external dependencies are required.
+
+### Display
+
+```ruby
+gj.to_s     # => "GeoJSON::FeatureCollection(5 features)"
+gj.inspect  # => "#<Geodetic::GeoJSON size=5>"
+```
+
+### Import
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `GeoJSON.load(path)` | Array | Read a GeoJSON file and return an Array of Geodetic objects |
+| `GeoJSON.parse(hash)` | Array | Parse a GeoJSON Hash and return an Array of Geodetic objects |
+
+```ruby
+objects = Geodetic::GeoJSON.load("west_coast.geojson")
+# => [Feature("Seattle", LLA), Feature("Portland", LLA), Segment, Polygon, ...]
+```
+
+`parse` accepts a Ruby Hash (useful when you already have parsed JSON):
+
+```ruby
+data = JSON.parse(File.read("west_coast.geojson"))
+objects = Geodetic::GeoJSON.parse(data)
+```
+
+**GeoJSON → Geodetic type mapping:**
+
+| GeoJSON type | Geodetic type |
+|--------------|---------------|
+| Point | `Coordinate::LLA` |
+| LineString (2 points) | `Segment` |
+| LineString (3+ points) | `Path` |
+| Polygon | `Areas::Polygon` (outer ring only; holes are dropped) |
+| MultiPoint | Multiple `Coordinate::LLA` |
+| MultiLineString | Multiple `Segment` or `Path` |
+| MultiPolygon | Multiple `Areas::Polygon` |
+| GeometryCollection | Flattened into individual geometries |
+
+**Feature handling:**
+
+- A GeoJSON Feature with a `"name"` property or any non-empty properties becomes a `Geodetic::Feature`. The `"name"` property maps to `label`, and remaining properties become `metadata` with symbol keys.
+- A GeoJSON Feature with empty properties (`{}`) returns the raw geometry with no Feature wrapper.
+
+This means a save/load roundtrip preserves Feature labels, metadata, and geometry types:
+
+```ruby
+# Save
+gj = Geodetic::GeoJSON.new
+gj << Geodetic::Feature.new(label: "Seattle", geometry: seattle, metadata: { state: "WA" })
+gj << portland  # raw coordinate, no Feature
+gj.save("cities.geojson")
+
+# Load
+objects = Geodetic::GeoJSON.load("cities.geojson")
+objects[0]          # => Feature (label: "Seattle", metadata: {state: "WA"})
+objects[0].label    # => "Seattle"
+objects[0].metadata # => {state: "WA"}
+objects[1]          # => LLA (raw coordinate, no Feature wrapper)
+```
+
+---
+
+## Geometry Mapping
+
+Each Geodetic geometry type maps to a specific GeoJSON geometry type:
+
+| Geodetic Type | GeoJSON Type | Notes |
+|---------------|-------------|-------|
+| Any coordinate (LLA, UTM, ECEF, ...) | Point | Converts through LLA |
+| `Segment` | LineString | 2 positions |
+| `Path` | LineString | N positions (default) |
+| `Path` (with `as: :polygon`) | Polygon | Auto-closes the ring |
+| `Areas::Polygon` (and subclasses) | Polygon | Boundary ring already closed |
+| `Areas::Circle` | Polygon | Approximated as N-gon (default 32) |
+| `Areas::BoundingBox` | Polygon | 4 corners, closed |
+| `Feature` | Feature | Geometry + properties |
+
+---
+
+## Individual `to_geojson` Methods
+
+### Coordinates
+
+All 18 coordinate classes gain a `to_geojson` method. It converts the coordinate to LLA and returns a GeoJSON Point.
+
+```ruby
+seattle = Geodetic::Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
+seattle.to_geojson
+# => {"type" => "Point", "coordinates" => [-122.3493, 47.6205]}
+```
+
+**Altitude handling:** The GeoJSON position array is `[lng, lat]` when altitude is zero, and `[lng, lat, alt]` when altitude is non-zero.
+
+```ruby
+Geodetic::Coordinate::LLA.new(lat: 47.62, lng: -122.35, alt: 184.0).to_geojson
+# => {"type" => "Point", "coordinates" => [-122.35, 47.62, 184.0]}
+```
+
+**Cross-system:** Any coordinate type works — UTM, ECEF, MGRS, GH, etc. are converted to LLA internally.
+
+```ruby
+seattle.to_utm.to_geojson       # => {"type" => "Point", ...}
+seattle.to_mgrs.to_geojson      # => {"type" => "Point", ...}
+```
+
+**ENU and NED:** These are relative coordinate systems with no absolute position. Calling `to_geojson` raises `ArgumentError` with a message explaining that conversion to an absolute system is required first.
+
+```ruby
+enu = Geodetic::Coordinate::ENU.new(e: 100, n: 200, u: 10)
+enu.to_geojson  # => ArgumentError
+```
+
+---
+
+### Segment
+
+Returns a GeoJSON LineString with two positions.
+
+```ruby
+seg = Geodetic::Segment.new(seattle, portland)
+seg.to_geojson
+# => {"type" => "LineString", "coordinates" => [[-122.3493, 47.6205], [-122.6784, 45.5152]]}
+```
+
+---
+
+### Path
+
+Returns a GeoJSON LineString by default. Requires at least 2 coordinates.
+
+```ruby
+route = Geodetic::Path.new(coordinates: [seattle, portland, sf])
+route.to_geojson
+# => {"type" => "LineString", "coordinates" => [[...], [...], [...]]}
+```
+
+**As polygon:** Pass `as: :polygon` to export as a closed GeoJSON Polygon. Requires at least 3 coordinates. The ring is auto-closed if the first and last coordinates differ.
+
+```ruby
+route.to_geojson(as: :polygon)
+# => {"type" => "Polygon", "coordinates" => [[[...], [...], [...], [...]]]}
+```
+
+**Edge cases:**
+
+| Condition | Behavior |
+|-----------|----------|
+| Empty path | Raises `ArgumentError` |
+| 1 coordinate (line_string) | Raises `ArgumentError` |
+| 2 coordinates (polygon) | Raises `ArgumentError` |
+
+---
+
+### Areas::Polygon
+
+Returns a GeoJSON Polygon. The boundary ring is already closed by `Polygon#initialize`.
+
+```ruby
+poly = Geodetic::Areas::Polygon.new(boundary: [a, b, c])
+poly.to_geojson
+# => {"type" => "Polygon", "coordinates" => [[[...], [...], [...], [...]]]}
+```
+
+All Polygon subclasses (`Triangle`, `Rectangle`, `Pentagon`, `Hexagon`, `Octagon`) inherit this method.
+
+---
+
+### Areas::Circle
+
+Returns a GeoJSON Polygon approximating the circle as a regular N-gon. Default is 32 segments.
+
+```ruby
+circle = Geodetic::Areas::Circle.new(centroid: seattle, radius: 10_000)
+
+circle.to_geojson                # => 32-gon (33 positions including closing)
+circle.to_geojson(segments: 64)  # => 64-gon (65 positions including closing)
+circle.to_geojson(segments: 8)   # => 8-gon (9 positions including closing)
+```
+
+The vertices are computed using `Geodetic::Vector#destination_from` (Vincenty direct), so the approximation is geodetically accurate.
+
+---
+
+### Areas::BoundingBox
+
+Returns a GeoJSON Polygon with 4 corners plus the closing point (5 positions total). Ring order follows the GeoJSON right-hand rule: NW → NE → SE → SW → NW.
+
+```ruby
+bbox = Geodetic::Areas::BoundingBox.new(
+  nw: Geodetic::Coordinate::LLA.new(lat: 48.0, lng: -123.0, alt: 0),
+  se: Geodetic::Coordinate::LLA.new(lat: 46.0, lng: -121.0, alt: 0)
+)
+bbox.to_geojson
+# => {"type" => "Polygon", "coordinates" => [[[-123.0, 48.0], [-121.0, 48.0], [-121.0, 46.0], [-123.0, 46.0], [-123.0, 48.0]]]}
+```
+
+---
+
+### Feature
+
+Returns a GeoJSON Feature. The `label` is mapped to the `"name"` property. The `metadata` hash is merged into `properties` with keys converted to strings.
+
+```ruby
+f = Geodetic::Feature.new(
+  label: "Seattle",
+  geometry: seattle,
+  metadata: { state: "WA", population: 750_000 }
+)
+f.to_geojson
+# => {
+#   "type" => "Feature",
+#   "geometry" => {"type" => "Point", "coordinates" => [-122.3493, 47.6205]},
+#   "properties" => {"name" => "Seattle", "state" => "WA", "population" => 750000}
+# }
+```
+
+| Feature field | GeoJSON mapping |
+|---------------|-----------------|
+| `label`       | `properties["name"]` (omitted if `nil`) |
+| `metadata`    | Merged into `properties` (symbol keys stringified) |
+| `geometry`    | Delegates to the geometry's `to_geojson` |
+
+The geometry can be any type: coordinate, segment, path, polygon, circle, or bounding box.
+
+```ruby
+# Feature wrapping a Path
+route_feature = Geodetic::Feature.new(
+  label: "West Coast Route",
+  geometry: route,
+  metadata: { mode: "driving" }
+)
+route_feature.to_geojson
+# => {"type" => "Feature", "geometry" => {"type" => "LineString", ...}, "properties" => {...}}
+```
+
+---
+
+## Complete Example
+
+```ruby
+require "geodetic"
+
+seattle  = Geodetic::Coordinate::LLA.new(lat: 47.6205, lng: -122.3493, alt: 0)
+portland = Geodetic::Coordinate::LLA.new(lat: 45.5152, lng: -122.6784, alt: 0)
+sf       = Geodetic::Coordinate::LLA.new(lat: 37.7749, lng: -122.4194, alt: 0)
+
+# Build a collection
+gj = Geodetic::GeoJSON.new
+
+# Add cities as features with metadata
+gj << Geodetic::Feature.new(label: "Seattle", geometry: seattle, metadata: { pop: 750_000 })
+gj << Geodetic::Feature.new(label: "Portland", geometry: portland, metadata: { pop: 650_000 })
+gj << Geodetic::Feature.new(label: "San Francisco", geometry: sf, metadata: { pop: 870_000 })
+
+# Add the route connecting them
+route = Geodetic::Path.new(coordinates: [seattle, portland, sf])
+gj << Geodetic::Feature.new(label: "West Coast Route", geometry: route)
+
+# Add a 50km radius around Seattle
+gj << Geodetic::Feature.new(
+  label: "Seattle Metro",
+  geometry: Geodetic::Areas::Circle.new(centroid: seattle, radius: 50_000)
+)
+
+# Export
+gj.save("west_coast.geojson", pretty: true)
+```
+
+The output file can be opened directly in [geojson.io](https://geojson.io), QGIS, Mapbox, Leaflet, or any other GeoJSON-compatible tool.
+
+---
+
+## GeoJSON Specification Notes
+
+- **Coordinate order** is `[longitude, latitude]` (not `[lat, lng]`), per [RFC 7946 Section 3.1.1](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.1).
+- **Altitude** is optional. Included as the third element when non-zero.
+- **Polygon rings** follow the right-hand rule: exterior rings are counterclockwise. BoundingBox uses NW → NE → SE → SW → NW.
+- **String keys** are used throughout (`"type"`, `"coordinates"`, `"properties"`, etc.) per JSON convention.
+
+---
+
+## Visualizing GeoJSON
+
+The easiest way to verify your exported GeoJSON is [geojson.io](https://geojson.io). It renders points, lines, and polygons on an interactive map with property inspection.
+
+To use it:
+
+1. Export your collection: `gj.save("my_map.geojson", pretty: true)`
+2. Open [geojson.io](https://geojson.io) in a browser
+3. Drag and drop the `.geojson` file onto the map, or paste the JSON into the editor panel
+
+Feature properties (name, metadata) appear in popups when you click on a rendered geometry. This makes it a quick way to confirm that coordinates, shapes, and metadata are correct before integrating with QGIS, Mapbox, Leaflet, or other GIS tools.
+- Output is a Ruby Hash. Call `.to_json` or `JSON.generate(hash)` to produce a JSON string.

data/examples/09_geojson_export.rb

@@ -0,0 +1,255 @@
+#!/usr/bin/env ruby
+
+# Demonstration of GeoJSON Export
+# Shows how to build a GeoJSON FeatureCollection from mixed Geodetic objects
+# and save it to a file that can be opened in any GeoJSON viewer.
+
+require_relative "../lib/geodetic"
+
+include Geodetic
+
+LLA      = Coordinate::LLA
+Distance = Geodetic::Distance
+Vector   = Geodetic::Vector
+
+puts "=== GeoJSON Export Demo ==="
+puts
+
+# ── 1. Individual to_geojson on each geometry type ─────────────────
+
+puts "--- 1. Coordinate → GeoJSON Point ---"
+puts
+
+seattle = LLA.new(lat: 47.6205, lng: -122.3493, alt: 0.0)
+puts "  seattle.to_geojson"
+puts "  => #{seattle.to_geojson}"
+puts
+
+# Works from any coordinate system — converts through LLA
+utm = seattle.to_utm
+puts "  seattle.to_utm.to_geojson"
+puts "  => #{utm.to_geojson}"
+puts
+
+# Altitude included when non-zero
+space_needle = LLA.new(lat: 47.6205, lng: -122.3493, alt: 184.0)
+puts "  With altitude: #{space_needle.to_geojson}"
+puts
+
+# ── 2. Segment → LineString ───────────────────────────────────────
+
+puts "--- 2. Segment → GeoJSON LineString ---"
+puts
+
+portland = LLA.new(lat: 45.5152, lng: -122.6784, alt: 0.0)
+seg = Segment.new(seattle, portland)
+puts "  Segment(seattle → portland).to_geojson"
+puts "  => #{seg.to_geojson}"
+puts
+
+# ── 3. Path → LineString or Polygon ───────────────────────────────
+
+puts "--- 3. Path → GeoJSON LineString ---"
+puts
+
+sf = LLA.new(lat: 37.7749, lng: -122.4194, alt: 0.0)
+la = LLA.new(lat: 34.0522, lng: -118.2437, alt: 0.0)
+route = Path.new(coordinates: [seattle, portland, sf, la])
+
+geojson = route.to_geojson
+puts "  Path(4 waypoints).to_geojson"
+puts "  type: #{geojson["type"]}, points: #{geojson["coordinates"].length}"
+puts
+
+# Path can also export as a polygon
+triangle_path = Path.new(coordinates: [
+  LLA.new(lat: 47.0, lng: -122.5, alt: 0),
+  LLA.new(lat: 46.0, lng: -121.0, alt: 0),
+  LLA.new(lat: 46.0, lng: -123.0, alt: 0)
+])
+poly_geojson = triangle_path.to_geojson(as: :polygon)
+puts "  Path(3 points).to_geojson(as: :polygon)"
+puts "  type: #{poly_geojson["type"]}, ring closed: #{poly_geojson["coordinates"][0].first == poly_geojson["coordinates"][0].last}"
+puts
+
+# ── 4. Areas → Polygon ────────────────────────────────────────────
+
+puts "--- 4. Areas → GeoJSON Polygon ---"
+puts
+
+# Polygon
+a = LLA.new(lat: 47.7, lng: -122.5, alt: 0)
+b = LLA.new(lat: 47.5, lng: -122.1, alt: 0)
+c = LLA.new(lat: 47.3, lng: -122.4, alt: 0)
+poly = Areas::Polygon.new(boundary: [a, b, c])
+puts "  Polygon(3 vertices).to_geojson"
+puts "  type: #{poly.to_geojson["type"]}"
+
+# Circle (approximated as 32-gon)
+circle = Areas::Circle.new(centroid: seattle, radius: 10_000)
+circle_gj = circle.to_geojson
+ring_size = circle_gj["coordinates"][0].length
+puts "  Circle(10km).to_geojson → #{ring_size - 1}-gon (#{ring_size} points including closing)"
+
+# Circle with custom resolution
+circle_gj_64 = circle.to_geojson(segments: 64)
+puts "  Circle(10km).to_geojson(segments: 64) → #{circle_gj_64["coordinates"][0].length - 1}-gon"
+
+# BoundingBox
+bbox = Areas::BoundingBox.new(
+  nw: LLA.new(lat: 48.0, lng: -123.0, alt: 0),
+  se: LLA.new(lat: 46.0, lng: -121.0, alt: 0)
+)
+puts "  BoundingBox.to_geojson → #{bbox.to_geojson["coordinates"][0].length} points (4 corners + closing)"
+puts
+
+# ── 5. Feature → GeoJSON Feature with properties ──────────────────
+
+puts "--- 5. Feature → GeoJSON Feature ---"
+puts
+
+city = Feature.new(
+  label: "Seattle",
+  geometry: seattle,
+  metadata: { state: "WA", population: 750_000, timezone: "PST" }
+)
+feature_gj = city.to_geojson
+puts "  Feature('Seattle').to_geojson"
+puts "  type:       #{feature_gj["type"]}"
+puts "  geometry:   #{feature_gj["geometry"]["type"]}"
+puts "  properties: #{feature_gj["properties"]}"
+puts
+
+# Feature wrapping a polygon
+park = Feature.new(
+  label: "Triangle Park",
+  geometry: poly,
+  metadata: { type: "park", area_sqkm: 12.5 }
+)
+park_gj = park.to_geojson
+puts "  Feature('Triangle Park', polygon).to_geojson"
+puts "  geometry:   #{park_gj["geometry"]["type"]}"
+puts "  properties: #{park_gj["properties"]}"
+puts
+
+# ── 6. Building a FeatureCollection ───────────────────────────────
+
+puts "--- 6. GeoJSON FeatureCollection ---"
+puts
+
+gj = GeoJSON.new
+puts "  gj = GeoJSON.new"
+puts "  gj.size: #{gj.size}, empty? #{gj.empty?}"
+puts
+
+# Add cities as features
+cities = {
+  "Seattle"  => LLA.new(lat: 47.6205, lng: -122.3493, alt: 0),
+  "Portland" => LLA.new(lat: 45.5152, lng: -122.6784, alt: 0),
+  "San Francisco" => LLA.new(lat: 37.7749, lng: -122.4194, alt: 0),
+  "Los Angeles" => LLA.new(lat: 34.0522, lng: -118.2437, alt: 0),
+  "New York" => LLA.new(lat: 40.7128, lng: -74.0060, alt: 0)
+}
+
+cities.each do |name, coord|
+  gj << Feature.new(label: name, geometry: coord, metadata: { type: "city" })
+end
+puts "  Added #{cities.size} cities as Features"
+
+# Add a route as a path
+west_coast = Path.new(coordinates: cities.values_at("Seattle", "Portland", "San Francisco", "Los Angeles"))
+gj << Feature.new(label: "West Coast Route", geometry: west_coast, metadata: { mode: "driving" })
+puts "  Added West Coast route (Path with 4 waypoints)"
+
+# Add an array of raw coordinates (auto-wrapped as Features)
+landmarks = [
+  LLA.new(lat: 48.8566, lng: 2.3522, alt: 0),   # Paris
+  LLA.new(lat: 51.5074, lng: -0.1278, alt: 0)    # London
+]
+gj << landmarks
+puts "  Added 2 landmarks via << [array]"
+
+# Add a bounding box and a circle
+gj << Feature.new(label: "Pacific NW", geometry: bbox, metadata: { region: true })
+gj << Feature.new(label: "Seattle Metro", geometry: circle, metadata: { radius_km: 10 })
+puts "  Added bounding box and circle"
+
+puts
+puts "  Total items: #{gj.size}"
+puts "  to_s: #{gj}"
+puts
+
+# ── 7. Initialize with objects ────────────────────────────────────
+
+puts "--- 7. Initialize with objects ---"
+puts
+
+gj2 = GeoJSON.new(seattle, portland, sf)
+puts "  GeoJSON.new(seattle, portland, sf) → size: #{gj2.size}"
+
+gj3 = GeoJSON.new([seattle, portland])
+puts "  GeoJSON.new([seattle, portland]) → size: #{gj3.size}"
+puts
+
+# ── 8. Delete and Clear ───────────────────────────────────────────
+
+puts "--- 8. Delete and Clear ---"
+puts
+
+gj4 = GeoJSON.new(seattle, portland, sf)
+puts "  Before delete: #{gj4.size}"
+gj4.delete(portland)
+puts "  After delete(portland): #{gj4.size}"
+gj4.clear
+puts "  After clear: #{gj4.size}, empty? #{gj4.empty?}"
+puts
+
+# ── 9. Enumerable ─────────────────────────────────────────────────
+
+puts "--- 9. Enumerable ---"
+puts
+
+gj5 = GeoJSON.new(seattle, portland, sf)
+puts "  Iterating:"
+gj5.each { |obj| puts "    #{obj.class}: #{obj.to_s(4)}" }
+puts "  map to classes: #{gj5.map(&:class).map(&:name)}"
+puts
+
+# ── 10. Export to Hash, JSON, and File ─────────────────────────────
+
+puts "--- 10. Export ---"
+puts
+
+# to_h
+h = gj.to_h
+puts "  to_h:"
+puts "    type: #{h["type"]}"
+puts "    features: #{h["features"].length}"
+puts "    geometry types: #{h["features"].map { |f| f["geometry"]["type"] }.tally}"
+puts
+
+# to_json (compact)
+json = gj.to_json
+puts "  to_json (compact): #{json.length} bytes"
+
+# to_json (pretty)
+pretty = gj.to_json(pretty: true)
+puts "  to_json(pretty: true): #{pretty.length} bytes, #{pretty.lines.count} lines"
+puts
+
+# save to file
+output_path = File.join(__dir__, "geodetic_demo.geojson")
+gj.save(output_path, pretty: true)
+puts "  Saved to: #{output_path}"
+puts "  File size: #{File.size(output_path)} bytes"
+puts
+
+# Show first few lines of the pretty-printed output
+puts "  Preview (first 15 lines):"
+pretty.lines.first(15).each { |line| puts "    #{line}" }
+puts "    ..."
+puts
+
+puts "=== Done ==="
+puts
+puts "Open #{output_path} in https://geojson.io to visualize the data."

data/examples/README.md

@@ -117,3 +117,17 @@ Demonstrates the operator-based geometry system and the `Geodetic::Vector` class
 - **Key distinction: + vs \*** where `P + V` returns a Segment (the journey) and `P * V` returns a Coordinate (the destination)
 - **Path corridors** with `to_corridor(width:)` converting a path into a polygon, and translating the corridor
 - **Composing operations** chaining arithmetic, vector math, and corridors in single expressions
+
+## 09 - GeoJSON Export
+
+Demonstrates the `Geodetic::GeoJSON` class for building and exporting GeoJSON FeatureCollections. Covers:
+
+- **Coordinate → Point** with `to_geojson` on any coordinate system, including altitude handling
+- **Segment → LineString** exporting two-point directed segments
+- **Path → LineString** and optional `to_geojson(as: :polygon)` for closed paths
+- **Areas → Polygon** for `Polygon`, `Circle` (32-gon approximation with configurable `segments:`), and `BoundingBox`
+- **Feature → GeoJSON Feature** with `label` mapped to `"name"` and `metadata` merged into `properties`
+- **FeatureCollection building** with `GeoJSON.new`, `<<` for single objects and arrays, and `GeoJSON.new(obj, ...)` initialization
+- **Delete and clear** removing individual objects or emptying the collection
+- **Enumerable** iteration over collected objects
+- **Export** via `to_h` (Ruby Hash), `to_json`/`to_json(pretty: true)` (JSON string), and `save(path, pretty:)` (file output)