tg_geometry 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdc6ab78992bee6ba1708b13adfdb0e4eec26fef04c4fc8eae87df21fbfed5fa
-  data.tar.gz: ada3eff77de10cb101cbedbd35e2d40e119fe37c5a09003afe9df1ab266827fe
+  metadata.gz: 7cb54eb85cd48036c2f32eb5f95fa3d19cbf994d375bc102b05f2d45dfb1f8ec
+  data.tar.gz: c5ff1c066708d8826c125185f34a346e1f1e2bf66f65fb1b1eb13e75bf955aad
 SHA512:
-  metadata.gz: 87200faec4b6d0442eab7df12f768807193aed725bb75b25502a64cc5b2e24e97f2f9d98cf9254c54e3f62d9b0481f39dc2287818f69a740e9728a33e97d9f0b
-  data.tar.gz: 3e14f4563facef36fc109e1c8006b707502bb384f67c1c27da05faa7dcec7b7a7970d82a22d39ac99c00595c74944c7a6467fa81a5cdd1d14129df70f4d3675a
+  metadata.gz: 981e37eb58fac8eaa20c3fa9604b751c263330e3f3dc2e8614cb1c91e36eb76d31431b4a13b3cbcd44475323d5ca76ec3e58c013d8c16de9d28e2ec890704962
+  data.tar.gz: 05db4ca563cd1c22e13d5c27e440845452397f50516cf01dde8675032fb3e12a527ba0fe52ccd32bc1fe313b3f8d083f46c17a54e4e8c316b6e8ce9766c278d5

data/CHANGELOG.md

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

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

data/benchmark/_support.rb

@@ -21,14 +21,454 @@ 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, :receiver
+  ].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,
+    :before_memsize, :after_memsize, :delta_memsize, :allocated_objects
+  ].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",
+    receiver: "receiver",
+    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",
+    before_memsize: "before B",
+    after_memsize: "after B",
+    delta_memsize: "delta B",
+    allocated_objects: "alloc objs"
+  }.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,
+         :before_memsize, :after_memsize, :delta_memsize, :allocated_objects
+      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 +531,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 +555,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/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