tg_geometry 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3b2fd9ecb971425116e95aed147c0467eba4105b151ff15ba128ef35b10ad6a
-  data.tar.gz: e87484d1ab62a0c21b19c79603ed7da3f0017962543c32b5cd5095cc353a044e
+  metadata.gz: cde617c534a8a3d9702b3fe212d46f966da46224499bb4fcb97bf40865590be8
+  data.tar.gz: 7e1767d31814249ef695ceae1965d6c5aaf9065ff7595309e95698abc053abbc
 SHA512:
-  metadata.gz: e82e6a1729a0e076fdd16e6c378b3e363a744fddb0b41216d1371a4a7e320234772f829cb38e024b5b397bca630dcb787ae9d31e0cc114e84836ae7cb0bb904e
-  data.tar.gz: '0529e7db75d831d0fa39877ca0ddd4f43d9138c985471f2827bbd92abefc9fec07ad9bba881ec9ba1c157f14a8c5c99be229d2c0fa9c08db73904620e043a029'
+  metadata.gz: 2cf6070d21ca5342425600e436523aae7215a2792d2d8392662a6c5257ba4e178301ff2a93c5ebb847fc7606d7b1aad60b9ab1fcd8e21b67f06d5f72f8c3cfa1
+  data.tar.gz: 99a9f9c086c6a2da9add012f57a99de800f67846007503ddf6c5d63ec25ac2a6d62cfe5b854fe1d44976ff0bddcbce04b8831db631dd8d174602c64914190e30

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # 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
+
+- `TG::Geometry.line_string`, `TG::Geometry.polygon`, and `TG::Geometry.multi_polygon` constructors from Ruby arrays.
+- `TG::Geometry::Geom#srid` with automatic EWKB SRID extraction in `parse_wkb` and `parse_hex`.
+- `TG::Geometry::Geom#to_ewkb` writer with explicit `srid:` override.
+- `TG::Geometry::Index#intersecting_geom_ids`, `#covering_geom_ids`, and `#containing_geom_ids`.
+- `TG::Geometry::Line#nearest_segment` and `TG::Geometry::Ring#nearest_segment` with `TG::Geometry::NearestSegment` result objects.
+- `TG::Geometry::ActiveRecordType` read-only optional require.
+- PostGIS/EWKB fixture suite in `spec/fixtures/postgis/`.
+
+### Fixed
+
+- Reject unsupported/unknown keywords on v0.3.0 APIs instead of silently ignoring them, including non-goals such as `release_gvl:`, `parse_wkb(srid:)`, and `parse_wkb(ewkb:)`.
+- Harden constructor cleanup paths so intermediate C `tg_ring` / `tg_poly` objects are released when Ruby exceptions occur during nested polygon construction.
+- Keep geometry-index query collection in a C-only status-returning phase before Ruby result materialization, preserving the intended no-GVL-safe internal shape.
+
+### Clarified
+
+- `Index.build(predicate:)` affects only legacy point query methods: `find_covering`, `covering_ids(x, y)`, and `covering_ids_batch_packed`.
+
+### Not included
+
+- 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 constructors.
+- Public `release_gvl:` option.
+
 ## 0.1.0 - unreleased
 
 Initial public release candidate for `tg_geometry`.

data/README.md

@@ -58,6 +58,44 @@ TG::Geometry.parse_geobin(bytes, index: :ystripes)
 
 `TG::Geometry::Geom` objects are immutable and cannot be manually allocated or manually freed from Ruby.
 
+## Constructors
+
+Construct simple planar geometries directly from Ruby arrays without parsing strings or bytes:
+
+```ruby
+line = TG::Geometry.line_string([[0.0, 0.0], [10.0, 0.0]], index: :natural, srid: 4326)
+poly = TG::Geometry.polygon(
+  [[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]],
+  holes: [[[2, 2], [4, 2], [4, 4], [2, 4], [2, 2]]],
+  index: :ystripes,
+  srid: 4326
+)
+mp = TG::Geometry.multi_polygon([
+  { exterior: [[0, 0], [1, 0], [1, 1], [0, 0]], holes: [] },
+  [[10, 10], [11, 10], [11, 11], [10, 10]]
+])
+```
+
+Constructors are strict: rings must already be closed, invalid coordinates raise `TG::Geometry::ArgumentError`, and no winding/self-intersection fixes are performed. `srid:` is metadata on the wrapper; it does not alter coordinates or perform reprojection.
+
+## SRID and EWKB
+
+`parse_wkb` and `parse_hex` preserve EWKB SRID metadata when the EWKB SRID flag is present:
+
+```ruby
+geom = TG::Geometry.parse_wkb(postgis_bytea)
+geom.srid # => 4326, 3857, 0, or nil for plain WKB
+```
+
+`to_wkb` always writes plain WKB. Use `to_ewkb` when a PostGIS-compatible SRID-bearing payload is required:
+
+```ruby
+ewkb = geom.to_ewkb              # uses geom.srid
+ewkb = geom.to_ewkb(srid: 4326)  # explicit override
+```
+
+SRID is metadata only. `tg_geometry` does not check SRID compatibility, transform coordinates, or calculate geodesic distances.
+
 ## Rect
 
 ```ruby
@@ -127,8 +165,29 @@ Accepted predicates:
 - `:covers` — default for geofencing; boundary points are included.
 - `:contains` — stricter containment semantics.
 
+The `predicate:` option affects only the legacy point-based query methods (`find_covering`, `covering_ids(x, y)`, `covering_ids_batch_packed`). The geometry-based query methods (`intersecting_geom_ids`, `covering_geom_ids`, `containing_geom_ids`) use their own predicates based on the method name.
+
 `strategy: :auto` is intentionally not exposed. Choose the strategy explicitly and benchmark on your own data.
 
+## Geometry-based index queries
+
+```ruby
+query = TG::Geometry.polygon([[1, 1], [2, 1], [2, 2], [1, 1]])
+index.intersecting_geom_ids(query)
+index.covering_geom_ids(query)
+index.containing_geom_ids(query)
+```
+
+Predicate direction is explicit:
+
+| 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 |
+
+Results are ids only and preserve insertion order. Duplicate ids remain possible if duplicate ids were inserted.
+
 ## GeoJSON FeatureSource
 
 `TG::Geometry::FeatureSource` reads GeoJSON `FeatureCollection` sources without `JSON.parse` of the whole document into Ruby Hash/Array objects.
@@ -186,6 +245,20 @@ index.covering_ids_batch_packed(points)
 
 Input is a Ruby String containing native-endian doubles in `lon, lat` pairs. Length must be a multiple of 16 bytes. Empty string returns `[]`.
 
+## Nearest segment
+
+`Line#nearest_segment(x, y)` and `Ring#nearest_segment(x, y)` return a frozen `TG::Geometry::NearestSegment`:
+
+```ruby
+nearest = polygon.polygon.exterior_ring.nearest_segment(5, 5)
+nearest.segment   # => TG::Geometry::Segment
+nearest.index     # => segment index
+nearest.distance  # => Float
+nearest.point     # => [x, y] projection on the segment
+```
+
+Distance is planar Euclidean distance in input coordinate units. It is not meters unless your input coordinates are already meters. Equal-distance tie-breaks follow tg iteration order and are not API-stable.
+
 ## Registry helper
 
 `Registry` is Ruby-level sugar over immutable indexes:
@@ -208,6 +281,23 @@ registry.find_covering(5, 5)
 
 Reload builds a new immutable index first and swaps the reference only after a successful build. Existing readers keep using the previous index safely.
 
+## ActiveRecord integration — read-only
+
+`TG::Geometry::ActiveRecordType` is an optional read-only convenience type for PostGIS columns. It is not required by `tg/geometry`; load it explicitly:
+
+```ruby
+require "tg/geometry/active_record_type"
+
+class Zone < ApplicationRecord
+  attribute :geom, TG::Geometry::ActiveRecordType.new
+end
+
+zone.geom.srid
+zone.geom.covers_xy?(lon, lat)
+```
+
+It can deserialize EWKB bytes, hex EWKB, `\x`-prefixed hex EWKB, GeoJSON, and WKT. Writing `Geom` values is intentionally unsupported in v0.3.0. User applications need `activemodel >= 6.0`; `activerecord` is not a gem dependency.
+
 ## Memory and concurrency
 
 The implementation uses explicit allocator pairs and Ruby GC accounting for native memory. `ObjectSpace.memsize_of(index)` includes entries, owned TG geometries, and exact rtree allocation bytes. Borrowed geometries are not double-counted by the index.
@@ -229,6 +319,9 @@ bundle exec ruby benchmark/rss_stability.rb
 bundle exec ruby benchmark/gvl_threshold.rb
 bundle exec ruby benchmark/falcon_concurrency.rb
 bundle exec ruby benchmark/feature_source.rb
+bundle exec ruby benchmark/geom_query.rb
+bundle exec ruby benchmark/nearest_segment.rb
+bundle exec ruby benchmark/ewkb_roundtrip.rb
 ```
 
 The benchmarks are engineering tools, not marketing claims.
@@ -239,20 +332,20 @@ The benchmarks are engineering tools, not marketing claims.
 
 Not included:
 
-- geocoding;
-- routing;
-- projections;
-- geodesic distance/area;
-- buffer / union / difference / overlay result geometry operations;
-- nearest POI index;
-- Rails dependency in the native extension;
-- Redis or external service dependency;
-- public callback/search APIs;
-- Ractor support claim;
-- no-GVL execution claim;
-- universal `:auto` strategy.
-
-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.
+- 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, perimeter, and nearest-segment distances are in input coordinate units, not meters.
 
 ## Development
 

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