Skip to content

Latest commit

 

History

History
134 lines (89 loc) · 3.96 KB

README.md

File metadata and controls

134 lines (89 loc) · 3.96 KB
Raw

Gem Version

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:

gem "shrine-blurhash"

Then run bundler

Usage

You first need to load the plugin in your Uploader;

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.

class PictureUploader < Shrine
  plugin :blurhash, resize_to: nil, components: [2, 2]
end

components

Type: [components_x, components_y] or a Proc Default: [4, 3]

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.

You can also pass a proc which receive the width and height and calculate the components on-the-fly:

plugin :blurhash, components: ->(width, height) { [width / 600, height / 600] }

resize_to

Type: Integer or nil Default: 100

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

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:

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:

$ bundle exec rake test

License

MIT