seadragon 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5ed5374126e0a3c22d70f11c64092c6bf22f0b3f
+  data.tar.gz: 448be2c364ba4e857e89e5c20a239806ac4610f3
+SHA512:
+  metadata.gz: 48415e8236450e8fa7e5b4c9d01001d90a8991f8650449189924a8eeaa914b130d054f4ca95abb19343b8bd9a494268909bd24d39c3c4bc0be67446997b85d8c
+  data.tar.gz: af2cecd3dc3475c98ebe8357e5ce4a9611293d2a675a8191b5b58268aa64d3d625efe7aa8a9774e41cc247dc91b9c100a07ca68ad999ef633e2032c9ae8a32fc

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.DS_Store

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+rvm:
+  - 2.2.0
+
+before_install:
+  - gem install bundler -v 1.8
+
+script: 'bundle exec rspec'
+
+notifications:
+  email:
+    recipients:
+      - eddiej@gmail.com
+    on_failure: change
+    on_success: never

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in seadragon.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,36 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features)
+
+## Uncomment to clear the screen before every task
+# clearing :on
+
+## Guard internally checks for changes in the Guardfile and exits.
+## If you want Guard to automatically start up again, run guard in a
+## shell loop, e.g.:
+##
+##  $ while bundle exec guard; do echo "Restarting Guard..."; done
+##
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+guard 'rspec', cmd: "bundle exec rspec" do
+  # watch /lib/ files
+  watch(%r{^lib/(.+).rb$}) do |m|
+    "spec/#{m[1]}_spec.rb"
+  end
+
+  # watch /spec/ files
+  watch(%r{^spec/(.+).rb$}) do |m|
+    "spec/#{m[1]}.rb"
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Eddie Johnston
+
+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 @@
+# Seadragon
+
+
+[![Build Status](https://travis-ci.org/eddiej/seadragon.png?branch=master)](https://travis-ci.org/eddiej/seadragon) 
+[![Coverage Status](https://coveralls.io/repos/eddiej/seadragon/badge.png)](https://coveralls.io/r/eddiej/seadragon)
+
+
+[OpenSeadragon](https://openseadragon.github.io/) is an open-source, web-based viewer for displaying high-resolution zoomable images. A viewer is displayed by passing paths to a set of image tiles and a DZI descriptor file to a function provided by the OpenSeadragon Javascript library.
+ 
+OpenSeadragon doesn't handle the creation of the required tile images or descriptor file; this gem provides methods for creating tiles and descriptor files along with a Rails helper method for rendering image viewers in your Rails view templates.  
+      
+There are a number of Ruby Gems that provide OpenSeadragon functionality. The [Openseadragon](https://github.com/IIIF/openseadragon-rails) gem packages the OpenSeadragon Javascript assets and provides helpers for using them, but leaves the descriptor and tile generation to the end-user. [SeadragonPaperclip](https://github.com/dustmoo/seadragon-paperclip) is a processor for the [Paperclip](https://github.com/thoughtbot/paperclip) gem that generates tiles, but it is tied to Paperclip and doesn't generate descriptor files or provide helper methods. This gem provides everything required for generating and displaying Deep Zoom Images on a webpage.
+
+
+## Requirements
+
+
+Seadragon uses [Rmagick](https://github.com/rmagick/rmagick) to process source images - this requires [ImageMagick](http://www.imagemagick.org/script/index.php) to be installed on your system.
+
+## Installation
+
+Install the latest stable release:
+
+```
+$ gem install seadragon
+```
+
+In Rails, add it to your Gemfile:
+
+```ruby
+gem 'seadragon'
+```
+
+Restart your server if required to apply the changes.
+
+## Usage
+
+
+### Backend - Creating the Image Tiles and Descriptor
+
+Before a viewer can be displayed, the required tile images and descriptor file must be created.
+
+First, create a Seadragon::Slice instance, passing to it the path to the image you want to tile, the output directory and a 
+unique handle, e.g.
+
+```ruby
+slicer = Seadragon::Slicer.new({
+  source_path: '/images/starrynight.jpg', 
+  tiles_path: '/www/public_html/deep_zoom_images', 
+  handle: 'starrynight'
+})
+```
+
+To generate the image tiles, run:
+
+```ruby
+slicer.slice!
+```
+
+The descriptor file can the be generated by calling the `write_dzi_specification` method:
+
+```ruby
+slicer.write_dzi_specification
+```
+
+The steps above would create a `starrynight_files` directory in `/www/public_html/deep_zoom_images` with a subfolder of tile images for each zoom level (calculated according to the dimensions of the image). The descriptor file, configuration information in JSON format required by OpenSeadragon, would be saved to `/www/public_html/deep_zoom_images/starrynight.dzi`. 
+
+### Frontend - Displaying a Viewer
+
+To display a viewer in your view, first ensure the gem's Javascript is referenced from `application.js` in your app:
+
+```css
+//= require seadragon
+```
+
+Then create an empty element to hold the viewer (giving it a height so that it is displayed), and call the `seadragon` helper method, passing the element's id and the path to the descriptor file, returned by the `write_dzi_specification` method above.
+
+```html
+<div id="starrynight_viewer" style="height: 400px;></div>
+
+<%= seadragon({id: "starrynight_viewer", tileSources: "/www/public_html/deep_zoom_images/starrynight.dzi"}) %>
+```
+
+This will construct a Javascript call to the bundled OpenSeadragon library which will render a viewer in the element specified.
+
+Any parameters that are used by the OpenSeadragon library can be passed to the `seadragon` helper method. 
+If you wanted to use your own set of navigation icons instead of the defaults, and set the defauly zoom level at 5 for example, you would call the `seadragon` method like this:
+
+
+```html
+<%= seadragon({
+  id: "starrynight_viewer", 
+  tileSources: "/www/public_html/deep_zoom_images/starrynight.dzi",
+  defaultZoomLevel: 5,
+  prefixUrl: /www/public_html/icons/
+}) %>
+```
+
+A full list of the OpenSeadragon options is available in the [OpenSeadragon documentation](https://openseadragon.github.io/docs/OpenSeadragon.html#Options). 
+
+## Tests
+
+Tests are written using RSpec. To start the test suite, run:
+
+```ruby
+bundle exec rspec
+```
+
+or view the tests and results output on [Travis CI](https://travis-ci.org/eddiej/seadragon).
+
+
+
+
+
+
+

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "seadragon"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/seadragon.rb

@@ -0,0 +1,151 @@
+require 'rmagick'
+require 'json'
+require "seadragon/version"
+require "seadragon/engine"
+
+module Seadragon
+
+class Slicer
+  attr_accessor :source_path, :tiles_path, :handle, :tile_size, :overlap, 
+    :quality, :format, :dzi_name, :source_image, :width, :height
+
+  def initialize(attributes = {})
+    raise ArgumentError.new('source and destination paths are required') unless attributes[:source_path] && attributes[:tiles_path]
+    raise ArgumentError.new('a handle is required') unless attributes[:handle]
+  
+    @source_path  = attributes[:source_path]
+    @tiles_path   = attributes[:tiles_path]
+    @handle       = attributes[:handle]
+    @tile_size    = attributes[:tile_size] || 512 
+    @overlap      = attributes[:overlap] || 1
+    @quality      = attributes[:quality] || 100
+    @format       = attributes[:format] || 'jpg' 
+
+    raise ArgumentError.new("source file doesn't exist") unless File.exist? @source_path
+    @source_image = Magick::Image.read(@source_path)[0] # an Image object.
+    @width, @height = @source_image.columns, @source_image.rows # image dims
+
+  end
+
+  ##
+  # Generates the tiles.
+  ##
+  def slice!
+    # duplicate the source image, we'll be resizing it for each zoom layer.
+    image = @source_image.dup 
+
+    # create a parent folder for all of the tiles
+    FileUtils.mkdir_p( File.join(tiles_path, handle+"_files") )
+
+    max_level(width, height).downto(0) do |level|
+
+      # get dimensions of the image (image is resized on each iteration)
+      current_level_width, current_level_height = image.columns, image.rows 
+      current_level_dir = File.join(tiles_path, handle+"_files", level.to_s)
+      FileUtils.mkdir_p(current_level_dir) # create dir for current level
+      
+      # iterate over columns
+      x, col_count = 0, 0
+      while x < current_level_width
+        # iterate over rows
+        y, row_count = 0, 0
+        while y < current_level_height
+          tile_file_path = File.join(current_level_dir, 
+            "#{col_count}_#{row_count}.#{format}")
+          tile_width, tile_height = tile_dimensions(x, y, tile_size, overlap)
+          save_tile(image, tile_file_path, x, y, tile_width, tile_height, quality) unless File.exist? tile_file_path
+          y += (tile_height - (2 * overlap))
+          row_count += 1
+        end
+        x += (tile_width - (2 * overlap))
+        col_count += 1
+      end
+      image.resize!(0.5)
+    end
+    image.destroy!
+  end
+
+  ##
+  # Generates the DZI (Deep Zoom Image format) descriptor file in JSON.
+  ##
+  def write_dzi_specification
+    properties = {
+      'Image': {
+        'xmlns':  "http://schemas.microsoft.com/deepzoom/2008",
+        'Format':  format,
+        'Overlap':  overlap.to_s,
+        'TileSize':  tile_size.to_s,
+        'Size': {
+          'Height': height.to_s,
+          'Width': width.to_s
+        }
+      }
+    }
+    
+    FileUtils.mkdir(tiles_path) unless File.exists?(tiles_path)
+    dzi_path = File.join(tiles_path, handle + ".dzi")
+    
+    File.open(dzi_path, 'w') do |f|
+      f.write(JSON.pretty_generate(properties))
+    end
+  end
+
+  private
+
+  ##
+  # Calculates how many times an image can
+  # be halved until it is resized to 1x1px.
+  ##
+  def max_level(width, height)
+    return (Math.log([width, height].max) / Math.log(2)).ceil
+  end
+
+  ##
+  # Determines width and height for tiles, dependent of tile position.
+  # Center tiles: overlapping on each side.
+  # Borders: no overlapping on the border side, overlapping on other sides.
+  # Corners: only overlapping on the right and lower border.
+  ##
+  def tile_dimensions(x, y, tile_size, overlap)
+    overlapping_tile_size = tile_size + (2 * overlap)
+    border_tile_size = tile_size + overlap
+    tile_width = (x > 0) ? overlapping_tile_size : border_tile_size
+    tile_height = (y > 0) ? overlapping_tile_size : border_tile_size
+    return tile_width, tile_height
+  end
+
+  # Crop a tile from the source image and writes it to dest_path.
+  # Params: image: may be an Magick::Image object or a path to an image.
+  # dest_path: path where cropped image should be stored.
+  # x, y: offset from upper left corner of source image.
+  # width, height: width and height of cropped image.
+  # quality: compression level 0-100 (or 0.0-1.0), lower number means higher compression.
+  def save_tile(image, dest_path, x, y, width, height, quality)
+    image = if image.is_a? Magick::Image
+            image
+          else
+            Magick::Image::read(image).first
+          end
+
+    quality = quality * 100 if quality < 1
+
+    tile = image.crop(x, y, width, height, true)
+    tile.write(dest_path)
+  end
+
+end
+
+module SeadragonHelper
+  def seadragon(options = {})
+    raise ArgumentError.new('a target element must be passed via the id key') unless options[:id]
+    raise ArgumentError.new('a tile source must be passed via the tileSources key') unless options[:tileSources]
+
+    options[:prefixUrl] ||= "/assets/openseadragon.github.io/"
+
+    script = javascript_tag("var viewer = OpenSeadragon(#{options.to_json});")
+  end
+end
+
+ActionView::Base.send :include, SeadragonHelper
+
+end

data/lib/seadragon/engine.rb

@@ -0,0 +1,4 @@
+module Seadragon
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/seadragon/version.rb

@@ -0,0 +1,3 @@
+module Seadragon
+  VERSION = "0.2.0"
+end

data/seadragon.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'seadragon/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "seadragon"
+  spec.version       = Seadragon::VERSION
+  spec.authors       = ["Eddie Johnston"]
+  spec.email         = ["eddie@beanstalk.ie"]
+
+  spec.summary       = %q{The Seadragon Gem provides everything you need to create and host your own Deep Zoom Images using the OpenSeadragon image viewer. It provides methods for generating descriptor files and tiles from an image and comes bundled with the required OpenSeadragon Javascript and assets for displaying viewers.}
+  spec.homepage      = "https://eddiej.github.io/seadragon"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.8"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rails" ## for testing ::Rails::Engine
+  spec.add_development_dependency "rspec-rails" 
+  spec.add_development_dependency "guard"
+  spec.add_development_dependency "guard-rspec"
+  
+  spec.add_dependency "rmagick"
+  spec.add_development_dependency "coveralls"
+end