tiletanic 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad44a71edeceac24a8ee1bdcfbf6e27f5cd9b5db6a2015f6de3bea43789515d9
+  data.tar.gz: 0a6acb6902e9c9dfda5f88c915891ad91225262fb859e299f21c40421bdeb71c
+SHA512:
+  metadata.gz: ba3102d89e3debc3c2b41ec883d2ff6561d9824d2807b4115e9328c6a1ab7a68a7c35f9a8c2e895cd431632b46655b526c31c744f2c5879c36235011f738c29f
+  data.tar.gz: 98390891cc013f65043c656a1edda19f9498abcf0a82bbe74fd4be24a6e5aff4d4ebd5343018962d22a80ba334d20f49674d2140e3c7b0894a24137f7f160a8c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DigitalGlobe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,116 @@
+# Tiletanic for Ruby
+[![CI](https://github.com/DigitalGlobe/tiletanic-rb/actions/workflows/ci.yml/badge.svg)](https://github.com/DigitalGlobe/tiletanic-rb/actions/workflows/ci.yml)
+
+This repository contains an idiomatic Ruby port of the original Python
+[`digitalglobe/tiletanic`](https://github.com/DigitalGlobe/tiletanic)
+library, packaged as a Ruby gem with a CLI and test suite.
+
+It provides geospatial tiling utilities for converting between tile
+coordinates, projected coordinates, quadkeys, and geometry coverings.
+
+The upstream Python project remains the reference implementation. This
+repository is the Ruby implementation packaged for RubyGems.
+
+## Installation
+
+GEOS must be available on the host system so `rgeo` can perform
+topology operations.
+
+```bash
+gem install tiletanic
+```
+
+Or add it to an application bundle:
+
+```bash
+bundle add tiletanic
+```
+
+Or, while working on this repo:
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+For developer linting:
+
+```bash
+bundle exec rubocop
+```
+
+## Publishing
+
+The public gem name is `tiletanic`, matching both `require "tiletanic"` and
+the `tiletanic` command-line executable. See [RELEASING.md](RELEASING.md) for
+the maintainer release checklist.
+
+## Repository Layout
+
+- `lib/` contains the Ruby library code.
+- `exe/tiletanic` provides the command-line interface.
+- `test/` contains the automated test suite.
+
+## Usage
+
+```ruby
+require "tiletanic"
+
+scheme = Tiletanic::TileSchemes::DGTiling.new
+tile = scheme.tile(-102.3, 43.9, 9)
+quadkey = scheme.quadkey(tile)
+
+factory = Tiletanic.geos_factory(srid: 4326)
+geometry = RGeo::GeoJSON.decode(
+  '{"type":"Point","coordinates":[-94.39453125,15.908203125]}',
+  geo_factory: factory,
+  json_parser: :json
+)
+
+cover = Tiletanic.cover_geometry(scheme, geometry, [11, 12]).to_a
+```
+
+## CLI
+
+```bash
+bundle exec tiletanic --version
+bundle exec tiletanic cover_geometry --zoom 9 aoi.geojson
+cat aoi.geojson | bundle exec tiletanic cover_geometry -
+bundle exec tiletanic cover_geometry --geojson aoi.geojson
+bundle exec tiletanic cover_geometry --geojson --output tiles.geojson aoi.geojson
+```
+
+## GeoJSON Precision
+
+When GeoJSON encodes `DGTiling` tile boundaries in EPSG:4326, the minimum
+decimal precision that preserves the exact same tile boundaries at zoom `z`
+is:
+
+```text
+max(0, z - 3)
+```
+
+This works because the `DGTiling` grid spacing at zoom `z` is
+`360 / 2^z` degrees, which is also `45 / 2^(z - 3)`. Those coordinates
+terminate in decimal after `z - 3` places, so writing fewer places can move a
+tile edge enough to change tile coverage after a read/write round trip.
+
+The `cover_geometry --geojson` output path rounds tile coordinates to this
+precision.
+
+This guarantee only applies to geometries already aligned to the `DGTiling`
+grid, including GeoJSON generated by `tiletanic`. It does not apply to
+arbitrary AOIs: if a boundary lies extremely close to a tile edge, no fixed
+zoom-only decimal precision can guarantee identical coverage.
+
+| Zoom | Digits | Zoom | Digits | Zoom | Digits |
+| --- | ---: | --- | ---: | --- | ---: |
+| 0 | 0 | 9 | 6 | 18 | 15 |
+| 1 | 0 | 10 | 7 | 19 | 16 |
+| 2 | 0 | 11 | 8 | 20 | 17 |
+| 3 | 0 | 12 | 9 | 21 | 18 |
+| 4 | 1 | 13 | 10 | 22 | 19 |
+| 5 | 2 | 14 | 11 | 23 | 20 |
+| 6 | 3 | 15 | 12 | 24 | 21 |
+| 7 | 4 | 16 | 13 | 25 | 22 |
+| 8 | 5 | 17 | 14 | 26 | 23 |

data/exe/tiletanic

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'tiletanic'
+
+exit(Tiletanic::CLI.start(ARGV))

data/lib/tiletanic/base.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Tiletanic
+  Tile = Struct.new(:x, :y, :z, keyword_init: true) do
+    def initialize(...)
+      super
+      freeze
+    end
+  end
+
+  Coords = Struct.new(:x, :y, keyword_init: true) do
+    def initialize(...)
+      super
+      freeze
+    end
+  end
+
+  CoordsBBox = Struct.new(:xmin, :ymin, :xmax, :ymax, keyword_init: true) do
+    def initialize(...)
+      super
+      freeze
+    end
+  end
+
+  CoordsBbox = CoordsBBox
+end

data/lib/tiletanic/cli.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'optparse'
+require 'rgeo'
+require 'rgeo/geo_json'
+
+module Tiletanic
+  class CLI
+    def self.start(argv = ARGV, stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      new(argv, stdin:, stdout:, stderr:).run
+    end
+
+    def initialize(argv, stdin:, stdout:, stderr:)
+      @argv = argv.dup
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run
+      case @argv.first
+      when nil, '-h', '--help'
+        @stdout.puts(root_help)
+        0
+      when '-v', '--version'
+        @stdout.puts("tiletanic #{VERSION}")
+        0
+      when 'cover_geometry'
+        @argv.shift
+        run_cover_geometry(@argv)
+      else
+        @stderr.puts("Unknown command: #{@argv.first}")
+        @stderr.puts(root_help)
+        1
+      end
+    end
+
+    private
+
+    def root_help
+      <<~HELP
+        Usage:
+          tiletanic [--help] [--version]
+          tiletanic cover_geometry [options] AOI_GEOJSON
+
+        Commands:
+          cover_geometry    Calculate a tile covering for GeoJSON input.
+      HELP
+    end
+
+    def run_cover_geometry(args)
+      options = {
+        tilescheme: 'DGTiling',
+        zoom: 9,
+        adjacent: false,
+        quadkey: true,
+        geojson: false,
+        output: nil
+      }
+
+      help_requested = false
+
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: tiletanic cover_geometry [options] AOI_GEOJSON'
+
+        opts.on('--tilescheme NAME', 'Tiling scheme to use (default: DGTiling)') do |value|
+          options[:tilescheme] = value
+        end
+
+        opts.on('--zoom ZOOM', Integer, 'Zoom level for the tile covering (default: 9)') do |value|
+          raise OptionParser::InvalidArgument, value.to_s if value.negative? || value > 26
+
+          options[:zoom] = value
+        end
+
+        opts.on('--[no-]adjacent', 'Include tiles that only touch the geometry boundary') do |value|
+          options[:adjacent] = value
+        end
+
+        opts.on('--[no-]quadkey', 'Output quadkeys instead of x,y,z lines') do |value|
+          options[:quadkey] = value
+        end
+
+        opts.on('--geojson', 'Output a GeoJSON FeatureCollection instead of text tiles') do
+          options[:geojson] = true
+        end
+
+        opts.on('--output PATH', 'Write output to PATH instead of stdout ("-" for stdout)') do |value|
+          options[:output] = value
+        end
+
+        opts.on('-h', '--help', 'Show help') do
+          help_requested = true
+        end
+      end
+
+      parser.parse!(args)
+      if help_requested
+        @stdout.puts(parser)
+        return 0
+      end
+
+      input_path = args.shift
+      raise OptionParser::MissingArgument, 'AOI_GEOJSON' if input_path.nil?
+      raise OptionParser::InvalidArgument, args.join(' ') unless args.empty?
+
+      scheme = resolve_tilescheme(options[:tilescheme])
+      geometry = load_geojson_geometry(read_input(input_path), scheme)
+      tiles = Tiletanic.cover_geometry(scheme, geometry, options[:zoom])
+      tiles = filter_interior_tiles(scheme, tiles, geometry) unless options[:adjacent]
+      write_output(render_output(scheme, tiles, options), options[:output])
+      0
+    rescue JSON::ParserError => e
+      @stderr.puts("Invalid GeoJSON input: #{e.message}")
+      1
+    rescue OptionParser::ParseError => e
+      @stderr.puts(e.message)
+      @stderr.puts(parser)
+      1
+    rescue ArgumentError, Tiletanic::Error => e
+      @stderr.puts(e.message)
+      1
+    end
+
+    def resolve_tilescheme(name)
+      case name
+      when 'DGTiling'
+        TileSchemes::DGTiling.new
+      else
+        raise ArgumentError, "tilescheme '#{name}' is unsupported."
+      end
+    end
+
+    def read_input(path)
+      path == '-' ? @stdin.read : File.read(path)
+    rescue SystemCallError => e
+      raise ArgumentError, "Could not read input: #{e.message}"
+    end
+
+    def load_geojson_geometry(payload, _scheme)
+      factory = Tiletanic.geos_factory(srid: 4326)
+      data = JSON.parse(payload)
+
+      case data['type']
+      when 'FeatureCollection'
+        geometries = Array(data['features']).filter_map do |feature|
+          geometry_data = feature['geometry']
+          next unless polygonal_geojson?(geometry_data)
+
+          decode_geometry(geometry_data, factory)
+        end
+
+        geometries.reduce { |memo, geometry| memo.union(geometry) } || factory.collection([])
+      when 'Feature'
+        decode_geometry(data.fetch('geometry'), factory)
+      when String
+        decode_geometry(data, factory)
+      else
+        raise ArgumentError,
+              "The AOI_GEOJSON 'type' #{data['type'].inspect} " \
+              "is unsupported, it must be 'Feature', 'FeatureCollection', or a GeoJSON geometry"
+      end
+    end
+
+    def decode_geometry(geometry_data, factory)
+      geometry = RGeo::GeoJSON.decode(JSON.generate(geometry_data), geo_factory: factory, json_parser: :json)
+      raise ArgumentError, 'Could not decode GeoJSON geometry' if geometry.nil?
+
+      geometry
+    end
+
+    def polygonal_geojson?(geometry_data)
+      %w[Polygon MultiPolygon].include?(geometry_data&.fetch('type', nil))
+    end
+
+    def filter_interior_tiles(tile_scheme, tiles, geometry)
+      return enum_for(__method__, tile_scheme, tiles, geometry) unless block_given?
+
+      tiles.each do |tile|
+        tile_geometry = tile_polygon(tile_scheme, tile, geometry.factory)
+        yield tile unless geometry.touches?(tile_geometry)
+      end
+    end
+
+    def tile_polygon(tile_scheme, tile, factory)
+      coords = tile_scheme.bbox(tile)
+      ring = factory.linear_ring(
+        [
+          factory.point(coords.xmin, coords.ymin),
+          factory.point(coords.xmax, coords.ymin),
+          factory.point(coords.xmax, coords.ymax),
+          factory.point(coords.xmin, coords.ymax),
+          factory.point(coords.xmin, coords.ymin)
+        ]
+      )
+
+      factory.polygon(ring)
+    end
+
+    def render_output(tile_scheme, tiles, options)
+      return "#{JSON.pretty_generate(tile_feature_collection(tile_scheme, tiles))}\n" if options[:geojson]
+
+      render_text_output(tile_scheme, tiles, options)
+    end
+
+    def render_text_output(tile_scheme, tiles, options)
+      lines = tiles.map do |tile|
+        options[:quadkey] ? tile_scheme.quadkey(tile) : [tile.x, tile.y, tile.z].join(',')
+      end
+
+      return nil if lines.empty?
+
+      "#{lines.join("\n")}\n"
+    end
+
+    def write_output(payload, path)
+      if path.nil? || path == '-'
+        @stdout.write(payload) unless payload.nil?
+      else
+        File.write(path, payload || '')
+      end
+    rescue SystemCallError => e
+      raise Tiletanic::Error, "Could not write output: #{e.message}"
+    end
+
+    def tile_feature_collection(tile_scheme, tiles)
+      {
+        type: 'FeatureCollection',
+        features: tiles.map { |tile| tile_feature(tile_scheme, tile) }
+      }
+    end
+
+    def tile_feature(tile_scheme, tile)
+      bbox = tile_scheme.bbox(tile)
+      precision = geojson_precision_for_tile(tile)
+      coordinates = tile_polygon_coordinates(bbox, precision)
+
+      {
+        type: 'Feature',
+        properties: {
+          quadkey: tile_scheme.quadkey(tile),
+          x: tile.x,
+          y: tile.y,
+          z: tile.z
+        },
+        geometry: {
+          type: 'Polygon',
+          coordinates: [coordinates]
+        }
+      }
+    end
+
+    def geojson_precision_for_tile(tile)
+      [tile.z - 3, 0].max
+    end
+
+    def tile_polygon_coordinates(bbox, precision)
+      [
+        rounded_position(bbox.xmin, bbox.ymin, precision),
+        rounded_position(bbox.xmax, bbox.ymin, precision),
+        rounded_position(bbox.xmax, bbox.ymax, precision),
+        rounded_position(bbox.xmin, bbox.ymax, precision),
+        rounded_position(bbox.xmin, bbox.ymin, precision)
+      ]
+    end
+
+    def rounded_position(x, y, precision)
+      [round_coordinate(x, precision), round_coordinate(y, precision)]
+    end
+
+    def round_coordinate(value, precision)
+      rounded = value.round(precision)
+      rounded.zero? ? 0.0 : rounded
+    end
+  end
+end

data/lib/tiletanic/geos_bootstrap.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Tiletanic
+  module GeosBootstrap
+    module_function
+
+    def call
+      geos_c_library = ENV.fetch('GEOS_LIBRARY_PATH', nil)
+      geos_c_library = discover_library_path if geos_c_library.nil? || geos_c_library.empty?
+      return unless geos_c_library && File.file?(geos_c_library)
+
+      ENV['GEOS_LIBRARY_PATH'] = geos_c_library
+      preload_base_library(associated_base_library(geos_c_library))
+    end
+
+    def discover_library_path
+      candidate_paths.find { |path| path && File.file?(path) }
+    end
+
+    def associated_base_library(geos_c_library)
+      directory = File.dirname(geos_c_library)
+      library_files(directory, 'libgeos').find { |path| path && File.file?(path) } || common_base_library
+    end
+
+    def candidate_paths
+      executable = find_executable('geos-config')
+
+      candidates = []
+      if executable
+        bin_dir = File.dirname(executable)
+        candidates.concat(library_files(File.expand_path('../lib', bin_dir)))
+        candidates.concat(library_files(File.expand_path('../../lib', bin_dir)))
+      end
+
+      candidates.concat(common_library_files)
+      candidates.compact.uniq
+    end
+
+    def common_library_files
+      %w[
+        /usr/local/lib
+        /opt/local/lib
+        /opt/homebrew/lib
+        /usr/lib
+      ].flat_map { |directory| library_files(directory) }
+    end
+
+    def common_base_library
+      %w[
+        /usr/local/lib
+        /opt/local/lib
+        /opt/homebrew/lib
+        /usr/lib
+      ].flat_map { |directory| library_files(directory, 'libgeos') }.find { |path| path && File.file?(path) }
+    end
+
+    def library_files(directory, basename = 'libgeos_c')
+      Dir.glob(File.join(directory, "#{basename}.{dylib,so,so.*,dll}"))
+    end
+
+    def find_executable(name)
+      ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).each do |directory|
+        executable = File.join(directory, name)
+        return executable if File.executable?(executable) && !File.directory?(executable)
+      end
+
+      nil
+    end
+
+    def preload_base_library(path)
+      return unless path && File.file?(path)
+
+      require 'ffi'
+      FFI::DynamicLibrary.open(path, FFI::DynamicLibrary::RTLD_LAZY | FFI::DynamicLibrary::RTLD_GLOBAL)
+    rescue LoadError, StandardError
+      nil
+    end
+  end
+end
+
+Tiletanic::GeosBootstrap.call

data/lib/tiletanic/tile_cover.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'rgeo'
+
+module Tiletanic
+  module TileCover
+    class << self
+      def cover_geometry(tile_scheme, geometry, zooms, &)
+        return enum_for(__method__, tile_scheme, geometry, zooms) unless block_given?
+
+        validate_geometry!(geometry)
+        return if geometry.empty?
+
+        zoom_levels = normalize_zoom_levels(zooms)
+        current_tile = Tile.new(x: 0, y: 0, z: 0)
+
+        if polygonal?(geometry)
+          cover_polygonal(tile_scheme, current_tile, geometry, zoom_levels, zoom_levels.max, &)
+        else
+          cover_non_polygonal(tile_scheme, current_tile, geometry, zoom_levels, &)
+        end
+      end
+
+      private
+
+      def validate_geometry!(geometry)
+        return if geometry.respond_to?(:factory) && geometry.respond_to?(:empty?) && geometry.respond_to?(:intersects?)
+
+        raise ArgumentError, 'Input geometry is not a known RGeo geometry type'
+      end
+
+      def normalize_zoom_levels(zooms)
+        levels = Array(zooms).map { |zoom| Integer(zoom) }.uniq.sort
+        raise ArgumentError, 'at least one zoom level is required' if levels.empty?
+
+        levels
+      end
+
+      def polygonal?(geometry)
+        RGeo::Feature::Polygon.check_type(geometry) || RGeo::Feature::MultiPolygon.check_type(geometry)
+      end
+
+      def cover_non_polygonal(tile_scheme, current_tile, geometry, zoom_levels, &block)
+        tile_geometry = tile_polygon(tile_scheme, current_tile, geometry.factory)
+        return unless geometry.intersects?(tile_geometry)
+
+        if zoom_levels.include?(current_tile.z)
+          yield current_tile
+        else
+          tile_scheme.children(current_tile).each do |child_tile|
+            cover_non_polygonal(tile_scheme, child_tile, geometry, zoom_levels, &block)
+          end
+        end
+      end
+
+      def cover_polygonal(tile_scheme, current_tile, geometry, zoom_levels, max_zoom, &block)
+        tile_geometry = tile_polygon(tile_scheme, current_tile, geometry.factory)
+        return unless geometry.intersects?(tile_geometry)
+
+        if current_tile.z == max_zoom
+          yield current_tile
+        elsif geometry.contains?(tile_geometry)
+          if zoom_levels.include?(current_tile.z)
+            yield current_tile
+          else
+            tile_scheme.children(current_tile).each do |child_tile|
+              containing_tiles(tile_scheme, child_tile, zoom_levels, &block)
+            end
+          end
+        else
+          collected_tiles = []
+          coverage = 0
+
+          tile_scheme.children(current_tile).each do |child_tile|
+            child_tiles = []
+            cover_polygonal(tile_scheme, child_tile, geometry, zoom_levels, max_zoom) do |tile|
+              child_tiles << tile
+            end
+
+            if zoom_levels.include?(current_tile.z)
+              child_tiles.each do |tile|
+                collected_tiles << tile
+                coverage += 4**(max_zoom - tile.z)
+              end
+            else
+              child_tiles.each(&block)
+            end
+          end
+
+          if zoom_levels.include?(current_tile.z) && coverage == 4**(max_zoom - current_tile.z)
+            yield current_tile
+          else
+            collected_tiles.each(&block)
+          end
+        end
+      end
+
+      def containing_tiles(tile_scheme, current_tile, zoom_levels, &block)
+        if zoom_levels.include?(current_tile.z)
+          yield current_tile
+        else
+          tile_scheme.children(current_tile).each do |child_tile|
+            containing_tiles(tile_scheme, child_tile, zoom_levels, &block)
+          end
+        end
+      end
+
+      def tile_polygon(tile_scheme, tile, factory)
+        coords = tile_scheme.bbox(tile)
+        ring = factory.linear_ring(
+          [
+            factory.point(coords.xmin, coords.ymin),
+            factory.point(coords.xmax, coords.ymin),
+            factory.point(coords.xmax, coords.ymax),
+            factory.point(coords.xmin, coords.ymax),
+            factory.point(coords.xmin, coords.ymin)
+          ]
+        )
+
+        factory.polygon(ring)
+      end
+    end
+  end
+end

data/lib/tiletanic/tilecover.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'tile_cover'