tg_geometry 0.2.0 → 0.3.0

data/lib/tg/geometry/active_record_source.rb

@@ -6,52 +6,34 @@ module TG
       module_function
 
       def call(scope, id:, geometry:, batch_size: 1_000)
-        entries = []
-
-        each_record(scope, batch_size: batch_size) do |record|
-          entries << [read_field(record, id), read_field(record, geometry)]
+        enumerator(scope, batch_size: batch_size).map do |record|
+          [read_field(record, id), read_field(record, geometry)]
         end
-
-        entries
       end
 
       def registry_source(scope, id:, geometry:, batch_size: 1_000)
-        proc do
-          TG::Geometry::ActiveRecordSource.call(
-            scope,
-            id: id,
-            geometry: geometry,
-            batch_size: batch_size
-          )
-        end
+        -> { TG::Geometry::ActiveRecordSource.call(scope, id: id, geometry: geometry, batch_size: batch_size) }
       end
 
-      def each_record(scope, batch_size:)
-        if scope.respond_to?(:find_each)
-          scope.find_each(batch_size: batch_size) { |record| yield record }
-        else
-          scope.each { |record| yield record }
+      class << self
+        private
+
+        def enumerator(scope, batch_size:)
+          scope.respond_to?(:find_each) ? scope.find_each(batch_size: batch_size) : scope.each
         end
-      end
-      private_class_method :each_record
 
-      def read_field(record, reader)
-        case reader
-        when Proc
-          reader.call(record)
-        when Symbol, String
-          if record.respond_to?(reader)
-            record.public_send(reader)
-          elsif record.respond_to?(:[])
-            record[reader]
-          else
+        def read_field(record, reader)
+          case reader
+          in Proc then reader.call(record)
+          in Symbol | String if record.respond_to?(reader) then record.public_send(reader)
+          in Symbol | String if record.respond_to?(:[])    then record[reader]
+          in Symbol | String
             raise TG::Geometry::ArgumentError, "record does not expose #{reader.inspect}"
+          else
+            raise TG::Geometry::ArgumentError, "field reader must be Symbol, String, or Proc"
           end
-        else
-          raise TG::Geometry::ArgumentError, "field reader must be Symbol, String, or Proc"
         end
       end
-      private_class_method :read_field
     end
   end
 end

data/lib/tg/geometry/active_record_type.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "tg/geometry"
+
+module TG
+  module Geometry
+    class ActiveRecordType < ActiveModel::Type::Value
+      HEX_PATTERN = /\A[0-9A-Fa-f]+\z/
+
+      def initialize(strict: true)
+        super()
+        @strict = strict
+      end
+
+      def type = :tg_geometry
+
+      def deserialize(value)
+        case value
+        when nil                then nil
+        when TG::Geometry::Geom then value
+        when String             then parse_string(value)
+        else
+          @strict ? raise(TG::Geometry::ArgumentError, "cannot deserialize #{value.class} as TG::Geometry::Geom") : nil
+        end
+      end
+
+      alias cast deserialize
+
+      def serialize(value)
+        case value
+        when nil, String then value
+        else raise TG::Geometry::ArgumentError, "TG::Geometry::ActiveRecordType is read-only in v0.3.0"
+        end
+      end
+
+      private
+
+      def parse_string(str)
+        stripped = str.strip
+
+        if stripped.start_with?("\\x") && stripped[2..].match?(HEX_PATTERN)
+          TG::Geometry.parse_hex(stripped[2..])
+        elsif stripped.match?(HEX_PATTERN)
+          TG::Geometry.parse_hex(stripped)
+        elsif str.encoding == Encoding::ASCII_8BIT
+          TG::Geometry.parse_wkb(str)
+        elsif stripped.start_with?("{")
+          TG::Geometry.parse_geojson(str)
+        else
+          TG::Geometry.parse_wkt(str)
+        end
+      rescue TG::Geometry::ParseError => e
+        raise if @strict
+
+        warn "TG::Geometry::ActiveRecordType: parse failed: #{e.message}"
+        nil
+      end
+    end
+  end
+end

data/lib/tg/geometry/registry.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 module TG
   module Geometry
     class Registry
+      extend Forwardable
+
       DEFAULT_INDEX_OPTIONS = {
         via: :geojson,
         strategy: :rtree,
@@ -11,41 +15,24 @@ module TG
       }.freeze
 
       class << self
-        def source(&definition)
-          if definition
-            @source = definition
-          elsif instance_variable_defined?(:@source)
-            @source
-          elsif superclass.respond_to?(:source)
-            superclass.source
-          end
+        def source(&block)
+          @source = block if block
+          @source || (superclass.source if superclass.respond_to?(:source))
         end
 
         def index_options(**options)
-          if options.empty?
-            inherited = superclass.respond_to?(:index_options) ? superclass.index_options : DEFAULT_INDEX_OPTIONS
-            inherited.merge(@index_options || {}).freeze
-          else
-            @index_options = index_options.merge(options).freeze
-          end
-        end
+          inherited = superclass.respond_to?(:index_options) ? superclass.index_options : DEFAULT_INDEX_OPTIONS
+          return inherited.merge(@index_options || {}).freeze if options.empty?
 
-        def active_record_source(scope, id:, geometry:, batch_size: 1_000)
-          require_relative "active_record_source"
-
-          source do
-            TG::Geometry::ActiveRecordSource.call(
-              scope,
-              id: id,
-              geometry: geometry,
-              batch_size: batch_size
-            )
-          end
+          @index_options = inherited.merge(@index_options || {}, options).freeze
         end
       end
 
       attr_reader :index_options
 
+      def_delegators :index, :size, :bbox, :find_covering, :covering_ids,
+                     :intersecting_rect, :covering_ids_batch_packed
+
       def initialize(entries: nil, source: nil, **index_options)
         @entries = entries
         @source = source
@@ -56,11 +43,7 @@ module TG
 
       def reload!
         new_index = TG::Geometry::Index.build(resolve_entries, **@index_options)
-
-        @reload_mutex.synchronize do
-          @index = new_index
-        end
-
+        @reload_mutex.synchronize { @index = new_index }
         new_index
       end
 
@@ -68,51 +51,17 @@ module TG
         @index || raise(TG::Geometry::Error, "registry index is not loaded; call reload! first")
       end
 
-      def loaded?
-        !@index.nil?
-      end
-
-      def size
-        current_index.size
-      end
-
-      def bbox
-        current_index.bbox
-      end
-
-      def find_covering(lon, lat)
-        current_index.find_covering(lon, lat)
-      end
-
-      def covering_ids(lon, lat)
-        current_index.covering_ids(lon, lat)
-      end
-
-      def intersecting_rect(min_x, min_y, max_x, max_y)
-        current_index.intersecting_rect(min_x, min_y, max_x, max_y)
-      end
-
-      def covering_ids_batch_packed(binary_string)
-        current_index.covering_ids_batch_packed(binary_string)
-      end
+      def loaded? = !@index.nil?
 
       private
 
-      def current_index
-        @index || raise(TG::Geometry::Error, "registry index is not loaded; call reload! first")
-      end
-
       def resolve_entries
-        return @entries unless @entries.nil?
+        return @entries if @entries
 
         callable = @source || self.class.source
         raise TG::Geometry::Error, "registry source is not configured" unless callable
 
-        if callable.respond_to?(:call)
-          instance_exec(&callable)
-        else
-          raise TG::Geometry::Error, "registry source must be callable"
-        end
+        instance_exec(&callable)
       end
     end
   end

data/lib/tg/geometry/version.rb

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

data/lib/tg/geometry.rb

@@ -4,3 +4,88 @@ require_relative "geometry/version"
 require "tg_geometry_ext_geometry_ext"
 require_relative "geometry/registry"
 require_relative "geometry/active_record_source"
+
+module TG
+  # Fast immutable planar geometry engine with proper indexes and clean
+  # EWKB/PostGIS boundaries. Not a GIS. Not an rgeo replacement.
+  #
+  # All distances and coordinates are in input units. SRID is metadata only;
+  # no reprojection is performed.
+  module Geometry
+    # @!method self.line_string(points, index: :natural, srid: nil)
+    #   @param points [Array<Array<Float>>]
+    #   @param index [:default, :none, :natural, :ystripes]
+    #   @param srid [Integer, nil]
+    #   @return [TG::Geometry::Geom]
+    #
+    # @!method self.polygon(exterior, holes: [], index: :ystripes, srid: nil)
+    #   @param exterior [Array<Array<Float>>]
+    #   @param holes [Array<Array<Array<Float>>>]
+    #   @param index [:default, :none, :natural, :ystripes]
+    #   @param srid [Integer, nil]
+    #   @return [TG::Geometry::Geom]
+    #
+    # @!method self.multi_polygon(polygons, index: :ystripes, srid: nil)
+    #   Each polygon is a Hash with :exterior and optional :holes, or an Array
+    #   shorthand for an exterior with no holes.
+    #   @param polygons [Array<Hash, Array>]
+    #   @return [TG::Geometry::Geom]
+    #
+    # @!method self.parse_wkb(bytes, index: :ystripes)
+    #   Parses WKB or EWKB. SRID is preserved when the EWKB SRID flag is set.
+    #   @return [TG::Geometry::Geom]
+    #
+    # @!method self.parse_hex(hex, index: :ystripes)
+    #   Parses HEXWKB or HEXEWKB. SRID is preserved when the EWKB SRID flag is set.
+    #   @return [TG::Geometry::Geom]
+
+    class Geom
+      # @!method srid
+      #   @return [Integer, nil] SRID metadata; not used for reprojection
+      #
+      # @!method to_ewkb(srid: nil)
+      #   Writes EWKB with the SRID flag set. Uses explicit srid: when provided,
+      #   otherwise Geom#srid. Raises if no SRID is available. to_wkb remains plain.
+      #   @return [String] frozen ASCII-8BIT EWKB string
+    end
+
+    class Index
+      # @!method self.build(entries, via:, strategy:, predicate: :covers, geometry_index: :ystripes)
+      #   predicate: affects only legacy point query methods: find_covering,
+      #   covering_ids(x, y), covering_ids_batch_packed. The *_geom_ids methods
+      #   use their own predicates derived from the method name.
+      #
+      # @!method intersecting_geom_ids(geom)
+      #   Stored geometries for which tg_geom_intersects(stored, query) is true.
+      #   @return [Array<Object>] ids in insertion order
+      #
+      # @!method covering_geom_ids(geom)
+      #   Stored geometries for which tg_geom_covers(stored, query) is true.
+      #   Direction: stored covers query. Boundary points are covered.
+      #   @return [Array<Object>] ids in insertion order
+      #
+      # @!method containing_geom_ids(geom)
+      #   Stored geometries for which tg_geom_contains(stored, query) is true.
+      #   Direction: stored contains query. Boundary points are not contained.
+      #   @return [Array<Object>] ids in insertion order
+    end
+
+    class Line
+      # @!method nearest_segment(x, y)
+      #   @return [TG::Geometry::NearestSegment, nil] planar Euclidean
+    end
+
+    class Ring
+      # @!method nearest_segment(x, y)
+      #   @return [TG::Geometry::NearestSegment, nil] planar Euclidean
+    end
+
+    # Result of Line#nearest_segment / Ring#nearest_segment.
+    class NearestSegment
+      # @!attribute [r] segment   @return [TG::Geometry::Segment]
+      # @!attribute [r] index     @return [Integer]
+      # @!attribute [r] distance  @return [Float] planar Euclidean in input units
+      # @!attribute [r] point     @return [Array(Float, Float)] projection
+    end
+  end
+end

data/spec/active_record_type_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "tg/geometry/active_record_type"
+
+RSpec.describe TG::Geometry::ActiveRecordType do
+  let(:type) { described_class.new }
+  let(:ewkb) { TG::Geometry.parse_wkt("POINT (1 2)").to_ewkb(srid: 4326) }
+  let(:geom) { TG::Geometry.parse_wkb(ewkb) }
+
+  it "deserializes supported read shapes" do
+    expect(type.type).to eq(:tg_geometry)
+    expect(type.deserialize(nil)).to be_nil
+    expect(type.deserialize(geom)).to equal(geom)
+    expect(type.deserialize(ewkb).srid).to eq(4326)
+    expect(type.deserialize(ewkb.unpack1("H*")).srid).to eq(4326)
+    expect(type.deserialize("\\x#{ewkb.unpack1('H*')}").srid).to eq(4326)
+    expect(type.deserialize('{"type":"Point","coordinates":[1,2]}').srid).to be_nil
+    expect(type.deserialize("POINT (1 2)").srid).to be_nil
+  end
+
+  it "detects ASCII-8BIT hex before WKB fallback" do
+    hex = ewkb.unpack1("H*").b
+
+    expect(type.deserialize(hex).srid).to eq(4326)
+  end
+
+  it "is strict by default and can warn+nil in non-strict mode" do
+    expect { type.deserialize("not geometry") }.to raise_error(TG::Geometry::ParseError)
+
+    non_strict = described_class.new(strict: false)
+    expect { expect(non_strict.deserialize("not geometry")).to be_nil }
+      .to output(/parse failed/).to_stderr
+  end
+
+  it "is read-only on serialize" do
+    expect(type.serialize(nil)).to be_nil
+    expect(type.serialize("raw")).to eq("raw")
+    expect { type.serialize(geom) }.to raise_error(TG::Geometry::ArgumentError)
+  end
+
+  it "uses cast as deserialize" do
+    expect(type.cast(ewkb).srid).to eq(4326)
+  end
+end

data/spec/constructors_spec.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Constructors" do
+  let(:square) { [[0.0, 0.0], [10.0, 0.0], [10.0, 10.0], [0.0, 10.0], [0.0, 0.0]] }
+  let(:hole_a) { [[2.0, 2.0], [4.0, 2.0], [4.0, 4.0], [2.0, 4.0], [2.0, 2.0]] }
+  let(:hole_b) { [[6.0, 6.0], [8.0, 6.0], [8.0, 8.0], [6.0, 8.0], [6.0, 6.0]] }
+
+  describe ".line_string" do
+    it "builds a frozen two-point linestring" do
+      geom = TG::Geometry.line_string([[0.0, 0.0], [1.0, 1.0]])
+
+      expect(geom).to be_frozen
+      expect(geom.type).to eq(:linestring)
+      expect(geom.line.num_points).to eq(2)
+      expect(geom.srid).to be_nil
+    end
+
+    it "builds a 100-point linestring" do
+      points = 100.times.map { |i| [i.to_f, (i * 2).to_f] }
+      geom = TG::Geometry.line_string(points)
+
+      expect(geom.line.num_points).to eq(100)
+    end
+
+    it "supports explicit index values and srid metadata" do
+      %i[default natural ystripes none].each do |index|
+        geom = TG::Geometry.line_string([[0, 0], [1, 1]], index: index, srid: 4326)
+        expect(geom.srid).to eq(4326)
+      end
+    end
+
+    it "rejects too few points" do
+      expect { TG::Geometry.line_string([[0, 0]]) }
+        .to raise_error(TG::Geometry::ArgumentError, "line_string requires at least 2 points, got 1")
+      expect { TG::Geometry.line_string([]) }
+        .to raise_error(TG::Geometry::ArgumentError, "line_string requires at least 2 points, got 0")
+    end
+
+    it "rejects non-finite coordinates with the bad point index in the message" do
+      expect { TG::Geometry.line_string([[0, 0], [Float::NAN, 1]]) }
+        .to raise_error(TG::Geometry::ArgumentError, /point 1/)
+      expect { TG::Geometry.line_string([[0, 0], [1, Float::INFINITY]]) }
+        .to raise_error(TG::Geometry::ArgumentError, /point 1/)
+    end
+
+    it "rejects out-of-range srid" do
+      expect { TG::Geometry.line_string([[0, 0], [1, 1]], srid: -1) }
+        .to raise_error(TG::Geometry::ArgumentError)
+    end
+  end
+
+  describe ".polygon" do
+    it "builds a square polygon" do
+      geom = TG::Geometry.polygon(square)
+
+      expect(geom.type).to eq(:polygon)
+      expect(geom.polygon.num_holes).to eq(0)
+      expect(geom.covers_xy?(5, 5)).to be(true)
+    end
+
+    it "builds polygons with one or two holes" do
+      one_hole = TG::Geometry.polygon(square, holes: [hole_a], srid: 4326)
+      two_holes = TG::Geometry.polygon(square, holes: [hole_a, hole_b])
+
+      expect(one_hole.srid).to eq(4326)
+      expect(one_hole.polygon.num_holes).to eq(1)
+      expect(one_hole.covers_xy?(3, 3)).to be(false)
+      expect(two_holes.polygon.num_holes).to eq(2)
+    end
+
+    it "treats holes: [] like omitted holes" do
+      expect(TG::Geometry.polygon(square, holes: []).polygon.num_holes).to eq(0)
+      expect(TG::Geometry.polygon(square).polygon.num_holes).to eq(0)
+    end
+
+    it "rejects invalid rings without autoclosing" do
+      expect { TG::Geometry.polygon(square[0...-1]) }
+        .to raise_error(TG::Geometry::ArgumentError, "polygon exterior ring is not closed")
+      expect { TG::Geometry.polygon(square[0, 3]) }
+        .to raise_error(TG::Geometry::ArgumentError, "polygon exterior ring requires at least 4 points")
+      expect { TG::Geometry.polygon(square, holes: [hole_a[0...-1]]) }
+        .to raise_error(TG::Geometry::ArgumentError, "polygon hole 0 is not closed")
+      expect { TG::Geometry.polygon(square, holes: [hole_a[0, 3]]) }
+        .to raise_error(TG::Geometry::ArgumentError, "polygon hole 0 requires at least 4 points")
+    end
+  end
+
+  describe ".multi_polygon" do
+    it "builds empty and non-empty multipolygons" do
+      expect(TG::Geometry.multi_polygon([]).type).to eq(:multipolygon)
+
+      geom = TG::Geometry.multi_polygon([
+        { exterior: square, holes: [hole_a] },
+        [[20.0, 20.0], [21.0, 20.0], [21.0, 21.0], [20.0, 21.0], [20.0, 20.0]]
+      ], srid: 3857)
+
+      expect(geom.type).to eq(:multipolygon)
+      expect(geom.srid).to eq(3857)
+      expect(geom.num_polygons).to eq(2)
+    end
+  end
+end

data/spec/fixtures/feature_source/invalid_geometry_middle.geojson

@@ -0,0 +1,8 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {"type":"Feature","properties":{"@id":"ok-a"},"geometry":{"type":"Polygon","coordinates":[[[0,0],[0,1],[1,1],[1,0],[0,0]]] }},
+    {"type":"Feature","properties":{"@id":"bad"},"geometry":{"type":"Polygon","coordinates":"not coordinates"}},
+    {"type":"Feature","properties":{"@id":"ok-b"},"geometry":{"type":"Polygon","coordinates":[[[2,2],[2,3],[3,3],[3,2],[2,2]]] }}
+  ]
+}

data/spec/fixtures/feature_source/malformed_json.geojson

@@ -0,0 +1 @@
+{"type":"FeatureCollection","features":[

data/spec/fixtures/feature_source/mixed_geometry_types.geojson

@@ -0,0 +1,8 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {"type":"Feature","properties":{"@id":"poly"},"geometry":{"type":"Polygon","coordinates":[[[0,0],[0,1],[1,1],[1,0],[0,0]]]}},
+    {"type":"Feature","properties":{"@id":"point"},"geometry":{"type":"Point","coordinates":[5,5]}},
+    {"type":"Feature","properties":{"@id":"line"},"geometry":{"type":"LineString","coordinates":[[0,0],[1,1]]}}
+  ]
+}

data/spec/fixtures/feature_source/osm_like_feature_collection.geojson

@@ -0,0 +1,10 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "properties": {"@id": "relation/100", "admin_level": "8"},
+      "geometry": {"type": "Polygon", "coordinates": [[[0,0],[0,1],[1,1],[1,0],[0,0]]]}
+    }
+  ]
+}

data/spec/fixtures/feature_source/properties_null_missing.geojson

@@ -0,0 +1,7 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {"type":"Feature","properties":null,"geometry":{"type":"Polygon","coordinates":[[[0,0],[0,1],[1,1],[1,0],[0,0]]]}},
+    {"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[2,2],[2,3],[3,3],[3,2],[2,2]]]}}
+  ]
+}

data/spec/fixtures/feature_source/simple_feature_collection.geojson

@@ -0,0 +1,15 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "properties": {"@id": "zone/a", "name": "A"},
+      "geometry": {"type": "Polygon", "coordinates": [[[0,0],[0,10],[10,10],[10,0],[0,0]]]}
+    },
+    {
+      "type": "Feature",
+      "properties": {"@id": 2},
+      "geometry": {"type": "MultiPolygon", "coordinates": [[[[20,20],[20,30],[30,30],[30,20],[20,20]]]]}
+    }
+  ]
+}

data/spec/fixtures/postgis/README.md

@@ -0,0 +1,16 @@
+# PostGIS / EWKB fixtures
+
+These files are committed binary EWKB fixtures used by the v0.3.0 SRID/EWKB tests.
+They are intentionally small and are not generated at spec runtime.
+
+Canonical PostGIS generation examples:
+
+```sql
+SELECT ST_AsEWKB(ST_GeomFromText('POINT(37.6 55.7)', 4326));
+SELECT ST_AsEWKB(ST_GeomFromText('POLYGON((0 0,10 0,10 10,0 10,0 0))', 4326));
+SELECT ST_AsEWKB(ST_GeomFromText('POLYGON((0 0,10 0,10 10,0 10,0 0),(2 2,4 2,4 4,2 4,2 2))', 4326));
+SELECT ST_AsEWKB(ST_GeomFromText('POLYGON((0 0,10 0,10 10,0 10,0 0))', 3857));
+```
+
+`multipolygon_large.ewkb` is a synthetic large multipolygon fixture with about 7000 points.
+It stands in for a real imported polygon while keeping the repository small.

data/spec/fixtures/postgis/boundary_point_cases.geojson

@@ -0,0 +1,83 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "inside_simple"
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          1.0,
+          1.0
+        ]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "boundary_simple"
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          0.0,
+          5.0
+        ]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "hole_center"
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          3.0,
+          3.0
+        ]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "between_hole_and_outer"
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          1.0,
+          1.0
+        ]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "large_inside"
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          100.0,
+          50.0
+        ]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "large_outside"
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          200.0,
+          50.0
+        ]
+      }
+    }
+  ]
+}