tg_geometry 0.2.0 → 0.3.0

data/spec/index_geom_query_spec.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Index geometry queries" do
+  def polygon(min_x, min_y, max_x, max_y)
+    TG::Geometry.polygon([[min_x, min_y], [max_x, min_y], [max_x, max_y], [min_x, max_y], [min_x, min_y]])
+  end
+
+  let(:zones) do
+    [
+      [:a, polygon(0, 0, 10, 10)],
+      [:b, polygon(8, 8, 18, 18)],
+      [:c, polygon(30, 30, 40, 40)]
+    ]
+  end
+
+  def build(strategy)
+    TG::Geometry::Index.build(zones, via: :geom, strategy: strategy)
+  end
+
+  it "returns intersecting ids in insertion order" do
+    query = polygon(9, 9, 12, 12)
+
+    expect(build(:flat).intersecting_geom_ids(query)).to eq(%i[a b])
+    expect(build(:rtree).intersecting_geom_ids(query)).to eq(%i[a b])
+  end
+
+  it "supports line query intersections" do
+    query = TG::Geometry.line_string([[35, 35], [45, 45]])
+
+    expect(build(:flat).intersecting_geom_ids(query)).to eq([:c])
+  end
+
+  it "returns empty arrays for outside query geometries" do
+    expect(build(:rtree).intersecting_geom_ids(polygon(100, 100, 101, 101))).to eq([])
+  end
+
+  it "uses stored_geom covers query semantics" do
+    index = build(:flat)
+
+    expect(index.covering_geom_ids(TG::Geometry.point(5, 5))).to eq([:a])
+    expect(index.covering_geom_ids(TG::Geometry.point(0, 5))).to eq([:a])
+    expect(index.covering_geom_ids(polygon(9, 9, 12, 12))).to eq([:b])
+  end
+
+  it "uses stored_geom contains query semantics and excludes boundary" do
+    index = build(:flat)
+
+    expect(index.containing_geom_ids(TG::Geometry.point(5, 5))).to eq([:a])
+    expect(index.containing_geom_ids(TG::Geometry.point(0, 5))).to eq([])
+    expect(index.covering_geom_ids(TG::Geometry.point(0, 5))).to eq([:a])
+  end
+
+  it "does not read Index.build predicate for geometry methods" do
+    index = TG::Geometry::Index.build(zones, via: :geom, strategy: :flat, predicate: :contains)
+
+    expect(index.covering_geom_ids(TG::Geometry.point(0, 5))).to eq([:a])
+  end
+
+  it "raises TypeError for non-Geom query values" do
+    index = build(:flat)
+
+    expect { index.intersecting_geom_ids(nil) }.to raise_error(TypeError)
+    expect { index.covering_geom_ids("bad") }.to raise_error(TypeError)
+    expect { index.containing_geom_ids(1) }.to raise_error(TypeError)
+  end
+end

data/spec/keyword_validation_spec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "strict keyword validation" do
+  let(:geom_without_srid) { TG::Geometry.parse_wkt("POINT (1 2)") }
+  let(:wkb) { geom_without_srid.to_wkb }
+
+  it "rejects unsupported SRID and EWKB flags on parse_wkb" do
+    expect { TG::Geometry.parse_wkb(wkb, srid: 4326) }
+      .to raise_error(TG::Geometry::ArgumentError, /unknown keyword: :srid/)
+    expect { TG::Geometry.parse_wkb(wkb, ewkb: true) }
+      .to raise_error(TG::Geometry::ArgumentError, /unknown keyword: :ewkb/)
+  end
+
+  it "rejects public release_gvl knobs on new v0.3.0 APIs" do
+    expect { TG::Geometry.line_string([[0, 0], [1, 1]], release_gvl: true) }
+      .to raise_error(TG::Geometry::ArgumentError, /unknown keyword: :release_gvl/)
+    expect { geom_without_srid.to_ewkb(srid: 4326, release_gvl: true) }
+      .to raise_error(TG::Geometry::ArgumentError, /unknown keyword: :release_gvl/)
+  end
+
+  it "rejects unknown constructor keywords" do
+    square = [[0, 0], [1, 0], [1, 1], [0, 0]]
+
+    expect { TG::Geometry.polygon(square, autoclose: true) }
+      .to raise_error(TG::Geometry::ArgumentError, /unknown keyword: :autoclose/)
+    expect { TG::Geometry.multi_polygon([{ exterior: square, holes: [], extra: true }]) }
+      .to raise_error(TG::Geometry::ArgumentError, /unknown keyword: :extra/)
+  end
+end

data/spec/nearest_segment_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "nearest_segment" do
+  it "finds nearest line segments and projection points" do
+    line = TG::Geometry.line_string([[0, 0], [10, 0], [10, 10]]).line
+    nearest = line.nearest_segment(5, 3)
+
+    expect(nearest).to be_a(TG::Geometry::NearestSegment)
+    expect(nearest).to be_frozen
+    expect(nearest.segment).to be_a(TG::Geometry::Segment)
+    expect(nearest.index).to be >= 0
+    expect(nearest.distance).to be_within(1e-12).of(3.0)
+    expect(nearest.point).to eq([5.0, 0.0])
+  end
+
+  it "returns zero distance for a point on a segment" do
+    nearest = TG::Geometry.line_string([[0, 0], [10, 0]]).line.nearest_segment(5, 0)
+
+    expect(nearest.index).to eq(0)
+    expect(nearest.distance).to be_within(1e-12).of(0.0)
+    expect(nearest.point).to eq([5.0, 0.0])
+  end
+
+  it "handles outside-bbox and degenerate segments" do
+    outside = TG::Geometry.line_string([[0, 0], [10, 0]]).line.nearest_segment(20, 5)
+    degenerate = TG::Geometry.line_string([[1, 1], [1, 1]]).line.nearest_segment(4, 5)
+
+    expect(outside.index).to eq(0)
+    expect(outside.point).to eq([10.0, 0.0])
+    expect(degenerate.index).to eq(0)
+    expect(degenerate.point).to eq([1.0, 1.0])
+  end
+
+  it "finds nearest ring segments without depending on equal-distance tie break" do
+    ring = TG::Geometry.polygon([[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]]).polygon.exterior_ring
+    center = ring.nearest_segment(5, 5)
+    corner = ring.nearest_segment(0, 0)
+
+    expect(center.index).to be_between(0, 3).inclusive
+    expect(center.distance).to be_within(1e-12).of(5.0)
+    expect(corner.distance).to be_within(1e-12).of(0.0)
+  end
+
+  it "keeps nearest result valid after parent GC" do
+    nearest = TG::Geometry.line_string([[0, 0], [10, 0]]).line.nearest_segment(5, 2)
+
+    GC.start
+    GC.compact if GC.respond_to?(:compact)
+
+    expect(nearest.segment.points).to eq([[0.0, 0.0], [10.0, 0.0]])
+    expect(nearest.point).to eq([5.0, 0.0])
+  end
+
+  it "rejects non-finite coordinates" do
+    line = TG::Geometry.line_string([[0, 0], [10, 0]]).line
+
+    expect { line.nearest_segment(Float::NAN, 0) }.to raise_error(TG::Geometry::ArgumentError)
+    expect { line.nearest_segment(0, Float::INFINITY) }.to raise_error(TG::Geometry::ArgumentError)
+  end
+end

data/spec/postgis_fixtures_spec.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "spec_helper"
+
+RSpec.describe "PostGIS EWKB fixtures" do
+  FIXTURE_ROOT = File.expand_path("fixtures/postgis", __dir__)
+
+  CASES = {
+    "point_4326.ewkb" => { srid: 4326, bbox: [37.6, 55.7, 37.6, 55.7] },
+    "polygon_4326_simple.ewkb" => { srid: 4326, bbox: [0.0, 0.0, 10.0, 10.0] },
+    "polygon_4326_with_hole.ewkb" => { srid: 4326, bbox: [0.0, 0.0, 10.0, 10.0] },
+    "polygon_3857.ewkb" => { srid: 3857, bbox: [0.0, 0.0, 10.0, 10.0] },
+    "multipolygon_large.ewkb" => { srid: 4326, bbox: [99.0, 49.0, 101.0, 51.0] }
+  }.freeze
+
+  CASES.each do |filename, expected|
+    it "parses and roundtrips #{filename}" do
+      bytes = File.binread(File.join(FIXTURE_ROOT, filename))
+      geom = TG::Geometry.parse_wkb(bytes)
+      bbox = geom.bbox
+
+      expect(geom.srid).to eq(expected[:srid])
+      expect([bbox.min_x, bbox.min_y, bbox.max_x, bbox.max_y]).to all(be_a(Float))
+      [bbox.min_x, bbox.min_y, bbox.max_x, bbox.max_y].zip(expected[:bbox]).each do |actual, expected_coord|
+        expect(actual).to be_within(1e-9).of(expected_coord)
+      end
+      expect(geom.to_ewkb).to eq(bytes)
+      expect(TG::Geometry.parse_wkb(geom.to_wkb).srid).to be_nil
+    end
+  end
+
+  it "keeps hole coverage semantics stable" do
+    geom = TG::Geometry.parse_wkb(File.binread(File.join(FIXTURE_ROOT, "polygon_4326_with_hole.ewkb")))
+
+    expect(geom.covers_xy?(3, 3)).to be(false)
+    expect(geom.covers_xy?(1, 1)).to be(true)
+  end
+
+  it "checks boundary cases from GeoJSON" do
+    simple = TG::Geometry.parse_wkb(File.binread(File.join(FIXTURE_ROOT, "polygon_4326_simple.ewkb")))
+    data = JSON.parse(File.read(File.join(FIXTURE_ROOT, "boundary_point_cases.geojson")))
+    points = data.fetch("features").to_h do |feature|
+      [feature.fetch("properties").fetch("name"), feature.fetch("geometry").fetch("coordinates")]
+    end
+
+    expect(simple.covers_xy?(*points.fetch("inside_simple"))).to be(true)
+    expect(simple.covers_xy?(*points.fetch("boundary_simple"))).to be(true)
+  end
+
+  it "sanity-checks the large multipolygon quickly" do
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    geom = TG::Geometry.parse_wkb(File.binread(File.join(FIXTURE_ROOT, "multipolygon_large.ewkb")))
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+    expect(elapsed).to be < 1.0
+    expect(geom.covers_xy?(100.0, 50.0)).to be(true)
+    expect(geom.covers_xy?(200.0, 50.0)).to be(false)
+  end
+
+  it "documents SRID mismatch as user responsibility" do
+    geom_4326 = TG::Geometry.parse_wkb(File.binread(File.join(FIXTURE_ROOT, "polygon_4326_simple.ewkb")))
+    geom_3857 = TG::Geometry.parse_wkb(File.binread(File.join(FIXTURE_ROOT, "polygon_3857.ewkb")))
+
+    expect(geom_4326.srid).not_to eq(geom_3857.srid)
+    expect(geom_4326.intersects?(geom_3857)).to be(true)
+  end
+end

data/spec/srid_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "SRID metadata" do
+  let(:plain_wkb) { TG::Geometry.parse_wkt("POINT (1 2)").to_wkb }
+  let(:ewkb_4326) { TG::Geometry.parse_wkt("POINT (1 2)").to_ewkb(srid: 4326) }
+  let(:ewkb_3857) { TG::Geometry.parse_wkt("POINT (1 2)").to_ewkb(srid: 3857) }
+  let(:ewkb_0) { TG::Geometry.parse_wkt("POINT (1 2)").to_ewkb(srid: 0) }
+
+  it "returns nil for plain WKB and non-SRID text formats" do
+    expect(TG::Geometry.parse_wkb(plain_wkb).srid).to be_nil
+    expect(TG::Geometry.parse_geojson('{"type":"Point","coordinates":[1,2]}').srid).to be_nil
+    expect(TG::Geometry.parse_wkt("POINT (1 2)").srid).to be_nil
+  end
+
+  it "extracts SRID from little-endian EWKB and hex EWKB" do
+    geom = TG::Geometry.parse_wkb(ewkb_4326)
+
+    expect(geom.srid).to eq(4326)
+    expect([geom.bbox.min_x, geom.bbox.min_y]).to eq([1.0, 2.0])
+    expect(TG::Geometry.parse_wkb(ewkb_3857).srid).to eq(3857)
+    expect(TG::Geometry.parse_wkb(ewkb_0).srid).to eq(0)
+    expect(TG::Geometry.parse_hex(ewkb_4326.unpack1("H*")).srid).to eq(4326)
+  end
+
+  it "extracts SRID from big-endian EWKB" do
+    # Big-endian EWKB: byte order 0, type POINT | SRID flag, SRID 4326, x=1.0, y=2.0.
+    ewkb = [0, 0x20000001, 4326].pack("C N N") + [1.0, 2.0].pack("G G")
+
+    expect(TG::Geometry.parse_wkb(ewkb).srid).to eq(4326)
+    expect(TG::Geometry.parse_wkb(ewkb).point).to eq([1.0, 2.0])
+  end
+
+  it "does not crash on malformed EWKB" do
+    expect { TG::Geometry.parse_wkb("\x01\x01\x00".b) }.to raise_error(TG::Geometry::ParseError)
+  end
+
+  it "uses constructor srid metadata" do
+    expect(TG::Geometry.polygon([[0, 0], [1, 0], [1, 1], [0, 0]], srid: 4326).srid).to eq(4326)
+    expect(TG::Geometry.polygon([[0, 0], [1, 0], [1, 1], [0, 0]]).srid).to be_nil
+  end
+end

data/spec/to_ewkb_spec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Geom#to_ewkb" do
+  let(:geom_without_srid) { TG::Geometry.parse_wkt("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))") }
+  let(:geom_with_srid) { TG::Geometry.parse_wkb(geom_without_srid.to_ewkb(srid: 4326)) }
+
+  it "roundtrips semantic geometry and SRID" do
+    ewkb = geom_with_srid.to_ewkb
+    reparsed = TG::Geometry.parse_wkb(ewkb)
+
+    expect(reparsed.srid).to eq(4326)
+    expect(reparsed.type).to eq(:polygon)
+    expect(reparsed.bbox.max_x).to eq(10.0)
+    expect(reparsed.covers_xy?(5, 5)).to be(true)
+  end
+
+  it "can add or override SRID explicitly" do
+    expect(TG::Geometry.parse_wkb(geom_without_srid.to_ewkb(srid: 4326)).srid).to eq(4326)
+    expect(TG::Geometry.parse_wkb(geom_with_srid.to_ewkb(srid: 3857)).srid).to eq(3857)
+  end
+
+  it "returns frozen binary strings" do
+    ewkb = geom_with_srid.to_ewkb
+
+    expect(ewkb.encoding).to eq(Encoding::BINARY)
+    expect(ewkb).to be_frozen
+  end
+
+  it "rejects missing or invalid SRID" do
+    expect { geom_without_srid.to_ewkb }.to raise_error(TG::Geometry::ArgumentError)
+    expect { geom_with_srid.to_ewkb(srid: -1) }.to raise_error(TG::Geometry::ArgumentError)
+    expect { geom_with_srid.to_ewkb(srid: 2**31) }.to raise_error(TG::Geometry::ArgumentError)
+    expect { geom_with_srid.to_ewkb(srid: "4326") }.to raise_error(TG::Geometry::ArgumentError)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tg_geometry
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Roman Haydarov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-26 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -38,6 +38,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
 description: Defines TG::Geometry with immutable Geom parsing and constructor wrappers,
   expanded geometry predicates and accessors, Rect helpers, Hex/GeoBIN writers, raw
   extra_json access, read-only borrowed Line/Ring/Polygon and GeometryCollection child
@@ -61,10 +81,13 @@ files:
 - Rakefile
 - benchmark/_support.rb
 - benchmark/batch_packed_vs_loop.rb
+- benchmark/ewkb_roundtrip.rb
 - benchmark/falcon_concurrency.rb
 - benchmark/feature_source.rb
 - benchmark/flat_vs_rtree.rb
+- benchmark/geom_query.rb
 - benchmark/gvl_threshold.rb
+- benchmark/nearest_segment.rb
 - benchmark/objectspace_memsize.rb
 - benchmark/parse_throughput.rb
 - benchmark/rss_stability.rb
@@ -74,8 +97,11 @@ files:
 - docs/CONCURRENCY.md
 - docs/ERROR_HANDLING.md
 - docs/FEATURE_SOURCE.md
+- docs/GEOMETRY_QUERIES.md
 - docs/LIMITATIONS.md
 - docs/MEMORY_OWNERSHIP.md
+- docs/NEAREST_SEGMENT.md
+- docs/SRID_AND_EWKB.md
 - ext/tg_geometry/extconf.rb
 - ext/tg_geometry/tg_geometry_ext.c
 - ext/tg_geometry/tg_geometry_vendor_json.c
@@ -98,17 +124,33 @@ files:
 - ext/tg_geometry/vendor/tg/tg.h
 - lib/tg/geometry.rb
 - lib/tg/geometry/active_record_source.rb
+- lib/tg/geometry/active_record_type.rb
 - lib/tg/geometry/registry.rb
 - lib/tg/geometry/version.rb
 - lib/tg_geometry.rb
 - script/vendor_libs.rb
 - spec/active_record_source_spec.rb
+- spec/active_record_type_spec.rb
 - spec/auto_strategy_spec.rb
 - spec/batch_packed_spec.rb
 - spec/concurrency_spec.rb
+- spec/constructors_spec.rb
 - spec/error_hardening_spec.rb
 - spec/feature_source_nogvl_spec.rb
 - spec/feature_source_spec.rb
+- spec/fixtures/feature_source/invalid_geometry_middle.geojson
+- spec/fixtures/feature_source/malformed_json.geojson
+- spec/fixtures/feature_source/mixed_geometry_types.geojson
+- spec/fixtures/feature_source/osm_like_feature_collection.geojson
+- spec/fixtures/feature_source/properties_null_missing.geojson
+- spec/fixtures/feature_source/simple_feature_collection.geojson
+- spec/fixtures/postgis/README.md
+- spec/fixtures/postgis/boundary_point_cases.geojson
+- spec/fixtures/postgis/multipolygon_large.ewkb
+- spec/fixtures/postgis/point_4326.ewkb
+- spec/fixtures/postgis/polygon_3857.ewkb
+- spec/fixtures/postgis/polygon_4326_simple.ewkb
+- spec/fixtures/postgis/polygon_4326_with_hole.ewkb
 - spec/format_coverage_spec.rb
 - spec/fuzz_spec.rb
 - spec/geom_api_spec.rb
@@ -116,17 +158,23 @@ files:
 - spec/index_borrowed_geometry_spec.rb
 - spec/index_build_spec.rb
 - spec/index_flat_query_spec.rb
+- spec/index_geom_query_spec.rb
 - spec/index_owned_geometry_spec.rb
 - spec/index_rtree_accounting_spec.rb
 - spec/index_rtree_order_spec.rb
+- spec/keyword_validation_spec.rb
 - spec/load_and_errors_spec.rb
 - spec/low_level_geometry_spec.rb
 - spec/memory_gc_spec.rb
+- spec/nearest_segment_spec.rb
+- spec/postgis_fixtures_spec.rb
 - spec/ractor_spec.rb
 - spec/rect_api_spec.rb
 - spec/registry_spec.rb
 - spec/spec_helper.rb
+- spec/srid_spec.rb
 - spec/tg_api_coverage_spec.rb
+- spec/to_ewkb_spec.rb
 - spec/vendor_sources_spec.rb
 homepage: https://github.com/roman-haidarov/tg_geometry
 licenses: