Tiletanic for Ruby

This repository contains an idiomatic Ruby port of the original Python 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.

On macOS:

brew install geos

On Debian or Ubuntu:

sudo apt-get install libgeos-dev

Then install the gem:

gem install tiletanic

Or add it to an application bundle:

bundle add tiletanic

Verify the install:

tiletanic --version
ruby -rtiletanic -e 'puts Tiletanic::VERSION'

Development

While working on this repo:

bundle install
bundle exec rake test

For developer linting:

bundle exec rubocop

Publishing

The public gem name is tiletanic, matching both require "tiletanic" and the tiletanic command-line executable. See RELEASING.md for the maintainer release checklist.

Repository Layout

• lib/ contains the Ruby library code.
• bin/tiletanic provides the command-line interface.
• test/ contains the automated test suite.

Usage

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

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:

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