riiif 2.1.0 → 2.8.1

data/app/services/riiif/vips_resize.rb

@@ -0,0 +1,47 @@
+module Riiif
+  # Represents a resize operation
+  class VipsResize
+    def initialize(size, image)
+      @size = size
+      @image = image
+    end
+
+    attr_reader :size, :image
+
+    # @return the parameters that vips will use to resize the image. This can be
+    #   1. A [Float] representing the scale factor, passed to Vips::Image#resize
+    #   2. An [Array], where the 1st elem is an Integer and the 2nd is a
+    #       Hash of options, passed to Vips::Image#thumbnail
+    #   3. [NilClass] when image should not be resized at all
+    def to_vips
+      case size
+      when IIIF::Image::Size::Percent
+        size.percentage
+      when IIIF::Image::Size::Width
+        resize_ratio(:width, image)
+      when IIIF::Image::Size::Height
+        resize_ratio(:height, image)
+      when IIIF::Image::Size::Absolute
+        [size.width, { height: size.height, size: :force }]
+      when IIIF::Image::Size::BestFit
+        [size.width, { height: size.height }]
+      when IIIF::Image::Size::Max, IIIF::Image::Size::Full
+        nil
+      else
+        raise "unknown size #{size.class}"
+      end
+    end
+
+    # @param [Symbol] - which side of the image to calculate, either :width or :height
+    # @return [Float] - the scale or percentage to resize the image by; passed to Vips::Image#resize
+    def resize_ratio(side, image)
+      length = image.send(side)
+      target_length = size.send(side)
+      if target_length < length
+        target_length / length.to_f # Size down
+      else
+        length / target_length.to_f # Size up
+      end
+    end
+  end
+end

data/app/transformers/riiif/vips_transformer.rb

@@ -0,0 +1,103 @@
+# Use ruby-vips to execute image transformations (via ffi gem) instead of
+# using the vips CLI. Since vips CLI commands can't be chained without creating
+# temp files after each operation, using the CLI would decrease performance.
+# See 'Chaining operations': https://www.libvips.org/API/current/using-cli.html
+require 'ruby-vips' if Riiif::Engine.config.use_vips
+
+module Riiif
+  class VipsTransformer < AbstractTransformer
+    include ActiveSupport::Benchmarkable
+    delegate :logger, to: :Rails
+
+    # @param path [String] The path of the source image file
+    # @param image_info [ImageInformation] information about the source
+    # @param [IIIF::Image::Transformation] transformation
+    def initialize(path, image_info, transformation, compression: 85, subsample: true, strip_metadata: true)
+      super(path, image_info, transformation)
+      @image = ::Vips::Image.new_from_file(path.to_s)
+      @compression = compression
+      @subsample = subsample
+      @strip_metadata = strip_metadata
+    end
+
+    attr_reader :image, :path, :compression, :subsample, :strip_metadata
+
+    # @return [String] all the image data
+    def transform
+      benchmark("Riiif transformed image using vips") do
+        transform_image.write_to_buffer(".#{format}#{format_options}")
+      end
+    end
+
+    private
+
+    # Chain every method in the array together and apply it to the image
+    # @return [Vips::Image] - the image after all transformations
+    def transform_image
+      result = [crop, resize, rotate, colourspace].reduce(image) do |image, array|
+        method, options = array
+        # Options are blank when transformation is not required (e.g. when requesting full size)
+        next image if options.blank?
+
+        case method
+        when :resize
+          image.send(method, VipsResize.new(transformation.size, image).to_vips)
+        when :thumbnail_image
+          # .thumbnail_image needs a positional argument (width) and keyword args (options)
+          # https://www.rubydoc.info/gems/ruby-vips/Vips/Image#thumbnail_image-instance_method
+          image.send(method, options.first, **options.last)
+        when :crop
+          # .crop needs positional arguments
+          image.send(method, *options)
+        else # :rotate or :colourspace
+          image.send(method, options)
+        end
+      end
+      # If result should be bitonal, set a value threshold
+      # https://github.com/libvips/libvips/issues/1840
+      transformation.quality == 'bitonal' ? (result > 200) : result
+    end
+
+    def format
+      # In cases where the input file has an alpha_channel but the transformation
+      # format is 'jpg', change to 'png' as jpeg does not support alpha channels
+      image.has_alpha? && transformation.format == 'jpg' ? 'png' : transformation.format
+    end
+
+    def format_options
+      format_string = [compression,
+                       ("optimize-coding" if format == 'jpg'),
+                       ("strip" if strip_metadata),
+                       ("no-subsample" unless subsample)].select(&:present?).join(',')
+
+      "[Q=#{format_string}]"
+    end
+
+    def resize
+      case transformation.size
+      when IIIF::Image::Size::Percent, IIIF::Image::Size::Width, IIIF::Image::Size::Height
+        [:resize, transformation.size]
+      else # IIIF::Image::Size::Absolute, IIIF::Image::Size::BestFit
+        [:thumbnail_image, VipsResize.new(transformation.size, image).to_vips]
+      end
+    end
+
+    def crop
+      [:crop, Crop.new(transformation.region, image_info).to_vips]
+    end
+
+    def rotate
+      angle = transformation.rotation.zero? ? nil : transformation.rotation
+      [:rotate, angle]
+    end
+
+    def colourspace
+      case transformation.quality
+      when 'gray', 'bitonal'
+        [:colourspace, :b_w]
+      else
+        [:colourspace, nil]
+      end
+    end
+  end
+end

data/docs/vips_comparison.md

@@ -0,0 +1,257 @@
+# Benchmarks comparing Vips, Imagemagick, and Graphicsmagick
+
+The following benchmarks were run using ApacheBench v. 2.3 on Ubuntu / Windows Subsystem for Linux (WSL) on a 32 GB (RAM) laptop.
+
+To generate the tables below, a simple resize `curl` command (more details below) was run 50 times in a row and the median response time was calculated.
+
+## Testing with a JPEG
+
+For a 4264 x 3282 jpeg image (26.8 MB)
+
+| Software Used  | Median processing time (ms) | Mean processing time (ms) |
+| ---------------|-----------------------------|---------------------------|
+| Imagemagick    | 753                         | 753                       |
+| Graphicsmagick | 662                         | 660                       |
+| Vips           | 79                          | 78                        |
+
+## Testing with a TIFF
+
+For a 7800 x 5865 tif image (7.11 MB)
+
+| Software Used  | Median processing time (ms) | Mean processing time (ms) |
+| ---------------|-----------------------------|---------------------------|
+| Imagemagick    | 1091                        | 1089                      |
+| Graphicsmagick | 800                         | 796                       |
+| Vips           | 130                         | 139                       |
+
+## More Resources & Discussion
+
+Those interested in more comprehensive benchmarking with Ruby may be interested in the [vips-benchmarks](https://github.com/jcupitt/vips-benchmarks?tab=readme-ov-file) code repository, which also tests memory usage.
+
+Glen Robson, Stefano Cossu, Ruven Pillay, and Michael D. Smith have written an [excellent article comparing the speed of different image processing tools and formats in a IIIF context](https://journal.code4lib.org/articles/17596). They write, "The testing clearly shows that tiled multi-resolution pyramid TIFF is the fastest format for IIIF, but it comes at a cost of significantly more storage space compared to both HTJ2K [([High Throughput JPEG2000](https://jpeg.org/jpeg2000/htj2k.html))] and JP2." The latter two standards are used by [Kakadu](https://kakadusoftware.com/), a proprietary image toolkit that is commonly used for IIIF servers.
+
+Based on their results, institutions/organizations that use large TIFFs as the base image for IIIF derivatives will likely see the best performance using vips. Conversely, institutions/organizations that use JP2 images will get the best performance using Kakadu HTJ2K.
+
+## Command and Detailed Results for JPGs
+
+Command: `ab -n 50 'http://localhost:3000/images/irises/full/!500,500/0/default.jpg'`
+
+### Using imagemagick
+
+```
+Document Path:          /images/irises/full/!500,500/0/default.jpg
+Document Length:        79018 bytes
+
+Concurrency Level:      1
+Time taken for tests:   37.655 seconds
+Complete requests:      50
+Failed requests:        0
+Total transferred:      3995500 bytes
+HTML transferred:       3950900 bytes
+Requests per second:    1.33 [#/sec] (mean)
+Time per request:       753.097 [ms] (mean)
+Time per request:       753.097 [ms] (mean, across all concurrent requests)
+Transfer rate:          103.62 [Kbytes/sec] received
+
+Connection Times (ms)
+min  mean[+/-sd] median   max
+Connect:        0    0   0.0      0       0
+Processing:   701  753  28.6    753     813
+Waiting:      701  753  28.6    753     813
+Total:        701  753  28.6    753     813
+
+Percentage of the requests served within a certain time (ms)
+50%    753
+66%    768
+75%    774
+80%    778
+90%    794
+95%    810
+98%    813
+99%    813
+100%    813 (longest request)
+```
+
+### Using graphicsmagick
+
+```
+Document Path:          /images/irises/full/!500,500/0/default.jpg
+Document Length:        78992 bytes
+
+Concurrency Level:      1
+Time taken for tests:   33.131 seconds
+Complete requests:      50
+Failed requests:        0
+Total transferred:      3994173 bytes
+HTML transferred:       3949600 bytes
+Requests per second:    1.51 [#/sec] (mean)
+Time per request:       662.629 [ms] (mean)
+Time per request:       662.629 [ms] (mean, across all concurrent requests)
+Transfer rate:          117.73 [Kbytes/sec] received
+
+Connection Times (ms)
+              min  mean[+/-sd] median   max
+Connect:        0    0   0.0      0       0
+Processing:   539  662  64.9    660     847
+Waiting:      539  662  64.9    660     847
+Total:        539  663  65.0    660     848
+
+Percentage of the requests served within a certain time (ms)
+  50%    660
+  66%    685
+  75%    703
+  80%    720
+  90%    739
+  95%    775
+  98%    848
+  99%    848
+ 100%    848 (longest request)
+```
+
+### Using libvips
+
+```
+Document Path:          /images/irises/full/!500,500/0/default.jpg
+Document Length:        77647 bytes
+
+Concurrency Level:      1
+Time taken for tests:   3.920 seconds
+Complete requests:      50
+Failed requests:        0
+Total transferred:      3926860 bytes
+HTML transferred:       3882350 bytes
+Requests per second:    12.75 [#/sec] (mean)
+Time per request:       78.409 [ms] (mean)
+Time per request:       78.409 [ms] (mean, across all concurrent requests)
+Transfer rate:          978.16 [Kbytes/sec] received
+
+Connection Times (ms)
+              min  mean[+/-sd] median   max
+Connect:        0    0   0.0      0       0
+Processing:    67   78   5.5     79      90
+Waiting:       67   78   5.5     79      90
+Total:         67   78   5.5     79      90
+
+Percentage of the requests served within a certain time (ms)
+  50%     79
+  66%     81
+  75%     81
+  80%     82
+  90%     86
+  95%     88
+  98%     90
+  99%     90
+ 100%     90 (longest request)
+```
+
+## Command and Detailed Results for TIFFs
+
+Command: `ab -n 50 'http://localhost:3000/images/big/full/!500,500/0/default.jpg'`
+
+### Using imagemagick
+
+```
+Document Path:          /images/big/full/!500,500/0/default.jpg
+Document Length:        82826 bytes
+
+Concurrency Level:      1
+Time taken for tests:   54.537 seconds
+Complete requests:      50
+Failed requests:        0
+Total transferred:      4185950 bytes
+HTML transferred:       4141300 bytes
+Requests per second:    0.92 [#/sec] (mean)
+Time per request:       1090.745 [ms] (mean)
+Time per request:       1090.745 [ms] (mean, across all concurrent requests)
+Transfer rate:          74.96 [Kbytes/sec] received
+
+Connection Times (ms)
+              min  mean[+/-sd] median   max
+Connect:        0    0   0.0      0       0
+Processing:  1004 1091  39.8   1089    1163
+Waiting:     1004 1091  39.8   1089    1163
+Total:       1004 1091  39.8   1089    1163
+
+Percentage of the requests served within a certain time (ms)
+  50%   1089
+  66%   1113
+  75%   1120
+  80%   1139
+  90%   1149
+  95%   1156
+  98%   1163
+  99%   1163
+ 100%   1163 (longest request)
+```
+
+### Using graphicsmagick
+
+```
+Document Path:          /images/big/full/!500,500/0/default.jpg
+Document Length:        82841 bytes
+
+Concurrency Level:      1
+Time taken for tests:   39.825 seconds
+Complete requests:      50
+Failed requests:        0
+Total transferred:      4186581 bytes
+HTML transferred:       4142050 bytes
+Requests per second:    1.26 [#/sec] (mean)
+Time per request:       796.495 [ms] (mean)
+Time per request:       796.495 [ms] (mean, across all concurrent requests)
+Transfer rate:          102.66 [Kbytes/sec] received
+
+Connection Times (ms)
+              min  mean[+/-sd] median   max
+Connect:        0    0   0.0      0       0
+Processing:   642  796  66.2    800     924
+Waiting:      642  796  66.2    800     924
+Total:        642  796  66.2    800     924
+
+Percentage of the requests served within a certain time (ms)
+  50%    800
+  66%    832
+  75%    845
+  80%    859
+  90%    880
+  95%    899
+  98%    924
+  99%    924
+ 100%    924 (longest request)
+```
+
+### Using libvips
+
+```
+Document Path:          /images/big/full/!500,500/0/default.jpg
+Document Length:        81878 bytes
+
+Concurrency Level:      1
+Time taken for tests:   6.661 seconds
+Complete requests:      50
+Failed requests:        0
+Total transferred:      4138502 bytes
+HTML transferred:       4093900 bytes
+Requests per second:    7.51 [#/sec] (mean)
+Time per request:       133.222 [ms] (mean)
+Time per request:       133.222 [ms] (mean, across all concurrent requests)
+Transfer rate:          606.73 [Kbytes/sec] received
+
+Connection Times (ms)
+              min  mean[+/-sd] median   max
+Connect:        0    0   0.0      0       0
+Processing:   115  133  12.0    130     160
+Waiting:      115  133  12.0    130     160
+Total:        115  133  12.0    130     160
+
+Percentage of the requests served within a certain time (ms)
+  50%    130
+  66%    141
+  75%    143
+  80%    146
+  90%    150
+  95%    154
+  98%    160
+  99%    160
+ 100%    160 (longest request)
+```

data/lib/riiif/engine.rb

@@ -10,5 +10,19 @@ module Riiif
 
     # Set to true to use kdu for jp2000 source images
     config.kakadu_enabled = false
+
+    # Set to true to use libvips to transform images
+    # https://www.libvips.org/
+    config.use_vips = false
+
+    config.before_configuration do
+      # see https://github.com/fxn/zeitwerk#for_gem
+      # We put a generator into LOCAL APP lib/generators, so tell
+      # zeitwerk to ignore the whole directory? If we're using a recent
+      # enough version of Rails to have zeitwerk config
+      #
+      # See: https://github.com/cbeer/engine_cart/issues/117
+      Rails.autoloaders.main.ignore(Rails.root.join('lib', 'generators')) if Rails.try(:autoloaders).try(:main).respond_to?(:ignore)
+    end
   end
 end

data/lib/riiif/version.rb

@@ -1,3 +1,3 @@
 module Riiif
-  VERSION = '2.1.0'.freeze
+  VERSION = '2.8.1'.freeze
 end

data/lib/riiif.rb

@@ -12,10 +12,24 @@ module Riiif
   # This error is raised when Riiif can't convert an image
   class ConversionError < Error; end
 
+  def self.deprecation
+    @deprecation ||= ActiveSupport::Deprecation.new('3.0', 'Riiif')
+  end
+
+  HTTPFileResolver = ActiveSupport::Deprecation::DeprecatedConstantProxy.new(
+    'Riiif::HTTPFileResolver',
+    'Riiif::HttpFileResolver',
+    Riiif.deprecation
+  )
+
   mattr_accessor :not_found_image # the image to use when a lookup fails
   mattr_accessor :unauthorized_image # the image to use when a user doesn't have access
 
   def self.kakadu_enabled?
     Engine.config.kakadu_enabled
   end
+
+  def self.use_vips?
+    Engine.config.use_vips
+  end
 end

data/riiif.gemspec

@@ -7,10 +7,10 @@ Gem::Specification.new do |spec|
   spec.name          = 'riiif'
   spec.version       = Riiif::VERSION
   spec.authors       = ['Justin Coyne']
-  spec.email         = ['administrator@curationexperts.com']
+  spec.email         = ['jcoyne85@stanford.edu']
   spec.description   = 'A IIIF image server'
-  spec.summary       = 'A rails engine that support IIIF requests'
-  spec.homepage      = 'https://github.com/curationexperts/riiif'
+  spec.summary       = 'A Rails engine that support IIIF requests'
+  spec.homepage      = 'https://github.com/sul-dlss/riiif'
   spec.license       = 'APACHE2'
 
   spec.files         = `git ls-files|grep -v spec/samples`.split($INPUT_RECORD_SEPARATOR)
@@ -18,14 +18,16 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'railties', '>= 4.2', '<6'
+  spec.add_dependency 'railties', '>= 4.2', '< 9'
   spec.add_dependency 'deprecation', '>= 1.0.0'
-  spec.add_dependency 'iiif-image-api', '~> 0.1.0'
+  spec.add_dependency 'iiif-image-api', '>= 0.1.0'
+  spec.add_dependency 'ruby-vips'
+
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'engine_cart', '~> 2.0'
   spec.add_development_dependency 'rspec-rails'
   spec.add_development_dependency 'sqlite3'
-  spec.add_development_dependency 'bixby', '~> 1.0.0'
-  spec.add_development_dependency 'coveralls'
+  spec.add_development_dependency 'bixby', '~> 5.0'
+  spec.add_development_dependency 'simplecov'
 end

data/spec/controllers/riiif/images_controller_spec.rb

@@ -24,9 +24,9 @@ RSpec.describe Riiif::ImagesController do
     it 'sends images to the service' do
       image = double
       expect(Riiif::Image).to receive(:new).with('abcd1234').and_return(image)
-      expect(image).to receive(:render).with('region' => 'full', 'size' => 'full',
+      expect(image).to receive(:render).with({ 'region' => 'full', 'size' => 'full',
                                              'rotation' => '0', 'quality' => 'default',
-                                             'format' => 'jpg').and_return('IMAGEDATA')
+                                             'format' => 'jpg' }).and_return('IMAGEDATA')
       get :show, params: { id: 'abcd1234', action: 'show', region: 'full', size: 'full',
                            rotation: '0', quality: 'default', format: 'jpg' }
       expect(response).to be_successful
@@ -102,9 +102,9 @@ RSpec.describe Riiif::ImagesController do
             raise Riiif::ImageNotFoundError unless file.present?
             not_found_image
           end.twice
-          expect(not_found_image).to receive(:render).with('region' => 'full', 'size' => 'full',
+          expect(not_found_image).to receive(:render).with({ 'region' => 'full', 'size' => 'full',
                                                            'rotation' => '0', 'quality' => 'default',
-                                                           'format' => 'jpg').and_return('default-image-data')
+                                                           'format' => 'jpg' }).and_return('default-image-data')
 
           get :show, params: { id: 'bad_id', action: 'show', region: 'full', size: 'full',
                                rotation: '0', quality: 'default', format: 'jpg' }
@@ -118,9 +118,9 @@ RSpec.describe Riiif::ImagesController do
             raise Riiif::ImageNotFoundError unless file.present?
             not_found_image
           end.twice
-          expect(not_found_image).to receive(:render).with('region' => 'full', 'size' => 'full',
+          expect(not_found_image).to receive(:render).with({ 'region' => 'full', 'size' => 'full',
                                                            'rotation' => '0', 'quality' => 'default',
-                                                           'format' => 'jpg').and_return('default-image-data')
+                                                           'format' => 'jpg' }).and_return('default-image-data')
 
           get :show, params: { id: 'bad_id', action: 'show', region: 'full', size: 'full',
                                rotation: '0', quality: 'default', format: 'jpg' }
@@ -155,12 +155,12 @@ RSpec.describe Riiif::ImagesController do
         get :info, params: { id: 'abcd1234', format: 'json' }
         expect(response).to be_successful
         expect(json).to eq '@context' => 'http://iiif.io/api/image/2/context.json',
-                           '@id' => 'http://test.host/abcd1234',
+                           '@id' => Rails.version > '6.1' ? 'http://test.host/images/abcd1234' : 'http://test.host/abcd1234',
                            'width' => 6000,
                            'height' => 4000,
                            'format' => 'JPEG',
                            'channels' => 'rgb',
-                           'profile' => ['http://iiif.io/api/image/2/level1.json', 'formats' => %w(jpg png)],
+                           'profile' => ['http://iiif.io/api/image/2/level1.json', 'formats' => %w(webp jpg png)],
                            'protocol' => 'http://iiif.io/api/image'
         expect(response.headers['Link']).to eq '<http://iiif.io/api/image/2/level1.json>;rel="profile"'
         expect(response.headers['Content-Type']).to eq 'application/ld+json; charset=utf-8'

data/spec/extractors/riiif/image_magick_info_extractor_spec.rb

@@ -0,0 +1,31 @@
+RSpec.describe Riiif::ImageMagickInfoExtractor do
+  it 'uses identify as its external command' do
+    expect(described_class.external_command).to eq "identify"
+  end
+
+  context 'with a jpg' do
+    let(:image) { Rails.root.join("spec", "fixtures", "test.jpg") }
+
+    it 'returns the extracted attributes' do
+      expect(described_class.new(image).extract).to eq({
+                                                         height: 397,
+                                                         width: 300,
+                                                         format: "JPEG",
+                                                         channels: "srgb"
+                                                       })
+    end
+  end
+
+  context 'with a png' do
+    let(:image) { Rails.root.join("spec", "fixtures", "test.png") }
+
+    it 'returns the extracted attributes' do
+      expect(described_class.new(image).extract).to eq({
+                                                         height: 50,
+                                                         width: 50,
+                                                         format: "PNG",
+                                                         channels: "srgba"
+                                                       })
+    end
+  end
+end

data/spec/extractors/riiif/vips_info_extractor_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+RSpec.describe Riiif::VipsInfoExtractor do
+  before do
+    allow(Riiif::CommandRunner).to receive(:execute).and_return(fake_info)
+    allow(Vips::Image).to receive(:new_from_file).and_return(image)
+  end
+
+  let(:image) { double(has_alpha?: false) }
+
+  let(:fake_info) do
+    "width: 500
+    height: 376
+    interpretation: srgb
+    filename: spec/fixtures/test.tif
+    vips-loader: tiffload"
+  end
+
+  it 'uses vipsheader as its external command' do
+    expect(described_class.external_command).to eq "vipsheader"
+  end
+
+  context 'on a file without transparency' do
+    it 'returns the extracted attributes' do
+      expect(described_class.new("path/to/image.jpg").extract).to eq({
+                                                                       height: 376,
+                                                                       width: 500,
+                                                                       format: "JPEG",
+                                                                       channels: "srgb"
+                                                                     })
+    end
+  end
+
+  context 'on a file with transparency' do
+    let(:image) { double(has_alpha?: true) }
+
+    let(:fake_info) do
+      "width: 50
+      height: 50
+      interpretation: srgb
+      filename: spec/fixtures/test.tif
+      vips-loader: pngload"
+    end
+
+    it 'returns the extracted attributes' do
+      expect(described_class.new(image).extract).to eq({
+                                                         height: 50,
+                                                         width: 50,
+                                                         format: "PNG",
+                                                         channels: "srgba"
+                                                       })
+    end
+  end
+
+  context 'on a JPEG file with extra EXIF metadata' do
+    let(:image) { double(has_alpha?: false) }
+
+    let(:fake_info) do
+      "width: 150
+      height: 150
+      interpretation: srgb
+      filename: spec/fixtures/test.jpeg
+      vips-loader: jpegload
+      exif-ifd0-Artist: University Library (Digital Object: Digital Media Group)"
+    end
+
+    it 'returns the extracted attributes' do
+      expect(described_class.new(image).extract).to eq({
+                                                         height: 150,
+                                                         width: 150,
+                                                         format: "JPEG",
+                                                         channels: "srgb"
+                                                       })
+    end
+  end
+end