riiif 2.7.0 → 2.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea4afe42b1178e584376a461d2a093dce410e4e7d6ffe7b77b03a65c2e90c787
-  data.tar.gz: 74cff5d88b9cb6e0bb5077b67e81cf104b04c400419728090dcb423051b7382d
+  metadata.gz: 5c83cf037ced763741c5aa704db17564fd43ee2610866d27629b1de4700c518a
+  data.tar.gz: 447135b1b851c29969cd42a91a51b26facb1084b47dc246422b11a15de0dcbc5
 SHA512:
-  metadata.gz: e3b19485e9b29e6383995a27540acd3356981e49ee2c62e27c069de234e87cd075b685c98818d947a9e03c073478ff55b4e2d49f8c377b9ea9bf9f563def5daf
-  data.tar.gz: a7f044747b0d275e60e7ef3aac3184d7ab033e88c02b1b0bbf7337e212c428d9c985ed604ab1ef95e8b0deb3101dd608ec9b08a66fad70c99531caac5a2a1879
+  metadata.gz: 86952c0517dfd44217aee70ae4927209aaa7c4078c9142126a6f0a06fe831774371dffb0191c2719cb868249b98b324cbfbf7853c2518622bb67dc2d1afab182
+  data.tar.gz: f315b4762cf831614a80728ac072678ea4ad9f1fc38cbc836cd7f6e3eaf6c2009b870682e0024d4cebca02c9da919a33dde3b66bcd98ac8da5f2f4d5691b23fd

data/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

data/.github/workflows/ruby.yml

@@ -18,12 +18,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: ["3.2", "3.3"]
-        rails: ["8.0.0", "7.2.2", "7.1.5"]
+        ruby: ["3.2", "3.3", "3.4"]
+        rails: ["8.1.1", "8.0.4", "7.2.3"]
     steps:
       - name: Install ImageMagick
         run: sudo apt install imagemagick
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v6
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:

data/.rubocop_todo.yml

@@ -69,7 +69,13 @@ Lint/SuppressedException:
 Metrics/BlockLength:
   Max: 237
 
-# Offense count: 1
+# Offense count: 2
+Metrics/ClassLength:
+  Exclude:
+    - 'app/services/riiif/crop.rb'
+    - 'app/services/riiif/resize.rb'
+
+      # Offense count: 1
 # Configuration parameters: IgnoredMethods.
 Metrics/CyclomaticComplexity:
   Max: 7

data/Gemfile

@@ -1,12 +1,11 @@
 source 'https://rubygems.org'
 
-gem 'byebug'
 # Specify your gem's dependencies in riiif.gemspec
 gemspec
 
 # BEGIN ENGINE_CART BLOCK
-# engine_cart: 2.0.1
-# engine_cart stanza: 0.10.0
+# engine_cart: 2.6.0
+# engine_cart stanza: 2.5.0
 # the below comes from engine_cart, a gem used to test this Rails engine gem in the context of a Rails app.
 file = File.expand_path('Gemfile', ENV['ENGINE_CART_DESTINATION'] || ENV['RAILS_ROOT'] || File.expand_path('.internal_test_app', File.dirname(__FILE__)))
 if File.exist?(file)
@@ -27,7 +26,5 @@ else
       gem 'rails', ENV['RAILS_VERSION']
     end
   end
-
-  gem 'sass-rails', '~> 5.0'
 end
 # END ENGINE_CART BLOCK

data/README.md

@@ -5,7 +5,9 @@ A Ruby IIIF image server as a rails engine.
 
 ## Installation
 
-RIIIF depends on Imagemagick so you must install that first. On a mac using Homebrew you can follow these instructions:
+To use RIIIF, you need to install at least one of Imagemagick, Graphicsmagick, or Vips (libvips) (see [comparison](docs/vips_comparison.md)). By default, RIIIF will use Imagemagick.
+
+To install Imagemagick on a Mac using Homebrew you can follow these instructions:
 
 ImageMagick (7.0.4) may be installed with a few options:
 * `--with-ghostscript` Compile with Ghostscript for Postscript/PDF support
@@ -31,6 +33,16 @@ Or install it yourself as:
 
 ## Configure
 
+Any of the following code examples should be included in a `config/initializers/riiif.rb` file in your application (or somewhere else loaded in your app environment) like so:
+
+```ruby
+Rails.application.config.to_prepare do
+  # code goes here
+end
+```
+
+For test applications generated by engine cart (see [Running the tests](#running-the-tests)), this would be `<cloned repo folder>/.internal_test_app/config/initializers/riiif.rb`.
+
 ### Images on the servers file system.
 
 By default Riiif is set to load images from the filesystem using the Riiif::FileSystemFileResolver.
@@ -75,15 +87,25 @@ See [benchmark](docs/benchmark.md) for details
 
 To use [GraphicsMagick](http://www.graphicsmagick.org/) instead of ImageMagick
 
-    Riiif::ImagemagickCommandFactory.external_command = "gm convert"
-    Riiif::ImageMagickInfoExtractor.external_command  = "gm identify"
+```ruby
+Riiif::ImagemagickCommandFactory.external_command = "gm convert"
+Riiif::ImageMagickInfoExtractor.external_command  = "gm identify"
+```
 
 You will of course need to install GraphicsMagick on your system.
 
+### Libvips (aka Vips)
+
+To use [libvips](https://www.libvips.org/) instead of ImageMagick
+
+```ruby
+Riiif::Engine.config.use_vips = true
+```
+
 ## Usage
 
 Add the routes to your application by inserting the following line into `config/routes.rb`
-```
+```ruby
   mount Riiif::Engine => '/image-service', as: 'riiif'
 ```
 

data/app/extractors/riiif/abstract_info_extractor.rb

@@ -0,0 +1,12 @@
+module Riiif
+  class AbstractInfoExtractor
+    # A basic image info extractor class from which ImageMagickInfoExtractor and
+    # VipsInfoExtractor inherit
+
+    class_attribute :external_command
+
+    def initialize(path)
+      @path = path
+    end
+  end
+end

data/app/{services → extractors}/riiif/image_magick_info_extractor.rb

@@ -1,14 +1,9 @@
 module Riiif
   # Get information using imagemagick to interrogate the file
-  class ImageMagickInfoExtractor
+  class ImageMagickInfoExtractor < AbstractInfoExtractor
     # perhaps you want to use GraphicsMagick instead, set to "gm identify"
-    class_attribute :external_command
     self.external_command = 'identify'
 
-    def initialize(path)
-      @path = path
-    end
-
     def extract
       height, width, format, channels = Riiif::CommandRunner.execute(
         "#{external_command} -format '%h %w %m %[channels]' '#{@path}[0]'"

data/app/extractors/riiif/vips_info_extractor.rb

@@ -0,0 +1,22 @@
+require 'ruby-vips' if Riiif::Engine.config.use_vips
+
+module Riiif
+  # Get information using (lib)vips to interrogate the file
+  class VipsInfoExtractor < AbstractInfoExtractor
+    self.external_command = 'vipsheader'
+
+    def extract
+      attributes = Riiif::CommandRunner.execute("#{external_command} '#{@path}' -a")
+                                       .split(/\n/)
+                                       .map { |str| str.strip.split(': ', 2) }.to_h
+      width, height = attributes.values_at("width", "height")
+
+      {
+        height: Integer(height),
+        width: Integer(width),
+        format: attributes["vips-loader"].match?("pngload") ? "PNG" : "JPEG",
+        channels: ::Vips::Image.new_from_file(@path.to_s).has_alpha? ? "srgba" : "srgb"
+      }
+    end
+  end
+end

data/app/models/riiif/file.rb

@@ -4,7 +4,14 @@ module Riiif
 
     class_attribute :info_extractor_class
     # TODO: add alternative that uses kdu_jp2info
-    self.info_extractor_class = ImageMagickInfoExtractor
+
+    def self.info_extractor_class
+      if Riiif.use_vips?
+        VipsInfoExtractor
+      else
+        ImageMagickInfoExtractor
+      end
+    end
 
     # @param input_path [String] The location of an image file
     def initialize(input_path, tempfile = nil)
@@ -20,7 +27,9 @@ module Riiif
     end
 
     def transformer
-      if Riiif.kakadu_enabled? && path.ends_with?('.jp2')
+      if Riiif.use_vips?
+        VipsTransformer
+      elsif Riiif.kakadu_enabled? && path.ends_with?('.jp2')
         KakaduTransformer
       else
         ImagemagickTransformer

data/app/services/riiif/crop.rb

@@ -45,8 +45,35 @@ module Riiif
       end
     end
 
+    def to_vips
+      case region
+      when IIIF::Image::Region::Full
+        nil
+      when IIIF::Image::Region::Absolute
+        [region.offset_x, region.offset_y, region.width, region.height]
+      when IIIF::Image::Region::Square
+        vips_square
+      when IIIF::Image::Region::Percent
+        vips_percent
+      end
+    end
+
     private
 
+      def vips_percent
+        # Calculate x values
+        offset_x, width = [region.x_pct, region.width_pct].map do |percent|
+          (image_info.width * percentage_to_fraction(percent)).round
+        end
+
+        # Calculate y values
+        offset_y, height = [region.y_pct, region.height_pct].map do |percent|
+          (image_info.height * percentage_to_fraction(percent)).round
+        end
+
+        [offset_x, offset_y, width, height]
+      end
+
       def imagemagick_percent
         offset_x = (image_info.width * percentage_to_fraction(region.x_pct)).round
         offset_y = (image_info.height * percentage_to_fraction(region.y_pct)).round
@@ -60,6 +87,19 @@ module Riiif
         "\{#{percentage_to_fraction(region.height_pct)},#{percentage_to_fraction(region.width_pct)}\}"
       end
 
+      def vips_square
+        min, max = [image_info.width, image_info.height].minmax
+        offset = (max - min) / 2
+
+        if image_info.height >= image_info.width
+          # Portrait: left, offset, width, height
+          [0, offset, min, min]
+        else
+          # Landscape: left, offset, width, height
+          [offset, 0, min, min]
+        end
+      end
+
       def kakadu_square
         min, max = [image_info.width, image_info.height].minmax
         offset = (max - min) / 2

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

@@ -11,6 +11,10 @@ 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

data/lib/riiif/version.rb

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

data/lib/riiif.rb

@@ -28,4 +28,8 @@ module Riiif
   def self.kakadu_enabled?
     Engine.config.kakadu_enabled
   end
+
+  def self.use_vips?
+    Engine.config.use_vips
+  end
 end

data/riiif.gemspec

@@ -21,6 +21,7 @@ Gem::Specification.new do |spec|
   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 'ruby-vips'
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'

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

data/spec/models/riiif/file_spec.rb

@@ -0,0 +1,35 @@
+RSpec.describe Riiif::File do
+  describe '#info_extractor_class' do
+    subject { described_class.info_extractor_class }
+
+    context 'when not using vips' do
+      it { is_expected.to eq Riiif::ImageMagickInfoExtractor }
+    end
+
+    context 'when vips is configured' do
+      before { allow(Riiif).to receive(:use_vips?).and_return true }
+
+      it { is_expected.to eq Riiif::VipsInfoExtractor }
+    end
+  end
+
+  describe '#transformer' do
+    subject { described_class.new('path.jp2', double).transformer }
+
+    context 'when vips is configured' do
+      before { allow(Riiif).to receive(:use_vips?).and_return true }
+
+      it { is_expected.to eq Riiif::VipsTransformer }
+    end
+
+    context 'when Kakadu is enabled' do
+      before { allow(Riiif).to receive(:kakadu_enabled?).and_return true }
+
+      it { is_expected.to eq Riiif::KakaduTransformer }
+    end
+
+    context 'when using image/graphicsmagick without Kakadu' do
+      it { is_expected.to eq Riiif::ImagemagickTransformer }
+    end
+  end
+end

data/spec/test_app_templates/lib/generators/test_app_generator.rb

@@ -1,9 +1,14 @@
 require 'rails/generators'
 
 class TestAppGenerator < Rails::Generators::Base
-  source_root 'spec/test_app_templates'
+  # source_root 'spec/test_app_templates'
+  source_root File.expand_path("../../../spec", __dir__)
 
   def add_routes
     route "mount Riiif::Engine => '/images', as: 'riiif'"
   end
+
+  def copy_fixtures
+    directory 'fixtures', 'spec/fixtures'
+  end
 end

data/spec/transformers/riiif/vips_transformer_spec.rb

@@ -0,0 +1,271 @@
+require 'spec_helper'
+
+begin
+  require 'ruby-vips'
+rescue LoadError
+  module Vips
+    class Image
+      # Intentionally blank.
+      #
+      # This prevents uninitialized constant errors if vips
+      # is not installed.
+    end
+  end
+end
+
+RSpec.describe Riiif::VipsTransformer do
+  let(:channels) { 'rgb' }
+
+  let(:path) { "path/to/image.tif" }
+
+  let(:image) { double('Vips Image', has_alpha?: false) }
+
+  let(:image_info) do
+    double({ height: 376,
+             width: 500,
+             format: 'jpg',
+             channels: channels })
+  end
+
+  let(:target) { 'jpg' }
+
+  let(:transformation) do
+    IIIF::Image::Transformation.new(region: region,
+                                    size: size,
+                                    rotation: rotation,
+                                    format: target)
+  end
+
+  # Default/Placeholder values that should be modified in tests
+  let(:size) { IIIF::Image::Size::Full.new }
+  let(:region) { IIIF::Image::Region::Full.new }
+  let(:rotation) { 0 }
+
+  before do
+    allow(Vips::Image).to receive(:new_from_file).and_return(image)
+  end
+
+  describe '#initialize' do
+    let(:path) { Pathname.new("path/to/image.tif") }
+
+    it 'normalizes pathnames to strings' do
+      expect(Vips::Image).to receive(:new_from_file).with("path/to/image.tif")
+      described_class.new(path, image_info, transformation)
+    end
+  end
+
+  describe '#transform' do
+    subject { described_class.new(path, image_info, transformation).transform }
+    before { allow(image).to receive(:write_to_buffer) }
+    after { subject }
+
+    context 'when requesting jpg format with default options' do
+      it 'writes to jpg format' do
+        expect(image).to receive(:write_to_buffer).with(".jpg[Q=85,optimize-coding,strip]")
+      end
+    end
+
+    context 'when requesting png format with default options' do
+      let(:target) { 'png' }
+
+      it 'writes to png format' do
+        expect(image).to receive(:write_to_buffer).with(".png[Q=85,strip]")
+      end
+    end
+
+    context 'when requesting jpeg format for a png' do
+      let(:image) { double('Vips Image', has_alpha?: true) }
+
+      it 'writes to png anyway to preserve transparency' do
+        expect(image).to receive(:write_to_buffer).with(".png[Q=85,strip]")
+      end
+    end
+
+    context 'with subsampling turned off' do
+      subject { described_class.new(path, image_info, transformation, subsample: false).transform }
+
+      it 'does not subsample' do
+        expect(image).to receive(:write_to_buffer).with(".jpg[Q=85,optimize-coding,strip,no-subsample]")
+      end
+    end
+
+    context 'when specifying compression factor' do
+      subject { described_class.new(path, image_info, transformation, compression: 90).transform }
+
+      it 'compresses to the correct quality' do
+        expect(image).to receive(:write_to_buffer).with(".jpg[Q=90,optimize-coding,strip]")
+      end
+    end
+
+    context 'when strip_metadata is false' do
+      subject { described_class.new(path, image_info, transformation, strip_metadata: false).transform }
+
+      it 'does not strip metadata' do
+        expect(image).to receive(:write_to_buffer).with(".jpg[Q=85,optimize-coding]")
+      end
+    end
+  end
+
+  describe '#transform_image' do
+    subject { described_class.new(path, image_info, transformation).send(:transform_image) }
+
+    before do
+      allow(image).to receive_messages(crop: image, resize: image, rotate: image, thumbnail_image: image, colourspace: image)
+    end
+
+    describe 'resize' do
+      context 'when specifing full size' do
+        it 'does not resize' do
+          expect(image).not_to receive(:resize)
+          expect(image).not_to receive(:thumbnail_image)
+          subject
+        end
+      end
+
+      context 'when specifing percent size' do
+        let(:size) { IIIF::Image::Size::Percent.new(50) }
+
+        it 'resizes the image' do
+          expect(image).to receive(:resize).with(50.0)
+          expect(image).not_to receive(:thumbnail_image)
+          subject
+        end
+      end
+
+      context 'when specifing float percent size' do
+        let(:size) { IIIF::Image::Size::Percent.new(12.5) }
+
+        it 'resizes the image' do
+          expect(image).to receive(:resize).with(12.5)
+          expect(image).not_to receive(:thumbnail_image)
+          subject
+        end
+      end
+
+      context 'when specifying width and/or height' do
+        context 'when specifing w, size' do
+          let(:size) { IIIF::Image::Size::Width.new(300) }
+
+          before { allow(image).to receive(:width).and_return(600) }
+
+          it 'resizes the image to 300px wide, maintaining aspect ratio' do
+            expect(image).to receive(:resize).with(0.5)
+            subject
+          end
+        end
+
+        context 'when specifing ,h size' do
+          let(:size) { IIIF::Image::Size::Height.new(200) }
+
+          before { allow(image).to receive(:height).and_return(500) }
+
+          it 'resizes the image to 300px high, maintaining aspect ratio' do
+            expect(image).to receive(:resize).with(0.4)
+            subject
+          end
+        end
+
+        context 'when specifing absolute w,h size' do
+          let(:size) { IIIF::Image::Size::Absolute.new(200, 300) }
+
+          it 'resizes the image, ignoring aspect ratio' do
+            expect(image).to receive(:thumbnail_image).with(200, height: 300, size: :force)
+            subject
+          end
+        end
+
+        context 'when specifing bestfit (!w,h) size' do
+          let(:size) { IIIF::Image::Size::BestFit.new(200, 300) }
+
+          it 'resizes the image so that the width and height are equal or less than the requested value' do
+            expect(image).to receive(:thumbnail_image).with(200, height: 300)
+            subject
+          end
+        end
+      end
+    end
+
+    describe 'crop' do
+      after { subject }
+
+      context 'when specifing full size' do
+        let(:region) { IIIF::Image::Region::Full.new }
+
+        it 'does not crop' do
+          expect(image).not_to receive(:crop)
+        end
+      end
+
+      context 'when specifing absolute geometry' do
+        let(:region) { IIIF::Image::Region::Absolute.new(80, 15, 60, 75) }
+
+        it 'crops to that region' do
+          expect(image).to receive(:crop).with(80, 15, 60, 75)
+        end
+      end
+
+      context 'when specifing percent geometry' do
+        let(:region) { IIIF::Image::Region::Percent.new(10, 10, 80, 70) }
+        before { allow(image_info).to receive_messages(width: 100, height: 100, format: 'jpeg', channels: channels) }
+
+        it 'crops to that region' do
+          expect(image).to receive(:crop).with(10, 10, 80, 70)
+        end
+      end
+
+      context 'when specifing square geometry' do
+        let(:region) { IIIF::Image::Region::Square.new }
+
+        it 'crops a square the size of the shortest edge' do
+          expect(image).to receive(:crop).with(62, 0, 376, 376)
+        end
+      end
+    end
+
+    describe 'rotate' do
+      after { subject }
+
+      context 'when no rotation (0) is specified' do
+        it 'does not rotate' do
+          expect(image).not_to receive(:rotate)
+        end
+      end
+
+      context 'when rotation is specified' do
+        let(:rotation) { 45 }
+
+        it 'rotates the image' do
+          expect(image).to receive(:rotate).with(45)
+        end
+      end
+    end
+
+    describe 'colourspace' do
+      after { subject }
+
+      context 'when quality is default or color' do
+        it 'leaves the image in color' do
+          expect(image).not_to receive(:colourspace).with(:b_w)
+          expect(image).not_to receive(:>)
+        end
+      end
+
+      context 'when quality is gray' do
+        let(:transformation) { IIIF::Image::Transformation.new(region: region, size: size, rotation: rotation, quality: 'gray') }
+
+        it 'makes the image grayscale' do
+          expect(image).to receive(:colourspace).with(:b_w)
+        end
+      end
+
+      context 'when quality is bitonal' do
+        let(:transformation) { IIIF::Image::Transformation.new(region: region, size: size, rotation: rotation, quality: 'bitonal') }
+
+        it 'makes the image bitonal' do
+          expect(image).to receive(:colourspace).with(:b_w)
+          expect(image).to receive(:>).with(200)
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: riiif
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.8.1
 platform: ruby
 authors:
 - Justin Coyne
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -58,6 +57,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: ruby-vips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -163,6 +176,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dependabot.yml"
 - ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rspec"
@@ -174,6 +188,9 @@ files:
 - README.md
 - Rakefile
 - app/controllers/riiif/images_controller.rb
+- app/extractors/riiif/abstract_info_extractor.rb
+- app/extractors/riiif/image_magick_info_extractor.rb
+- app/extractors/riiif/vips_info_extractor.rb
 - app/models/riiif/file.rb
 - app/models/riiif/image.rb
 - app/models/riiif/image_information.rb
@@ -183,17 +200,19 @@ files:
 - app/resolvers/riiif/http_file_resolver.rb
 - app/services/riiif/command_runner.rb
 - app/services/riiif/crop.rb
-- app/services/riiif/image_magick_info_extractor.rb
 - app/services/riiif/imagemagick_command_factory.rb
 - app/services/riiif/kakadu_command_factory.rb
 - app/services/riiif/link_name_service.rb
 - app/services/riiif/nil_authorization_service.rb
 - app/services/riiif/resize.rb
+- app/services/riiif/vips_resize.rb
 - app/transformers/riiif/abstract_transformer.rb
 - app/transformers/riiif/imagemagick_transformer.rb
 - app/transformers/riiif/kakadu_transformer.rb
+- app/transformers/riiif/vips_transformer.rb
 - config/routes.rb
 - docs/benchmark.md
+- docs/vips_comparison.md
 - lib/riiif.rb
 - lib/riiif/engine.rb
 - lib/riiif/rails/routes.rb
@@ -201,7 +220,13 @@ files:
 - lib/riiif/version.rb
 - riiif.gemspec
 - spec/controllers/riiif/images_controller_spec.rb
+- spec/extractors/riiif/image_magick_info_extractor_spec.rb
+- spec/extractors/riiif/vips_info_extractor_spec.rb
+- spec/fixtures/test.jpg
+- spec/fixtures/test.png
+- spec/fixtures/test.tif
 - spec/models/riiif/akubra_system_file_resolver_spec.rb
+- spec/models/riiif/file_spec.rb
 - spec/models/riiif/file_system_file_resolver_spec.rb
 - spec/models/riiif/http_file_resolver_spec.rb
 - spec/models/riiif/image_information_spec.rb
@@ -214,11 +239,11 @@ files:
 - spec/test_app_templates/Gemfile.extra
 - spec/test_app_templates/lib/generators/test_app_generator.rb
 - spec/transformers/riiif/kakadu_transformer_spec.rb
+- spec/transformers/riiif/vips_transformer_spec.rb
 homepage: https://github.com/sul-dlss/riiif
 licenses:
 - APACHE2
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -233,13 +258,18 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key:
+rubygems_version: 4.0.7
 specification_version: 4
 summary: A Rails engine that support IIIF requests
 test_files:
 - spec/controllers/riiif/images_controller_spec.rb
+- spec/extractors/riiif/image_magick_info_extractor_spec.rb
+- spec/extractors/riiif/vips_info_extractor_spec.rb
+- spec/fixtures/test.jpg
+- spec/fixtures/test.png
+- spec/fixtures/test.tif
 - spec/models/riiif/akubra_system_file_resolver_spec.rb
+- spec/models/riiif/file_spec.rb
 - spec/models/riiif/file_system_file_resolver_spec.rb
 - spec/models/riiif/http_file_resolver_spec.rb
 - spec/models/riiif/image_information_spec.rb
@@ -252,3 +282,4 @@ test_files:
 - spec/test_app_templates/Gemfile.extra
 - spec/test_app_templates/lib/generators/test_app_generator.rb
 - spec/transformers/riiif/kakadu_transformer_spec.rb
+- spec/transformers/riiif/vips_transformer_spec.rb