tg_geometry 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cde617c534a8a3d9702b3fe212d46f966da46224499bb4fcb97bf40865590be8
-  data.tar.gz: 7e1767d31814249ef695ceae1965d6c5aaf9065ff7595309e95698abc053abbc
+  metadata.gz: 7cb54eb85cd48036c2f32eb5f95fa3d19cbf994d375bc102b05f2d45dfb1f8ec
+  data.tar.gz: c5ff1c066708d8826c125185f34a346e1f1e2bf66f65fb1b1eb13e75bf955aad
 SHA512:
-  metadata.gz: 2cf6070d21ca5342425600e436523aae7215a2792d2d8392662a6c5257ba4e178301ff2a93c5ebb847fc7606d7b1aad60b9ab1fcd8e21b67f06d5f72f8c3cfa1
-  data.tar.gz: 99a9f9c086c6a2da9add012f57a99de800f67846007503ddf6c5d63ec25ac2a6d62cfe5b854fe1d44976ff0bddcbce04b8831db631dd8d174602c64914190e30
+  metadata.gz: 981e37eb58fac8eaa20c3fa9604b751c263330e3f3dc2e8614cb1c91e36eb76d31431b4a13b3cbcd44475323d5ca76ec3e58c013d8c16de9d28e2ec890704962
+  data.tar.gz: 05db4ca563cd1c22e13d5c27e440845452397f50516cf01dde8675032fb3e12a527ba0fe52ccd32bc1fe313b3f8d083f46c17a54e4e8c316b6e8ce9766c278d5

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.3.2 - unreleased
+
+### Added
+
+- Added explicit point-to-geometry distance APIs on `TG::Geometry::Geom`:
+  `distance_to_lnglat_meters`, `boundary_distance_to_lnglat_meters`,
+  `nearest_point_lnglat`, `distance_to_xy`, `boundary_distance_to_xy`, and
+  `nearest_point_xy`.
+- Added `TG::Geometry::Index#within_distance_lnglat_meters`,
+  `#within_distance_ids_lnglat_meters`, `#within_distance_xy`, and
+  `#within_distance_ids_xy` using bbox prefilter plus exact distance filtering.
+- Added distance specs and benchmarks for point-to-geometry and radius queries, including
+  tiny-index/full-extent radius cases and distance receiver memory-accounting checks.
+
+### Clarified
+
+- lng/lat distance is approximate local equirectangular meters for local geofencing,
+  not geodesic distance; GeoJSON segments remain straight coordinate segments.
+- The lng/lat metric is raw planar and does not wrap or split at the antimeridian.
+- Distance query methods keep the GVL and do not claim Falcon/Async/Ractor behavior.
+
 ## 0.3.1 - 28.05.2026
 
 ### Changed

data/README.md

@@ -188,6 +188,46 @@ Predicate direction is explicit:
 
 Results are ids only and preserve insertion order. Duplicate ids remain possible if duplicate ids were inserted.
 
+
+
+## Point-to-geometry distance
+
+`TG::Geometry::Geom` exposes explicit point distance APIs. Units are encoded in the method names; there is no `metric:` option and no automatic lng/lat-vs-XY detection.
+
+```ruby
+zone.distance_to_lnglat_meters(lng, lat)          # => Float, approximate meters
+zone.boundary_distance_to_lnglat_meters(lng, lat) # => Float, approximate meters
+zone.nearest_point_lnglat(lng, lat)               # => [lng, lat]
+
+zone.distance_to_xy(x, y)                         # => Float in input coordinate units
+zone.boundary_distance_to_xy(x, y)                # => Float in input coordinate units
+zone.nearest_point_xy(x, y)                       # => [x, y]
+```
+
+For areal geometries (`Polygon`, `MultiPolygon`, and areal collection members), `distance_to_*` returns `0.0` for points inside the covered area or on the boundary. Holes are excluded, so a point inside a hole measures to the nearest hole ring. `boundary_distance_to_*` always measures to the nearest boundary/ring/segment; for an interior point it does not return `0.0` merely because the point is covered. `nearest_point_*` returns the nearest boundary point for areal geometries, including interior queries.
+
+Distance methods for lng/lat geometries return approximate meters using a per-query local equirectangular frame. Segments are GeoJSON straight coordinate segments, not great-circle arcs. This is geofencing-grade metric distance, not geodesy. Accuracy is intended for local geofencing and degrades with latitude separation.
+
+The lng/lat metric is raw planar lng/lat and does not wrap longitude at `+/-180`. A point at `179.9` and a point at `-179.9` are treated as about `360` degrees apart, matching the gem's planar `covers_xy?` model. Data that crosses the antimeridian should be cut at `+/-180` before import.
+
+`Index` supports radius filters with an rtree bbox prefilter followed by exact distance filtering:
+
+```ruby
+index.within_distance_lnglat_meters(lng, lat, radius_m, sort: false)
+# => [[id, distance_m], ...]
+index.within_distance_ids_lnglat_meters(lng, lat, radius_m)
+# => [id, ...]
+
+index.within_distance_xy(x, y, radius, sort: false)
+# => [[id, distance], ...]
+index.within_distance_ids_xy(x, y, radius)
+# => [id, ...]
+```
+
+`sort: true` sorts filtered `[id, distance]` pairs by ascending distance. The ids variants intentionally do not accept `sort:`. Index kNN / `nearest_ids` is not implemented.
+
+Distance radius benchmarks compare `rtree prefilter + exact filter` against a brute-force full index scan. Any ratio from those benchmarks is a prefilter-vs-full-scan result, not a claim that the exact distance calculation itself is hundreds of times faster. The benchmark suite includes tiny-index/full-extent cases where the rtree prefilter may be neutral or slower.
+
 ## GeoJSON FeatureSource
 
 `TG::Geometry::FeatureSource` reads GeoJSON `FeatureCollection` sources without `JSON.parse` of the whole document into Ruby Hash/Array objects.
@@ -345,7 +385,7 @@ Not included:
 - Z/M variants of array constructors;
 - Public `release_gvl:` option.
 
-TG works in planar XY coordinates. If lon/lat coordinates are passed in, length, area, perimeter, and nearest-segment distances are in input coordinate units, not meters.
+TG works in planar XY coordinates. If lon/lat coordinates are passed in, length, area, perimeter, and low-level nearest-segment distances are in input coordinate units, not meters. The explicit `*_lnglat_meters` point-to-geometry APIs are the exception: they return approximate local meters using the query-local frame documented above, not geodesic meters.
 
 ## Development
 

data/benchmark/_support.rb

@@ -292,7 +292,7 @@ module TGGeometryBench
     :rect_index, :rect,
     :segments, :target_bytes, :payload_bytes,
     :points_per_batch, :threads,
-    :entries, :rebuilds, :cycle
+    :entries, :rebuilds, :cycle, :receiver
   ].freeze
 
   TABLE_METRIC_COLUMNS = [
@@ -302,7 +302,8 @@ module TGGeometryBench
     :iterations, :operations,
     :geom_memsize, :flat_memsize, :rtree_memsize, :rtree_over_flat,
     :start_rss_kb, :peak_rss_kb, :finish_rss_kb, :drift_kb, :max_drift_kb,
-    :elapsed_sec, :queries, :sample_count, :rss_kb
+    :elapsed_sec, :queries, :sample_count, :rss_kb,
+    :before_memsize, :after_memsize, :delta_memsize, :allocated_objects
   ].freeze
 
   TABLE_INTERNAL_COLUMNS = [
@@ -348,6 +349,7 @@ module TGGeometryBench
     rebuilds: "rebuilds",
     queries: "queries",
     cycle: "cycle",
+    receiver: "receiver",
     rss_kb: "rss KB",
     geom_memsize: "geom B",
     flat_memsize: "flat B",
@@ -359,7 +361,11 @@ module TGGeometryBench
     drift_kb: "drift KB",
     max_drift_kb: "max drift KB",
     elapsed_sec: "elapsed s",
-    sample_count: "samples"
+    sample_count: "samples",
+    before_memsize: "before B",
+    after_memsize: "after B",
+    delta_memsize: "delta B",
+    allocated_objects: "alloc objs"
   }.freeze
 
   def human_int(value)
@@ -407,7 +413,8 @@ module TGGeometryBench
          :rss_kb, :geom_memsize, :flat_memsize, :rtree_memsize, :rtree_over_flat,
          :start_rss_kb, :peak_rss_kb, :finish_rss_kb, :drift_kb, :max_drift_kb,
          :target_bytes, :payload_bytes, :segments, :points_per_batch, :threads,
-         :sample_count, :median_minor_gc, :median_major_gc
+         :sample_count, :median_minor_gc, :median_major_gc,
+         :before_memsize, :after_memsize, :delta_memsize, :allocated_objects
       human_int(value)
     when :full, :adaptive, :gc_disabled
       value ? "yes" : "no"

data/benchmark/distance_memory_accounting.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+require "objspace"
+
+TGGeometryBench.say_header("distance_memory_accounting")
+
+geom = TG::Geometry.polygon([[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]])
+index = TG::Geometry::Index.build([[:zone, geom]], via: :geom, strategy: :rtree)
+
+CASES = [
+  ["geom_distance_to_xy", "Geom", geom, -> { geom.distance_to_xy(5, 5) }],
+  ["geom_boundary_distance_to_xy", "Geom", geom, -> { geom.boundary_distance_to_xy(5, 5) }],
+  ["geom_nearest_point_xy", "Geom", geom, -> { geom.nearest_point_xy(5, 5) }],
+  ["geom_distance_to_lnglat_meters", "Geom", geom, -> { geom.distance_to_lnglat_meters(0.01, 0.01) }],
+  ["index_within_distance_xy", "Index", index, -> { index.within_distance_xy(5, 5, 10) }],
+  ["index_within_distance_lnglat_meters", "Index", index, -> { index.within_distance_lnglat_meters(0.01, 0.01, 2_000) }]
+].freeze
+
+ITERATIONS = TGGeometryBench.env_integer("TGEOMETRY_DISTANCE_MEMORY_ITERATIONS", 10_000, min: 1)
+
+CASES.each do |name, receiver_name, receiver, callable|
+  TGGeometryBench.gc_start
+  before_memsize = ObjectSpace.memsize_of(receiver)
+  before_allocated = GC.stat[:total_allocated_objects]
+
+  ITERATIONS.times { callable.call }
+
+  TGGeometryBench.gc_start
+  after_memsize = ObjectSpace.memsize_of(receiver)
+  after_allocated = GC.stat[:total_allocated_objects]
+
+  TGGeometryBench.report(
+    "distance_memory_accounting",
+    {
+      case: name,
+      receiver: receiver_name,
+      operations: ITERATIONS,
+      before_memsize: before_memsize,
+      after_memsize: after_memsize,
+      delta_memsize: after_memsize - before_memsize,
+      allocated_objects: after_allocated - before_allocated,
+      note: "delta B must stay 0; Ruby result allocations are expected for arrays/pairs"
+    }
+  )
+end

data/benchmark/distance_point_geom.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+
+TGGeometryBench.say_header("distance_point_geom")
+
+VERTEX_COUNTS = (TGGeometryBench.full? ? [16, 128, 1_024, 8_192] : [16, 128, 1_024]).freeze
+
+def regular_polygon(vertex_count, radius: 1.0)
+  points = vertex_count.times.map do |i|
+    angle = (2.0 * Math::PI * i) / vertex_count
+    [Math.cos(angle) * radius, Math.sin(angle) * radius]
+  end
+  points << points.first
+  TG::Geometry.polygon(points)
+end
+
+def zigzag_line(vertex_count, scale: 1.0)
+  points = vertex_count.times.map { |i| [i.to_f * scale, (i.even? ? 0.0 : 1.0) * scale] }
+  TG::Geometry.line_string(points)
+end
+
+VERTEX_COUNTS.each do |vertices|
+  geometries = {
+    polygon_xy: regular_polygon(vertices, radius: 10.0),
+    line_xy: zigzag_line(vertices),
+    polygon_lnglat_meters: regular_polygon(vertices, radius: 0.01),
+    line_lnglat_meters: zigzag_line(vertices, scale: 0.0001)
+  }
+
+  geometries.each do |kind, geom|
+    method, args = case kind
+                   when :polygon_xy then [:distance_to_xy, [20.0, 0.0]]
+                   when :line_xy then [:distance_to_xy, [vertices / 2.0, 5.0]]
+                   when :polygon_lnglat_meters then [:distance_to_lnglat_meters, [0.02, 0.0]]
+                   when :line_lnglat_meters then [:distance_to_lnglat_meters, [vertices / 20_000.0, 0.002]]
+                   end
+
+    stats = TGGeometryBench.measure_counted(initial_iterations: TGGeometryBench.initial_iterations(1_000)) do |iter|
+      iter.times { geom.public_send(method, *args) }
+    end
+
+    TGGeometryBench.report(
+      "distance_point_geom",
+      { kind: kind, n: vertices, method: method, note: "distance methods keep the GVL" },
+      stats: stats
+    )
+  end
+end

data/benchmark/distance_within_radius.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+
+TGGeometryBench.say_header("distance_within_radius")
+
+COUNTS = (TGGeometryBench.full? ? [1_000, 10_000, 50_000] : [1_000, 10_000]).freeze
+# Contract-required honesty case: tiny index + radius covering the whole data extent.
+# This shows the crossover zone where paying for the rtree prefilter may not help
+# compared to a direct full scan. The result is empirical: on some Ruby/CPU builds
+# rtree may still win, but the benchmark must expose the scenario instead of
+# only showing selective-radius wins.
+TINY_COUNTS = (TGGeometryBench.full? ? [50, 100, 250] : [50, 100]).freeze
+
+def box(x, y, size = 0.8)
+  TG::Geometry.polygon([[x, y], [x + size, y], [x + size, y + size], [x, y + size], [x, y]])
+end
+
+def entries(count)
+  count.times.map do |i|
+    x = (i % 250).to_f * 2.0
+    y = (i / 250).to_f * 2.0
+    [i, box(x, y)]
+  end
+end
+
+def brute_force(entries, x, y, radius)
+  entries.filter_map do |id, geom|
+    distance = geom.distance_to_xy(x, y)
+    [id, distance] if distance <= radius
+  end
+end
+
+def measure_radius_case(data, index, count, query_name, x, y, radius, initial:)
+  [
+    [:rtree_prefilter_exact_filter, -> { index.within_distance_xy(x, y, radius) }],
+    [:brute_force_full_scan, -> { brute_force(data, x, y, radius) }]
+  ].each do |method, callable|
+    stats = TGGeometryBench.measure_counted(initial_iterations: TGGeometryBench.initial_iterations(initial)) do |iterations|
+      iterations.times { callable.call }
+    end
+
+    TGGeometryBench.report(
+      "distance_within_radius",
+      { n: count, query: query_name, method: method, note: "prefilter vs full scan; distance radius search keeps the GVL" },
+      stats: stats
+    )
+  end
+end
+
+COUNTS.each do |count|
+  data = entries(count)
+  index = TG::Geometry::Index.build(data, via: :geom, strategy: :rtree)
+
+  {
+    selective: [10.5, 10.5, 1.0, 250],
+    broad: [150.0, 20.0, 180.0, 25]
+  }.each do |query_name, (x, y, radius, initial)|
+    measure_radius_case(data, index, count, query_name, x, y, radius, initial: initial)
+  end
+end
+
+TINY_COUNTS.each do |count|
+  data = entries(count)
+  index = TG::Geometry::Index.build(data, via: :geom, strategy: :rtree)
+
+  # Query at the tiny grid center with a radius that covers the whole generated extent.
+  max_x = ((count - 1) % 250).to_f * 2.0 + 0.8
+  max_y = ((count - 1) / 250).to_f * 2.0 + 0.8
+  x = max_x / 2.0
+  y = max_y / 2.0
+  radius = Math.hypot(max_x, max_y) + 1.0
+
+  measure_radius_case(data, index, count, :tiny_full_extent, x, y, radius, initial: 100)
+end

data/docs/BENCHMARKING.md

@@ -15,6 +15,9 @@ The repository includes these benchmark entry points:
 - `benchmark/falcon_concurrency.rb`
 - `benchmark/objectspace_memsize.rb`
 - `benchmark/rss_stability.rb`
+- `benchmark/distance_point_geom.rb`
+- `benchmark/distance_within_radius.rb`
+- `benchmark/distance_memory_accounting.rb`
 
 Run after compiling the extension:
 
@@ -42,7 +45,11 @@ Benchmark generators cover:
 - flat vs rtree;
 - scalar vs packed batch;
 - parse small/medium/large geometry strings;
-- RSS stability over repeated build/query/free.
+- RSS stability over repeated build/query/free;
+- point-to-geometry distance over different vertex counts;
+- radius search as `rtree prefilter + exact filter` versus brute-force full index scan;
+- tiny-index/full-extent radius cases where the rtree prefilter may not help;
+- distance receiver memory accounting before and after repeated calls.
 
 ## Output format
 
@@ -54,6 +61,26 @@ kind=compact n=1000 query=point lon=0.4 lat=0.4 flat_sec=... rtree_sec=... flat_
 
 These records are intentionally plain text so they can be redirected to files and compared across machines.
 
+
+## Distance benchmarks
+
+`benchmark/distance_point_geom.rb` measures point-to-geometry distance method cost over geometries with different vertex counts. The `*_lnglat_meters` rows measure the local equirectangular frame overhead; they are not geodesic benchmarks.
+
+`benchmark/distance_within_radius.rb` compares two query strategies:
+
+- `rtree_prefilter_exact_filter`: existing rtree bbox prefilter followed by exact distance filtering;
+- `brute_force_full_scan`: direct scan over every geometry with the same exact distance method.
+
+Any speedup ratio from this script is a prefilter-vs-full-scan result. It must not be described as “distance is N times faster”. The benchmark intentionally includes selective-radius cases where the index should help and tiny-index/full-extent-radius cases where the prefilter may be neutral or slower. If rtree still wins on a machine, document that measured result instead of inventing a crossover.
+
+`benchmark/distance_memory_accounting.rb` checks `ObjectSpace.memsize_of` before and after repeated distance calls. The expected receiver `delta B` is `0`; Ruby result allocations are still expected for returned arrays and `[id, distance]` pairs.
+
+For noisy rows, especially short selective radius runs, increase timing before publishing numbers:
+
+```bash
+TGEOMETRY_BENCH_MIN_SECONDS=1.0 bundle exec ruby benchmark/distance_within_radius.rb
+```
+
 ## No `:auto` strategy yet
 
 The first release does not expose `strategy: :auto`. Choosing a threshold requires project-owned benchmark output across the required scenario matrix. Internal rtree constants such as leaf capacity are not a flat-vs-rtree crossover threshold.

data/docs/CONCURRENCY.md

@@ -69,3 +69,11 @@ No Falcon or Async performance claim is made. `benchmark/falcon_concurrency.rb`
 ## Low-level borrowed wrappers
 
 `TG::Geometry::Line`, `TG::Geometry::Ring`, `TG::Geometry::Polygon`, and borrowed GeometryCollection child `TG::Geometry::Geom` wrappers are immutable borrowed wrappers. They do not mutate or free child TG pointers. Each wrapper marks and compacts the parent `TG::Geometry::Geom` through `geom_owner`, so the parent native geometry remains alive while a child wrapper is in use.
+
+## Distance query concurrency
+
+Point-to-geometry distance methods are read-only over immutable `Geom` and `Index` objects. They do not mutate geometry, mutate index entries, cache query state on receivers, or add persistent native memory. They do not call `rb_gc_adjust_memory_usage`.
+
+`Index#within_distance_*` uses rtree callbacks only to mark candidate ordinals in C memory. Ruby arrays and `[id, distance]` pairs are materialized after `rtree_search` returns under the GVL. The callback safety rules above apply unchanged.
+
+Distance methods deliberately keep the GVL. Do not treat them as no-GVL, Falcon/Async-aware, or Ractor-shareable APIs.

data/docs/GEOMETRY_QUERIES.md

@@ -21,3 +21,45 @@ It does not affect `intersecting_geom_ids`, `covering_geom_ids`, or `containing_
 Results are arrays of ids in insertion order. Duplicate ids are preserved if duplicate ids were inserted.
 
 In v0.3.0 these operations run under the GVL. The heavy C phase is structured without Ruby API calls so it can be made no-GVL-safe later after benchmarking, but there is no public `release_gvl:` knob.
+
+## Point-to-geometry distance queries
+
+Distance APIs are intentionally split by unit/model:
+
+| Receiver | Method | Units / result |
+| --- | --- | --- |
+| `Geom` | `distance_to_lnglat_meters(lng, lat)` | `Float`, approximate meters |
+| `Geom` | `boundary_distance_to_lnglat_meters(lng, lat)` | `Float`, approximate meters to nearest boundary/segment/point |
+| `Geom` | `nearest_point_lnglat(lng, lat)` | `[lng, lat]`, raw planar nearest point |
+| `Geom` | `distance_to_xy(x, y)` | `Float`, input coordinate units |
+| `Geom` | `boundary_distance_to_xy(x, y)` | `Float`, input coordinate units |
+| `Geom` | `nearest_point_xy(x, y)` | `[x, y]`, input coordinate units |
+| `Index` | `within_distance_lnglat_meters(lng, lat, radius_m, sort: false)` | `[[id, distance_m], ...]` |
+| `Index` | `within_distance_ids_lnglat_meters(lng, lat, radius_m)` | `[id, ...]` |
+| `Index` | `within_distance_xy(x, y, radius, sort: false)` | `[[id, distance], ...]` |
+| `Index` | `within_distance_ids_xy(x, y, radius)` | `[id, ...]` |
+
+Coordinate order is always `(lng, lat)` for `*_lnglat_meters` and `(x, y)` for `*_xy`. There is no `metric:` keyword and no automatic coordinate-system detection.
+
+Areal geometry semantics:
+
+- `Polygon`, `MultiPolygon`, and areal `GeometryCollection` members return `0.0` from `distance_to_*` when the query point is inside the covered area or on the boundary.
+- Holes are excluded: a point inside a hole measures to the nearest hole-ring segment.
+- `boundary_distance_to_*` always measures to the nearest boundary/ring/segment. For an interior point it does not return `0.0` merely because the point is covered.
+- `nearest_point_*` returns the nearest boundary point for areal types, including interior queries.
+
+Non-areal geometry semantics:
+
+- `Point` / `MultiPoint` measure to the nearest point.
+- `LineString` / `MultiLineString` measure to the nearest segment.
+- `GeometryCollection` returns the minimum over measurable members; empty members are skipped. A geometry with no measurable component raises `TG::Geometry::ArgumentError`.
+
+Distance methods for lng/lat geometries return approximate meters using a per-query local equirectangular frame. Segments are GeoJSON straight coordinate segments, not great-circle arcs. This is geofencing-grade metric distance, not geodesy. Accuracy is intended for local geofencing and degrades with latitude separation.
+
+The lng/lat metric is raw planar lng/lat. It does not wrap longitude at `+/-180`, does not split antimeridian boxes, and does not normalize returned `nearest_point_lnglat` longitudes. A geometry near `179.9` and a query near `-179.9` are treated as far apart in raw planar coordinates, consistent with `covers_xy?`. Cut antimeridian-crossing data at `+/-180` before import.
+
+`Index#within_distance_*` uses two phases: one bbox prefilter through the existing index path and one exact distance filter over candidates. The returned distance is the exact filter value; it is not discarded and recomputed later. `sort: true` sorts the filtered pair array by ascending distance. The ids-only variants intentionally reject `sort:`.
+
+Radius-query benchmarks should be read as `rtree prefilter + exact filter` versus brute-force full index scan. They measure the value of avoiding a full scan for selective radii, not a standalone speedup of the exact distance primitive. Tiny indexes and radii covering the whole data extent are benchmarked separately because the prefilter can become neutral or slower there.
+
+No kNN, `nearest_ids`, rtree nearest traversal, projection/reprojection, signed distance, geometry-to-geometry distance, or geodesic distance is implemented by these APIs.

data/docs/LIMITATIONS.md

@@ -22,3 +22,15 @@ TG works in planar XY coordinates. If lon/lat coordinates are passed in, length,
 FeatureSource reads the full source into memory. It avoids a Ruby `JSON.parse` object tree, but it is not a streaming backend. There is no gzip, NDGeoJSON, GeoJSONSeq, or FlatGeobuf support.
 
 FeatureSource returns raw properties JSON strings. It does not parse properties into Ruby Hash objects.
+
+## Distance limitations
+
+`*_lnglat_meters` distance methods are approximate local-meter helpers for geofencing. They use a per-query local equirectangular frame anchored at the query latitude. Segments are GeoJSON straight coordinate segments, not great-circle arcs. Accuracy is intended for local geofencing and degrades with latitude separation. This is not geodesy.
+
+The metric is raw planar lng/lat and does not wrap longitude at `+/-180`. Cross-antimeridian proximity is not detected: `179.9` and `-179.9` are treated as roughly `360` degrees apart. This matches the rest of the gem's planar model and `covers_xy?` behavior. Data that legitimately crosses the antimeridian should be cut at `+/-180` before import.
+
+Near the poles, longitude scale approaches zero. Distance methods remain finite and avoid NaN/Inf, but the local frame understates longitude distance. Radius queries near poles may therefore include accepted false positives relative to real geodesy; that is an accuracy limitation of the planar metric, not a geodesic guarantee.
+
+`*_xy` distance methods never convert units. They return input coordinate units.
+
+Distance queries keep the GVL. There is no no-GVL, Falcon, Async, Ractor, projection/reprojection, kNN, `nearest_ids`, signed distance, polygon-to-polygon distance, or geometry-to-geometry distance support in this feature.