tiletanic 0.1.0

data/lib/tiletanic/tileschemes.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Tiletanic
+  module TileSchemes
+    class BasicTiling
+      QUADKEY_PATTERN = /\A[0-3]+\z/
+
+      attr_reader :bounds
+
+      def initialize(xmin, ymin, xmax, ymax)
+        raise ArgumentError, 'xmax must be greater than xmin' unless xmax > xmin
+        raise ArgumentError, 'ymax must be greater than ymin' unless ymax > ymin
+
+        @functional_bounds = CoordsBBox.new(
+          xmin: Float(xmin),
+          ymin: Float(ymin),
+          xmax: Float(xmax),
+          ymax: Float(ymax)
+        )
+        @bounds = CoordsBBox.new(
+          xmin: Float(xmin),
+          ymin: Float(ymin),
+          xmax: Float(xmax),
+          ymax: Float(ymax)
+        )
+      end
+
+      def tile(xcoord, ycoord, zoom)
+        zoom = Integer(zoom)
+        Tile.new(
+          x: x_index(Float(xcoord), zoom),
+          y: y_index(Float(ycoord), zoom),
+          z: zoom
+        )
+      end
+
+      def parent(*tile)
+        x, y, z = extract_tile(*tile)
+        Tile.new(x: x / 2, y: y / 2, z: z - 1)
+      end
+
+      def children(*tile)
+        x, y, z = extract_tile(*tile)
+        [[0, 0], [1, 0], [0, 1], [1, 1]].map do |delta_x, delta_y|
+          Tile.new(x: (2 * x) + delta_x, y: (2 * y) + delta_y, z: z + 1)
+        end
+      end
+
+      def bbox(*tile)
+        upper_left = ul(*tile)
+        bottom_right = br(*tile)
+
+        CoordsBBox.new(
+          xmin: upper_left.x,
+          ymin: bottom_right.y,
+          xmax: bottom_right.x,
+          ymax: upper_left.y
+        )
+      end
+
+      def quadkey(*tile)
+        x, y, z = extract_tile(*tile)
+        return '' if z.zero?
+
+        z.downto(1).map do |zoom|
+          digit = 0
+          mask = 1 << (zoom - 1)
+          digit += 1 if x.anybits?(mask)
+          digit += 2 if y.anybits?(mask)
+          digit
+        end.join
+      end
+
+      def quadkey_to_tile(quadkey)
+        raise ArgumentError, 'Input quadkey is invalid.' unless QUADKEY_PATTERN.match?(quadkey)
+
+        x = 0
+        y = 0
+
+        quadkey.reverse.each_char.with_index do |digit, index|
+          mask = 1 << index
+
+          case digit
+          when '1'
+            x |= mask
+          when '2'
+            y |= mask
+          when '3'
+            x |= mask
+            y |= mask
+          end
+        end
+
+        Tile.new(x: x, y: y, z: quadkey.length)
+      end
+
+      private
+
+      attr_reader :functional_bounds
+
+      def extract_tile(*tile)
+        values =
+          if tile.length == 1
+            candidate = tile.first
+            raise ArgumentError, 'expected a Tile or x/y/z components' unless candidate.respond_to?(:to_a)
+
+            candidate.to_a
+          else
+            tile
+          end
+
+        raise ArgumentError, 'expected exactly three tile components' unless values.length == 3
+
+        values.map { |value| Integer(value) }
+      end
+
+      def x_coord(x, zoom)
+        ((x / (2.0**zoom) * (functional_bounds.xmax - functional_bounds.xmin)) + functional_bounds.xmin)
+      end
+
+      def x_index(xcoord, zoom)
+        ((2.0**zoom) * (xcoord - functional_bounds.xmin) / (functional_bounds.xmax - functional_bounds.xmin)).floor
+      end
+    end
+
+    class BasicTilingBottomLeft < BasicTiling
+      def ul(*tile)
+        x, y, z = send(:extract_tile, *tile)
+        Coords.new(x: send(:x_coord, x, z), y: y_coord(y + 1, z))
+      end
+
+      def br(*tile)
+        x, y, z = send(:extract_tile, *tile)
+        Coords.new(x: send(:x_coord, x + 1, z), y: y_coord(y, z))
+      end
+
+      private
+
+      def y_coord(y, zoom)
+        bounds = send(:functional_bounds)
+        ((y / (2.0**zoom) * (bounds.ymax - bounds.ymin)) + bounds.ymin)
+      end
+
+      def y_index(ycoord, zoom)
+        bounds = send(:functional_bounds)
+        ((2.0**zoom) * (ycoord - bounds.ymin) / (bounds.ymax - bounds.ymin)).floor
+      end
+    end
+
+    class BasicTilingTopLeft < BasicTiling
+      def ul(*tile)
+        x, y, z = send(:extract_tile, *tile)
+        Coords.new(x: send(:x_coord, x, z), y: y_coord(y, z))
+      end
+
+      def br(*tile)
+        x, y, z = send(:extract_tile, *tile)
+        Coords.new(x: send(:x_coord, x + 1, z), y: y_coord(y + 1, z))
+      end
+
+      private
+
+      def y_coord(y, zoom)
+        bounds = send(:functional_bounds)
+        bounds.ymax - (y / (2.0**zoom) * (bounds.ymax - bounds.ymin))
+      end
+
+      def y_index(ycoord, zoom)
+        bounds = send(:functional_bounds)
+        ((2.0**zoom) * (bounds.ymax - ycoord) / (bounds.ymax - bounds.ymin)).floor
+      end
+    end
+
+    class DGTiling < BasicTilingBottomLeft
+      def initialize
+        super(-180, -90, 180, 270)
+        @bounds = CoordsBBox.new(xmin: -180.0, ymin: -90.0, xmax: 180.0, ymax: 90.0)
+      end
+
+      def children(*tile)
+        x, y, z = send(:extract_tile, *tile)
+        return [Tile.new(x: 0, y: 0, z: 1), Tile.new(x: 1, y: 0, z: 1)] if z.zero?
+
+        super(x, y, z)
+      end
+    end
+
+    class WebMercatorBL < BasicTilingBottomLeft
+      WEB_MERCATOR_LIMIT = 20_037_508.342789244
+
+      def initialize
+        super(-WEB_MERCATOR_LIMIT, -WEB_MERCATOR_LIMIT, WEB_MERCATOR_LIMIT, WEB_MERCATOR_LIMIT)
+      end
+
+      def quadkey(*tile)
+        x, y, z = send(:extract_tile, *tile)
+        return '' if z.zero?
+
+        z.downto(1).map do |zoom|
+          digit = 0
+          mask = 1 << (zoom - 1)
+          digit += 1 if x.anybits?(mask)
+          digit += 2 if y.nobits?(mask)
+          digit
+        end.join
+      end
+
+      def quadkey_to_tile(quadkey)
+        tile = super
+        Tile.new(x: tile.x, y: (2**quadkey.length) - tile.y - 1, z: tile.z)
+      end
+    end
+
+    class WebMercator < BasicTilingTopLeft
+      WEB_MERCATOR_LIMIT = WebMercatorBL::WEB_MERCATOR_LIMIT
+
+      def initialize
+        super(-WEB_MERCATOR_LIMIT, -WEB_MERCATOR_LIMIT, WEB_MERCATOR_LIMIT, WEB_MERCATOR_LIMIT)
+      end
+    end
+
+    class UTMTiling < BasicTilingTopLeft
+      attr_reader :tile_size, :zoom
+
+      def initialize(tile_size)
+        raise ArgumentError, 'tile_size must be positive' unless tile_size.positive?
+
+        @tile_size = tile_size
+        internal_zoom = Math.log2(10_000_000.0 / tile_size).ceil
+        map_size = tile_size * (2**internal_zoom)
+        @zoom = internal_zoom + 1
+
+        super(-map_size + 500_000.0, -map_size, map_size + 500_000.0, map_size)
+      end
+    end
+
+    class UTM5kmTiling < UTMTiling
+      def initialize
+        super(5_000)
+      end
+    end
+
+    class UTM10kmTiling < UTMTiling
+      def initialize
+        super(10_000)
+      end
+    end
+
+    class UTM100kmTiling < UTMTiling
+      def initialize
+        super(100_000)
+      end
+    end
+  end
+end

data/lib/tiletanic/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tiletanic
+  VERSION = '0.1.0'
+end

data/lib/tiletanic.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'tiletanic/version'
+require_relative 'tiletanic/base'
+require_relative 'tiletanic/tileschemes'
+require_relative 'tiletanic/geos_bootstrap'
+require_relative 'tiletanic/tile_cover'
+require_relative 'tiletanic/tilecover'
+require_relative 'tiletanic/cli'
+
+module Tiletanic
+  class Error < StandardError; end
+
+  module_function
+
+  def cover_geometry(...)
+    TileCover.cover_geometry(...)
+  end
+
+  def geos_factory(**options)
+    factory_options = { uses_lenient_assertions: true }.merge(options)
+
+    if defined?(RGeo::Geos) && (!RGeo::Geos.respond_to?(:supported?) || RGeo::Geos.supported?)
+      return RGeo::Geos.factory(factory_options)
+    end
+
+    RGeo::Cartesian.preferred_factory(options)
+  rescue StandardError => e
+    raise Error, "Could not create an RGeo geometry factory: #{e.message}"
+  end
+end

data/test/cli_test.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+
+class CLITest < Minitest::Test
+  ROOT = File.expand_path('..', __dir__)
+  EXECUTABLE = File.join(ROOT, 'exe', 'tiletanic')
+  FEATURE_COLLECTION_PAYLOAD = <<~JSON
+    {"type":"FeatureCollection","features":[{"geometry":{"type":"Polygon","coordinates":[[[-101.953125,43.59375],[-101.953125,44.296875],[-102.65625,44.296875],[-102.65625,43.59375],[-101.953125,43.59375]]]},"type":"Feature","properties":{}}]}
+  JSON
+  FEATURE_PAYLOAD = <<~JSON
+    {"geometry":{"coordinates":[[[-101.953125,43.59375],[-101.953125,44.296875],[-102.65625,44.296875],[-102.65625,43.59375],[-101.953125,43.59375]]],"type":"Polygon"},"type":"Feature"}
+  JSON
+  MULTIPOLYGON_PAYLOAD = <<~JSON
+    {"type":"MultiPolygon","coordinates":[[[[-101.953125,43.59375],[-101.953125,44.296875],[-102.65625,44.296875],[-102.65625,43.59375],[-101.953125,43.59375]]]]}
+  JSON
+  ZOOM_14_TILE_PAYLOAD = <<~JSON
+    {"geometry":{"coordinates":[[[0.0,0.0],[0.02197265625,0.0],[0.02197265625,0.02197265625],[0.0,0.02197265625],[0.0,0.0]]],"type":"Polygon"},"type":"Feature"}
+  JSON
+
+  def run_cli(*args, stdin_data: nil)
+    Open3.capture3(
+      Gem.ruby,
+      '-I',
+      File.join(ROOT, 'lib'),
+      EXECUTABLE,
+      *args,
+      stdin_data: stdin_data
+    )
+  end
+
+  def test_root_command
+    stdout, stderr, status = run_cli
+
+    assert status.success?, stderr
+    assert_includes stdout, 'cover_geometry'
+  end
+
+  def test_version
+    stdout, stderr, status = run_cli('--version')
+
+    assert status.success?, stderr
+    assert_equal "tiletanic #{Tiletanic::VERSION}\n", stdout
+  end
+
+  def test_cover_geometry_feature_collection
+    stdout, stderr, status = run_cli('cover_geometry', '-', stdin_data: FEATURE_COLLECTION_PAYLOAD)
+
+    assert status.success?, stderr
+    assert_equal "021323330\n", stdout
+  end
+
+  def test_cover_geometry_multipolygon_geometry
+    stdout, stderr, status = run_cli('cover_geometry', '-', stdin_data: MULTIPOLYGON_PAYLOAD)
+
+    assert status.success?, stderr
+    assert_equal "021323330\n", stdout
+  end
+
+  def test_cover_geometry_adjacent_tiles
+    stdout, stderr, status = run_cli('cover_geometry', '--adjacent', '-', stdin_data: FEATURE_PAYLOAD)
+
+    assert status.success?, stderr
+    assert_equal <<~OUTPUT, stdout
+      021323303
+      021323312
+      021323313
+      021323321
+      021323323
+      021323330
+      021323331
+      021323332
+      021323333
+    OUTPUT
+  end
+
+  def test_cover_geometry_geojson_stdout
+    stdout, stderr, status = run_cli('cover_geometry', '--geojson', '-', stdin_data: FEATURE_COLLECTION_PAYLOAD)
+
+    assert status.success?, stderr
+
+    payload = JSON.parse(stdout)
+    assert_equal 'FeatureCollection', payload['type']
+    assert_equal 1, payload['features'].length
+
+    feature = payload['features'].first
+    assert_equal 'Feature', feature['type']
+    assert_equal(
+      { 'quadkey' => '021323330', 'x' => 110, 'y' => 190, 'z' => 9 },
+      feature['properties']
+    )
+    assert_equal(
+      [[[-102.65625, 43.59375], [-101.953125, 43.59375], [-101.953125, 44.296875],
+        [-102.65625, 44.296875], [-102.65625, 43.59375]]],
+      feature.dig('geometry', 'coordinates')
+    )
+  end
+
+  def test_cover_geometry_geojson_file_output
+    Tempfile.create(%w[tiles .geojson]) do |file|
+      file.close
+
+      stdout, stderr, status = run_cli(
+        'cover_geometry',
+        '--geojson',
+        '--output',
+        file.path,
+        '-',
+        stdin_data: FEATURE_COLLECTION_PAYLOAD
+      )
+
+      assert status.success?, stderr
+      assert_equal '', stdout
+
+      payload = JSON.parse(File.read(file.path))
+      assert_equal 'FeatureCollection', payload['type']
+      assert_equal 1, payload['features'].length
+      assert_equal '021323330', payload.dig('features', 0, 'properties', 'quadkey')
+    end
+  end
+
+  def test_cover_geometry_geojson_rounds_tile_edges_to_zoom_precision
+    stdout, stderr, status = run_cli(
+      'cover_geometry',
+      '--zoom',
+      '14',
+      '--geojson',
+      '-',
+      stdin_data: ZOOM_14_TILE_PAYLOAD
+    )
+
+    assert status.success?, stderr
+    assert_includes stdout, '0.02197265625'
+
+    payload = JSON.parse(stdout)
+    feature = payload.fetch('features').first
+    assert_equal(
+      { 'quadkey' => '12000000000000', 'x' => 8192, 'y' => 4096, 'z' => 14 },
+      feature['properties']
+    )
+    assert_equal(
+      [[[0.0, 0.0], [0.02197265625, 0.0], [0.02197265625, 0.02197265625], [0.0, 0.02197265625], [0.0, 0.0]]],
+      feature.dig('geometry', 'coordinates')
+    )
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'minitest/autorun'
+require 'json'
+require 'open3'
+require 'set'
+require 'tempfile'
+
+require 'tiletanic'
+
+module GeometryAssertions
+  def geos_factory(srid: 4326)
+    @geos_factories ||= {}
+    @geos_factories[srid] ||= Tiletanic.geos_factory(srid: srid)
+  end
+
+  def decode_geometry(hash = nil, srid: 4326, **kwargs)
+    hash ||= kwargs
+    RGeo::GeoJSON.decode(JSON.generate(hash), geo_factory: geos_factory(srid:), json_parser: :json)
+  end
+
+  def assert_coords(expected_x, expected_y, actual, delta: 1e-9)
+    assert_in_delta(expected_x, actual.x, delta)
+    assert_in_delta(expected_y, actual.y, delta)
+  end
+
+  def assert_bbox(expected, actual, delta: 1e-9)
+    assert_in_delta(expected[:xmin], actual.xmin, delta)
+    assert_in_delta(expected[:ymin], actual.ymin, delta)
+    assert_in_delta(expected[:xmax], actual.xmax, delta)
+    assert_in_delta(expected[:ymax], actual.ymax, delta)
+  end
+end

data/test/tile_cover_test.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+
+class TileCoverTest < Minitest::Test
+  include GeometryAssertions
+
+  def setup
+    @dg = Tiletanic::TileSchemes::DGTiling.new
+    @wm = Tiletanic::TileSchemes::WebMercator.new
+  end
+
+  def test_rejects_non_rgeo_input
+    assert_raises(ArgumentError) { Tiletanic.cover_geometry(@dg, nil, 4).to_a }
+  end
+
+  def test_point_cover_matches_python_reference_values
+    point = decode_geometry(type: 'Point', coordinates: [-94.39453125, 15.908203125])
+
+    assert_equal [Tiletanic::Tile.new(x: 3, y: 4, z: 4)], Tiletanic.cover_geometry(@dg, point, 4).to_a
+    assert_equal Set[
+      Tiletanic::Tile.new(x: 973, y: 1204, z: 12),
+      Tiletanic::Tile.new(x: 973, y: 1205, z: 12),
+      Tiletanic::Tile.new(x: 974, y: 1204, z: 12),
+      Tiletanic::Tile.new(x: 974, y: 1205, z: 12)
+    ], Tiletanic.cover_geometry(@dg, point, 12).to_a.to_set
+  end
+
+  def test_multi_zoom_cover_collapses_to_larger_tiles_when_possible
+    point = decode_geometry(type: 'Point', coordinates: [-94.39453125, 15.908203125])
+
+    assert_equal Set[
+      Tiletanic::Tile.new(x: 486, y: 602, z: 11),
+      Tiletanic::Tile.new(x: 487, y: 602, z: 11)
+    ], Tiletanic.cover_geometry(@dg, point, [11, 12]).to_a.to_set
+  end
+
+  def test_polygon_cover_matches_python_reference_values
+    polygon = decode_geometry(
+      type: 'Polygon',
+      coordinates: [[
+        [74.5751953125, 46.86019101567027],
+        [73.916015625, 46.45299704748289],
+        [73.564453125, 46.21785176740299],
+        [73.32275390625, 45.920587344733654],
+        [73.289794921875, 45.56021795715051],
+        [73.465576171875, 45.27488643704894],
+        [74.036865234375, 44.96479793033104],
+        [74.256591796875, 45.07352060670971],
+        [74.322509765625, 45.48324350868221],
+        [74.46533203125, 45.91294412737392],
+        [74.849853515625, 46.057985244793024],
+        [74.99267578125, 46.354510837365254],
+        [75.465087890625, 46.40756396630067],
+        [76.102294921875, 46.42271253466719],
+        [76.904296875, 46.34692761055676],
+        [77.376708984375, 46.27863122156088],
+        [78.2666015625, 46.195042108660154],
+        [78.94775390625, 46.31658418182218],
+        [79.29931640625, 46.5286346952717],
+        [79.398193359375, 46.77749276376827],
+        [79.12353515625, 47.017716353979225],
+        [78.42041015625, 46.912750956378915],
+        [77.574462890625, 46.76244305208004],
+        [76.46484375, 46.81509864599243],
+        [76.036376953125, 46.98025235521883],
+        [75.399169921875, 46.830133640447386],
+        [74.893798828125, 46.93526088057719],
+        [74.5751953125, 46.86019101567027]
+      ]]
+    )
+
+    assert_equal Set[
+      Tiletanic::Tile.new(x: 90, y: 48, z: 7),
+      Tiletanic::Tile.new(x: 91, y: 48, z: 7),
+      Tiletanic::Tile.new(x: 180, y: 95, z: 8),
+      Tiletanic::Tile.new(x: 184, y: 96, z: 8),
+      Tiletanic::Tile.new(x: 184, y: 97, z: 8)
+    ], Tiletanic.cover_geometry(@dg, polygon, [7, 8]).to_a.to_set
+  end
+
+  def test_polygon_with_hole_cover_matches_python_reference_values
+    polygon = decode_geometry(
+      type: 'Polygon',
+      coordinates: [
+        [
+          [31.794433593749996, -28.979312036722447],
+          [31.289062500000004, -29.401319510041485],
+          [31.036376953125, -29.897805610155864],
+          [30.377197265625, -30.845647420182598],
+          [29.278564453125, -31.886886525780806],
+          [26.74072265625, -31.94283997285307],
+          [23.9501953125, -31.184609135743237],
+          [23.917236328125, -28.98892237190413],
+          [25.5322265625, -27.615406013399603],
+          [27.894287109374996, -27.019984007982554],
+          [30.377197265625, -27.32297494724568],
+          [31.794433593749996, -28.979312036722447]
+        ],
+        [
+          [28.652343749999996, -28.584521719370393],
+          [28.399658203125, -28.632746799225856],
+          [28.3282470703125, -28.724313406473463],
+          [28.1634521484375, -28.729130483430154],
+          [28.015136718749996, -28.8831596093235],
+          [27.745971679687496, -28.92163128242129],
+          [27.531738281249996, -29.200123477644983],
+          [27.410888671874996, -29.382175075145277],
+          [27.257080078125, -29.54956657394792],
+          [26.987915039062496, -29.640320395351402],
+          [27.1966552734375, -30.002516938570686],
+          [27.31201171875, -30.140376821599734],
+          [27.3834228515625, -30.14987731644208],
+          [27.366943359375, -30.249577240467637],
+          [27.39990234375, -30.334953881988564],
+          [27.454833984375, -30.33021268543272],
+          [27.745971679687496, -30.60954979719083],
+          [27.8997802734375, -30.619004797647793],
+          [28.108520507812496, -30.680439786468128],
+          [28.1744384765625, -30.50075098029068],
+          [28.14697265625, -30.462879341709876],
+          [28.229370117187496, -30.410781790845878],
+          [28.2513427734375, -30.29701788337205],
+          [28.3612060546875, -30.202113679097216],
+          [28.71826171875, -30.135626231134587],
+          [28.9544677734375, -30.026299582223675],
+          [29.179687499999996, -29.912090918781477],
+          [29.1192626953125, -29.831113764737136],
+          [29.141235351562504, -29.67850809103362],
+          [29.256591796874996, -29.640320395351402],
+          [29.300537109374996, -29.492206334848714],
+          [29.410400390625, -29.40610505570927],
+          [29.443359375, -29.31993078977759],
+          [29.393920898437496, -29.195328267099118],
+          [29.2950439453125, -29.08977693862319],
+          [29.091796875, -28.936054482136658],
+          [28.976440429687496, -28.90239722855847],
+          [28.916015625, -28.762843805266016],
+          [28.800659179687496, -28.772474183943018],
+          [28.789672851562496, -28.6905876542507],
+          [28.7017822265625, -28.656851034203406],
+          [28.652343749999996, -28.584521719370393]
+        ]
+      ]
+    )
+
+    assert_equal 11, Tiletanic.cover_geometry(@dg, polygon, 7).to_a.size
+  end
+
+  def test_web_mercator_cover_uses_top_left_tilescheme
+    bbox = @wm.bbox(3, 5, 4)
+    polygon = decode_geometry(
+      {
+        type: 'Polygon',
+        coordinates: [[
+          [bbox.xmin + 10, bbox.ymin + 10],
+          [bbox.xmax - 10, bbox.ymin + 10],
+          [bbox.xmax - 10, bbox.ymax - 10],
+          [bbox.xmin + 10, bbox.ymax - 10],
+          [bbox.xmin + 10, bbox.ymin + 10]
+        ]]
+      },
+      srid: 3857
+    )
+
+    assert_equal [Tiletanic::Tile.new(x: 3, y: 5, z: 4)], Tiletanic.cover_geometry(@wm, polygon, 4).to_a
+  end
+end