tg_geometry 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3b2fd9ecb971425116e95aed147c0467eba4105b151ff15ba128ef35b10ad6a
-  data.tar.gz: e87484d1ab62a0c21b19c79603ed7da3f0017962543c32b5cd5095cc353a044e
+  metadata.gz: fdc6ab78992bee6ba1708b13adfdb0e4eec26fef04c4fc8eae87df21fbfed5fa
+  data.tar.gz: ada3eff77de10cb101cbedbd35e2d40e119fe37c5a09003afe9df1ab266827fe
 SHA512:
-  metadata.gz: e82e6a1729a0e076fdd16e6c378b3e363a744fddb0b41216d1371a4a7e320234772f829cb38e024b5b397bca630dcb787ae9d31e0cc114e84836ae7cb0bb904e
-  data.tar.gz: '0529e7db75d831d0fa39877ca0ddd4f43d9138c985471f2827bbd92abefc9fec07ad9bba881ec9ba1c157f14a8c5c99be229d2c0fa9c08db73904620e043a029'
+  metadata.gz: 87200faec4b6d0442eab7df12f768807193aed725bb75b25502a64cc5b2e24e97f2f9d98cf9254c54e3f62d9b0481f39dc2287818f69a740e9728a33e97d9f0b
+  data.tar.gz: 3e14f4563facef36fc109e1c8006b707502bb384f67c1c27da05faa7dcec7b7a7970d82a22d39ac99c00595c74944c7a6467fa81a5cdd1d14129df70f4d3675a

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 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/ewkb_roundtrip.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "benchmark"
+require_relative "_support"
+
+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
+end
+
+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
+    end
+  rescue LoadError
+    warn "rgeo is not installed"
+  end
+end

data/benchmark/geom_query.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "benchmark"
+require_relative "_support"
+
+COUNTS = [1_000, 10_000].freeze
+STRATEGIES = %i[flat rtree].freeze
+
+
+def box(x, y, size = 1.0)
+  TG::Geometry.polygon([[x, y], [x + size, y], [x + size, y + size], [x, y + size], [x, y]])
+end
+
+COUNTS.each do |count|
+  entries = count.times.map do |i|
+    x = (i % 100).to_f * 2.0
+    y = (i / 100).to_f * 2.0
+    [i, box(x, y)]
+  end
+
+  small_query = box(10.5, 10.5, 2.0)
+  large_query = box(0.5, 0.5, 120.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) } }
+    end
+  end
+end

data/benchmark/nearest_segment.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "benchmark"
+require_relative "_support"
+
+[100, 1_000, 10_000].each do |count|
+  points = count.times.map do |i|
+    angle = 2.0 * Math::PI * i / count
+    [Math.cos(angle), Math.sin(angle)]
+  end
+  points << points.first
+  ring = TG::Geometry.polygon(points).polygon.exterior_ring
+
+  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
+  end
+end

data/docs/GEOMETRY_QUERIES.md

@@ -0,0 +1,23 @@
+# Geometry-based index queries
+
+v0.3.0 adds geometry query methods to `TG::Geometry::Index`:
+
+| Method | Predicate direction | Boundary semantics |
+| --- | --- | --- |
+| `intersecting_geom_ids(query)` | `stored_geom` intersects `query` | any intersection |
+| `covering_geom_ids(query)` | `stored_geom` covers `query` | boundary included |
+| `containing_geom_ids(query)` | `stored_geom` contains `query` | strict interior; boundary excluded |
+
+The direction is always from the stored geometry to the query geometry. For example, `covering_geom_ids(query)` asks which indexed geometries cover the query.
+
+The `predicate:` option on `Index.build` affects only the legacy point-based methods:
+
+- `find_covering(x, y)`
+- `covering_ids(x, y)`
+- `covering_ids_batch_packed(packed_doubles)`
+
+It does not affect `intersecting_geom_ids`, `covering_geom_ids`, or `containing_geom_ids`.
+
+Results are arrays of ids in insertion order. Duplicate ids are preserved if duplicate ids were inserted.
+
+In v0.3.0 these operations run under the GVL. The heavy C phase is structured without Ruby API calls so it can be made no-GVL-safe later after benchmarking, but there is no public `release_gvl:` knob.

data/docs/LIMITATIONS.md

@@ -4,16 +4,18 @@
 
 Not included:
 
-- geocoding;
-- routing;
-- projections;
-- geodesic distance/area;
-- buffer / union / difference / overlay result geometry operations;
-- nearest POI indexing;
-- public callback/search APIs;
-- Ractor support claim;
-- no-GVL execution claim;
-- automatic strategy selection.
+- Geodesic / Haversine distance;
+- Projection / reprojection;
+- Buffer / union / difference / convex hull;
+- Index nearest_ids (KNN);
+- GeoBIN bbox helpers;
+- Streaming FeatureSource;
+- Index serialization / mmap;
+- Ractor support;
+- Windows / JRuby;
+- Write-side ActiveRecordType / AR scopes / migrations;
+- Z/M variants of array constructors;
+- Public `release_gvl:` option.
 
 TG works in planar XY coordinates. If lon/lat coordinates are passed in, length, area, and perimeter-style values are in input coordinate units, not meters.
 

data/docs/NEAREST_SEGMENT.md

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

data/docs/SRID_AND_EWKB.md

@@ -0,0 +1,23 @@
+# SRID and EWKB
+
+EWKB extends WKB with extra metadata bits. PostGIS sets the SRID flag (`0x20000000`) in the geometry type word and inserts a 32-bit SRID after the type header.
+
+`tg` already understands EWKB enough to parse the geometry payload correctly, but it does not expose SRID metadata. `tg_geometry` therefore reads the EWKB header at wrapper level before passing the original bytes to `tg_parse_wkb_ix` / `tg_parse_hexn_ix`.
+
+The original bytes are not modified. The native `tg_geom` remains a plain planar geometry. The Ruby `TG::Geometry::Geom` wrapper stores SRID metadata in parallel:
+
+```ruby
+geom = TG::Geometry.parse_wkb(ewkb)
+geom.srid # => Integer or nil
+```
+
+`parse_wkb` and `parse_hex` preserve SRID metadata. GeoJSON, WKT, GeoBIN, and `parse(format: :auto)` do not guarantee SRID preservation in v0.3.0.
+
+`to_wkb` intentionally stays plain WKB. Use `to_ewkb` for PostGIS-compatible SRID-bearing output:
+
+```ruby
+geom.to_ewkb
+geom.to_ewkb(srid: 4326)
+```
+
+SRID is metadata only. No reprojection, SRID compatibility check, meter conversion, or geodesic calculation is performed.