kml-path-parser 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1ba7b9a23862285aed743abf581d2c6d93d72558ebb7679730560f3626f3051d
+  data.tar.gz: 82e88798ec57e4644616fb9718f7dcebd8fdeca773a81c2b2a567d8d479bba3a
+SHA512:
+  metadata.gz: 85669be59563792510ac0ea60bfdb5bf81650ec7226503b9dccebb88b8e9c013fda3e19a926862076d444f7c7c94b647b1315ceff0fc7f4b97ce7da3ba2c2ee1
+  data.tar.gz: 41b78088cac7f4c57e75492ec631954e403883a4e898312b0aa0bc14706a46085de810a02caaf1c0a415c180c05bb1c4fcf18745968c80f981ea2b1c5ba9f47b

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# 1.0.0
+
+Initial release.
+
+- Parse `LineString` and `gx:Track` geometry from KML and KMZ uploads
+- `#parse` returns a `Kml::Path::Result`; `#parse!` raises `Kml::Path::ParseError` on failure
+- Shipped fixture files and `Kml::Path::Fixtures` helper for consumer tests

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh McArthur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,106 @@
+# kml-path-parser
+
+Extract path geometry from user-uploaded KML and KMZ files.
+
+`kml-path-parser` is a focused library for fitness and mapping apps that need to import route tracks from real-world exports (Google Earth, My Maps, QGIS, and similar tools). It is **not** a general-purpose KML codec: it only extracts `LineString` and `gx:Track` paths.
+
+Extracted from [VirtualTrails](https://virtualtrails.app).
+
+## Installation
+
+```ruby
+gem "kml-path-parser", "~> 1.0"
+```
+
+## Usage
+
+The parser expects a file-like upload object responding to `read`, `rewind`, `original_filename`, and `content_type` (as Rails `ActionDispatch::Http::UploadedFile` and `Rack::Test::UploadedFile` do).
+
+### `#parse` — non-exceptional failures
+
+```ruby
+require "kml"
+
+parser = Kml::Path::Parser.new(file: upload)
+result = parser.parse
+
+if result.success?
+  puts result.name
+  result.coordinates.each do |longitude, latitude, altitude|
+    puts [longitude, latitude, altitude]
+  end
+else
+  puts result.error
+end
+```
+
+### `#parse!` — raises on failure
+
+```ruby
+result = parser.parse!
+# => Kml::Path::Result
+
+# On invalid input:
+# Kml::Path::ParseError: must contain a LineString or gx:Track
+```
+
+### Lazy accessors
+
+`#content` returns the extracted KML string (from a `.kml` file or from inside a `.kmz` archive). `#name` resolves the route name without requiring a successful coordinate parse.
+
+## Shipped fixtures
+
+The gem includes real-world KML/KMZ fixtures for testing and documentation:
+
+```ruby
+fixture_path = Kml::Path::Fixtures.path("valid/sample_route.kml")
+catalog = Kml::Path::Fixtures::CATALOG
+```
+
+Fixtures live under `lib/kml/path/fixtures/` (`valid/` and `reject/`).
+
+## Supported formats
+
+| Format | Support |
+|--------|---------|
+| KML (`.kml`) | Yes |
+| KMZ (`.kmz`) | Yes — uses `doc.kml` when present, otherwise the first `.kml` entry (skips `__MACOSX/`) |
+
+## Parsing policies
+
+- **Geometry:** first `LineString` in the document wins; otherwise first `gx:Track` (first track in `gx:MultiTrack`)
+- **Name priority:** Document name → Placemark name → any `name` element → upload filename → `"Untitled"`
+- **Coordinates:** returned as `[longitude, latitude, altitude]` arrays; altitude may be `nil`
+- **Invalid coordinates:** lat/lon pairs outside valid ranges are filtered silently
+
+## Rejected inputs
+
+These return a failed `Result` (or raise `ParseError` via `#parse!`):
+
+- Empty documents
+- Point-only geometry
+- Polygon-only geometry
+- Empty `LineString` elements
+- KMZ archives with no KML file
+- Corrupt KMZ archives (`could not be parsed: …`)
+
+A single-point `LineString` parses successfully; callers that need a minimum path length should enforce that themselves.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+bundle exec rubocop
+```
+
+## Releasing
+
+1. Bump `Kml::Path::VERSION` in `lib/kml/path/version.rb`
+2. Update `CHANGELOG.md`
+3. Commit, tag (`v1.0.1`), and push the tag
+4. GitHub Actions publishes to RubyGems when `RUBYGEMS_API_KEY` is configured
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/kml/path/fixtures/reject/empty_document.kml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document></Document>
+</kml>

data/lib/kml/path/fixtures/reject/empty_linestring.kml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Empty LineString</name>
+    <Placemark>
+      <LineString>
+        <coordinates></coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/reject/point_only.kml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Point Only</name>
+    <Placemark>
+      <Point>
+        <coordinates>144.9631,-37.8136,0</coordinates>
+      </Point>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/reject/polygon_only.kml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Polygon Only</name>
+    <Placemark>
+      <Polygon>
+        <outerBoundaryIs>
+          <LinearRing>
+            <coordinates>
+              144.9631,-37.8136,0
+              144.9731,-37.8236,0
+              144.9831,-37.8336,0
+              144.9631,-37.8136,0
+            </coordinates>
+          </LinearRing>
+        </outerBoundaryIs>
+      </Polygon>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/reject/single_point.kml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>One Point</name>
+    <Placemark>
+      <LineString>
+        <coordinates>144.9631,-37.8136,0</coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/cdata_name.kml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name><![CDATA[Trail & "Path" <special>]]></name>
+    <Placemark>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/coordinates_extra_whitespace.kml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Whitespace</name>
+    <Placemark>
+      <LineString>
+        <coordinates>
+          144.9631, -37.8136 , 0
+			144.9731,-37.8236,0
+
+          144.9831,-37.8336,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/coordinates_no_altitude.kml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>No Altitude</name>
+    <Placemark>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136
+          144.9731,-37.8236
+          144.9831,-37.8336
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/coordinates_single_line.kml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Single Line</name>
+    <Placemark>
+      <LineString>
+        <coordinates>144.9631,-37.8136,0 144.9731,-37.8236,0 144.9831,-37.8336,0</coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/crlf_line_endings.kml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Sample Trail</name>
+    <Placemark>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+          144.9831,-37.8336,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/document_name_priority.kml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Official Name</name>
+    <Placemark>
+      <name>Ignored Placemark Name</name>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/gx_multitrack_first_wins.kml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2">
+  <Document>
+    <name>Multi Track</name>
+    <Placemark>
+      <gx:MultiTrack>
+        <gx:Track>
+          <gx:coord>144.9631 -37.8136 0</gx:coord>
+          <gx:coord>144.9731 -37.8236 0</gx:coord>
+        </gx:Track>
+        <gx:Track>
+          <gx:coord>145.0000 -38.0000 0</gx:coord>
+          <gx:coord>145.0100 -38.0100 0</gx:coord>
+        </gx:Track>
+      </gx:MultiTrack>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/gx_track.kml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2">
+  <Document>
+    <name>GPS Track</name>
+    <Placemark>
+      <gx:Track>
+        <gx:coord>144.9631 -37.8136 0</gx:coord>
+        <gx:coord>144.9731 -37.8236 0</gx:coord>
+        <gx:coord>144.9831 -37.8336 0</gx:coord>
+      </gx:Track>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/gx_track_with_timestamps.kml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2">
+  <Document>
+    <name>Timestamped Track</name>
+    <Placemark>
+      <gx:Track>
+        <when>2024-01-01T00:00:00Z</when>
+        <when>2024-01-01T00:05:00Z</when>
+        <when>2024-01-01T00:10:00Z</when>
+        <gx:coord>144.9631 -37.8136 0</gx:coord>
+        <gx:coord>144.9731 -37.8236 0</gx:coord>
+        <gx:coord>144.9831 -37.8336 0</gx:coord>
+      </gx:Track>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/invalid_coords_filtered.kml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Filtered Coords</name>
+    <Placemark>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          200.0000,100.0000,0
+          144.9731,-37.8236,0
+          144.9831,-37.8336,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/linestring_attributes.kml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Attributed Line</name>
+    <Placemark>
+      <LineString>
+        <extrude>1</extrude>
+        <tessellate>1</tessellate>
+        <altitudeMode>clampToGround</altitudeMode>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+          144.9831,-37.8336,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/linestring_before_point.kml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Line Before Point</name>
+    <Placemark>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+        </coordinates>
+      </LineString>
+      <Point>
+        <coordinates>145.0000,-38.0000,0</coordinates>
+      </Point>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/many_points.kml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Many Points</name>
+    <Placemark>
+      <LineString>
+        <coordinates>
+          144.9600,-37.8100,0
+          144.9610,-37.8110,0
+          144.9620,-37.8120,0
+          144.9630,-37.8130,0
+          144.9640,-37.8140,0
+          144.9650,-37.8150,0
+          144.9660,-37.8160,0
+          144.9670,-37.8170,0
+          144.9680,-37.8180,0
+          144.9690,-37.8190,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/multi_geometry.kml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Split Route</name>
+    <Placemark>
+      <MultiGeometry>
+        <LineString>
+          <coordinates>
+            144.9631,-37.8136,0
+            144.9731,-37.8236,0
+          </coordinates>
+        </LineString>
+        <LineString>
+          <coordinates>
+            145.0000,-38.0000,0
+            145.0100,-38.0100,0
+          </coordinates>
+        </LineString>
+      </MultiGeometry>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/multiple_placemarks_first_wins.kml

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Multiple Placemarks</name>
+    <Placemark>
+      <name>First Trail</name>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+    <Placemark>
+      <name>Second Trail</name>
+      <LineString>
+        <coordinates>
+          145.0000,-38.0000,0
+          145.0100,-38.0100,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/namespace_less.kml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml>
+  <Document>
+    <name>Legacy Export</name>
+    <Placemark>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+          144.9831,-37.8336,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/nested_folder.kml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Nested Folder</name>
+    <Folder>
+      <name>Trails</name>
+      <Placemark>
+        <name>Inner Trail</name>
+        <LineString>
+          <coordinates>
+            144.9631,-37.8136,0
+            144.9731,-37.8236,0
+            144.9831,-37.8336,0
+          </coordinates>
+        </LineString>
+      </Placemark>
+    </Folder>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/nested_multigeometry_folder.kml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Nested MultiGeometry</name>
+    <Folder>
+      <Placemark>
+        <MultiGeometry>
+          <LineString>
+            <coordinates>
+              144.9631,-37.8136,0
+              144.9731,-37.8236,0
+              144.9831,-37.8336,0
+            </coordinates>
+          </LineString>
+        </MultiGeometry>
+      </Placemark>
+    </Folder>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/placemark_name.kml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <Placemark>
+      <name>Coastal Walk</name>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+          144.9831,-37.8336,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/qgis_export.kml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>QGIS Export</name>
+    <description>Exported from QGIS</description>
+    <ExtendedData>
+      <Data name="layer">
+        <value>trails</value>
+      </Data>
+    </ExtendedData>
+    <Placemark>
+      <name>trail_1</name>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+          144.9831,-37.8336,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/sample_route.kml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Sample Trail</name>
+    <Placemark>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+          144.9831,-37.8336,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/two_points.kml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Minimum Path</name>
+    <Placemark>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/unicode_name.kml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>Øresundsstien 日本語</name>
+    <Placemark>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures/valid/unnamed.kml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <Placemark>
+      <LineString>
+        <coordinates>
+          144.9631,-37.8136,0
+          144.9731,-37.8236,0
+        </coordinates>
+      </LineString>
+    </Placemark>
+  </Document>
+</kml>

data/lib/kml/path/fixtures.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Kml
+  module Path
+    module Fixtures
+      ROOT = File.expand_path("fixtures", __dir__).freeze
+
+      def self.path(relative)
+        File.join(ROOT, relative)
+      end
+
+      def self.read(relative)
+        File.read(path(relative))
+      end
+
+      CATALOG = {
+        valid: {
+          "valid/sample_route.kml" => { name: "Sample Trail", point_count: 3 },
+          "valid/sample_route.kmz" => { name: "Sample Trail", point_count: 3 },
+          "valid/placemark_name.kml" => { name: "Coastal Walk", point_count: 3 },
+          "valid/gx_track.kml" => { name: "GPS Track", point_count: 3 },
+          "valid/multi_geometry.kml" => { name: "Split Route", point_count: 2, first_point: [144.9631, -37.8136] },
+          "valid/namespace_less.kml" => { name: "Legacy Export", point_count: 3 },
+          "valid/document_name_priority.kml" => { name: "Official Name", point_count: 2 },
+          "valid/two_points.kml" => { name: "Minimum Path", point_count: 2 },
+          "valid/coordinates_no_altitude.kml" => { name: "No Altitude", point_count: 3 },
+          "valid/coordinates_single_line.kml" => { name: "Single Line", point_count: 3 },
+          "valid/coordinates_extra_whitespace.kml" => { name: "Whitespace", point_count: 3 },
+          "valid/nested_folder.kml" => { name: "Nested Folder", point_count: 3 },
+          "valid/multiple_placemarks_first_wins.kml" => {
+            name: "Multiple Placemarks",
+            point_count: 2,
+            first_point: [144.9631, -37.8136]
+          },
+          "valid/unicode_name.kml" => { name: "Øresundsstien 日本語", point_count: 2 },
+          "valid/cdata_name.kml" => { name: "Trail & \"Path\" <special>", point_count: 2 },
+          "valid/crlf_line_endings.kml" => { name: "Sample Trail", point_count: 3 },
+          "valid/gx_track_with_timestamps.kml" => { name: "Timestamped Track", point_count: 3 },
+          "valid/gx_multitrack_first_wins.kml" => {
+            name: "Multi Track",
+            point_count: 2,
+            first_point: [144.9631, -37.8136]
+          },
+          "valid/linestring_attributes.kml" => { name: "Attributed Line", point_count: 3 },
+          "valid/qgis_export.kml" => { name: "QGIS Export", point_count: 3 },
+          "valid/invalid_coords_filtered.kml" => { name: "Filtered Coords", point_count: 3 },
+          "valid/nested_multigeometry_folder.kml" => { name: "Nested MultiGeometry", point_count: 3 },
+          "valid/many_points.kml" => { name: "Many Points", point_count: 10 },
+          "valid/linestring_before_point.kml" => { name: "Line Before Point", point_count: 2 },
+          "valid/kmz_custom_kml_name.kmz" => { name: "Minimum Path", point_count: 2 },
+          "valid/kmz_with_macosx_junk.kmz" => { name: "Sample Trail", point_count: 3 }
+        }.freeze,
+        reject: {
+          "reject/empty_document.kml" => "must contain a LineString or gx:Track",
+          "reject/point_only.kml" => "must contain a LineString or gx:Track",
+          "reject/polygon_only.kml" => "must contain a LineString or gx:Track",
+          "reject/empty_linestring.kml" => "must contain a LineString or gx:Track",
+          "reject/empty_archive.kmz" => "must contain a KML file"
+        }.freeze
+      }.freeze
+    end
+  end
+end

data/lib/kml/path/parse_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Kml
+  module Path
+    class ParseError < StandardError
+    end
+  end
+end

data/lib/kml/path/parser.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Kml
+  module Path
+    class Parser
+      KMZ_CONTENT_TYPES = %w[application/vnd.google-earth.kmz application/zip].freeze
+      KML_NAMESPACES = {
+        "kml" => "http://www.opengis.net/kml/2.2",
+        "gx" => "http://www.google.com/kml/ext/2.2"
+      }.freeze
+      NAME_XPATHS = [
+        ["//kml:Document/kml:name", KML_NAMESPACES],
+        ["//kml:Placemark/kml:name", KML_NAMESPACES],
+        ["//kml:name", KML_NAMESPACES],
+        ["//Document/name", nil],
+        ["//Placemark/name", nil]
+      ].freeze
+      MISSING_GEOMETRY = "must contain a LineString or gx:Track"
+      MISSING_KML = "must contain a KML file"
+
+      def initialize(file:)
+        @file = file
+      end
+
+      def parse
+        @parse ||= build_parse_result
+      end
+
+      def parse!
+        result = parse
+        raise ParseError, result.error if result.failure?
+
+        result
+      end
+
+      def name
+        parse.success? ? parse.name : extract_name
+      end
+
+      def content
+        parse
+        @content
+      end
+
+      private
+
+      attr_reader :file
+
+      def build_parse_result
+        kml_content = extract_kml_content
+        return failure(MISSING_KML) if kml_content.nil? || kml_content.empty?
+
+        @content = kml_content
+        coordinates = extract_coordinates
+        return failure(MISSING_GEOMETRY) if coordinates.nil? || coordinates.empty?
+
+        Result.new(success: true, name: extract_name, coordinates:, error: nil)
+      rescue Zip::Error => e
+        failure("could not be parsed: #{e.message}")
+      end
+
+      def failure(message)
+        Result.new(success: false, name: nil, coordinates: nil, error: message)
+      end
+
+      def extract_kml_content
+        file_content = read_file
+        return file_content unless kmz_file?
+
+        extract_kml_from_kmz(file_content)
+      end
+
+      def read_file
+        @read_file ||= begin
+          file.rewind if file.respond_to?(:rewind)
+          file.read
+        end
+      end
+
+      def kmz_file?
+        filename = file.original_filename.to_s.downcase
+        return true if filename.end_with?(".kmz")
+
+        KMZ_CONTENT_TYPES.include?(file.content_type.to_s)
+      end
+
+      def extract_kml_from_kmz(content)
+        kml = nil
+
+        Zip::File.open_buffer(content) do |archive|
+          entry_name = archive.find_entry("doc.kml")&.name || find_kml_entry_name(archive)
+          kml = archive.get_input_stream(entry_name, &:read) if entry_name
+        end
+
+        kml
+      end
+
+      def find_kml_entry_name(archive)
+        archive.entries.map(&:name).reject do |name|
+          name.start_with?("__MACOSX/") || !name.downcase.end_with?(".kml")
+        end.first
+      end
+
+      def extract_name
+        NAME_XPATHS.each do |xpath, namespaces|
+          document_name = xpath_value(xpath, namespaces)
+          return document_name if document_name
+        end
+
+        present_string(File.basename(file.original_filename.to_s, ".*")) || "Untitled"
+      end
+
+      def extract_coordinates
+        coordinates_node = line_string_coordinates_node || gx_track_coordinate_node
+        return unless coordinates_node
+
+        coordinates_from_node(coordinates_node)
+      end
+
+      def document
+        @document ||= Nokogiri::XML(@content)
+      end
+
+      def coordinates_from_node(node)
+        case node.name
+        when "coordinates"
+          parse_coordinates_text(node.text)
+        when "coord"
+          parse_gx_coords(gx_track_coordinate_nodes)
+        end
+      end
+
+      def xpath_value(xpath, namespaces)
+        node = namespaces ? document.at_xpath(xpath, namespaces) : document.at_xpath(xpath)
+        present_string(node&.text)
+      end
+
+      def line_string_coordinates_node
+        document.at_xpath("//kml:LineString/kml:coordinates", KML_NAMESPACES) ||
+          document.at_xpath("//LineString/coordinates")
+      end
+
+      def gx_track_coordinate_node
+        first_gx_track&.at_xpath("gx:coord", KML_NAMESPACES) ||
+          first_gx_track&.at_xpath("*[local-name()='coord']")
+      end
+
+      def gx_track_coordinate_nodes
+        track = first_gx_track
+        return document.xpath("//none") unless track
+
+        nodes = track.xpath("gx:coord", KML_NAMESPACES)
+        return nodes if nodes.any?
+
+        track.xpath("*[local-name()='coord']")
+      end
+
+      def first_gx_track
+        document.at_xpath("//gx:Track", KML_NAMESPACES) ||
+          document.at_xpath("//*[local-name()='Track']")
+      end
+
+      def parse_coordinates_text(text)
+        normalized = text.gsub(/\s*,\s*/, ",")
+        normalized.strip.split(/\s+/).filter_map do |coordinate|
+          parse_coordinate_values(coordinate.split(","))
+        end
+      end
+
+      def parse_gx_coords(nodes)
+        nodes.filter_map { |node| parse_coordinate_values(node.text.strip.split) }
+      end
+
+      def parse_coordinate_values(values)
+        return if values.length < 2
+
+        longitude = values[0].to_f
+        latitude = values[1].to_f
+        altitude = values[2]&.to_f
+        return unless valid_coordinate?(latitude, longitude)
+
+        [longitude, latitude, altitude]
+      end
+
+      def valid_coordinate?(latitude, longitude)
+        latitude.between?(-90, 90) && longitude.between?(-180, 180)
+      end
+
+      def present_string(value)
+        return if value.nil?
+
+        stripped = value.to_s.strip
+        stripped.empty? ? nil : stripped
+      end
+    end
+  end
+end

data/lib/kml/path/result.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Kml
+  module Path
+    class Result
+      attr_reader :name, :coordinates, :error
+
+      def initialize(success:, name:, coordinates:, error:)
+        @success = success
+        @name = name
+        @coordinates = coordinates
+        @error = error
+      end
+
+      def success?
+        @success
+      end
+
+      def failure?
+        !success?
+      end
+    end
+  end
+end

data/lib/kml/path/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Kml
+  module Path
+    VERSION = "1.0.0"
+  end
+end

data/lib/kml.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "zip"
+require_relative "kml/path/version"
+require_relative "kml/path/parse_error"
+require_relative "kml/path/result"
+require_relative "kml/path/fixtures"
+require_relative "kml/path/parser"
+
+module Kml
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: kml-path-parser
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Josh McArthur
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+description: Parse LineString and gx:Track geometry from real-world KML and KMZ exports
+  (Google Earth, My Maps, and similar tools) into path names and coordinate arrays.
+email:
+- joshua.mcarthur@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/kml.rb
+- lib/kml/path/fixtures.rb
+- lib/kml/path/fixtures/reject/empty_archive.kmz
+- lib/kml/path/fixtures/reject/empty_document.kml
+- lib/kml/path/fixtures/reject/empty_linestring.kml
+- lib/kml/path/fixtures/reject/point_only.kml
+- lib/kml/path/fixtures/reject/polygon_only.kml
+- lib/kml/path/fixtures/reject/single_point.kml
+- lib/kml/path/fixtures/valid/cdata_name.kml
+- lib/kml/path/fixtures/valid/coordinates_extra_whitespace.kml
+- lib/kml/path/fixtures/valid/coordinates_no_altitude.kml
+- lib/kml/path/fixtures/valid/coordinates_single_line.kml
+- lib/kml/path/fixtures/valid/crlf_line_endings.kml
+- lib/kml/path/fixtures/valid/document_name_priority.kml
+- lib/kml/path/fixtures/valid/gx_multitrack_first_wins.kml
+- lib/kml/path/fixtures/valid/gx_track.kml
+- lib/kml/path/fixtures/valid/gx_track_with_timestamps.kml
+- lib/kml/path/fixtures/valid/invalid_coords_filtered.kml
+- lib/kml/path/fixtures/valid/kmz_custom_kml_name.kmz
+- lib/kml/path/fixtures/valid/kmz_with_macosx_junk.kmz
+- lib/kml/path/fixtures/valid/linestring_attributes.kml
+- lib/kml/path/fixtures/valid/linestring_before_point.kml
+- lib/kml/path/fixtures/valid/many_points.kml
+- lib/kml/path/fixtures/valid/multi_geometry.kml
+- lib/kml/path/fixtures/valid/multiple_placemarks_first_wins.kml
+- lib/kml/path/fixtures/valid/namespace_less.kml
+- lib/kml/path/fixtures/valid/nested_folder.kml
+- lib/kml/path/fixtures/valid/nested_multigeometry_folder.kml
+- lib/kml/path/fixtures/valid/placemark_name.kml
+- lib/kml/path/fixtures/valid/qgis_export.kml
+- lib/kml/path/fixtures/valid/sample_route.kml
+- lib/kml/path/fixtures/valid/sample_route.kmz
+- lib/kml/path/fixtures/valid/two_points.kml
+- lib/kml/path/fixtures/valid/unicode_name.kml
+- lib/kml/path/fixtures/valid/unnamed.kml
+- lib/kml/path/parse_error.rb
+- lib/kml/path/parser.rb
+- lib/kml/path/result.rb
+- lib/kml/path/version.rb
+homepage: https://github.com/joshmcarthur/kml-path-parser
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/joshmcarthur/kml-path-parser
+  source_code_uri: https://github.com/joshmcarthur/kml-path-parser
+  changelog_uri: https://github.com/joshmcarthur/kml-path-parser/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Extract paths from user-uploaded KML and KMZ files
+test_files: []