travertine 0.2.0 → 0.3.0

data/README.textile

@@ -0,0 +1,41 @@
+h1. travertine
+
+Travertine (named for the tile) is a library for cutting images into square tiles used for map display. The map tiling algorithm is based on the "YM4R":http://rubyforge.org/projects/ym4r/ project.
+
+h2. Example
+
+<pre>
+image = Magick::ImageList.new("mymap.jpg")
+zoom_levels = 3
+
+tile_sets = Travertine.cut_tiles(image, zoom_levels)
+
+tile_sets.each_with_index do |tile_set, zoom|
+  coordinates = Travertine.tile_coordinates_for_zoom(zoom)
+  tile_set.each_with_index do |tile, i|
+    # Writes each tile out to a file named like 'tile_zoom_x_y.jpg'
+    tile.write("tile_#{zoom}_#{coordinates[i][0]}_#{coordinates[i][1]}.jpg")
+  end
+end
+</pre>
+
+
+h2. Todo
+
+* Crop and/or autofill source image to make it square prior to tiling
+* Allow for stitching together multiple source images
+
+h2. Contributing to travertine
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+h4. Copyright
+
+Copyright (c) 2011 Micah Wedemeyer. See LICENSE.txt for
+further details.

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/lib/travertine.rb

@@ -1,8 +1,18 @@
 class Travertine
-
   # This is the correct size for Google maps tiles
   DEFAULT_TILE_SIZE = 256
 
+  # Cuts tiles from a source image at various zoom levels.
+  #
+  # Parameters:
+  #
+  # <tt>img</tt>: A +Magick::Image+ object for the source image. For proper tiling it should be exactly square.
+  # <tt>max_zoom</tt>: The maximum level of zoom. max_zoom of 0 has 1 tile. Each successive level has 4 times as many tiles as the previous.
+  # <tt>tile_size</tt>: The size of each tile in pixels.
+  #
+  # Returns:
+  #
+  # An +Array+ of +Arrays+, where each inner array contains the tiles for a given zoom level. The first +Array+ will have 1 tile, for zoom level 0. The second will have 4 for zoom level 1, and so on.
   def self.cut_tiles(img, max_zoom, tile_size = DEFAULT_TILE_SIZE)
     tile_sets = []
     (0..max_zoom).collect.reverse.each do |zoom|
@@ -18,6 +28,18 @@ class Travertine
     tile_sets.reverse
   end
 
+  # Cuts a tile from the source image.
+  #
+  # Parameters:
+  #
+  # <tt>img</tt>: A +Magick::Image+ object for the source image.
+  # <tt>x</tt>: The x coordinate of the tile to cut. Coordinates are specified in terms of the tile grid, not pixels.
+  # <tt>y</tt>: The y coordinate of the tile to cut. Coordinates are specified in terms of the tile grid, not pixels.
+  # <tt>tile_size</tt>: The size of each tile in pixels.
+  #
+  # Returns:
+  #
+  # A +Magick::Image+ tile.
   def self.cut_tile(img, x, y, tile_size = DEFAULT_TILE_SIZE)
     tile = Magick::Image.new(tile_size, tile_size)
 
@@ -27,6 +49,15 @@ class Travertine
     tile.import_pixels(0, 0, tile_size, tile_size, "RGBA",img.export_pixels(img_x, img_y, tile_size, tile_size, "RGBA"))
   end
 
+  # Calculates the tile grid for a given zoom level.
+  #
+  # Parameters:
+  #
+  # <tt>zoom_level</tt>: The level of zoom to compute the tile grid for.
+  #
+  # Returns:
+  #
+  # An +Array+ of 2-element +Arrays+ representing the tile x,y coordinates. For example, the tile grid at zoom 1 is [[0,0,], [0,1], [1,0], [1,1]]
   def self.tile_coordinates_for_zoom(zoom_level)
     [].tap do |coords|
       (0..((2 ** zoom_level) - 1)).each do |x|
@@ -37,11 +68,50 @@ class Travertine
     end
   end
 
+  # Calculates the total tile count for a given zoom level.
+  #
+  # Parameters:
+  #
+  # <tt>zoom_level</tt>: The level of zoom to compute the tile grid for.
+  #
+  # Returns:
+  #
+  # An +Integer+ count of the number of tiles for a given zoom level.
+  def self.tile_count_for_zoom(zoom_level)
+    4 ** zoom_level
+  end
+
+  # Resizes the image to the correct size for cutting tiles at the given zoom level. It does an in-place resize which modifies the passed-in image.
+  #
+  # Note: If the image is not square, tiles will probably be incorrect.
+  #
+  # Parameters:
+  #
+  # <tt>img</tt>: The source image as +Magick::Image+.
+  # <tt>zoom_level</tt>: The level of zoom to compute the tile grid for.
+  # <tt>tile_size</tt>: The size of each tile in pixels.
+  #
+  # Returns:
+  #
+  # <tt>nil</tt> - The resize is done in-place, modifying the passed in image.
   def self.resize_to_zoom_level(img, zoom_level, tile_size = DEFAULT_TILE_SIZE)
     size = zoom_image_size(zoom_level, tile_size)
     img.resize!(size, size)
   end
 
+  # Calculates the correct size in pixels for a source image at the given zoom level. This assumes the image
+  # to resize will be square.
+  #
+  # For example, at zoom_level 2 and tile_size 256, the image size is 2048px on a side.
+  #
+  # Parameters:
+  #
+  # <tt>zoom_level</tt>: The level of zoom to compute the image size for.
+  # <tt>tile_size</tt>: The size of each tile in pixels.
+  #
+  # Returns:
+  #
+  # The size in pixels of each side of the square image for a source image at the given zoom.
   def self.zoom_image_size(zoom_level, tile_size = DEFAULT_TILE_SIZE)
     tile_size * (2 ** zoom_level )
   end

data/spec/travertine/travertine_spec.rb

@@ -40,6 +40,14 @@ describe Travertine do
     end
   end
 
+  describe "#tile_count_for_zoom" do
+    it "should calculate the number of tiles for a given zoom level" do
+      Travertine.tile_count_for_zoom(0).should == 1
+      Travertine.tile_count_for_zoom(2).should == 16
+      Travertine.tile_count_for_zoom(4).should == 256
+    end
+  end
+
   describe "#zoom_image_size" do
     it "should calculate the size in pixels that the source image must be resized to" do
       Travertine.zoom_image_size(0).should == Travertine::DEFAULT_TILE_SIZE

data/travertine.gemspec

@@ -5,23 +5,23 @@
 
 Gem::Specification.new do |s|
   s.name = %q{travertine}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Micah Wedemeyer"]
-  s.date = %q{2011-09-25}
+  s.date = %q{2011-10-02}
   s.description = %q{Image tiling with Ruby}
   s.email = %q{me@micahwedemeyer.com}
   s.extra_rdoc_files = [
     "LICENSE.txt",
-    "README.rdoc"
+    "README.textile"
   ]
   s.files = [
     ".document",
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
-    "README.rdoc",
+    "README.textile",
     "Rakefile",
     "VERSION",
     "lib/travertine.rb",

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: travertine
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 19
   prerelease: 
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Micah Wedemeyer
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-25 00:00:00 -04:00
+date: 2011-10-02 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -88,13 +88,13 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE.txt
-- README.rdoc
+- README.textile
 files: 
 - .document
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- README.rdoc
+- README.textile
 - Rakefile
 - VERSION
 - lib/travertine.rb

data/README.rdoc

@@ -1,19 +0,0 @@
-= travertine
-
-Description goes here.
-
-== Contributing to travertine
- 
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
-* Fork the project
-* Start a feature/bugfix branch
-* Commit and push until you are happy with your contribution
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
-
-== Copyright
-
-Copyright (c) 2011 Micah Wedemeyer. See LICENSE.txt for
-further details.
-