image_processing 0.4.5 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 64e87e9088659e34b81c4258d20b85b8e513a830
-  data.tar.gz: d49790aed2ab213fbb407ae7fbfe07b61f9cfa22
+  metadata.gz: b8d0ca27be8b8095076a74f66c0b2c0300a83ced
+  data.tar.gz: a237d603ae08dc18ecafb46cb9338d3234bc0559
 SHA512:
-  metadata.gz: 3014727fc666cf5e55cc78f1a7f34048c972173d4dad1d6f7f1a8da288c33f5103ee06c823aa3ca71d79028754f997512ed31962e7ce56e86566da50012ec7b4
-  data.tar.gz: de09e70b7a7ae58bcf2279da17162cd77c5ce503a8a3528270a8c55b8f71459b2948dc71af313cc7d9f52017be1e99b31fccc1ed3f60e6ab12b43082ccd978a9
+  metadata.gz: 85d90cb3afff7bb64f6a6ab0e85bcfa0e3e5300163c72157e7c893050ebd6908c0a3224577df0bd246ea2a727dd61e5cf6c3d537971673d6f2c9449a2704b074
+  data.tar.gz: 94823a28788aa45e276c16894678d7137d4092c397e0d3f962ab3e46685df08eb5ea09fc7eaaa713fb380cd26bfc79449f086622e5f1a01dffc38c9c55c340fa

data/CHANGELOG.md

@@ -0,0 +1,65 @@
+## 0.9.0 (2018-03-16)
+
+* Added libvips module (@GustavoCaso, @janko-m)
+
+* Drop official support for MRI 2.0 and 2.1
+
+## 0.4.5 (2017-09-08)
+
+* Add `lib/image_processing.rb` to allow loading via `Bundler.require` (@printercu)
+
+## 0.4.4 (2017-06-16)
+
+* Fix last changes being incompatible with older Ruby versions, again (@janko-m)
+
+## 0.4.3 (2017-06-16)
+
+* Fix last changes being incompatible with older Ruby versions (@janko-m)
+
+## 0.4.2 (2017-06-16)
+
+* Don't use path of input file as basename for output file (@janko-m)
+
+## 0.4.1 (2016-09-08)
+
+* Maintain transparent background of PNGs in `#resize_to_fill` (janko-m)
+
+## 0.4.0 (2016-11-07)
+
+* Add `#corrupted?` for checking whether an image is corrupted (janko-m)
+
+## 0.3.0 (2016-05-03)
+
+* Add cropping functionality to `ImageProcessing::MiniMagick` (paulgoetze)
+
+## 0.2.5 (2016-03-24)
+
+* Rewind the file after making a copy in non-destructive methods (janko-m)
+
+* Add ability to supply page number to `#convert` (janko-m)
+
+## 0.2.4 (2015-10-21)
+
+* Don't error when checking MiniMagick version for older versions of MiniMagick (janko-m)
+
+## 0.2.3 (2015-10-17)
+
+* Fix uploading tempfiles to S3 using aws-sdk (janko-m)
+
+* Make nondestructive methods available on class methods on `ImageProcessing::MiniMagick` (janko-m)
+
+## 0.2.2 (2015-10-04)
+
+* Make `ImageProcessing::MiniMagick#with_minimagick` public (janko-m)
+
+* Add `ImageProcessing::MiniMagick#auto_orient` (janko-m)
+
+## 0.2.1 (2015-10-03)
+
+* Include the actual code in the gem (janko-m)
+
+## 0.2.0 (2015-10-03)
+
+* Add `ImageProcessing::MiniMagick#resample` for changing resolution (janko-m)
+
+* Fix padding in `ImageProcessing::MiniMagick#resize_and_pad` (janko-m)

data/README.md

@@ -1,23 +1,337 @@
 # ImageProcessing
 
-Provides higher-level helper methods for image processing in Ruby using
-ImageMagick.
+Provides higher-level image processing functionality that is commonly needed
+when accepting user uploads. Supports processing with [VIPS] and
+[ImageMagick]/[GraphicsMagick].
 
-These methods were extracted from [refile-mini_magick], and were made generic so
-that they can be used in any project. The goal of image_processing is to have a
-centralized place where helper methods for image processing are maintained,
-instead of CarrierWave, Dragonfly and Refile each implementing their own.
-
-It's been tested with MRI 2.x and JRuby.
+The goal of this project is to have a single place where common image
+processing helper methods are maintained, instead of Paperclip, CarrierWave,
+Refile, Dragonfly and ActiveStorage each implementing their own versions.
 
 ## Installation
 
-```ruby
-gem 'image_processing'
-gem 'mini_magick', '>= 4.3.5'
+```rb
+gem "image_processing"
+```
+
+## ruby-vips
+
+The `ImageProcessing::Vips` module contains processing macros that use the
+[ruby-vips] gem, which you need to install:
+
+```rb
+# Gemfile
+gem "ruby-vips", "~> 2.0"
+```
+
+Note that you'll need to have [libvips] 8.6 or higher installed; see
+the [installation instructions][libvips installation] for more details.
+
+### Usage
+
+`ImageProcessing::Vips` lets you define the processing pipeline using a
+chainable API:
+
+```rb
+require "image_processing/vips"
+
+processed = ImageProcessing::Vips
+  .source(file)
+  .autorot
+  .resize_to_limit(400, 400)
+  .convert("png")
+  .call
+
+processed #=> #<File:/var/folders/.../image_processing-vips20180316-18446-1j247h6.png>
+```
+
+This allows easy branching when generating multiple derivatives:
+
+```rb
+pipeline = ImageProcessing::Vips
+  .source(file)
+  .autorot
+  .convert("png")
+
+large  = pipeline.resize_to_limit!(800, 800)
+medium = pipeline.resize_to_limit!(500, 500)
+small  = pipeline.resize_to_limit!(300, 300)
+```
+
+The processing is executed on `#call` or when a processing method is called
+with a bang (`!`).
+
+```rb
+processed = ImageProcessing::Vips
+  .convert("png")
+  .resize_to_limit(400, 400)
+  .call(image)
+
+# OR
+
+processed = ImageProcessing::Vips
+  .source(image) # declare source image
+  .convert("png")
+  .resize_to_limit(400, 400)
+  .call
+
+# OR
+
+processed = ImageProcessing::Vips
+  .source(image)
+  .convert("png")
+  .resize_to_limit!(400, 400) # bang method
 ```
 
-## Usage
+The source image needs to be an object that responds to `#path` or a
+`Vips::Image` object. The result is a `Tempfile` object, or a `Vips::Image`
+object if `save: false` is passed in.
+
+```rb
+pipeline = ImageProcessing::Vips.source(image)
+
+tempfile = pipeline.call
+tempfile #=> #<Tempfile ...>
+
+vips_image = pipeline.call(save: false)
+vips_image #=> #<Vips::Image ...>
+```
+
+#### `#resize_to_limit`
+
+Downsizes the image to fit within the specified dimensions while retaining the
+original aspect ratio. Will only resize the image if it's larger than the
+specified dimensions.
+
+```rb
+pipeline = ImageProcessing::Vips.source(image) # 600x800
+
+result = pipeline.resize_to_limit!(400, 400)
+
+Vips::Image.new_from_file(result.path).size
+#=> [300, 400]
+```
+
+It's possible to omit one dimension, in which case the image will be resized
+only by the provided dimension.
+
+```rb
+pipeline.resize_to_limit!(400, nil)
+# or
+pipeline.resize_to_limit!(nil, 400)
+```
+
+Any additional options are forwarded to [`Vips::Image#thumbnail_image`]:
+
+```rb
+pipeline.resize_to_limit!(400, 400, linear: true)
+```
+
+See [`vips_thumbnail()`] for more details.
+
+#### `#resize_to_fit`
+
+Resizes the image to fit within the specified dimensions while retaining the
+original aspect ratio. Will downsize the image if it's larger than the
+specified dimensions or upsize if it's smaller.
+
+```rb
+pipeline = ImageProcessing::Vips.source(image) # 600x800
+
+result = pipeline.resize_to_fit!(400, 400)
+
+Vips::Image.new_from_file(result.path).size
+#=> [300, 400]
+```
+
+It's possible to omit one dimension, in which case the image will be resized
+only by the provided dimension.
+
+```rb
+pipeline.resize_to_fit!(400, nil)
+# or
+pipeline.resize_to_fit!(nil, 400)
+```
+
+Any additional options are forwarded to [`Vips::Image#thumbnail_image`]:
+
+```rb
+pipeline.resize_to_fit!(400, 400, linear: true)
+```
+
+See [`vips_thumbnail()`] for more details.
+
+#### `#resize_to_fill`
+
+Resizes the image to fill the specified dimensions while retaining the original
+aspect ratio. If necessary, will crop the image in the larger dimension.
+
+```rb
+pipeline = ImageProcessing::Vips.source(image) # 600x800
+
+result = pipeline.resize_to_fill!(400, 400)
+
+Vips::Image.new_from_file(result.path).size
+#=> [400, 400]
+```
+
+Any additional options are forwarded to [`Vips::Image#thumbnail_image`]:
+
+```rb
+pipeline.resize_to_fill!(400, 400, crop: :attention) # smart crop
+```
+
+See [`vips_thumbnail()`] for more details.
+
+#### `#resize_and_pad`
+
+Resizes the image to fit within the specified dimensions while retaining the
+original aspect ratio. If necessary, will pad the remaining area with the given
+color, which defaults to transparent (for GIF and PNG, white for JPEG).
+
+```rb
+pipeline = ImageProcessing::Vips.source(image) # 600x800
+
+result = pipeline.resize_and_pad!(400, 400)
+
+Vips::Image.new_from_file(result.path).size
+#=> [400, 400]
+```
+
+You can specify the background [color] that will be used for padding:
+
+```rb
+pipeline.resize_and_pad!(400, 400, color: "RoyalBlue")
+```
+
+You can also specify the [direction] where the source image will be positioned:
+
+```rb
+pipeline.resize_and_pad!(400, 400, gravity: "north-west")
+```
+
+Any additional options are forwarded to [`Vips::Image#thumbnail_image`]:
+
+```rb
+pipeline.resize_to_fill!(400, 400, linear: true)
+```
+
+See [`vips_thumbnail()`] and [`vips_gravity()`] for more details.
+
+#### `#convert`
+
+Specifies the output format.
+
+```rb
+pipeline = ImageProcessing::Vips.source(image)
+
+result = pipeline.convert!("png")
+
+File.extname(result.path)
+#=> ".png"
+```
+
+By default the original format is retained when writing the image to a file. If
+the source file doesn't have a file extension, the format will default to JPEG.
+
+#### `#set`, `#set_type`
+
+Sets `Vips::Image` metadata. Delegates to [`Vips::Image#set`] and
+[`Vips::Image#set_type`].
+
+```rb
+pipeline = ImageProcessing::Vips.source(image)
+
+pipeline.set("icc-profile-data", profile).call
+# or
+pipeline.set_type(Vips::BLOB_TYPE, "icc-profile-data", profile).call
+```
+
+#### `#method_missing`
+
+Any unknown methods will be delegated to [`Vips::Image`].
+
+```rb
+ImageProcessing::Vips
+  .crop(0, 0, 300, 300)
+  .invert
+  .gaussblur(2)
+  # ...
+```
+
+#### `#custom`
+
+Calls the provided block with the intermediary `Vips::Image` object. The return
+value of the provided block must be a `Vips::Image` object.
+
+```rb
+ImageProcessing::Vips
+  .source(file)
+  .resize_to_limit(400, 400)
+  .custom { |image| image + image.invert }
+  .call
+```
+
+#### `#loader`
+
+Specifies options that will be forwarded to [`Vips::Image.new_from_file`].
+
+```rb
+ImageProcessing::Vips
+  .loader(access: :sequential)
+  .resize_to_limit(400, 400)
+  .call(source)
+```
+
+See [`vips_jpegload()`], [`vips_pngload()`] etc. for more details on
+format-specific load options.
+
+If you would like to have more control over loading, you can load the image
+directly using `Vips::Image`, and just pass the `Vips::Image` object as the
+source file.
+
+```rb
+vips_image = Vips::Image.magickload(file.path, n: -1)
+
+ImageProcessing::Vips
+  .source(vips_image)
+  # ...
+```
+
+#### `#saver`
+
+Specifies options that will be forwarded to [`Vips::Image#write_to_file`].
+
+```rb
+ImageProcessing::Vips
+  .saver(Q: 100)
+  .resize_to_limit(400, 400)
+  .call(source)
+```
+
+See [`vips_jpegsave()`], [`vips_pngsave()`] etc. for more details on
+format-specific save options.
+
+If you would like to have more control over saving, you can call `#call(save:
+false)` to get the `Vips::Image` object, and call the saver on it directly.
+
+```rb
+vips_image = ImageProcessing::Vips
+  .resize_to_limit(400, 400)
+  .call(save: false)
+
+vips_image.write_to_file("/path/to/destination", **options)
+```
+
+## MiniMagick
+
+The `ImageProcessing::MiniMagick` module contains processing methods that use
+the [MiniMagick] gem, which you need to install:
+
+```rb
+# Gemfile
+gem "mini_magick", ">= 4.3.5"
+```
 
 Typically you will include the module in your class:
 
@@ -29,16 +343,15 @@ include ImageProcessing::MiniMagick
 original = File.open("path/to/image.jpg")
 
 converted = convert(original, "png") # makes a converted copy
-converted #=> #<Tempfile:/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/mini_magick20151003-23030-9e1vjz.png (closed)>
+converted #=> #<File:/var/folders/.../mini_magick20151003-23030-9e1vjz.png (closed)>
 File.exist?(original.path) #=> true
 
 converted = convert!(original, "png") # converts the file in-place
-converted #=> #<Tempfile:/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/mini_magick20151003-23030-9e1vjz.png (closed)>
+converted #=> #<File:/var/folders/.../mini_magick20151003-23030-9e1vjz.png (closed)>
 File.exist?(original.path) #=> false
 ```
 
-If you would rather not pollute your namespace, you can also call the methods
-directly on the module:
+You can also call processing methods directly on the module:
 
 ```rb
 image = File.open("path/to/image.jpg")
@@ -48,8 +361,9 @@ ImageProcessing::MiniMagick.resize_to_fit(image, 400, 400)
 
 ### Methods
 
-The following is the list of helper methods that ImageProcessing provides (each
-one has both a destructive and a nondestructive version):
+The following is the list of processing methods provided by
+`ImageProcessing::MiniMagick` (each one has both a destructive and a
+nondestructive version):
 
 ```rb
 # Adjust an image so that its orientation is suitable for viewing.
@@ -82,11 +396,11 @@ resize_and_pad[!](file, width, height, background: "transparent", gravity: "Cent
 resample[!](file, horizontal, vertical)
 
 # Returns true if the given image is corrupted
-currupted?(file)
+corrupted?(file)
 ```
 
-For `#resize_to_limit[!]` and `#resize_to_fit[!]` you can don't have to specify
-both dimensions:
+The `#resize_to_limit[!]` and `#resize_to_fit[!]` allow specifying only one
+dimension:
 
 ```rb
 resize_to_limit(image, 300, nil)
@@ -96,7 +410,7 @@ resize_to_fit(image, nil, 500)
 ### Dropping to MiniMagick
 
 If you want to do custom MiniMagick processing, each of the above optionally
-yields an instance of `MiniMagick::Tool`, so you can use it for additional
+yields an instance of `MiniMagick::Tool`, which you can use for additional
 processing:
 
 ```rb
@@ -121,21 +435,47 @@ processed #=> #<File ...>
 
 ## Contributing
 
-ImageMagick and GraphicsMagick are both required to be installed, on Mac this is
+Test suite requires `imagemagick`, `graphicsmagick` and `libvips` be installed.
+On Mac OS you can install them with Homebrew:
 
 ```
-$ brew install imagemagick
-$ brew install graphicsmagick
+$ brew install imagemagick graphicsmagick vips
 ```
 
-Run tests with
+Afterwards you can run tests with
 
 ```
 $ rake test
 ```
 
+## Credits
+
+The `ImageProcessing::MiniMagick` functionality was extracted from
+[refile-mini_magick].
+
 ## License
 
 [MIT](LICENSE.txt)
 
+[ImageMagick]: https://www.imagemagick.org
+[GraphicsMagick]: http://www.graphicsmagick.org
+[VIPS]: http://jcupitt.github.io/libvips/
+[MiniMagick]: https://github.com/minimagick/minimagick
+[ruby-vips]: https://github.com/jcupitt/ruby-vips
+[libvips]: https://github.com/jcupitt/libvips
+[libvips installation]: https://github.com/jcupitt/libvips/wiki#building-and-installing
 [refile-mini_magick]: https://github.com/refile/refile-mini_magick
+[`Vips::Image`]: http://www.rubydoc.info/gems/ruby-vips/Vips/Image
+[`Vips::Image.new_from_file`]: http://www.rubydoc.info/gems/ruby-vips/Vips/Image#new_from_file-class_method
+[`Vips::Image#write_to_file`]: http://www.rubydoc.info/gems/ruby-vips/Vips/Image#write_to_file-instance_method
+[`Vips::Image#thumbnail_image`]: http://www.rubydoc.info/gems/ruby-vips/Vips/Image#thumbnail_image-instance_method
+[`Vips::Image#set`]: http://www.rubydoc.info/gems/ruby-vips/Vips/Image#set-instance_method
+[`Vips::Image#set_type`]: http://www.rubydoc.info/gems/ruby-vips/Vips/Image#set_type-instance_method
+[`vips_thumbnail()`]: https://jcupitt.github.io/libvips/API/current/libvips-resample.html#vips-thumbnail
+[`vips_gravity()`]: http://jcupitt.github.io/libvips/API/current/libvips-conversion.html#vips-gravity
+[`vips_jpegload()`]: https://jcupitt.github.io/libvips/API/current/VipsForeignSave.html#vips-jpegload
+[`vips_pngload()`]: https://jcupitt.github.io/libvips/API/current/VipsForeignSave.html#vips-pngload
+[`vips_jpegsave()`]: https://jcupitt.github.io/libvips/API/current/VipsForeignSave.html#vips-jpegsave
+[`vips_pngsave()`]: https://jcupitt.github.io/libvips/API/current/VipsForeignSave.html#vips-pngsave
+[color]: https://www.imagemagick.org/script/color.php#color_names
+[direction]: http://jcupitt.github.io/libvips/API/current/libvips-conversion.html#VipsCompassDirection