From aff2614ae472e1fff54ce02ec287d5655fda431b Mon Sep 17 00:00:00 2001 From: Ola Tuvesson <196348+clickworkorange@users.noreply.github.com> Date: Tue, 6 Feb 2024 18:35:10 +0000 Subject: [PATCH] Updated README to include information about Vips and the "crop" processing method. --- README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 48 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 08bda8b24..d8ff43f67 100644 --- a/README.md +++ b/README.md @@ -979,14 +979,6 @@ class AvatarUploader < CarrierWave::Uploader::Base end ``` -#### List of available processing methods: - -- `convert` - Changes the image encoding format to the given format(eg. jpg). This operation is treated specially to trigger the change of the file extension, so it matches with the format of the resulting file. -- `resize_to_limit` - Resize the image to fit within the specified dimensions while retaining the original aspect ratio. Will only resize the image if it is larger than the specified dimensions. The resulting image may be shorter or narrower than specified in the smaller dimension but will not be larger than the specified values. -- `resize_to_fit` - Resize the image to fit within the specified dimensions while retaining the original aspect ratio. The image may be shorter or narrower than specified in the smaller dimension but will not be larger than the specified values. -- `resize_to_fill` - Resize the image to fit within the specified dimensions while retaining the aspect ratio of the original image. If necessary, crop the image in the larger dimension. Optionally, a "gravity" may be specified, for example "Center", or "NorthEast". -- `resize_and_pad` - Resize 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). Optionally, a "gravity" may be specified, as above. - See `carrierwave/processing/mini_magick.rb` for details. ### Using RMagick @@ -1018,6 +1010,54 @@ end Check out the manipulate! method, which makes it easy for you to write your own manipulation methods. +### Using Vips + +CarrierWave version 2.2.0 added support for the `libvips` image processing library, through [ImageProcessing::Vips](https://github.com/janko/image_processing/blob/master/doc/vips.md). Its functionality matches that of the RMagic and MiniMagic processors, but it uses less memory and offers [faster processing](https://github.com/libvips/libvips/wiki/Speed-and-memory-use). To use the Vips processing module you must first install `libvips`, for example: + +````bash +$ sudo apt install libvips +```` + +You also need to tell your uploader to use Vips: + +````ruby +class ImageFileUploader < CarrierWave::Uploader::Base + include CarrierWave::Vips +end +```` + +### List of available processing methods: + +> [!NOTE] +> While the intetion is to provide uniform interfaces to al three processing libraries the availability and implementation of processing methods can vary slightly between them. + +- `convert` - Changes the image encoding format to the given format (eg. jpg). This operation is treated specially to trigger the change of the file extension, so it matches with the format of the resulting file. +- `resize_to_limit` - Resize the image to fit within the specified dimensions while retaining the original aspect ratio. Will only resize the image if it is larger than the specified dimensions. The resulting image may be shorter or narrower than specified in the smaller dimension but will not be larger than the specified values. +- `resize_to_fit` - Resize the image to fit within the specified dimensions while retaining the original aspect ratio. The image may be shorter or narrower than specified in the smaller dimension but will not be larger than the specified values. +- `resize_to_fill` - Resize the image to fit within the specified dimensions while retaining the aspect ratio of the original image. If necessary, crop the image in the larger dimension. Optionally, a "gravity" may be specified, for example "Center", or "NorthEast". +- `resize_and_pad` - Resize 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). Optionally, a "gravity" may be specified, as above. +- `crop` - Crop the image to the contents of a box with the specified height and width, positioned a given number of pixels from the top and left. The original image edge will be retained should the bottom and/or right edge of the box fall outside the image bounds. + +#### Supported processing methods + +The following table shows which processing methods are supported by each processing library, and which parameters they accept: + +Method|RMagick|MiniMagick|Vips +------|-----------------|-----------------|-----------------| +`convert`|`format`|`format`, `page`1|`format`, `page`1 +`resize_to_limit`|`width`, `height`|`width`, `height`|`width`, `height` +`resize_to_fit`|`width`, `height`|`width`, `height`|`width`, `height` +`resize_to_fill`|`width`, `height`, `gravity`2|`width`, `height`, `gravity`2|`width`, `height` +`resize_and_pad`|`width`, `height`, `background`, `gravity`2|`width`, `height`, `background`, `gravity`2|`width`, `height`, `background`, `gravity`2 +`resize_to_geometry_string`|`geometry_string`3|*not implemented*|*not implemented* +`crop`|`left`, `top`, `width`, `height`|`left`, `top`, `width`, `height`|`left`, `top`, `width`, `height` + +1`page` refers to the page number when converting from PDF, frame number when converting from GIF, and layer number when converting from PSD. + +2`gravity` refers to an image position given as one of `Center`, `North`, `NorthWest`, `West`, `SouthWest`, `South`, `SouthEast`, `East`, or `NorthEast`. + +3`geometry_string` is an [ImageMagick geometry string](https://rmagick.github.io/imusage.html#geometry). + ## Migrating from Paperclip If you are using Paperclip, you can use the provided compatibility module: