tg_geometry 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cde617c534a8a3d9702b3fe212d46f966da46224499bb4fcb97bf40865590be8
-  data.tar.gz: 7e1767d31814249ef695ceae1965d6c5aaf9065ff7595309e95698abc053abbc
+  metadata.gz: 27136bafb4a0114a2921af0413c047391bfffb38a6ff41f6c4f011f7cf4ab2ad
+  data.tar.gz: 7b2148e42f78fa74b3d5ac41e492e78673dd2617aa887c0023affcfa8fe555bf
 SHA512:
-  metadata.gz: 2cf6070d21ca5342425600e436523aae7215a2792d2d8392662a6c5257ba4e178301ff2a93c5ebb847fc7606d7b1aad60b9ab1fcd8e21b67f06d5f72f8c3cfa1
-  data.tar.gz: 99a9f9c086c6a2da9add012f57a99de800f67846007503ddf6c5d63ec25ac2a6d62cfe5b854fe1d44976ff0bddcbce04b8831db631dd8d174602c64914190e30
+  metadata.gz: e91a5dd12b3240540e9f6171c9c8a3c0f959d9e24779e392ae6c02c2e478712d2585bff5e37b3524bdf7d3b8581ebb30e14029b4aa038eb549229f92f0eee388
+  data.tar.gz: 806918f8eaaa7025b0693ef07e6d244e37cdb4998ff4cc5845a752c4b200f2cb341391a43f37afbdb696525e18d3415f55833c8d09712c31161eb2e879e179f5

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.3.3 - 28.10.2026
+
+### Changed
+
+- Updated vendored `tidwall/tg`, `rtree.c` to v0.6.1, and `json.c` to pinned upstream revisions.
+- Vendor sync now removes trailing whitespace from C sources and headers.
+
+### Fixed
+
+- Avoided querying TG parse errors when geometry allocation fails in FeatureSource.
+- Corrected JSON UTF-16 surrogate boundary handling through the updated `json.c` vendor.
+
+## 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

@@ -8,7 +8,25 @@ It exposes the public Ruby namespace `TG::Geometry`:
 require "tg/geometry"
 ```
 
-The gem is focused on fast in-process planar geometry parsing, predicates, format conversion, GeoJSON FeatureCollection imports, and immutable geofencing indexes. It is not a full GIS system.
+The gem is focused on fast in-process planar geometry parsing, predicates, format conversion, GeoJSON FeatureCollection imports, point-to-geometry distance queries, and immutable geofencing indexes. It is not a full GIS system.
+
+## Start here
+
+For runnable examples, use **[GET_STARTED.md](GET_STARTED.md)**.
+
+That guide shows the normal path from install to real queries:
+
+- parsing GeoJSON/WKT/WKB/Hex/GeoBIN;
+- direct Ruby constructors;
+- immutable `Index` builds;
+- point geofencing queries;
+- packed batch point queries;
+- point-to-geometry distance in planar XY and approximate lon/lat meters;
+- GeoJSON FeatureCollection imports;
+- SRID/EWKB conversion;
+- nearest segment helpers;
+- Registry and optional ActiveRecord integration;
+- safe immutable-index reload pattern.
 
 ## Installation
 
@@ -26,277 +44,86 @@ The extension builds from vendored C sources. It does not require GEOS, PostGIS,
 
 Supported platforms: Linux and macOS on x86_64/aarch64. Windows is not supported for the first release.
 
-## Parsing and predicates
-
-```ruby
-zone = TG::Geometry.parse_geojson(<<~JSON)
-  {
-    "type": "Polygon",
-    "coordinates": [[[0,0], [10,0], [10,10], [0,10], [0,0]]]
-  }
-JSON
-
-zone.frozen?          # => true
-zone.type             # => :polygon
-zone.covers_xy?(5, 5) # => true
-zone.covers_xy?(0, 0) # => true, boundary is covered
-zone.bbox             # => #<TG::Geometry::Rect ...>
-zone.to_wkt
-zone.to_wkb
-```
-
-Parse shortcuts:
-
-```ruby
-TG::Geometry.parse(str, format: :auto, index: :ystripes)
-TG::Geometry.parse_geojson(str, index: :ystripes)
-TG::Geometry.parse_wkt(str, index: :ystripes)
-TG::Geometry.parse_wkb(bytes, index: :ystripes)
-TG::Geometry.parse_hex(str, index: :ystripes)
-TG::Geometry.parse_geobin(bytes, index: :ystripes)
-```
-
-`TG::Geometry::Geom` objects are immutable and cannot be manually allocated or manually freed from Ruby.
-
-## Constructors
-
-Construct simple planar geometries directly from Ruby arrays without parsing strings or bytes:
-
-```ruby
-line = TG::Geometry.line_string([[0.0, 0.0], [10.0, 0.0]], index: :natural, srid: 4326)
-poly = TG::Geometry.polygon(
-  [[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]],
-  holes: [[[2, 2], [4, 2], [4, 4], [2, 4], [2, 2]]],
-  index: :ystripes,
-  srid: 4326
-)
-mp = TG::Geometry.multi_polygon([
-  { exterior: [[0, 0], [1, 0], [1, 1], [0, 0]], holes: [] },
-  [[10, 10], [11, 10], [11, 11], [10, 10]]
-])
-```
-
-Constructors are strict: rings must already be closed, invalid coordinates raise `TG::Geometry::ArgumentError`, and no winding/self-intersection fixes are performed. `srid:` is metadata on the wrapper; it does not alter coordinates or perform reprojection.
-
-## SRID and EWKB
-
-`parse_wkb` and `parse_hex` preserve EWKB SRID metadata when the EWKB SRID flag is present:
-
-```ruby
-geom = TG::Geometry.parse_wkb(postgis_bytea)
-geom.srid # => 4326, 3857, 0, or nil for plain WKB
-```
-
-`to_wkb` always writes plain WKB. Use `to_ewkb` when a PostGIS-compatible SRID-bearing payload is required:
-
-```ruby
-ewkb = geom.to_ewkb              # uses geom.srid
-ewkb = geom.to_ewkb(srid: 4326)  # explicit override
-```
-
-SRID is metadata only. `tg_geometry` does not check SRID compatibility, transform coordinates, or calculate geodesic distances.
-
-## Rect
-
-```ruby
-rect = TG::Geometry::Rect.new(0, 0, 10, 10)
-rect.center                  # => [5.0, 5.0]
-rect.contains_point?(5, 5)   # => true
-rect.intersects?(other_rect)
-rect.expand_to_include(other_rect)
-rect.expand_to_include_point(x, y)
-```
-
-`Rect` rejects non-finite coordinates and invalid coordinate order. It is frozen after construction.
+## API map
 
-## Immutable Index
+This README intentionally stays compact. The runnable examples live in [GET_STARTED.md](GET_STARTED.md); deeper design notes live in `docs/`.
 
-```ruby
-entries = [
-  [:zone_a, '{"type":"Polygon","coordinates":[[[0,0],[10,0],[10,10],[0,10],[0,0]]]}'],
-  [:zone_b, '{"type":"Polygon","coordinates":[[[20,20],[30,20],[30,30],[20,30],[20,20]]]}']
-]
-
-index = TG::Geometry::Index.build(
-  entries,
-  via: :geojson,
-  strategy: :rtree,
-  predicate: :covers,
-  geometry_index: :ystripes
-)
-
-index.frozen?               # => true
-index.size                  # => 2
-index.strategy              # => :rtree
-index.predicate             # => :covers
-index.find_covering(5, 5)   # => :zone_a
-index.covering_ids(5, 5)    # => [:zone_a]
-index.intersecting_rect(0, 0, 25, 25)
-```
+### Parsing and format conversion
 
-Accepted input shape:
+`TG::Geometry.parse` auto-detects GeoJSON, WKT, WKB, Hex, and GeoBIN. Explicit shortcuts are also available: `parse_geojson`, `parse_wkt`, `parse_wkb`, `parse_hex`, and `parse_geobin`.
 
-```ruby
-[[id1, object1], [id2, object2], ...]
-```
+`TG::Geometry::Geom` objects are immutable and can be converted back to WKT/WKB/GeoJSON where supported.
 
-Rules:
+See [GET_STARTED.md#2-parse-a-geometry](GET_STARTED.md#2-parse-a-geometry).
 
-- `entries` must be an Array.
-- Every entry must be a two-element Array.
-- `id` may be any Ruby object except `nil`.
-- Duplicate ids are allowed.
-- Returned ids are the same Ruby objects stored in the index.
-- Result order is insertion order for both `:flat` and `:rtree`.
+### Constructors
 
-Accepted `via:` modes:
+Planar geometries can be constructed directly from Ruby arrays without parsing strings or bytes: point, multipoint, line string, polygon, multiline, multipolygon, and geometry collection helpers are available.
 
-- `:geom` — borrow an existing `TG::Geometry::Geom` and keep its owner alive.
-- `:geojson` — parse and own native TG geometries inside the index.
-- `:wkb` — parse and own native TG geometries inside the index.
+See [GET_STARTED.md#3-construct-geometries-directly](GET_STARTED.md#3-construct-geometries-directly).
 
-Accepted strategies:
+### SRID and EWKB
 
-- `:flat`
-- `:rtree`
+EWKB SRID metadata is preserved on parse when present. `to_wkb` writes plain WKB; `to_ewkb` writes a PostGIS-compatible SRID-bearing payload. SRID is metadata only: no coordinate transformation is performed.
 
-Accepted predicates:
+See [GET_STARTED.md#8-preserve-srid-and-write-ewkb](GET_STARTED.md#8-preserve-srid-and-write-ewkb) and [docs/SRID_AND_EWKB.md](docs/SRID_AND_EWKB.md).
 
-- `:covers` — default for geofencing; boundary points are included.
-- `:contains` — stricter containment semantics.
+### Rect
 
-The `predicate:` option affects only the legacy point-based query methods (`find_covering`, `covering_ids(x, y)`, `covering_ids_batch_packed`). The geometry-based query methods (`intersecting_geom_ids`, `covering_geom_ids`, `containing_geom_ids`) use their own predicates based on the method name.
+`TG::Geometry::Rect` is an immutable helper for bounding boxes, containment checks, intersections, and expansion.
 
-`strategy: :auto` is intentionally not exposed. Choose the strategy explicitly and benchmark on your own data.
+See [GET_STARTED.md#4-use-rect-helpers](GET_STARTED.md#4-use-rect-helpers).
 
-## Geometry-based index queries
+### Immutable Index
 
-```ruby
-query = TG::Geometry.polygon([[1, 1], [2, 1], [2, 2], [1, 1]])
-index.intersecting_geom_ids(query)
-index.covering_geom_ids(query)
-index.containing_geom_ids(query)
-```
+`TG::Geometry::Index` stores immutable entries with explicit `via:`, `strategy:`, and `predicate:` options. `:rtree` builds a spatial index; `:flat` does a linear scan with bbox prefiltering. There is no `:auto` strategy by design.
 
-Predicate direction is explicit:
+See [GET_STARTED.md#5-build-an-immutable-index](GET_STARTED.md#5-build-an-immutable-index).
 
-| Method | Predicate direction | Boundary semantics |
-| --- | --- | --- |
-| `intersecting_geom_ids(query)` | stored geom intersects query | any intersection |
-| `covering_geom_ids(query)` | stored geom covers query | boundary included |
-| `containing_geom_ids(query)` | stored geom contains query | strict interior; boundary excluded |
+### Point and geometry queries
 
-Results are ids only and preserve insertion order. Duplicate ids remain possible if duplicate ids were inserted.
+Index methods cover point geofencing, packed batch point queries, rectangle intersection, and geometry-vs-geometry predicates.
 
-## GeoJSON FeatureSource
+See:
 
-`TG::Geometry::FeatureSource` reads GeoJSON `FeatureCollection` sources without `JSON.parse` of the whole document into Ruby Hash/Array objects.
+- [GET_STARTED.md#5-build-an-immutable-index](GET_STARTED.md#5-build-an-immutable-index)
+- [GET_STARTED.md#6-batch-point-queries](GET_STARTED.md#6-batch-point-queries)
+- [docs/GEOMETRY_QUERIES.md](docs/GEOMETRY_QUERIES.md)
 
-```ruby
-entries = TG::Geometry::FeatureSource.read_entries_file(
-  "zones.geojson",
-  id: ["properties", "@id"],
-  only: [:polygon, :multipolygon]
-)
-
-index = TG::Geometry::Index.build(
-  entries,
-  via: :geojson,
-  strategy: :rtree,
-  predicate: :covers
-)
-```
+### Point-to-geometry distance
 
-For imports that also need raw properties JSON:
+Distance APIs are explicit about units:
 
-```ruby
-features = TG::Geometry::FeatureSource.read_features_file(
-  "zones.geojson",
-  id: ["properties", "@id"],
-  report: true,
-  on_invalid: :skip
-)
-
-features[:features].each do |id, geometry_json, properties_json|
-  # Store geometry_json and parse properties_json in application code if needed.
-end
-```
+- `*_xy` returns input coordinate units;
+- `*_lnglat_meters` returns approximate local meters for lon/lat geofencing.
 
-For direct file-to-index loading:
+There is no `metric:` option, no automatic lon/lat-vs-XY detection, no kNN index, and no geodesic/great-circle segment distance.
 
-```ruby
-index = TG::Geometry::FeatureSource.build_index_file(
-  "zones.geojson",
-  id: ["properties", "@id"],
-  strategy: :rtree,
-  predicate: :covers
-)
-```
+See [GET_STARTED.md#7-measure-distance-to-a-zone](GET_STARTED.md#7-measure-distance-to-a-zone) and [docs/GEOMETRY_QUERIES.md](docs/GEOMETRY_QUERIES.md).
 
-FeatureSource methods are explicit: use `_file` for paths, `_json` for raw content strings, and `_io` for IO objects. There is no path/content auto-detection.
+### GeoJSON FeatureSource
 
-## Packed batch point queries
+`TG::Geometry::FeatureSource` reads GeoJSON `FeatureCollection` sources without `JSON.parse` of the whole document into Ruby Hash/Array objects. It can return index entries, feature triples with raw properties JSON, reports, or build an index directly.
 
-```ruby
-points = [5.0, 5.0, 25.0, 25.0].pack("d*")
-index.covering_ids_batch_packed(points)
-# => [:zone_a, :zone_b]
-```
+See [GET_STARTED.md#9-import-a-geojson-featurecollection](GET_STARTED.md#9-import-a-geojson-featurecollection) and [docs/FEATURE_SOURCE.md](docs/FEATURE_SOURCE.md).
 
-Input is a Ruby String containing native-endian doubles in `lon, lat` pairs. Length must be a multiple of 16 bytes. Empty string returns `[]`.
+### Nearest segment
 
-## Nearest segment
+`Line#nearest_segment(x, y)` and `Ring#nearest_segment(x, y)` expose low-level planar nearest-segment helpers.
 
-`Line#nearest_segment(x, y)` and `Ring#nearest_segment(x, y)` return a frozen `TG::Geometry::NearestSegment`:
+See [GET_STARTED.md#10-use-nearest-segment-helpers](GET_STARTED.md#10-use-nearest-segment-helpers) and [docs/NEAREST_SEGMENT.md](docs/NEAREST_SEGMENT.md).
 
-```ruby
-nearest = polygon.polygon.exterior_ring.nearest_segment(5, 5)
-nearest.segment   # => TG::Geometry::Segment
-nearest.index     # => segment index
-nearest.distance  # => Float
-nearest.point     # => [x, y] projection on the segment
-```
+### Registry helper
 
-Distance is planar Euclidean distance in input coordinate units. It is not meters unless your input coordinates are already meters. Equal-distance tie-breaks follow tg iteration order and are not API-stable.
+`TG::Geometry::Registry` is Ruby-level sugar over immutable indexes with safe reload semantics.
 
-## Registry helper
+See [GET_STARTED.md#11-wrap-an-index-in-a-registry](GET_STARTED.md#11-wrap-an-index-in-a-registry).
 
-`Registry` is Ruby-level sugar over immutable indexes:
+### Optional ActiveRecord integration
 
-```ruby
-class DeliveryZones < TG::Geometry::Registry
-  source do
-    [
-      [:zone_a, '{"type":"Polygon","coordinates":[[[0,0],[10,0],[10,10],[0,10],[0,0]]]}']
-    ]
-  end
-
-  index_options via: :geojson, strategy: :rtree, predicate: :covers
-end
-
-registry = DeliveryZones.new
-registry.reload!
-registry.find_covering(5, 5)
-```
-
-Reload builds a new immutable index first and swaps the reference only after a successful build. Existing readers keep using the previous index safely.
-
-## ActiveRecord integration — read-only
-
-`TG::Geometry::ActiveRecordType` is an optional read-only convenience type for PostGIS columns. It is not required by `tg/geometry`; load it explicitly:
-
-```ruby
-require "tg/geometry/active_record_type"
-
-class Zone < ApplicationRecord
-  attribute :geom, TG::Geometry::ActiveRecordType.new
-end
-
-zone.geom.srid
-zone.geom.covers_xy?(lon, lat)
-```
+`TG::Geometry::ActiveRecordType` is an optional read-only convenience type for PostGIS-like geometry columns. It is not required by `tg/geometry`; load it explicitly.
 
-It can deserialize EWKB bytes, hex EWKB, `\x`-prefixed hex EWKB, GeoJSON, and WKT. Writing `Geom` values is intentionally unsupported in v0.3.0. User applications need `activemodel >= 6.0`; `activerecord` is not a gem dependency.
+See [GET_STARTED.md#12-optional-activerecord-read-only-type](GET_STARTED.md#12-optional-activerecord-read-only-type).
 
 ## Memory and concurrency
 
@@ -306,25 +133,13 @@ The implementation uses explicit allocator pairs and Ruby GC accounting for nati
 
 No Ractor support and no universal performance claim are advertised.
 
-## Benchmarks
+See [docs/MEMORY_OWNERSHIP.md](docs/MEMORY_OWNERSHIP.md) and [docs/CONCURRENCY.md](docs/CONCURRENCY.md).
 
-Benchmark scripts live in `benchmark/`:
+## Benchmarks
 
-```bash
-bundle exec ruby benchmark/parse_throughput.rb
-bundle exec ruby benchmark/flat_vs_rtree.rb
-bundle exec ruby benchmark/batch_packed_vs_loop.rb
-bundle exec ruby benchmark/objectspace_memsize.rb
-bundle exec ruby benchmark/rss_stability.rb
-bundle exec ruby benchmark/gvl_threshold.rb
-bundle exec ruby benchmark/falcon_concurrency.rb
-bundle exec ruby benchmark/feature_source.rb
-bundle exec ruby benchmark/geom_query.rb
-bundle exec ruby benchmark/nearest_segment.rb
-bundle exec ruby benchmark/ewkb_roundtrip.rb
-```
+Benchmark scripts live in `benchmark/`. They are engineering tools, not marketing claims.
 
-The benchmarks are engineering tools, not marketing claims.
+Start with [docs/BENCHMARKING.md](docs/BENCHMARKING.md).
 
 ## Limitations
 
@@ -345,7 +160,21 @@ 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 a query-local equirectangular frame, not geodesic meters.
+
+See [docs/LIMITATIONS.md](docs/LIMITATIONS.md) for the full list.
+
+## Documentation
+
+- [GET_STARTED.md](GET_STARTED.md) — runnable examples
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — how the C extension is wired
+- [docs/MEMORY_OWNERSHIP.md](docs/MEMORY_OWNERSHIP.md) — allocator pair table
+- [docs/CONCURRENCY.md](docs/CONCURRENCY.md) — threading rules
+- [docs/ERROR_HANDLING.md](docs/ERROR_HANDLING.md) — exception hierarchy
+- [docs/BENCHMARKING.md](docs/BENCHMARKING.md) — running the benchmark scripts
+- [docs/FEATURE_SOURCE.md](docs/FEATURE_SOURCE.md) — GeoJSON FeatureCollection imports
+- [docs/GEOMETRY_QUERIES.md](docs/GEOMETRY_QUERIES.md) — geometry query details
+- [docs/LIMITATIONS.md](docs/LIMITATIONS.md) — non-goals and accuracy boundaries
 
 ## Development
 
@@ -362,6 +191,7 @@ bundle exec rspec spec/batch_packed_spec.rb
 bundle exec rspec spec/memory_gc_spec.rb
 bundle exec rspec spec/concurrency_spec.rb
 bundle exec rspec spec/fuzz_spec.rb
+bundle exec rspec spec/distance_spec.rb
 ```
 
 ## License

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