tg_geometry 0.2.0 → 0.3.1

data/benchmark/batch_packed_vs_loop.rb

@@ -3,25 +3,57 @@
 require_relative "_support"
 
 TGGeometryBench.say_header("batch_packed_vs_loop")
-iterations = TGGeometryBench.iterations(500)
+points_per_batch = TGGeometryBench.env_integer("TGEOMETRY_BENCH_BATCH_POINTS", 1_000, min: 1)
 
 %i[compact long_thin overlapping].each do |kind|
   TGGeometryBench.sizes.each do |size|
     entries = TGGeometryBench.entries_for(kind, size)
-    points = Array.new(1_000) { |i| TGGeometryBench.points_for(kind)[i % TGGeometryBench.points_for(kind).length] }
+    points = TGGeometryBench.repeated_points(kind, points_per_batch)
     packed = TGGeometryBench.packed_points(points)
 
     %i[flat rtree].each do |strategy|
       index = TGGeometryBench.build_index(entries, strategy: strategy)
 
-      scalar_time = Benchmark.realtime do
-        iterations.times { points.map { |lon, lat| index.find_covering(lon, lat) } }
+      scalar = TGGeometryBench.measure_counted(
+        initial_iterations: TGGeometryBench.initial_iterations(50),
+        operations_per_iteration: points.length
+      ) do |iterations|
+        iterations.times do
+          points.each { |lon, lat| index.find_covering(lon, lat) }
+        end
       end
-      batch_time = Benchmark.realtime do
+
+      batch = TGGeometryBench.measure_counted(
+        initial_iterations: TGGeometryBench.initial_iterations(50),
+        operations_per_iteration: points.length
+      ) do |iterations|
         iterations.times { index.covering_ids_batch_packed(packed) }
       end
 
-      puts "kind=#{kind} n=#{size} strategy=#{strategy} points=#{points.length} scalar_sec=%.6f batch_sec=%.6f scalar_batches_per_sec=%.2f batch_batches_per_sec=%.2f" % [scalar_time, batch_time, iterations / scalar_time, iterations / batch_time]
+      TGGeometryBench.report(
+        "batch_packed_vs_loop",
+        {
+          kind: kind,
+          n: size,
+          strategy: strategy,
+          mode: :scalar_loop,
+          points_per_batch: points.length,
+          batches_per_sec: scalar[:ops_per_sec] / points.length
+        },
+        stats: scalar
+      )
+      TGGeometryBench.report(
+        "batch_packed_vs_loop",
+        {
+          kind: kind,
+          n: size,
+          strategy: strategy,
+          mode: :packed_batch,
+          points_per_batch: points.length,
+          batches_per_sec: batch[:ops_per_sec] / points.length
+        },
+        stats: batch
+      )
     end
   end
 end

data/benchmark/ewkb_roundtrip.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+
+TGGeometryBench.say_header("ewkb_roundtrip")
+
+geom = TG::Geometry.polygon([[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]], srid: 4326)
+ewkb = geom.to_ewkb
+
+stats = TGGeometryBench.measure_counted(initial_iterations: TGGeometryBench.initial_iterations(5_000)) do |iterations|
+  iterations.times { TG::Geometry.parse_wkb(ewkb).to_ewkb }
+end
+
+TGGeometryBench.report(
+  "ewkb_roundtrip",
+  { library: :tg_geometry, operation: :parse_wkb_to_ewkb, payload_bytes: ewkb.bytesize },
+  stats: stats
+)
+
+if ENV["WITH_RGEO"]
+  begin
+    require "rgeo"
+    factory = RGeo::Cartesian.factory(srid: 4326)
+    rgeo_geom = factory.parse_wkt("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))")
+
+    rgeo_stats = TGGeometryBench.measure_counted(initial_iterations: TGGeometryBench.initial_iterations(5_000)) do |iterations|
+      iterations.times { factory.parse_wkt(rgeo_geom.as_text) }
+    end
+
+    TGGeometryBench.report(
+      "ewkb_roundtrip",
+      { library: :rgeo, operation: :wkt_parse, payload_bytes: rgeo_geom.as_text.bytesize },
+      stats: rgeo_stats
+    )
+  rescue LoadError
+    warn "rgeo is not installed"
+  end
+end

data/benchmark/falcon_concurrency.rb

@@ -3,23 +3,30 @@
 require_relative "_support"
 
 TGGeometryBench.say_header("falcon_concurrency")
-puts "No Falcon dependency is used here. This is a thread-read baseline for the immutable Index model."
-puts "Falcon/Async behavior remains an Pending decision until Roman approves a dedicated dependency/setup."
+TGGeometryBench.report("falcon_concurrency_note", note: "thread_read_baseline_only_no_falcon_dependency")
 
-entries = TGGeometryBench.compact_entries(1_000)
+entries_count = TGGeometryBench.env_integer("TGEOMETRY_BENCH_ENTRIES", 1_000, min: 1)
+threads = TGGeometryBench.env_integer("TGEOMETRY_BENCH_THREADS", 4, min: 1)
+entries = TGGeometryBench.compact_entries(entries_count)
 index = TGGeometryBench.build_index(entries, strategy: :rtree)
-threads = Integer(ENV.fetch("TGEOMETRY_BENCH_THREADS", "4"))
-iterations = TGGeometryBench.iterations(10_000)
+points = TGGeometryBench.points_for(:compact)
 
-elapsed = Benchmark.realtime do
-  threads.times.map do
+stats = TGGeometryBench.measure_counted(
+  initial_iterations: TGGeometryBench.initial_iterations(2_000),
+  operations_per_iteration: threads
+) do |iterations_per_thread|
+  threads.times.map do |thread_index|
     Thread.new do
-      iterations.times do |i|
-        lon, lat = TGGeometryBench.points_for(:compact)[i % 3]
+      iterations_per_thread.times do |i|
+        lon, lat = points[(i + thread_index) % points.length]
         index.find_covering(lon, lat)
       end
     end
   end.each(&:join)
 end
 
-puts "threads=#{threads} iterations_per_thread=#{iterations} total_queries=#{threads * iterations} seconds=%.6f qps=%.2f" % [elapsed, (threads * iterations) / elapsed]
+TGGeometryBench.report(
+  "falcon_concurrency",
+  { threads: threads, entries: entries_count, strategy: :rtree, operation: :find_covering },
+  stats: stats
+)

data/benchmark/feature_source.rb

@@ -40,7 +40,7 @@ end
 
 TGGeometryBench.say_header("feature_source")
 
-sizes = ENV["TGEOMETRY_BENCH_FULL"] == "1" ? [100, 1_000, 10_000, 50_000] : [100, 1_000]
+sizes = TGGeometryBench.full? ? [100, 1_000, 10_000, 50_000] : [100, 1_000, 10_000]
 
 sizes.each do |size|
   json = FeatureSourceBenchData.feature_collection(size)
@@ -54,38 +54,64 @@ sizes.each do |size|
     direct_index = nil
     roundtrip_index = nil
 
-    ruby_time = Benchmark.realtime do
-      ruby_entries = FeatureSourceBenchData.ruby_json_parse_entries(path)
+    ruby = TGGeometryBench.measure_counted(initial_iterations: 1, min_seconds: 0.30) do |iterations|
+      iterations.times { ruby_entries = FeatureSourceBenchData.ruby_json_parse_entries(path) }
     end
 
-    read_entries_time = Benchmark.realtime do
-      feature_entries = TG::Geometry::FeatureSource.read_entries_file(path, id: ["properties", "@id"])
+    read_entries = TGGeometryBench.measure_counted(initial_iterations: 1, min_seconds: 0.30) do |iterations|
+      iterations.times do
+        feature_entries = TG::Geometry::FeatureSource.read_entries_file(path, id: ["properties", "@id"])
+      end
     end
 
-    read_features_time = Benchmark.realtime do
-      feature_rows = TG::Geometry::FeatureSource.read_features_file(path, id: ["properties", "@id"])
+    read_features = TGGeometryBench.measure_counted(initial_iterations: 1, min_seconds: 0.30) do |iterations|
+      iterations.times do
+        feature_rows = TG::Geometry::FeatureSource.read_features_file(path, id: ["properties", "@id"])
+      end
     end
 
-    direct_index_time = Benchmark.realtime do
-      direct_index = TG::Geometry::FeatureSource.build_index_file(path, id: ["properties", "@id"], strategy: :rtree)
+    direct_index_stat = TGGeometryBench.measure_counted(initial_iterations: 1, min_seconds: 0.30) do |iterations|
+      iterations.times do
+        direct_index = TG::Geometry::FeatureSource.build_index_file(path, id: ["properties", "@id"], strategy: :rtree)
+      end
     end
 
-    roundtrip_index_time = Benchmark.realtime do
-      roundtrip_index = TG::Geometry::Index.build(feature_entries, via: :geojson, strategy: :rtree)
+    # Ensure the roundtrip benchmark does not accidentally include read_entries.
+    feature_entries ||= TG::Geometry::FeatureSource.read_entries_file(path, id: ["properties", "@id"])
+
+    roundtrip_index_stat = TGGeometryBench.measure_counted(initial_iterations: 1, min_seconds: 0.30) do |iterations|
+      iterations.times do
+        roundtrip_index = TG::Geometry::Index.build(feature_entries, via: :geojson, strategy: :rtree)
+      end
     end
 
-    puts "n=#{size} ruby_json_parse_sec=%.6f read_entries_sec=%.6f read_features_sec=%.6f build_index_direct_sec=%.6f build_index_from_entries_sec=%.6f entries=%d features=%d direct_size=%d roundtrip_size=%d rss_kb=%d" % [
-      ruby_time,
-      read_entries_time,
-      read_features_time,
-      direct_index_time,
-      roundtrip_index_time,
-      ruby_entries.length,
-      feature_rows.length,
-      direct_index.size,
-      roundtrip_index.size,
-      TGGeometryBench.rss_kb
-    ]
+    read_plus_roundtrip_sec = read_entries[:median_sec] + roundtrip_index_stat[:median_sec]
+    read_plus_roundtrip_ops_per_sec = read_plus_roundtrip_sec.positive? ? read_entries[:iterations] / read_plus_roundtrip_sec : 0.0
+
+    common = {
+      n: size,
+      json_bytes: json.bytesize,
+      ruby_entries: ruby_entries.length,
+      feature_entries: feature_entries.length,
+      feature_rows: feature_rows.length,
+      direct_size: direct_index.size,
+      roundtrip_size: roundtrip_index.size,
+      rss_kb: TGGeometryBench.rss_kb
+    }
+
+    TGGeometryBench.report("feature_source", common.merge(mode: :ruby_json_parse_entries), stats: ruby)
+    TGGeometryBench.report("feature_source", common.merge(mode: :read_entries_file), stats: read_entries)
+    TGGeometryBench.report("feature_source", common.merge(mode: :read_features_file), stats: read_features)
+    TGGeometryBench.report("feature_source", common.merge(mode: :build_index_direct), stats: direct_index_stat)
+    TGGeometryBench.report("feature_source", common.merge(mode: :build_index_from_prepared_entries), stats: roundtrip_index_stat)
+    TGGeometryBench.report(
+      "feature_source_end_to_end",
+      common.merge(
+        mode: :read_entries_plus_build_index,
+        median_sec: read_plus_roundtrip_sec,
+        ops_per_sec: read_plus_roundtrip_ops_per_sec
+      )
+    )
   ensure
     file.close!
   end

data/benchmark/flat_vs_rtree.rb

@@ -3,25 +3,67 @@
 require_relative "_support"
 
 TGGeometryBench.say_header("flat_vs_rtree")
-iterations = TGGeometryBench.iterations(1_000)
 
 %i[compact long_thin overlapping].each do |kind|
   TGGeometryBench.sizes.each do |size|
     entries = TGGeometryBench.entries_for(kind, size)
 
-    build_flat = Benchmark.realtime { @flat = TGGeometryBench.build_index(entries, strategy: :flat) }
-    build_rtree = Benchmark.realtime { @rtree = TGGeometryBench.build_index(entries, strategy: :rtree) }
+    flat = nil
+    rtree = nil
 
-    TGGeometryBench.points_for(kind).each do |lon, lat|
-      flat_time = Benchmark.realtime { iterations.times { @flat.find_covering(lon, lat) } }
-      rtree_time = Benchmark.realtime { iterations.times { @rtree.find_covering(lon, lat) } }
-      puts "kind=#{kind} n=#{size} query=point lon=#{lon} lat=#{lat} flat_sec=%.6f rtree_sec=%.6f flat_qps=%.2f rtree_qps=%.2f build_flat=%.6f build_rtree=%.6f" % [flat_time, rtree_time, iterations / flat_time, iterations / rtree_time, build_flat, build_rtree]
+    flat_build = TGGeometryBench.measure_counted(initial_iterations: 1, min_seconds: 0.25) do |iterations|
+      iterations.times { flat = TGGeometryBench.build_index(entries, strategy: :flat) }
     end
+    rtree_build = TGGeometryBench.measure_counted(initial_iterations: 1, min_seconds: 0.25) do |iterations|
+      iterations.times { rtree = TGGeometryBench.build_index(entries, strategy: :rtree) }
+    end
+
+    # Rebuild once outside the build benchmark so query numbers do not depend on
+    # the last object produced by calibration/repeats.
+    flat = TGGeometryBench.build_index(entries, strategy: :flat)
+    rtree = TGGeometryBench.build_index(entries, strategy: :rtree)
+
+    TGGeometryBench.report("flat_vs_rtree_build", { kind: kind, n: size, strategy: :flat }, stats: flat_build)
+    TGGeometryBench.report("flat_vs_rtree_build", { kind: kind, n: size, strategy: :rtree }, stats: rtree_build)
+
+    TGGeometryBench.points_for(kind).each_with_index do |(lon, lat), point_index|
+      flat_stats = TGGeometryBench.measure_counted(initial_iterations: TGGeometryBench.initial_iterations(2_000)) do |iterations|
+        iterations.times { flat.find_covering(lon, lat) }
+      end
+      rtree_stats = TGGeometryBench.measure_counted(initial_iterations: TGGeometryBench.initial_iterations(2_000)) do |iterations|
+        iterations.times { rtree.find_covering(lon, lat) }
+      end
+
+      TGGeometryBench.report(
+        "flat_vs_rtree_point",
+        { kind: kind, n: size, strategy: :flat, point_index: point_index, lon: lon, lat: lat },
+        stats: flat_stats
+      )
+      TGGeometryBench.report(
+        "flat_vs_rtree_point",
+        { kind: kind, n: size, strategy: :rtree, point_index: point_index, lon: lon, lat: lat },
+        stats: rtree_stats
+      )
+    end
+
+    TGGeometryBench.rects_for(kind).each_with_index do |rect, rect_index|
+      flat_stats = TGGeometryBench.measure_counted(initial_iterations: TGGeometryBench.initial_iterations(200)) do |iterations|
+        iterations.times { flat.intersecting_rect(*rect) }
+      end
+      rtree_stats = TGGeometryBench.measure_counted(initial_iterations: TGGeometryBench.initial_iterations(200)) do |iterations|
+        iterations.times { rtree.intersecting_rect(*rect) }
+      end
 
-    TGGeometryBench.rects_for(kind).each do |rect|
-      flat_time = Benchmark.realtime { iterations.times { @flat.intersecting_rect(*rect) } }
-      rtree_time = Benchmark.realtime { iterations.times { @rtree.intersecting_rect(*rect) } }
-      puts "kind=#{kind} n=#{size} query=rect rect=#{rect.join(',')} flat_sec=%.6f rtree_sec=%.6f flat_qps=%.2f rtree_qps=%.2f" % [flat_time, rtree_time, iterations / flat_time, iterations / rtree_time]
+      TGGeometryBench.report(
+        "flat_vs_rtree_rect",
+        { kind: kind, n: size, strategy: :flat, rect_index: rect_index, rect: rect },
+        stats: flat_stats
+      )
+      TGGeometryBench.report(
+        "flat_vs_rtree_rect",
+        { kind: kind, n: size, strategy: :rtree, rect_index: rect_index, rect: rect },
+        stats: rtree_stats
+      )
     end
   end
 end

data/benchmark/geom_query.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+
+TGGeometryBench.say_header("geom_query")
+
+COUNTS = (TGGeometryBench.full? ? [1_000, 10_000, 50_000] : [1_000, 10_000]).freeze
+STRATEGIES = %i[flat rtree].freeze
+
+def box(x, y, size = 1.0)
+  TG::Geometry.polygon([[x, y], [x + size, y], [x + size, y + size], [x, y + size], [x, y]])
+end
+
+COUNTS.each do |count|
+  entries = count.times.map do |i|
+    x = (i % 100).to_f * 2.0
+    y = (i / 100).to_f * 2.0
+    [i, box(x, y)]
+  end
+
+  queries = {
+    small: box(10.5, 10.5, 2.0),
+    large: box(0.5, 0.5, 120.0),
+    miss: box(-1_000.0, -1_000.0, 1.0)
+  }
+
+  STRATEGIES.each do |strategy|
+    index = TG::Geometry::Index.build(entries, via: :geom, strategy: strategy)
+
+    queries.each do |query_name, query_geom|
+      initial = query_name == :large ? 100 : 1_000
+      stats = TGGeometryBench.measure_counted(initial_iterations: TGGeometryBench.initial_iterations(initial)) do |iterations|
+        iterations.times { index.intersecting_geom_ids(query_geom) }
+      end
+
+      TGGeometryBench.report(
+        "geom_query",
+        { n: count, strategy: strategy, query: query_name, method: :intersecting_geom_ids },
+        stats: stats
+      )
+    end
+  end
+end

data/benchmark/gvl_threshold.rb

@@ -3,12 +3,9 @@
 require_relative "_support"
 
 TGGeometryBench.say_header("gvl_threshold")
-puts "First release intentionally performs parse/write/batch/query with GVL held."
-puts "This harness records baseline parse wall time only; it does not enable no-GVL execution."
+TGGeometryBench.report("gvl_threshold_note", note: "baseline_only_gvl_is_held_no_public_release_gvl_knob")
 
-# Build one valid WKT polygon close to the requested byte size.  The previous
-# implementation accidentally benchmarked the same tiny 39-byte polygon for all
-# target sizes because it used Array(...).first.
+# Build one valid WKT polygon close to the requested byte size.
 def polygon_wkt_at_least(target_bytes)
   points_count = [4, target_bytes / 38].max
 
@@ -27,15 +24,17 @@ def polygon_wkt_at_least(target_bytes)
   end
 end
 
-sizes = [128, 1_024, 16_384, 262_144]
-iterations = TGGeometryBench.iterations(2_000)
-
-sizes.each do |target_bytes|
+[128, 1_024, 16_384, 262_144].each do |target_bytes|
   payload = polygon_wkt_at_least(target_bytes)
+  initial = target_bytes >= 262_144 ? 10 : 500
 
-  time = Benchmark.realtime do
+  stats = TGGeometryBench.measure_counted(initial_iterations: TGGeometryBench.initial_iterations(initial)) do |iterations|
     iterations.times { TG::Geometry.parse_wkt(payload) }
   end
 
-  puts "target_bytes=#{target_bytes} payload_bytes=#{payload.bytesize} iterations=#{iterations} seconds=%.6f ops_per_sec=%.2f" % [time, iterations / time]
+  TGGeometryBench.report(
+    "gvl_threshold_parse_wkt",
+    { target_bytes: target_bytes, payload_bytes: payload.bytesize },
+    stats: stats
+  )
 end

data/benchmark/nearest_segment.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "_support"
+
+TGGeometryBench.say_header("nearest_segment")
+
+[100, 1_000, 10_000].each do |count|
+  points = count.times.map do |i|
+    angle = 2.0 * Math::PI * i / count
+    [Math.cos(angle), Math.sin(angle)]
+  end
+  points << points.first
+  ring = TG::Geometry.polygon(points).polygon.exterior_ring
+
+  stats = TGGeometryBench.measure_counted(initial_iterations: TGGeometryBench.initial_iterations(10_000)) do |iterations|
+    iterations.times { ring.nearest_segment(0.25, 0.33) }
+  end
+
+  TGGeometryBench.report(
+    "nearest_segment",
+    { segments: ring.num_segments, query: "0.25:0.33" },
+    stats: stats
+  )
+end

data/benchmark/objectspace_memsize.rb

@@ -8,10 +8,23 @@ TGGeometryBench.say_header("objectspace_memsize")
 %i[compact long_thin overlapping].each do |kind|
   TGGeometryBench.sizes.each do |size|
     entries = TGGeometryBench.entries_for(kind, size)
+    TGGeometryBench.gc_start
     flat = TGGeometryBench.build_index(entries, strategy: :flat)
+    TGGeometryBench.gc_start
     rtree = TGGeometryBench.build_index(entries, strategy: :rtree)
     geom = TG::Geometry.parse_geojson(entries.first.last)
 
-    puts "kind=#{kind} n=#{size} geom_memsize=#{ObjectSpace.memsize_of(geom)} flat_memsize=#{ObjectSpace.memsize_of(flat)} rtree_memsize=#{ObjectSpace.memsize_of(rtree)}"
+    TGGeometryBench.report(
+      "objectspace_memsize",
+      {
+        kind: kind,
+        n: size,
+        geom_memsize: ObjectSpace.memsize_of(geom),
+        flat_memsize: ObjectSpace.memsize_of(flat),
+        rtree_memsize: ObjectSpace.memsize_of(rtree),
+        rtree_over_flat: ObjectSpace.memsize_of(rtree) - ObjectSpace.memsize_of(flat),
+        rss_kb: TGGeometryBench.rss_kb
+      }
+    )
   end
 end

data/benchmark/parse_throughput.rb

@@ -21,18 +21,21 @@ geojson = '{"type":"Polygon","coordinates":[[[0,0],[10,0],[10,10],[0,10],[0,0]]]
 wkb = TG::Geometry.parse_wkt(small).to_wkb
 
 cases = {
-  "wkt:small" => [small, :wkt],
-  "geojson:small" => [geojson, :geojson],
-  "wkb:small" => [wkb, :wkb],
-  "wkt:medium" => [medium, :wkt],
-  "wkt:large" => [large, :wkt]
+  "wkt_small" => [small, :wkt, 5_000],
+  "geojson_small" => [geojson, :geojson, 5_000],
+  "wkb_small" => [wkb, :wkb, 5_000],
+  "wkt_medium" => [medium, :wkt, 500],
+  "wkt_large" => [large, :wkt, 50]
 }
 
-iterations = TGGeometryBench.iterations(10_000)
-
-cases.each do |name, (payload, format)|
-  time = Benchmark.realtime do
+cases.each do |name, (payload, format, initial)|
+  stats = TGGeometryBench.measure_counted(initial_iterations: TGGeometryBench.initial_iterations(initial)) do |iterations|
     iterations.times { TG::Geometry.parse(payload, format: format) }
   end
-  puts "%s iterations=%d seconds=%.6f ops_per_sec=%.2f" % [name, iterations, time, iterations / time]
+
+  TGGeometryBench.report(
+    "parse_throughput",
+    { case: name, format: format, payload_bytes: payload.bytesize },
+    stats: stats
+  )
 end

data/benchmark/rss_stability.rb

@@ -4,27 +4,28 @@ require_relative "_support"
 
 TGGeometryBench.say_header("rss_stability")
 
-total_queries = Integer(ENV.fetch("TGEOMETRY_RSS_QUERIES", "10_000_000"))
-rebuilds = Integer(ENV.fetch("TGEOMETRY_RSS_REBUILDS", "100"))
-entries_count = Integer(ENV.fetch("TGEOMETRY_RSS_ENTRIES", "1_000"))
-max_drift_kb = Integer(ENV.fetch("TGEOMETRY_RSS_MAX_DRIFT_KB", "51_200"))
+total_queries = TGGeometryBench.env_integer("TGEOMETRY_RSS_QUERIES", 10_000_000, min: 1)
+rebuilds = TGGeometryBench.env_integer("TGEOMETRY_RSS_REBUILDS", 100, min: 1)
+entries_count = TGGeometryBench.env_integer("TGEOMETRY_RSS_ENTRIES", 1_000, min: 1)
+max_drift_kb = TGGeometryBench.env_integer("TGEOMETRY_RSS_MAX_DRIFT_KB", 51_200, min: 0)
 
 queries_per_rebuild = (total_queries / rebuilds).clamp(1, total_queries)
 entries = TGGeometryBench.compact_entries(entries_count)
 points = TGGeometryBench.points_for(:compact)
 packed_batch = TGGeometryBench.packed_points(points * 10)
 
-GC.start
-GC.start
+TGGeometryBench.gc_start
+TGGeometryBench.gc_start
 start_rss = TGGeometryBench.rss_kb
 peak_rss = start_rss
 samples = []
 
 queries_executed = 0
-started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+started_at = TGGeometryBench.monotonic
 
 rebuilds.times do |cycle|
-  index = TGGeometryBench.build_index(entries, strategy: (cycle.even? ? :flat : :rtree))
+  strategy = cycle.even? ? :flat : :rtree
+  index = TGGeometryBench.build_index(entries, strategy: strategy)
 
   queries_per_rebuild.times do |q|
     lon, lat = points[(q + cycle) % points.length]
@@ -39,29 +40,39 @@ rebuilds.times do |cycle|
 
   index = nil
 
-  if (cycle % 10).zero?
-    GC.start
-    rss = TGGeometryBench.rss_kb
-    peak_rss = [peak_rss, rss].max
-    samples << [cycle, queries_executed, rss]
-  end
+  next unless (cycle % 10).zero?
+
+  TGGeometryBench.gc_start
+  rss = TGGeometryBench.rss_kb
+  peak_rss = [peak_rss, rss].max
+  samples << [cycle, queries_executed, rss]
 end
 
-GC.start
-GC.start
+TGGeometryBench.gc_start
+TGGeometryBench.gc_start
 finish_rss = TGGeometryBench.rss_kb
-elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+elapsed = TGGeometryBench.monotonic - started_at
 drift_kb = finish_rss - start_rss
 
-puts format(
-  "queries=%d rebuilds=%d entries=%d elapsed_s=%.2f start_rss_kb=%d peak_rss_kb=%d finish_rss_kb=%d drift_kb=%d",
-  queries_executed, rebuilds, entries_count, elapsed,
-  start_rss, peak_rss, finish_rss, drift_kb
+TGGeometryBench.report(
+  "rss_stability",
+  {
+    queries: queries_executed,
+    rebuilds: rebuilds,
+    entries: entries_count,
+    elapsed_sec: elapsed,
+    qps: queries_executed / elapsed,
+    start_rss_kb: start_rss,
+    peak_rss_kb: peak_rss,
+    finish_rss_kb: finish_rss,
+    drift_kb: drift_kb,
+    max_drift_kb: max_drift_kb,
+    sample_count: samples.length
+  }
 )
 
-if samples.length > 1
-  puts "samples (cycle, queries, rss_kb):"
-  samples.each { |row| puts "  #{row.inspect}" }
+samples.each do |cycle, queries, rss|
+  TGGeometryBench.report("rss_stability_sample", cycle: cycle, queries: queries, rss_kb: rss)
 end
 
 if max_drift_kb.positive? && drift_kb > max_drift_kb

data/docs/GEOMETRY_QUERIES.md

@@ -0,0 +1,23 @@
+# Geometry-based index queries
+
+v0.3.0 adds geometry query methods to `TG::Geometry::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 |
+
+The direction is always from the stored geometry to the query geometry. For example, `covering_geom_ids(query)` asks which indexed geometries cover the query.
+
+The `predicate:` option on `Index.build` affects only the legacy point-based methods:
+
+- `find_covering(x, y)`
+- `covering_ids(x, y)`
+- `covering_ids_batch_packed(packed_doubles)`
+
+It does not affect `intersecting_geom_ids`, `covering_geom_ids`, or `containing_geom_ids`.
+
+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.

data/docs/LIMITATIONS.md

@@ -4,16 +4,18 @@
 
 Not included:
 
-- geocoding;
-- routing;
-- projections;
-- geodesic distance/area;
-- buffer / union / difference / overlay result geometry operations;
-- nearest POI indexing;
-- public callback/search APIs;
-- Ractor support claim;
-- no-GVL execution claim;
-- automatic strategy selection.
+- Geodesic / Haversine distance;
+- Projection / reprojection;
+- Buffer / union / difference / convex hull;
+- Index nearest_ids (KNN);
+- GeoBIN bbox helpers;
+- Streaming FeatureSource;
+- Index serialization / mmap;
+- Ractor support;
+- Windows / JRuby;
+- Write-side ActiveRecordType / AR scopes / migrations;
+- 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, and perimeter-style values are in input coordinate units, not meters.
 

data/docs/NEAREST_SEGMENT.md

@@ -0,0 +1,17 @@
+# Nearest segment
+
+`Line#nearest_segment(x, y)` and `Ring#nearest_segment(x, y)` compute the nearest segment to a point in planar XY space.
+
+```ruby
+nearest = ring.nearest_segment(x, y)
+nearest.segment   # TG::Geometry::Segment
+nearest.index     # Integer segment index in the parent line/ring
+nearest.distance  # Float
+nearest.point     # [x, y] projection onto the segment
+```
+
+Distance is Euclidean distance in input coordinate units. It is not meters unless the input coordinate system is already meters.
+
+Degenerate segments (`a == b`) are handled as point distance. The projection point for a degenerate segment is the segment endpoint.
+
+When several segments have the same distance, tie-break behaviour follows tg iteration order. Code should not rely on a specific equal-distance segment.