shrine-blurhash 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d996837d159a23efc83e220f7f937ad440bf3acfe98093f7483b4e08de221091
+  data.tar.gz: d956efac6992fff592f1b37c46fbbb9bdfe2b09ef5dfb3414feee57eee9adc5b
+SHA512:
+  metadata.gz: 32e9956e147d75ab3bb218c58e14dd46eeb4878a9d91812e064d17cb23d7210aebce352280f64b775849231a0d40a032b3f82418dd16d6f83be7c68da71976bc
+  data.tar.gz: 27c0e803e7f930c70629ec1a70a6aa256c05eea6f6fbf65cccc9e348f78d7027555d85d5e72d03d5409c2f23f7826fc3f2fd0891cc1a48f419948a6f4b2171ef

data/README.md

@@ -0,0 +1,128 @@
+[![Gem Version](https://badge.fury.io/rb/shrine-blurhash.svg)](https://badge.fury.io/rb/shrine-blurhash)
+
+# Shrine::Blurhash
+
+Provides [Blurhash] computing for [Shrine].
+
+Main features:
+- Multiple pixel extractors support. Current implementations:
+  - `ruby-vips`
+- Resize the image before computing blurhash (to 100 pixels by default) for a faster computation
+- Supports custom blurhash components parameter
+
+## Installation
+
+Simply add the gem to your `Gemfile`:
+
+```ruby
+gem "shrine-blurhash"
+```
+
+Then run `bundler`
+
+## Usage
+
+You first need to load the plugin in your Uploader;
+
+```ruby
+class PictureUploader < Shrine
+  plugin :blurhash
+end
+```
+
+Blurhash will be now be computed when you upload a file and stored in a `blurhash` metadata, with a `.blurhash` method for quick access.
+
+## Options
+
+You can pass options to the plugin to customize its behavior.
+
+```ruby
+class PictureUploader < Shrine
+  plugin :blurhash, resize_to: nil, components: [2, 2]
+end
+```
+
+### ```components```
+
+Type: `[components_x, components_y]`
+Default: `[4, 3]`
+
+```ruby
+plugin :blurhash, components: [2, 2]
+```
+
+This allows you to customize the number of components on each axis for the Blurhash algorithm. The visual result will look like a grid of `X * Y` blurred colors.
+
+### `resize_to`
+
+Type: `Integer` or `nil`
+Default: `100`
+
+```ruby
+plugin :blurhash, resize_to: 100
+plugin :blurhash, resize_to: nil
+```
+
+Before computing the Blurhash for an image, this plugin needs to extract every pixel and store them in an array. This can result in a lot of memory allocations. To avoid using too much memory, this plugin resizes the image before extracting the pixels. This should not affect the visual result.
+
+You can either specify the target size or `nil` to disable image resizing completely.
+
+### `extractor`
+
+Type: `symbol` or `lambda`
+
+```ruby
+plugin :blurhash, extractor: :ruby-vips
+```
+
+Supported extractors:
+
+| Name           | Description                                                                                                                                   |
+| :-----------   | :-----------                                                                                                                                  |
+| `:ruby_vips`   | Uses the [ruby-vips] gem to extract pixels from File objects. If non-file IO object is given it will be temporarily downloaded to disk.   |
+
+You can also create your own custom pixel extractor, where you can reuse
+any of the built-in analyzers. The analyzer is a lambda that accepts an IO
+object and returns a `[width, height, pixels]` array containing image width, image height and all the pixels in the images in an array, or `nil` if pixels could not be extracted.
+
+### `auto_extraction`
+
+Type: `boolean`
+
+- Multiple pixel extractors support, even if only VIPS is implemented right now
+- Allows to resize the image before computing blurhash (to 100 pixels by default) for a faster computation
+- Supports custom blurhash components parameter
+
+## Errors
+
+By default, any exceptions that the plugin raises while computing blurhash
+will be caught and a warning will be printed out. This allows you to have the
+plugin loaded even for files that are not images.
+
+However, you can choose different strategies for handling these exceptions:
+
+```rb
+plugin :blurhash, on_error: :warn        # prints a warning (default)
+plugin :blurhash, on_error: :fail        # raises the exception
+plugin :blurhash, on_error: :ignore      # ignores exceptions
+plugin :blurhash, on_error: -> (error) { # custom handler
+  # report the exception to your exception handler
+}
+```
+
+## Contributing
+
+### Running tests
+
+After setting up your bucket, run the tests:
+
+```sh
+$ bundle exec rake test
+```
+
+## License
+
+[MIT](http://opensource.org/licenses/MIT)
+
+[Shrine]: https://github.com/shrinerb/shrine
+[Blurhash]: https://blurha.sh

data/lib/shrine/plugins/blurhash.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "blurhash"
+
+class Shrine
+  module Plugins
+    module Blurhash
+      LOG_SUBSCRIBER = lambda do |event|
+        Shrine.logger.info "Blurhash (#{event.duration}ms) – #{{
+          io: event[:io].class,
+          uploader: event[:uploader],
+        }.inspect}"
+      end
+
+      def self.configure(uploader, log_subscriber: LOG_SUBSCRIBER, **opts)
+        uploader.opts[:blurhash] ||= {
+          extractor: :ruby_vips,
+          on_error: :warn,
+          auto_extraction: true,
+          resize_to: 100,
+          components: [4, 3],
+        }
+        uploader.opts[:blurhash].merge!(opts)
+
+        # resolve error strategy
+        uploader.opts[:blurhash][:on_error] =
+          case uploader.opts[:blurhash][:on_error]
+          when :fail   then ->(error) { raise error }
+          when :warn   then ->(error) { Shrine.warn "Error occurred when attempting to extract blurhash: #{error.inspect}" }
+          when :ignore then ->(error) {}
+          else
+            uploader.opts[:blurhash][:on_error]
+          end
+
+        uploader.subscribe(:blurhash, &log_subscriber) if uploader.respond_to?(:subscribe)
+      end
+
+      module ClassMethods
+        def compute_blurhash(io)
+          extractor = opts[:blurhash][:extractor]
+          extractor = pixels_extractor(extractor) if extractor.is_a?(Symbol)
+
+          resize_to = opts[:blurhash][:resize_to]
+          args = [io, resize_to, pixels_extractors].take(extractor.arity.abs)
+
+          blurhash = instrument_blurhash(io) do
+            pixels = extractor.call(*args)
+
+            components = opts[:blurhash][:components]
+            ::Blurhash.encode(pixels[:width], pixels[:height], pixels[:pixels], x_comp: components[0], y_comp: components[1])
+          end
+
+          io.rewind
+
+          blurhash
+        end
+
+        # Returns a hash of built-in pixels extractors, where keys are
+        # extractors names and values are `#call`-able objects which accepts the
+        # IO object.
+        def pixels_extractors
+          @pixels_extractors ||= PixelsExtractor::SUPPORTED_EXTRACTORS.inject({}) do |hash, tool|
+            hash.merge!(tool => pixels_extractor(tool))
+          end
+        end
+
+        # Returns callable pixels extractor object.
+        def pixels_extractor(name)
+          on_error = opts[:blurhash][:on_error]
+
+          PixelsExtractor.new(name, on_error: on_error).method(:call)
+        end
+
+        private
+
+        # Sends a `blurhash.shrine` event for instrumentation plugin.
+        def instrument_blurhash(io, &block)
+          return yield unless respond_to?(:instrument)
+
+          instrument(:blurhash, io: io, &block)
+        end
+      end
+
+      module InstanceMethods
+        def extract_metadata(io, **options)
+          return super unless self.class.opts[:blurhash][:auto_extraction]
+
+          blurhash = self.class.compute_blurhash(io)
+          super.merge!("blurhash" => blurhash)
+        end
+      end
+
+      module FileMethods
+        def blurhash
+          metadata["blurhash"]
+        end
+      end
+
+      class PixelsExtractor
+        SUPPORTED_EXTRACTORS = [:ruby_vips].freeze
+
+        def initialize(tool, on_error: method(:fail))
+          unless SUPPORTED_EXTRACTORS.include?(tool)
+            raise Error, "unknown pixel extractor #{tool.inspect}, supported extractors are: #{SUPPORTED_EXTRACTORS.join(',')}"
+          end
+
+          @tool     = tool
+          @on_error = on_error
+        end
+
+        def call(io, resize_to)
+          dimensions = send(:"extract_with_#{@tool}", io, resize_to)
+          io.rewind
+          dimensions
+        end
+
+        private
+
+        def extract_with_ruby_vips(io, resize_to)
+          require "vips"
+
+          begin
+            Shrine.with_file(io) do |file|
+              image = Vips::Image.new_from_file(file.path, access: :sequential)
+              image = image.resize(resize_to.fdiv(image.width), vscale: resize_to.fdiv(image.height)) if resize_to
+
+              {
+                width: image.width,
+                height: image.height,
+                pixels: image.to_a.flatten,
+              }
+            end
+          rescue Vips::Error => e
+            on_error(e)
+          end
+        end
+
+        def on_error(error)
+          @on_error.call(error)
+          nil
+        end
+      end
+    end
+
+    register_plugin(:blurhash, Blurhash)
+  end
+end

data/shrine-blurhash.gemspec

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |gem|
+  gem.name          = "shrine-blurhash"
+  gem.version       = "0.0.1"
+
+  gem.required_ruby_version = ">= 2.5"
+
+  gem.summary      = "Shrine plugin to compute Blurhash on image attachments"
+  gem.homepage     = "https://github.com/renchap/shrine-blurhash"
+  gem.authors      = ["Renaud Chaput"]
+  gem.email        = ["renchap@gmail.com"]
+  gem.license      = "MIT"
+
+  gem.files        = Dir["README.md", "LICENSE.txt", "lib/**/*.rb", "shrine-blurhash.gemspec"]
+  gem.require_path = "lib"
+
+  gem.add_dependency "blurhash", "~> 0.1.4"
+  gem.add_dependency "shrine", "~> 3.0"
+
+  gem.add_development_dependency "minitest"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "ruby-vips"
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: shrine-blurhash
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Renaud Chaput
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-05-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: blurhash
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.4
+- !ruby/object:Gem::Dependency
+  name: shrine
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby-vips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- renchap@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/shrine/plugins/blurhash.rb
+- shrine-blurhash.gemspec
+homepage: https://github.com/renchap/shrine-blurhash
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Shrine plugin to compute Blurhash on image attachments
+test_files: []