honua 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9dcc6198120b25c09baeb8619f31cf9069d60c7b0dd7926e45aaff7144273302
+  data.tar.gz: c7c86a44e9e0e26384adc9b77a79f01904dc88684f076d4abd58916603fe70b9
+SHA512:
+  metadata.gz: 942643724880d18c28337d3ea140f9c2baebfd787e1b411f2de2e8e550d1d29a4c590b090a8da6901b4f007e2539a02f612c55d855fac30fdfd4071595989a46
+  data.tar.gz: 41fdf1137a3e5208fe0529a8c9b8b350fc47f9574a5b90644b0dee015a70e2a4973e8915046a06619ec19954b1e7bdc493b1783f69a5210c6f02e6019a83f0f6

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2021 dingsdax
+
+MIT License
+
+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,184 @@
+# Honua
+
+![](docs/header.png)
+
+> Honua is Hawaiian for earth 🌍
+
+Honua is a simple geographic mapping Library for Ruby. It allows you to stitch geographic map images based on map tiles, provided by a rastered tile server (in Mercator projection). It was highly inspired by [ModestMaps](https://github.com/modestmaps/).
+
+## Requirements
+
+1. [Ruby 3.0](https://www.ruby-lang.org)
+2. [libvips](https://libvips.github.io/libvips/)
+
+## Setup
+
+To install, run:
+``` ruby
+gem install honua
+```
+
+Add the following to your Gemfile:
+
+``` ruby
+gem "honua"
+```
+
+## Usage
+
+### Coordinate Systems
+
+Like almost every popular mapping library it uses the [Web Mercator Projection](https://en.wikipedia.org/wiki/Web_Mercator_projection) as basis for conversions and its tile coordinate system.
+
+* A [Location](lib/honua/location.rb) is a geographic place described in latitude and longitude coordinates in degrees.
+* A [Coordinate](lib/honua/coordinate.rb) is a geographic place described in a tile coordinate system with columns (x), rows (y) and a zoom level.
+
+To convert from `Location` to `Coordinate` at a certain zoom level:
+
+1. convert latitude and longitude to radians
+2. [reproject coordinates](https://epsg.io/transform#s_srs=4326&t_srs=3857) to Web Mercator projections
+3. transform range of `column` and `row` to 0 - 1 and shift origin to top left corner
+4. multiply `row` and `column` with number of tiles (2**zoom) and round results
+
+### Configuration
+
+At minimal you need to provide the url for a [tile server](https://github.com/Overv/openstreetmap-tile-server) and the appropriate attribution text for the used tiles. If the map is too small to show the attribution it will be skipped and you need to provide it separetly. Don't forget to check out terms and service for the tile server you are planning to use.
+
+``` ruby
+Honua.configure do |config|
+  # each zoom level is a directory, each column is a subdirectory, and each tile in that column is a file
+  config.tiles_url = 'http://localhost:8080/%<zoom>s/%<column>s/%<row>s.png'
+  config.attribution_text = '<b>© OpenStreetMap contributors</b>'
+end
+```
+
+Checkout [configuration.rb](lib/honua/configuration.rb) for further details.
+
+A map is defined by a center location, map dimensions (width and height in pixels) and a [zoom level](https://wiki.openstreetmap.org/wiki/Zoom_levels). The `draw` method downloads all necessary tiles for the map, stitches them together, adds the proper attribution at the bottom and finally returns a [`Vips::Image`](https://www.rubydoc.info/gems/ruby-vips/Vips/Image).
+
+``` ruby
+map_center = Honua::Location.new(35.689487, 139.691711) # Tokyo
+map = Honua::Map.new(center: map_center, width: 600, height: 600, zoom: 12)
+map_image = map.draw
+map_image.write_to_file('tokyo.png') # use Vips to write to file
+```
+
+### Helpers
+
+There might be use cases, where you have a bunch of location instead of map center, or you either have map dimensions or a zoom level but not both. Honua includes helpers that can be used to calculate the needed map input parameters:
+
+* [`Honua::Helpers.map_span(locations:)`](lib/honua/helpers.rb) returns the top left and bottom right coordinates at zoom level 0
+* [`Honua::Helpers.map_span(top_left:, bottom_right:)`](lib/honua/helpers.rb) returns the center coordinate based on map spanning top left and bottom right coordinates
+* [`Honua::Helpers.calculate_zoom(top_left:, bottom_right:, width:, height:)`](lib/honua/helpers.rb) returns zoom level based on map spanning coordinates and map dimensions
+* [`Honua::Helpers.calculate_map_dimensions(top_left:, bottom_right:, zoom:)`](lib/honua/helpers.rb) returns map dimensions (in pixels) based on map spanning coordinates and a zoom value
+* [`Honua::Helpers.text_label((text:, dpi:, text_colour:, shadow_colour:))`](lib/honua/helpers.rb) generates a text label image with shadow and shadow offset, which can be places on the map.
+* [`Honua::Helpers.hex2rgb(hex)`](lib/honua/helpers.rb) converts hex color strings to an array of RGB
+
+Please refer to the [examples](docs) for how these helpers might be used.
+
+[🏙 World & Cities](docs/world_calc_zoom.rb)
+
+![](docs/the_world.png)
+
+
+[🌉 From SF to LA](docs/from_sf_to_la.rb)
+
+![](docs/california.png)
+
+
+[🇨🇦 Maps of Vancouer](docs/vancouver_maps.rb)
+
+![](docs/vancouver_500x500z11.png)
+
+## Development
+
+To contribute, run:
+
+    git clone https://github.com//honua.git
+    cd honua
+    bundle install
+
+You can also use the IRB console for direct access to all objects:
+``` shell
+bin/console
+```
+
+### Tile Server
+
+If you want to use the included [tile server](https://github.com/Overv/openstreetmap-tile-server) be sure to install [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/).
+
+After you downloaded an `.osm.pbf` extract and `.poly` file from e.g [Geofabrik](https://download.geofabrik.de/) for the region that you're interested in, replace the placeholders in `docker-compose.yml` and run the importer with:
+``` shell
+docker compose up osmimport
+
+```
+
+To start the tile server, run:
+``` shell
+docker compose up osmtileserver
+
+```
+
+You can now go to `localhost:8080` for a fullscreen [Leaflet](https://leafletjs.com/) based map. To use the tile server in Honua, add the following configuration in your code:
+``` ruby
+Honua.configure do |config|
+  config.tiles_url = 'http://localhost:8080/tile/%<zoom>s/%<column>s/%<row>s.png'
+  config.attribution_text = '<b>© OpenStreetMap contributors</b>' # don't forget to attribute 👍
+end
+```
+
+
+😏 If you want to merge 2 or more extracts you can use [osmctools](https://gitlab.com/osm-c-tools/osmctools) or [osmctools-docker](https://github.com/tobilg/osmctools-docker).
+
+## Tests
+
+To test, run:
+``` shell
+bundle exec rake
+```
+
+## Versioning
+
+Read [Semantic Versioning](https://semver.org) for details. Briefly, it means:
+
+- Major (X.y.z) - Incremented for any backwards incompatible public API changes.
+- Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
+- Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.
+
+## Contributions
+
+Read [CONTRIBUTING](CONTRIBUTING.md) for details.
+
+## License
+
+Copyright 2021 by dingsdax.
+Read [LICENSE](LICENSE) for details.
+
+## History
+
+Read [CHANGES](CHANGES.md) for details.
+Built with [Gemsmith](https://www.alchemists.io/projects/gemsmith).
+
+## Further Reading & Credits
+
+Some of the resources that helped building and understanding the underlying logic behind this gem.
+This started out as a Ruby port of [modest-maps.js](https://github.com/modestmaps/modestmaps-js) but took on a life of its own. [ModestMaps](https://github.com/modestmaps/) and [Stamen](https://stamen.com/) are awesome! Big shoutout for their work and inspiration 🙇‍♂️.
+
+* [Bing Maps Tile System](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system)
+* [OpenLayers FAQ](https://openlayers.org/en/latest/doc/faq.html)
+* [OSM Slippy map tilenames](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)
+* [ModestMaps Wiki](https://github.com/modestmaps/modestmaps-js/wiki)
+* [Mercator Projection](https://en.wikipedia.org/wiki/Mercator_projection)
+* [Tiles à la Google Maps](https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection)
+* [Coordinate Systems Worldwide](https://epsg.io)
+
+## Attributions
+
+<div>Logo & marker icons made by <a href="https://www.freepik.com" title="Freepik">Freepik</a> from <a href="https://www.flaticon.com/" title="Flaticon">www.flaticon.com</a></div>
+
+Toner & Terrain map tiles by Stamen Design (http://stamen.com),
+under CC BY 3.0 (http://creativecommons.org/licenses/by/3.0).
+Data by OpenStreetMap (http://openstreetmap.org), under ODbL (http://www.openstreetmap.org/copyright).
+
+[Explorer Base Map header image](https://visibleearth.nasa.gov/images/147190/explorer-base-map/147193)
+NASA Earth Observatory map by Joshua Stevens using data from NASA’s MODIS Land Cover, the Shuttle Radar Topography Mission (SRTM), the General Bathymetric Chart of the Oceans (GEBCO), and Natural Earth boundaries.

data/lib/honua.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module Honua
+  Point = Struct.new(:x, :y)
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+  end
+end

data/lib/honua/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Honua
+  class Configuration
+    attr_accessor :attribution_bgcolor, :attribution_fgcolor, :attribution_text,
+                  :max_fetch_attempts, :tile_height, :tile_width,
+                  :tiles_url, :user_agent
+
+    def initialize
+      # max attempts to fetch a tile until given up and returning an empty tile
+      @max_fetch_attempts = 3
+
+      # OSM map tiles are typically 256x256
+      # https://wiki.openstreetmap.org/wiki/Tiles
+      @tile_height = 256
+      @tile_width = 256
+
+      # user agent that's used to make requests to the tile server
+      @user_agent = Honua::Identity::VERSION_LABEL
+
+      # attribution_text can contain some Pango markup
+      # https://developer.gnome.org/pango/stable/pango-Markup.html
+      @attribution_text = nil
+      @attribution_fgcolor = '#fff'
+      @attribution_bgcolor = '#000'
+    end
+  end
+end

data/lib/honua/coordinate.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# a coordinate is used to indentify a tile based on the zoom level and the tile grid's x/y coordinates
+module Honua
+  class Coordinate
+    attr_accessor :row, :column, :zoom
+
+    def initialize(row, column, zoom = 0)
+      @row    = row
+      @column = column
+      @zoom   = zoom
+    end
+
+    def zoom_to(zoom_level)
+      Coordinate.new(
+        row * (2**(zoom_level - zoom)),
+        column * (2**(zoom_level - zoom)),
+        zoom_level
+      )
+    end
+
+    # the top left most coordinate within the same tile
+    # used to identify the tile within the the tile rid
+    def container
+      Coordinate.new(row.to_i, column.to_i, zoom)
+    end
+
+    def up(distance = 1)
+      Coordinate.new(row - distance, column, zoom)
+    end
+
+    def right(distance = 1)
+      Coordinate.new(row, column + distance, zoom)
+    end
+
+    def down(distance = 1)
+      Coordinate.new(row + distance, column, zoom)
+    end
+
+    def left(distance = 1)
+      Coordinate.new(row, column - distance, zoom)
+    end
+
+    def to_location
+      n = 2.0**zoom
+      lon = column / n * 360.0 - 180
+      lat_rad = Math.atan(Math.sinh(Math::PI * (1 - 2 * row / n)))
+      lat = rad2deg(lat_rad)
+
+      Location.new(lat, lon)
+    end
+
+    def ==(other)
+      row == other.row &&
+        column == other.column &&
+        zoom == other.zoom
+    end
+
+    private
+
+    # radians to degrees
+    def rad2deg(radians)
+      radians * (180 / Math::PI)
+    end
+  end
+end

data/lib/honua/helpers.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Honua
+  class Helpers
+    class << self
+      # returns the top left and bottom right coordinates at zoom level 0
+      # these corners are used to define the map span
+      def map_span(locations:)
+        coordinates = locations.map(&:to_coordinate)
+
+        top_left = Coordinate.new(
+          coordinates.min_by(&:row).row,
+          coordinates.min_by(&:column).column,
+          coordinates.min_by(&:zoom).zoom
+        )
+
+        bottom_right = Coordinate.new(
+          coordinates.max_by(&:row).row,
+          coordinates.max_by(&:column).column,
+          coordinates.max_by(&:zoom).zoom
+        )
+
+        [top_left, bottom_right]
+      end
+
+      # returns the center coordinate based on map spanning top left and bottom right coordinates
+      def map_center_coordinate(top_left:, bottom_right:)
+        row    = (top_left.row    + bottom_right.row)    / 2.0
+        column = (top_left.column + bottom_right.column) / 2.0
+        zoom   = (top_left.zoom   + bottom_right.zoom)   / 2.0
+
+        Coordinate.new(row, column, zoom)
+      end
+
+      # returns zoom level based on map spanning coordinates and map dimensions
+      # shameless copy from modestmaps.js
+      def calculate_zoom(top_left:, bottom_right:, width:, height:)
+        # multiplication factor between horizontal span and map width
+        h_factor = (bottom_right.column - top_left.column) / (width.to_f / Honua.configuration.tile_width)
+
+        # possible horizontal zoom to fit geographical extent in map width
+        h_possible_zoom = top_left.zoom - (Math.log(h_factor) / Math.log(2)).ceil
+
+        # multiplication factor between vertical span and map height
+        v_factor = (bottom_right.row - top_left.row) / (height.to_f / Honua.configuration.tile_height)
+
+        # possible vertical zoom to fit geographical extent in map height
+        v_possible_zoom = top_left.zoom - (Math.log(v_factor) / Math.log(2)).ceil
+
+        # initial zoom to fit extent vertically and horizontally
+        [h_possible_zoom, v_possible_zoom].min
+      end
+
+      # returns map dimensions (in pixels) based on map spanning coordinates and a zoom value
+      def calculate_map_dimensions(top_left:, bottom_right:, zoom:)
+        top_left = top_left.zoom_to(zoom)
+        bottom_right = bottom_right.zoom_to(zoom)
+
+        # map width and height in pixels
+        width = ((bottom_right.column - top_left.column) * Honua.configuration.tile_width).to_i
+        height = ((bottom_right.row - top_left.row) * Honua.configuration.tile_height).to_i
+
+        [width, height]
+      end
+
+      # text can contain some Pango markup
+      # https://developer.gnome.org/pango/stable/pango-Markup.html
+      def text_label(text:, dpi: 100, text_colour: [0, 0, 0, 255], shadow_colour: [255, 255, 255, 150], blur: 1.5)
+        text_mask, = Vips::Image.text(text, dpi: dpi)
+
+        canvas_width = text_mask.width + 10
+        canvas_height = text_mask.height + 10
+        text_mask = text_mask.gravity('west', canvas_width, canvas_height)
+        # use 0 - 1 for the masks
+        text_mask /= 255
+
+        shadow_mask = text_mask.gaussblur(blur)
+        # credit: https://github.com/libvips/pyvips/issues/204
+        text_mask = text_mask * text_colour + ((text_mask * -1) + 1) * shadow_mask * shadow_colour
+
+        text_mask.unpremultiply.copy(interpretation: 'srgb')
+      end
+
+      # convert hex color string to something VIPS understands
+      def hex2rgb(hex)
+        color_array = (hex.match(/#(..?)(..?)(..?)/))[1..3]
+        color_array.map! { |x| x + x } if hex.size == 4 # e.g. #333
+        color_array.map(&:hex)
+      end
+    end
+  end
+end

data/lib/honua/identity.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Honua
+  module Identity
+    NAME = 'honua'
+    LABEL = 'Honua'
+    VERSION = '0.1.0'
+    VERSION_LABEL = "#{LABEL} #{VERSION}"
+  end
+end

data/lib/honua/location.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Honua
+  # locations are actual places in the world
+  # they are in latitude and longitude (EPSG:4326)
+  Location = Struct.new(:lat, :lon) do
+    def to_coordinate(zoom: 0)
+      lat_rad = deg2rad(lat)
+      n = 2.0**zoom
+      column = ((lon + 180) / 360.0 * n)
+      row = ((1 - Math.log(Math.tan(lat_rad) + (1 / Math.cos(lat_rad))) / Math::PI) / 2 * n)
+
+      Coordinate.new(row, column, zoom)
+    end
+
+    private
+
+    # degrees to radians
+    def deg2rad(degrees)
+      (degrees * Math::PI) / 180
+    end
+  end
+end

data/lib/honua/map.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'async'
+require 'forwardable'
+require 'ruby-vips'
+
+module Honua
+  class Map
+    extend Forwardable
+
+    attr_reader :width, :height, :zoom
+
+    def initialize(center:, width:, height:, zoom:)
+      @width = width
+      @height = height
+      @reference, @offset = reference_point(center.zoom_to(zoom))
+      @tiles = []
+      @zoom = zoom
+    end
+
+    def_delegators 'Honua.configuration',
+                   :tile_width, :tile_height,
+                   :attribution_text, :attribution_fgcolor, :attribution_bgcolor
+
+    def draw
+      fetch_tiles
+      render
+    end
+
+    # return an x,y point on the map image for a geographical location
+    def location2point(location)
+      x = @offset.x
+      y = @offset.y
+      coordinate = location.to_coordinate(zoom: @reference.zoom)
+
+      # distance from the know coordinate offset
+      x += tile_width * (coordinate.column - @reference.column)
+      y += tile_height * (coordinate.row - @reference.row)
+
+      x += @width / 2
+      y += @height / 2
+
+      Point.new(x.to_i, y.to_i)
+    end
+
+    def point2location(point)
+      # TODO: to be implemented
+    end
+
+    private
+
+    # returns the initial tile coordinate and its offset relative to the map center
+    def reference_point(coordinate)
+      # top left coordinate of tile containing center coordinate
+      top_left_coordinate = coordinate.container
+
+      # initial tile position offset, assuming centered tile in grid
+      offset_x = ((top_left_coordinate.column - coordinate.column) * Honua.configuration.tile_width).round
+      offset_y = ((top_left_coordinate.row - coordinate.row) * Honua.configuration.tile_height).round
+      offset = Point.new(offset_x, offset_y)
+
+      [top_left_coordinate, offset]
+    end
+
+    def fetch_tiles
+      coordinate, corner = top_left
+
+      Async do
+        (corner.y..@height).step(tile_height).each do |y|
+          current_coordinate = coordinate.dup
+          (corner.x..@width).step(tile_width).each do |x|
+            Async do
+              @tiles << Tile.get(current_coordinate, Point.new(x, y))
+            end
+            current_coordinate = current_coordinate.right
+          end
+          coordinate = coordinate.down
+        end
+      end
+    end
+
+    # get top left coordinate and offset to map
+    def top_left
+      x_shift = 0
+      y_shift = 0
+
+      corner = Point.new(@offset.x + @width / 2, @offset.y + @height / 2)
+
+      # move left on the map until we have the starting coordinate and offset
+      while corner.x.positive?
+        corner.x -= tile_width
+        x_shift += 1
+      end
+
+      # move up on the map until we have the starting coordinate and offset
+      while corner.y.positive?
+        corner.y -= tile_height
+        y_shift += 1
+      end
+
+      coordinate = Coordinate.new(@reference.row - y_shift, @reference.column - x_shift, @reference.zoom)
+
+      [coordinate, corner]
+    end
+
+    # create a canvas and draw tile images based on their offset onto it
+    def render
+      canvas = Vips::Image.grey(@width, @height)
+
+      @tiles.each do |tile|
+        canvas = canvas.insert(tile.image, tile.offset.x, tile.offset.y) # rubocop:disable Style/RedundantSelfAssignment
+      end
+
+      # add attribution image to bottom corner if available & attribution fits into image
+      if add_attribution?
+        options = { x: canvas.width - attribution.width, y: canvas.height - attribution.height }
+        canvas = canvas.composite2(attribution, :over, **options)
+      end
+
+      canvas
+    end
+
+    # create attribution image
+    def attribution
+      @attribution ||= begin
+        mask = Vips::Image.text(attribution_text)
+        mask = mask.embed(4, 2, mask.width + 8, mask.height + 4)
+        mask.ifthenelse(Helpers.hex2rgb(attribution_fgcolor), Helpers.hex2rgb(attribution_bgcolor), blend: true)
+      end
+    end
+
+    def add_attribution?
+      !attribution_text.nil? && attribution.width < @width && attribution.height < @height
+    end
+  end
+end

data/lib/honua/tile.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'open-uri'
+require 'ruby-vips'
+
+# a tile is an image file representing a coordinate at a certain zoom level
+# * request a tile from the tile server for a coordinate
+# * use scaled version if not available at on of the next zoom levels
+# * if row or column is out of bounds => start from the left again
+# * if max_fetch_attempts are reached => use empty tile
+module Honua
+  class Tile
+    extend Forwardable
+
+    attr_reader :image, :offset, :coordinate
+
+    def self.get(coordinate, offset)
+      tile = Tile.new(coordinate, offset)
+      tile.fetch
+
+      tile
+    end
+
+    def initialize(coordinate, offset)
+      @coordinate = coordinate
+      @offset = offset
+
+      @image = blank_tile
+    end
+
+    def_delegators :@coordinate, :column, :row, :zoom
+    def_delegators 'Honua.configuration', :max_fetch_attempts, :tiles_url, :tile_width, :tile_height, :user_agent
+
+    # fetch tile image through url that includes zoom level and the tile grid's x/y coordinates
+    def fetch(attempt = 1, scale = 1)
+      if attempt >= max_fetch_attempts
+        @image = blank_tile
+      else
+        raw_tile = if url.start_with?('file://')
+                     File.read(url.gsub('file://', ''))
+                   else
+                     URI.parse(url).open('User-Agent' => user_agent, &:read)
+                   end
+
+        @image = Vips::Image.new_from_buffer(raw_tile, '')
+      end
+
+      @image = @image.resize(scale) if scale > 1
+    rescue OpenURI::HTTPError, Errno::ENOENT
+      old_row = @coordinate.row
+      old_column = @coordinate.column
+
+      # out of bounds columns or rows => try starting from the left or top
+      @coordinate.row    = @coordinate.row - (2**@coordinate.zoom)    if @coordinate.row > (2**@coordinate.zoom - 1)
+      @coordinate.column = @coordinate.column - (2**@coordinate.zoom) if @coordinate.column > (2**@coordinate.zoom - 1)
+
+      @coordinate.row    = @coordinate.row + (2**@coordinate.zoom)    if @coordinate.row.negative?
+      @coordinate.column = @coordinate.column + (2**@coordinate.zoom) if @coordinate.column.negative?
+
+      return fetch(attempt + 1) if old_row != @coordinate.row || old_column != @coordinate.column # if out of bounds
+
+      # if tile was not available try next zoom level and scale
+      recalculate!(scale)
+      fetch(attempt + 1, scale * 2)
+    end
+
+    private
+
+    # try the next lower zoom level if tile is not available
+    def recalculate!(scale)
+      neighbor = @coordinate.zoom_to(zoom - 1)
+      parent = neighbor.container
+
+      col_shift = 2 * (neighbor.column - parent.column)
+      row_shift = 2 * (neighbor.row - parent.row)
+
+      @offset.x -= scale * tile_width * col_shift
+      @offset.y -= scale * tile_height * row_shift
+      @coordinate = parent
+    end
+
+    def url
+      format(tiles_url, zoom: zoom, column: column, row: row)
+    end
+
+    def blank_tile
+      Vips::Image.grey(tile_width, tile_height)
+    end
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: honua
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joesi D.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-02-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.28'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.28'
+- !ruby/object:Gem::Dependency
+  name: ruby-vips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+description: |
+  A mapping library to stitch geographic map images based on map tiles
+  provided by a rastered tile server.
+email:
+- dingsdax@fastmail.fm
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE
+files:
+- LICENSE
+- README.md
+- lib/honua.rb
+- lib/honua/configuration.rb
+- lib/honua/coordinate.rb
+- lib/honua/helpers.rb
+- lib/honua/identity.rb
+- lib/honua/location.rb
+- lib/honua/map.rb
+- lib/honua/tile.rb
+homepage: https://github.com/dingsdax/honua
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/dingsdax/honua/issues
+  changelog_uri: https://github.com/dingsdax/honua/blob/master/CHANGES.md
+  documentation_uri: https://github.com/dingsdax/honua
+  source_code_uri: https://github.com/dingsdax/honua
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: A Ruby geographic mapping library
+test_files: []