tg_geometry 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdc6ab78992bee6ba1708b13adfdb0e4eec26fef04c4fc8eae87df21fbfed5fa
-  data.tar.gz: ada3eff77de10cb101cbedbd35e2d40e119fe37c5a09003afe9df1ab266827fe
+  metadata.gz: cde617c534a8a3d9702b3fe212d46f966da46224499bb4fcb97bf40865590be8
+  data.tar.gz: 7e1767d31814249ef695ceae1965d6c5aaf9065ff7595309e95698abc053abbc
 SHA512:
-  metadata.gz: 87200faec4b6d0442eab7df12f768807193aed725bb75b25502a64cc5b2e24e97f2f9d98cf9254c54e3f62d9b0481f39dc2287818f69a740e9728a33e97d9f0b
-  data.tar.gz: 3e14f4563facef36fc109e1c8006b707502bb384f67c1c27da05faa7dcec7b7a7970d82a22d39ac99c00595c74944c7a6467fa81a5cdd1d14129df70f4d3675a
+  metadata.gz: 2cf6070d21ca5342425600e436523aae7215a2792d2d8392662a6c5257ba4e178301ff2a93c5ebb847fc7606d7b1aad60b9ab1fcd8e21b67f06d5f72f8c3cfa1
+  data.tar.gz: 99a9f9c086c6a2da9add012f57a99de800f67846007503ddf6c5d63ec25ac2a6d62cfe5b854fe1d44976ff0bddcbce04b8831db631dd8d174602c64914190e30

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.1 - 28.05.2026
+
+### Changed
+- Optimized R-tree-backed point lookup by removing per-query candidate bitmap
+allocation and full entry scan from Index#find_covering. The new path tracks
+the lowest matching ordinal directly in the R-tree callback, preserving
+insertion-order semantics while significantly improving rtree point queries
+and packed batch point lookup.
+
 ## 0.3.0 - 27.05.2026
 
 ### Added

data/benchmark/_support.rb

@@ -21,14 +21,447 @@ module TGGeometryBench
   module_function
 
   SIZES = [100, 500, 1_000, 5_000, 50_000].freeze
-  FAST_SIZES = [100, 500, 1_000].freeze
+  FAST_SIZES = [100, 1_000, 5_000].freeze
+
+  DEFAULT_REPEATS = 5
+  DEFAULT_MIN_SECONDS = 0.25
+  DEFAULT_WARMUP_SECONDS = 0.05
+  DEFAULT_MAX_ITERATIONS = 100_000_000
+
+  def full?
+    ENV["TGEOMETRY_BENCH_FULL"] == "1"
+  end
 
   def sizes
-    ENV["TGEOMETRY_BENCH_FULL"] == "1" ? SIZES : FAST_SIZES
+    full? ? SIZES : FAST_SIZES
+  end
+
+  def env_integer(name, default, min: nil)
+    value = Integer(ENV.fetch(name, default.to_s))
+    if min && value < min
+      raise ArgumentError, "#{name} must be >= #{min}, got #{value}"
+    end
+    value
+  end
+
+  def env_float(name, default, min: nil)
+    value = Float(ENV.fetch(name, default.to_s))
+    if min && value < min
+      raise ArgumentError, "#{name} must be >= #{min}, got #{value}"
+    end
+    value
+  end
+
+  def initial_iterations(default)
+    env_integer("TGEOMETRY_BENCH_ITERATIONS", default, min: 1)
+  end
+
+  def repeats(default = DEFAULT_REPEATS)
+    env_integer("TGEOMETRY_BENCH_REPEATS", default, min: 1)
+  end
+
+  def min_seconds(default = DEFAULT_MIN_SECONDS)
+    env_float("TGEOMETRY_BENCH_MIN_SECONDS", default, min: 0.0)
+  end
+
+  def warmup_seconds(default = DEFAULT_WARMUP_SECONDS)
+    env_float("TGEOMETRY_BENCH_WARMUP_SECONDS", default, min: 0.0)
+  end
+
+  def max_iterations(default = DEFAULT_MAX_ITERATIONS)
+    env_integer("TGEOMETRY_BENCH_MAX_ITERATIONS", default, min: 1)
+  end
+
+  def adaptive?
+    ENV.fetch("TGEOMETRY_BENCH_ADAPTIVE", "1") != "0"
+  end
+
+  def disable_gc_during_timed?
+    ENV["TGEOMETRY_BENCH_DISABLE_GC"] == "1"
+  end
+
+  def monotonic
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  def median(values)
+    sorted = values.sort
+    n = sorted.length
+    return 0.0 if n.zero?
+
+    mid = n / 2
+    n.odd? ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2.0
+  end
+
+  def percentile(values, pct)
+    sorted = values.sort
+    return 0.0 if sorted.empty?
+
+    rank = (pct * (sorted.length - 1)).round
+    sorted.fetch(rank)
+  end
+
+  def gc_start
+    GC.start(full_mark: true, immediate_sweep: true)
+  rescue ArgumentError
+    GC.start
+  end
+
+  def timed_gc_delta
+    before = GC.stat
+    seconds = nil
+
+    if disable_gc_during_timed?
+      was_enabled = GC.enable
+      GC.disable
+      seconds = Benchmark.realtime { yield }
+      GC.enable if was_enabled
+    else
+      seconds = Benchmark.realtime { yield }
+    end
+
+    after = GC.stat
+    [
+      seconds,
+      after[:total_allocated_objects] - before[:total_allocated_objects],
+      after[:minor_gc_count] - before[:minor_gc_count],
+      after[:major_gc_count] - before[:major_gc_count]
+    ]
+  ensure
+    GC.enable if disable_gc_during_timed?
+  end
+
+  def calibrate_iterations(initial_iterations:, min_seconds:, max_iterations: self.max_iterations, &block)
+    iterations = initial_iterations
+    return iterations unless adaptive?
+    return iterations if min_seconds <= 0.0
+
+    loop do
+      gc_start
+      seconds = Benchmark.realtime { block.call(iterations) }
+      break iterations if seconds >= min_seconds || iterations >= max_iterations
+
+      if seconds <= 0.0
+        iterations = [iterations * 10, max_iterations].min
+        next
+      end
+
+      target = (iterations * (min_seconds / seconds) * 1.50).ceil
+      iterations = [[target, iterations * 2].max, max_iterations].min
+    end
+  end
+
+  def warmup_for(seconds, iterations, &block)
+    return if seconds <= 0.0
+
+    deadline = monotonic + seconds
+    begin
+      block.call(iterations)
+    end while monotonic < deadline
+  end
+
+  def measure_counted(initial_iterations:, operations_per_iteration: 1, min_seconds: self.min_seconds,
+                      repeats: self.repeats, warmup_seconds: self.warmup_seconds,
+                      max_iterations: self.max_iterations, &block)
+    iterations = calibrate_iterations(
+      initial_iterations: initial_iterations,
+      min_seconds: min_seconds,
+      max_iterations: max_iterations,
+      &block
+    )
+
+    warmup_for(warmup_seconds, iterations, &block)
+
+    seconds_samples = []
+    allocation_samples = []
+    minor_gc_samples = []
+    major_gc_samples = []
+
+    repeats.times do
+      gc_start
+      seconds, allocations, minor_gc, major_gc = timed_gc_delta { block.call(iterations) }
+      seconds_samples << seconds
+      allocation_samples << allocations
+      minor_gc_samples << minor_gc
+      major_gc_samples << major_gc
+    end
+
+    total_operations = iterations * operations_per_iteration
+    median_sec = median(seconds_samples)
+
+    {
+      iterations: iterations,
+      operations_per_iteration: operations_per_iteration,
+      operations_per_repeat: total_operations,
+      repeats: repeats,
+      min_seconds: min_seconds,
+      warmup_seconds: warmup_seconds,
+      best_sec: seconds_samples.min,
+      median_sec: median_sec,
+      worst_sec: seconds_samples.max,
+      mean_sec: seconds_samples.sum / seconds_samples.length,
+      p90_sec: percentile(seconds_samples, 0.90),
+      ops_per_sec: median_sec.positive? ? total_operations / median_sec : 0.0,
+      ns_per_op: median_sec.positive? ? (median_sec / total_operations) * 1e9 : 0.0,
+      spread_pct: seconds_samples.min.positive? ? ((seconds_samples.max - seconds_samples.min) / seconds_samples.min) * 100.0 : 0.0,
+      median_allocations: median(allocation_samples),
+      allocations_per_op: total_operations.positive? ? median(allocation_samples) / total_operations.to_f : 0.0,
+      median_minor_gc: median(minor_gc_samples),
+      median_major_gc: median(major_gc_samples),
+      samples_sec: seconds_samples
+    }
+  end
+
+  def format_value(value)
+    case value
+    when Float
+      if value.finite?
+        "%.6f" % value
+      else
+        value.to_s
+      end
+    when Array
+      value.join(":")
+    else
+      value.to_s.gsub(/\s+/, "_")
+    end
+  end
+
+  def output_format
+    ENV.fetch("TGEOMETRY_BENCH_FORMAT", "table")
+  end
+
+  def kv_output?
+    %w[kv both].include?(output_format)
+  end
+
+  def table_output?
+    %w[table both].include?(output_format)
+  end
+
+  def report_rows
+    @report_rows ||= []
+  end
+
+  def kv_line(payload)
+    payload.map { |key, value| "#{key}=#{format_value(value)}" }.join(" ")
+  end
+
+  def report(benchmark, fields = nil, stats: nil, **kwargs)
+    fields = (fields || {}).merge(kwargs)
+
+    payload = {
+      benchmark: benchmark,
+      ruby: RUBY_VERSION,
+      platform: RUBY_PLATFORM,
+      full: full?,
+      adaptive: adaptive?,
+      gc_disabled: disable_gc_during_timed?
+    }.merge(fields)
+
+    if stats
+      payload = payload.merge(
+        iterations: stats[:iterations],
+        ops_per_iteration: stats[:operations_per_iteration],
+        operations: stats[:operations_per_repeat],
+        repeats: stats[:repeats],
+        min_seconds: stats[:min_seconds],
+        median_sec: stats[:median_sec],
+        best_sec: stats[:best_sec],
+        worst_sec: stats[:worst_sec],
+        ops_per_sec: stats[:ops_per_sec],
+        ns_per_op: stats[:ns_per_op],
+        spread_pct: stats[:spread_pct],
+        median_allocations: stats[:median_allocations],
+        allocations_per_op: stats[:allocations_per_op],
+        median_minor_gc: stats[:median_minor_gc],
+        median_major_gc: stats[:median_major_gc]
+      )
+    end
+
+    puts kv_line(payload) if kv_output?
+    report_rows << payload if table_output?
+    payload
   end
 
-  def iterations(default)
-    Integer(ENV.fetch("TGEOMETRY_BENCH_ITERATIONS", default.to_s))
+  TABLE_CONTEXT_COLUMNS = [
+    :kind, :n, :strategy, :mode,
+    :query, :method, :case, :format,
+    :library, :operation,
+    :point_index, :lon, :lat,
+    :rect_index, :rect,
+    :segments, :target_bytes, :payload_bytes,
+    :points_per_batch, :threads,
+    :entries, :rebuilds, :cycle
+  ].freeze
+
+  TABLE_METRIC_COLUMNS = [
+    :batches_per_sec, :ops_per_sec, :qps, :ns_per_op,
+    :median_sec, :spread_pct, :allocations_per_op,
+    :median_minor_gc, :median_major_gc,
+    :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
+  ].freeze
+
+  TABLE_INTERNAL_COLUMNS = [
+    :benchmark, :ruby, :platform, :full, :adaptive, :gc_disabled,
+    :repeats, :min_seconds, :warmup_seconds, :max_iterations,
+    :ops_per_iteration, :median_allocations,
+    :best_sec, :worst_sec
+  ].freeze
+
+  TABLE_HEADERS = {
+    kind: "kind",
+    n: "n",
+    strategy: "strategy",
+    mode: "mode",
+    query: "query",
+    method: "method",
+    case: "case",
+    format: "format",
+    library: "lib",
+    operation: "op",
+    point_index: "pt#",
+    rect_index: "rect#",
+    lon: "lon",
+    lat: "lat",
+    rect: "rect",
+    segments: "segments",
+    target_bytes: "target B",
+    payload_bytes: "payload B",
+    points_per_batch: "points/batch",
+    batches_per_sec: "batches/s",
+    ops_per_sec: "ops/s",
+    qps: "qps",
+    ns_per_op: "ns/op",
+    median_sec: "median s",
+    spread_pct: "spread %",
+    allocations_per_op: "alloc/op",
+    median_minor_gc: "minor GC",
+    median_major_gc: "major GC",
+    iterations: "iters",
+    operations: "ops",
+    threads: "threads",
+    entries: "entries",
+    rebuilds: "rebuilds",
+    queries: "queries",
+    cycle: "cycle",
+    rss_kb: "rss KB",
+    geom_memsize: "geom B",
+    flat_memsize: "flat B",
+    rtree_memsize: "rtree B",
+    rtree_over_flat: "rtree-flat B",
+    start_rss_kb: "start KB",
+    peak_rss_kb: "peak KB",
+    finish_rss_kb: "finish KB",
+    drift_kb: "drift KB",
+    max_drift_kb: "max drift KB",
+    elapsed_sec: "elapsed s",
+    sample_count: "samples"
+  }.freeze
+
+  def human_int(value)
+    Integer(value).to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1_').reverse
+  rescue StandardError
+    value.to_s
+  end
+
+  def human_rate(value)
+    v = Float(value)
+    return "0" if v.zero?
+
+    abs = v.abs
+    if abs >= 1_000_000
+      "%.2fM" % (v / 1_000_000.0)
+    elsif abs >= 1_000
+      "%.1fk" % (v / 1_000.0)
+    elsif abs >= 100
+      "%.1f" % v
+    else
+      "%.3f" % v
+    end
+  end
+
+  def format_table_cell(key, value)
+    return "" if value.nil?
+
+    case key
+    when :ops_per_sec, :batches_per_sec, :qps
+      human_rate(value)
+    when :ns_per_op
+      "%.1f" % Float(value)
+    when :median_sec, :elapsed_sec
+      "%.4f" % Float(value)
+    when :spread_pct
+      "%.2f" % Float(value)
+    when :allocations_per_op
+      v = Float(value)
+      v < 0.01 ? ("%.5f" % v) : ("%.3f" % v)
+    when :lon, :lat
+      "%.3f" % Float(value)
+    when :rect
+      Array(value).map { |v| (Float(v) % 1).zero? ? Integer(v).to_s : ("%.3f" % Float(v)) }.join(":")
+    when :n, :iterations, :operations, :entries, :rebuilds, :queries, :cycle,
+         :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
+      human_int(value)
+    when :full, :adaptive, :gc_disabled
+      value ? "yes" : "no"
+    else
+      value.to_s
+    end
+  end
+
+  def table_columns(rows)
+    keys = rows.flat_map(&:keys).uniq
+    context = TABLE_CONTEXT_COLUMNS.select { |key| keys.include?(key) }
+    metrics = TABLE_METRIC_COLUMNS.select { |key| keys.include?(key) }
+    extras = keys - context - metrics - TABLE_INTERNAL_COLUMNS
+    context + extras + metrics
+  end
+
+  def print_table(rows, columns)
+    headers = columns.map { |key| TABLE_HEADERS.fetch(key, key.to_s) }
+    body = rows.map do |row|
+      columns.map { |key| format_table_cell(key, row[key]) }
+    end
+    widths = headers.each_with_index.map do |header, index|
+      ([header.length] + body.map { |cells| cells[index].length }).max
+    end
+
+    separator = "+-#{widths.map { |w| "-" * w }.join("-+-")}-+"
+    puts separator
+    puts "| #{headers.each_with_index.map { |h, i| h.ljust(widths[i]) }.join(" | ")} |"
+    puts separator
+    body.each do |cells|
+      puts "| #{cells.each_with_index.map { |cell, i| cell.rjust(widths[i]) }.join(" | ")} |"
+    end
+    puts separator
+  end
+
+  def flush_reports
+    rows = report_rows
+    return if rows.empty?
+
+    rows.group_by { |row| row[:benchmark] }.each do |benchmark, group_rows|
+      notes, measured = group_rows.partition { |row| row.key?(:note) && row.keys.none? { |key| TABLE_METRIC_COLUMNS.include?(key) } }
+
+      notes.each do |row|
+        puts "\n-- #{benchmark} --"
+        puts row[:note]
+      end
+
+      next if measured.empty?
+
+      puts "\n-- #{benchmark} --"
+      print_table(measured, table_columns(measured))
+    end
+  ensure
+    rows&.clear
   end
 
   def box_wkt(min_x, min_y, max_x, max_y)
@@ -91,6 +524,11 @@ module TGGeometryBench
     end
   end
 
+  def repeated_points(kind, count)
+    seed = points_for(kind)
+    Array.new(count) { |i| seed[i % seed.length] }
+  end
+
   def packed_points(points)
     points.flatten.pack("d*")
   end
@@ -110,6 +548,13 @@ module TGGeometryBench
 
   def say_header(title)
     puts "\n== #{title} =="
-    puts "ruby=#{RUBY_VERSION} platform=#{RUBY_PLATFORM} full=#{ENV['TGEOMETRY_BENCH_FULL'] == '1'}"
+    puts "ruby=#{RUBY_VERSION} platform=#{RUBY_PLATFORM} sizes=#{sizes.join(":")} repeats=#{repeats} " \
+         "min_seconds=#{format_table_cell(:median_sec, min_seconds)} warmup=#{format_table_cell(:median_sec, warmup_seconds)} " \
+         "adaptive=#{adaptive? ? "yes" : "no"} gc_disabled=#{disable_gc_during_timed? ? "yes" : "no"}"
+    puts "output=table; set TGEOMETRY_BENCH_FORMAT=kv for machine-readable key=value lines" if table_output? && !kv_output?
   end
 end
+
+at_exit do
+  TGGeometryBench.flush_reports if TGGeometryBench.table_output?
+end

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

@@ -1,28 +1,37 @@
 # frozen_string_literal: true
 
-require "benchmark"
 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
 
-Benchmark.bm(32) do |x|
-  x.report("tg parse_wkb -> to_ewkb 100k") do
-    100_000.times { TG::Geometry.parse_wkb(ewkb).to_ewkb }
-  end
+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))")
 
-    Benchmark.bm(32) do |x|
-      x.report("rgeo WKT parse 100k") do
-        100_000.times { factory.parse_wkt(rgeo_geom.as_text) }
-      end
+    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

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

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "benchmark"
 require_relative "_support"
 
-COUNTS = [1_000, 10_000].freeze
-STRATEGIES = %i[flat rtree].freeze
+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]])
@@ -18,16 +18,26 @@ COUNTS.each do |count|
     [i, box(x, y)]
   end
 
-  small_query = box(10.5, 10.5, 2.0)
-  large_query = box(0.5, 0.5, 120.0)
+  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)
+  }
 
-  puts "\n#{count} polygons"
   STRATEGIES.each do |strategy|
     index = TG::Geometry::Index.build(entries, via: :geom, strategy: strategy)
 
-    Benchmark.bm(32) do |x|
-      x.report("#{strategy} small intersecting_geom_ids") { 10_000.times { index.intersecting_geom_ids(small_query) } }
-      x.report("#{strategy} large intersecting_geom_ids") { 1_000.times { index.intersecting_geom_ids(large_query) } }
+    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

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-require "benchmark"
 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
@@ -11,10 +12,13 @@ require_relative "_support"
   points << points.first
   ring = TG::Geometry.polygon(points).polygon.exterior_ring
 
-  puts "\nring segments: #{ring.num_segments}"
-  Benchmark.bm(28) do |x|
-    x.report("1M nearest_segment calls") do
-      1_000_000.times { ring.nearest_segment(0.25, 0.33) }
-    end
+  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/ext/tg_geometry/tg_geometry_ext.c

@@ -3127,6 +3127,43 @@ static bool rtree_mark_candidate_iter(const double *min, const double *max, cons
     return true;
 }
 
+typedef struct {
+    const tg_index_t *idx;
+    const struct tg_geom *point;
+    const tg_index_entry_t *best;
+    long best_ordinal;
+} tg_rtree_find_args_t;
+
+static bool rtree_find_covering_iter(const double *min, const double *max, const void *data,
+                                     void *udata) {
+    const tg_index_entry_t *entry = (const tg_index_entry_t *)data;
+    tg_rtree_find_args_t *args = (tg_rtree_find_args_t *)udata;
+
+    (void)min;
+    (void)max;
+
+    if (!entry) {
+        return true;
+    }
+
+    if (entry->ordinal < 0 || entry->ordinal >= args->idx->len) {
+        return true;
+    }
+
+    if (args->best && entry->ordinal >= args->best_ordinal) {
+        return true;
+    }
+    if (index_entry_matches_point(args->idx, entry, args->point)) {
+        args->best = entry;
+        args->best_ordinal = entry->ordinal;
+
+        if (entry->ordinal == 0) {
+            return false;
+        }
+    }
+    return true;
+}
+
 static unsigned char *rtree_candidate_marks(tg_index_t *idx, struct tg_rect query_rect) {
     unsigned char *marks;
     tg_rtree_mark_args_t args;
@@ -3195,33 +3232,31 @@ static VALUE index_find_covering_value(tg_index_t *idx, double lon, double lat)
 
     if (idx->strategy == TG_GEOMETRY_INDEX_STRATEGY_RTREE) {
         struct tg_rect point_rect = tg_rect_from_xyxy(lon, lat, lon, lat);
-        unsigned char *candidates = rtree_candidate_marks(idx, point_rect);
+        tg_rtree_find_args_t args;
+        double min[2];
+        double max[2];
 
         point = tg_query_point_new(lon, lat);
-        if (!point) {
-            free(candidates);
-            rb_raise(rb_eNoMemError, "TG point geometry allocation failed");
-        }
-        if (tg_geom_error(point)) {
+        tg_query_point_raise_if_invalid(point);
+
+        if (!idx->rtree) {
             tg_geom_free(point);
-            free(candidates);
-            rb_raise(eTGGeometryError, "TG point geometry error");
+            return Qnil;
         }
 
-        for (long i = 0; i < idx->len; i++) {
-            tg_index_entry_t *entry = &idx->entries[i];
+        args.idx = idx;
+        args.point = point;
+        args.best = NULL;
+        args.best_ordinal = 0;
 
-            if (!candidates[i]) {
-                continue;
-            }
-            if (index_entry_matches_point(idx, entry, point)) {
-                result = entry->id;
-                break;
-            }
+        tg_rect_to_arrays(point_rect, min, max);
+        rtree_search(idx->rtree, min, max, rtree_find_covering_iter, &args);
+
+        if (args.best) {
+            result = args.best->id;
         }
 
         tg_geom_free(point);
-        free(candidates);
         return result;
     }
 

data/lib/tg/geometry/version.rb

@@ -2,6 +2,6 @@
 
 module TG
   module Geometry
-    VERSION = "0.3.0"
+    VERSION = "0.3.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tg_geometry
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Roman Haydarov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-27 00:00:00.000000000 Z
+date: 2026-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake