geodetic 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82e74456b38ec9c888ee70e68de3e626f0333b9f791c8de7779f5aa544cbbbc7
-  data.tar.gz: a76e9a726d4a503f0e2331f321de25a3b7c155e8712a27a18c53ba8e5ab27953
+  metadata.gz: 44b5221a45f63382e712aa88d033d1cb0b8165f8804833a1fd8523a9d7d8ce32
+  data.tar.gz: 787dc88782b277262e15dde4fa1f61801894d1d34eff304dc63965147a3b10e8
 SHA512:
-  metadata.gz: 4bd3b6a3c7664f9f0b20c7bd5c9cee52d80528fe91f97d5a9d2a8a48c9f8314d34027f50ba3b091581650965721e8275b268564ac6fb203fdc896c1f7fa25fa4
-  data.tar.gz: f7d83378049a016a388e2f8b4130179e7166704e20b10525a6f5c5a88a12a8812b703fe484dbfd8c40d7af7d8e6ddda7a903052575ea52b48a169c1ebff3fd8d
+  metadata.gz: ffb91f043c3c0c9a2bb6b44fad7952936121a09b18879350398cf260fd2be1f594f33c405df7cea0027f59c0e06679f1d4f718192d7626032a4b5fab195626f9
+  data.tar.gz: dd922521aa23db80a5d9fdf56dbb98dcdfab811f72a126978d9b8dffe248f72f3dd83c3cae1e41d3ee2a1cf11455d70120d6c81fff7523f3aac798397250fbca

data/CHANGELOG.md

@@ -8,6 +8,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 
+## [0.5.2] - 2026-03-10
+
+### Added
+
+- **`Geodetic::GeoJSON.load(path)`** — read a GeoJSON file and return an Array of Geodetic objects
+- **`Geodetic::GeoJSON.parse(hash)`** — same as `load` but accepts an already-parsed Ruby Hash
+- Roundtrip-safe import: Features with `"name"` or non-empty properties restore as `Geodetic::Feature` (label from `"name"`, remaining properties as `metadata` with symbol keys); Features with empty properties restore as raw geometry
+- GeoJSON → Geodetic type mapping:
+  - Point → `Coordinate::LLA` (altitude preserved when present)
+  - LineString (2 points) → `Segment`
+  - LineString (3+ points) → `Path`
+  - Polygon → `Areas::Polygon` (outer ring; holes dropped)
+  - MultiPoint, MultiLineString, MultiPolygon → flattened into multiple objects
+  - GeometryCollection → flattened into individual geometries
+- 17 new tests covering load, parse, roundtrip, multi-geometries, and edge cases
+
+### Changed
+
+- Updated README with `GeoJSON.load` usage example
+- Updated `docs/reference/geojson.md` with Import section, type mapping table, and roundtrip example
+- Updated `mkdocs.yml` nav to include all 7 missing coordinate systems (GH36, GH, HAM, OLC, GEOREF, GARS, H3) and 3 missing reference pages (Vector, Arithmetic, GeoJSON Export)
+- GeoJSON demo (`examples/09_geojson_export.rb`) now saves output to `examples/` directory instead of system temp
+
 ## [0.5.1] - 2026-03-10
 
 ### Added

data/README.md

@@ -760,6 +760,15 @@ feature.to_geojson                        # => {"type" => "Feature", ...}
 
 Features carry their `label` as `"name"` and `metadata` as `properties` in the GeoJSON output. Non-Feature objects added to the collection are auto-wrapped as Features with empty properties.
 
+**Loading GeoJSON files:**
+
+```ruby
+objects = Geodetic::GeoJSON.load("map.geojson")
+# => [Feature("Seattle", LLA), Segment, Path, Polygon, LLA, ...]
+```
+
+`load` returns an Array of Geodetic objects. Features with a `"name"` or non-empty properties round-trip as `Feature` objects; bare geometries with empty properties return as raw coordinates, segments, paths, or polygons. `GeoJSON.parse(hash)` does the same from an already-parsed Hash.
+
 ### Web Mercator Tile Coordinates
 
 ```ruby

data/docs/reference/geojson.md

@@ -99,6 +99,60 @@ 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
@@ -317,4 +371,18 @@ The output file can be opened directly in [geojson.io](https://geojson.io), QGIS
 - **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

@@ -5,7 +5,6 @@
 # and save it to a file that can be opened in any GeoJSON viewer.
 
 require_relative "../lib/geodetic"
-require "tmpdir"
 
 include Geodetic
 
@@ -239,7 +238,7 @@ puts "  to_json(pretty: true): #{pretty.length} bytes, #{pretty.lines.count} lin
 puts
 
 # save to file
-output_path = File.join(Dir.tmpdir, "geodetic_demo.geojson")
+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"

data/examples/geodetic_demo.geojson

@@ -0,0 +1,305 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          -122.3493,
+          47.6205
+        ]
+      },
+      "properties": {
+        "name": "Seattle",
+        "type": "city"
+      }
+    },
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          -122.6784,
+          45.5152
+        ]
+      },
+      "properties": {
+        "name": "Portland",
+        "type": "city"
+      }
+    },
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          -122.4194,
+          37.7749
+        ]
+      },
+      "properties": {
+        "name": "San Francisco",
+        "type": "city"
+      }
+    },
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          -118.2437,
+          34.0522
+        ]
+      },
+      "properties": {
+        "name": "Los Angeles",
+        "type": "city"
+      }
+    },
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          -74.006,
+          40.7128
+        ]
+      },
+      "properties": {
+        "name": "New York",
+        "type": "city"
+      }
+    },
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "LineString",
+        "coordinates": [
+          [
+            -122.3493,
+            47.6205
+          ],
+          [
+            -122.6784,
+            45.5152
+          ],
+          [
+            -122.4194,
+            37.7749
+          ],
+          [
+            -118.2437,
+            34.0522
+          ]
+        ]
+      },
+      "properties": {
+        "name": "West Coast Route",
+        "mode": "driving"
+      }
+    },
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          2.3522,
+          48.8566
+        ]
+      },
+      "properties": {}
+    },
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          -0.1278,
+          51.5074
+        ]
+      },
+      "properties": {}
+    },
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Polygon",
+        "coordinates": [
+          [
+            [
+              -123.0,
+              48.0
+            ],
+            [
+              -121.0,
+              48.0
+            ],
+            [
+              -121.0,
+              46.0
+            ],
+            [
+              -123.0,
+              46.0
+            ],
+            [
+              -123.0,
+              48.0
+            ]
+          ]
+        ]
+      },
+      "properties": {
+        "name": "Pacific NW",
+        "region": true
+      }
+    },
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Polygon",
+        "coordinates": [
+          [
+            [
+              -122.3493,
+              47.710441151017214
+            ],
+            [
+              -122.32330338127136,
+              47.708710028492575
+            ],
+            [
+              -122.29831079292721,
+              47.70358352014371
+            ],
+            [
+              -122.27528691572327,
+              47.69525958316883
+            ],
+            [
+              -122.25511936150583,
+              47.684059519927274
+            ],
+            [
+              -122.23858413342101,
+              47.67041541322468
+            ],
+            [
+              -122.22631565848305,
+              47.654853266080394
+            ],
+            [
+              -122.21878256554382,
+              47.63797253321124
+            ],
+            [
+              -122.21627011382594,
+              47.62042286978415
+            ],
+            [
+              -122.21886987894307,
+              47.602879023582524
+            ],
+            [
+              -122.2264769927538,
+              47.586014856783315
+            ],
+            [
+              -122.23879492708923,
+              47.57047750255195
+            ],
+            [
+              -122.25534752329217,
+              47.5568626411414
+            ],
+            [
+              -122.27549771006404,
+              47.54569182325386
+            ],
+            [
+              -122.2984721281491,
+              47.53739267934147
+            ],
+            [
+              -122.32339069534318,
+              47.532282737212164
+            ],
+            [
+              -122.3493,
+              47.53055743197494
+            ],
+            [
+              -122.37520930465682,
+              47.532282737212164
+            ],
+            [
+              -122.4001278718509,
+              47.53739267934147
+            ],
+            [
+              -122.42310228993595,
+              47.54569182325386
+            ],
+            [
+              -122.44325247670783,
+              47.55686264114141
+            ],
+            [
+              -122.45980507291077,
+              47.57047750255195
+            ],
+            [
+              -122.4721230072462,
+              47.58601485678331
+            ],
+            [
+              -122.47973012105693,
+              47.60287902358252
+            ],
+            [
+              -122.48232988617406,
+              47.62042286978415
+            ],
+            [
+              -122.47981743445618,
+              47.63797253321123
+            ],
+            [
+              -122.47228434151695,
+              47.6548532660804
+            ],
+            [
+              -122.46001586657898,
+              47.670415413224674
+            ],
+            [
+              -122.44348063849417,
+              47.684059519927274
+            ],
+            [
+              -122.42331308427673,
+              47.69525958316883
+            ],
+            [
+              -122.40028920707279,
+              47.70358352014371
+            ],
+            [
+              -122.37529661872864,
+              47.708710028492575
+            ],
+            [
+              -122.3493,
+              47.710441151017214
+            ]
+          ]
+        ]
+      },
+      "properties": {
+        "name": "Seattle Metro",
+        "radius_km": 10
+      }
+    }
+  ]
+}

data/lib/geodetic/geojson.rb

@@ -101,6 +101,8 @@ module Geodetic
     # ---------------------------------------------------------------
 
     class << self
+      # --- Export helpers ---
+
       def position(lla)
         if lla.alt != 0.0
           [lla.lng, lla.lat, lla.alt]
@@ -120,6 +122,93 @@ module Geodetic
       def polygon_hash(rings)
         { "type" => "Polygon", "coordinates" => rings.map { |ring| ring.map { |p| position(p) } } }
       end
+
+      # --- Import ---
+
+      def load(path)
+        data = JSON.parse(File.read(path))
+        parse(data)
+      end
+
+      def parse(data)
+        case data["type"]
+        when "FeatureCollection"
+          data["features"].flat_map { |f| parse(f) }
+        when "Feature"
+          parse_feature(data)
+        when "GeometryCollection"
+          data["geometries"].flat_map { |g| parse_geometry(g) }
+        else
+          [parse_geometry(data)]
+        end
+      end
+
+      private
+
+      def parse_feature(data)
+        geometry = parse_geometry(data["geometry"])
+        properties = data["properties"] || {}
+
+        results = geometry.is_a?(Array) ? geometry : [geometry]
+
+        results.map do |geom|
+          name = properties["name"]
+          metadata = properties.reject { |k, _| k == "name" }
+
+          if name || !metadata.empty?
+            Feature.new(
+              label: name,
+              geometry: geom,
+              metadata: metadata.transform_keys(&:to_sym)
+            )
+          else
+            geom
+          end
+        end
+      end
+
+      def parse_geometry(data)
+        case data["type"]
+        when "Point"
+          parse_point(data["coordinates"])
+        when "LineString"
+          parse_line_string(data["coordinates"])
+        when "Polygon"
+          parse_polygon(data["coordinates"])
+        when "MultiPoint"
+          data["coordinates"].map { |pos| parse_point(pos) }
+        when "MultiLineString"
+          data["coordinates"].map { |coords| parse_line_string(coords) }
+        when "MultiPolygon"
+          data["coordinates"].map { |rings| parse_polygon(rings) }
+        when "GeometryCollection"
+          data["geometries"].flat_map { |g| parse_geometry(g) }
+        else
+          raise ArgumentError, "unknown GeoJSON geometry type: #{data["type"]}"
+        end
+      end
+
+      def parse_point(coords)
+        lng, lat = coords[0], coords[1]
+        alt = coords[2] || 0.0
+        Coordinate::LLA.new(lat: lat, lng: lng, alt: alt)
+      end
+
+      def parse_line_string(coords)
+        points = coords.map { |pos| parse_point(pos) }
+        if points.length == 2
+          Segment.new(points[0], points[1])
+        else
+          Path.new(coordinates: points)
+        end
+      end
+
+      def parse_polygon(rings)
+        outer = rings[0].map { |pos| parse_point(pos) }
+        # Remove closing point if it duplicates the first (Polygon#initialize adds it)
+        outer.pop if outer.length > 1 && outer.first == outer.last
+        Areas::Polygon.new(boundary: outer)
+      end
     end
 
     # ---------------------------------------------------------------

data/lib/geodetic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Geodetic
-  VERSION = "0.5.1"
+  VERSION = "0.5.2"
 end

data/mkdocs.yml

@@ -132,6 +132,13 @@ nav:
       - UPS: coordinate-systems/ups.md
       - State Plane: coordinate-systems/state-plane.md
       - BNG: coordinate-systems/bng.md
+      - GH36: coordinate-systems/gh36.md
+      - GH: coordinate-systems/gh.md
+      - HAM: coordinate-systems/ham.md
+      - OLC: coordinate-systems/olc.md
+      - GEOREF: coordinate-systems/georef.md
+      - GARS: coordinate-systems/gars.md
+      - H3: coordinate-systems/h3.md
   - Reference:
       - Datums: reference/datums.md
       - Geoid Height: reference/geoid-height.md
@@ -141,4 +148,7 @@ nav:
       - Feature: reference/feature.md
       - Serialization: reference/serialization.md
       - Conversions: reference/conversions.md
+      - Vector: reference/vector.md
+      - Arithmetic: reference/arithmetic.md
+      - GeoJSON Export: reference/geojson.md
       - Map Rendering: reference/map-rendering.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: geodetic
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.2
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -79,6 +79,7 @@ files:
 - examples/08_geodetic_arithmetic.rb
 - examples/09_geojson_export.rb
 - examples/README.md
+- examples/geodetic_demo.geojson
 - fiddle_pointer_buffer_pool.md
 - lib/geodetic.rb
 - lib/geodetic/areas.rb