Module: CarrierWave::MiniMagick

Extended by:
ActiveSupport::Concern
Defined in:
lib/carrierwave/processing/mini_magick.rb

Overview

This module simplifies manipulation with MiniMagick by providing a set of convenient helper methods. If you want to use them, you’ll need to require this file:

require 'carrierwave/processing/mini_magick'

And then include it in your uploader:

class MyUploader < CarrierWave::Uploader::Base
  include CarrierWave::MiniMagick
end

You can now use the provided helpers:

class MyUploader < CarrierWave::Uploader::Base
  include CarrierWave::MiniMagick

  process :resize_to_fit => [200, 200]
end

Or create your own helpers with the powerful minimagick! method, which yields an ImageProcessing::Builder object. Check out the ImageProcessing docs at github.com/janko-m/image_processing and the list of all available ImageMagick options at www.imagemagick.org/script/command-line-options.php for more info.

class MyUploader < CarrierWave::Uploader::Base
  include CarrierWave::MiniMagick

  process :radial_blur => 10

  def radial_blur(amount)
    minimagick! do |builder|
      builder.radial_blur(amount)
      builder = yield(builder) if block_given?
      builder
    end
  end
end

Note

The ImageProcessing gem uses MiniMagick, a mini replacement for RMagick that uses ImageMagick command-line tools, to build a “convert” command that performs the processing.

You can find more information here:

github.com/minimagick/minimagick/

Defined Under Namespace

Modules: ClassMethods

Instance Method Summary collapse

Instance Method Details

#convert(format, page = nil, &block) ⇒ Object

Changes the image encoding format to the given format

See www.imagemagick.org/script/command-line-options.php#format

Parameters

format (#to_s)

an abbreviation of the format

Yields

MiniMagick::Image

additional manipulations to perform

Examples

image.convert(:png)



105
106
107
108
109
110
111
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 105

def convert(format, page=nil, &block)
  minimagick!(block) do |builder|
    builder = builder.convert(format)
    builder = builder.loader(page: page) if page
    builder
  end
end

#crop(left, top, width, height, combine_options: {}, &block) ⇒ Object

Crop the image to the contents of a box positioned at [left] and [top], with the dimensions given by [width] and [height]. The original image bottom/right edge is preserved if the cropping box falls outside the image bounds.

Parameters

left (integer)

left edge of area to extract

top (integer)

top edge of area to extract

width (Integer)

width of area to extract

height (Integer)

height of area to extract

Yields

MiniMagick::Image

additional manipulations to perform



233
234
235
236
237
238
239
240
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 233

def crop(left, top, width, height, combine_options: {}, &block)
  width, height = resolve_dimensions(width, height)

  minimagick!(block) do |builder|
    builder.crop(left, top, width, height)
      .apply(combine_options)
  end
end

#height ⇒ Object

Returns the height of the image in pixels.

Returns

Integer

the image’s height in pixels



260
261
262
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 260

def height
  mini_magick_image[:height]
end

#manipulate! ⇒ Object

Manipulate the image with MiniMagick. This method will load up an image and then pass each of its frames to the supplied block. It will then save the image to disk.

NOTE: This method exists mostly for backwards compatibility, you should probably use #minimagick!.

Gotcha

This method assumes that the object responds to current_path. Any class that this module is mixed into must have a current_path method. CarrierWave::Uploader does, so you won’t need to worry about this in most cases.

Yields

MiniMagick::Image

manipulations to perform

Raises

CarrierWave::ProcessingError

if manipulation failed.



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 287

def manipulate!
  cache_stored_file! if !cached?
  image = ::MiniMagick::Image.open(current_path)

  image = yield(image)
  FileUtils.mv image.path, current_path

  ::MiniMagick::Image.new(current_path).identify
rescue ::MiniMagick::Error, ::MiniMagick::Invalid => e
  raise e if e.message =~ /(You must have .+ installed|is not installed|executable not found|delegate failed)/
  message = I18n.translate(:"errors.messages.processing_error")
  raise CarrierWave::ProcessingError, message
ensure
  image.destroy! if image
end

#minimagick!(block = nil) ⇒ Object

Process the image with MiniMagick, using the ImageProcessing gem. This method will build a “convert” ImageMagick command and execute it on the current image.

Gotcha

This method assumes that the object responds to current_path. Any class that this module is mixed into must have a current_path method. CarrierWave::Uploader does, so you won’t need to worry about this in most cases.

Yields

ImageProcessing::Builder

use it to define processing to be performed

Raises

CarrierWave::ProcessingError

if processing failed.



321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 321

def minimagick!(block = nil)
  builder = ImageProcessing::MiniMagick.source(current_path)
  builder = yield(builder)

  result = builder.call
  result.close

  # backwards compatibility (we want to eventually move away from MiniMagick::Image)
  if block
    image  = ::MiniMagick::Image.new(result.path, result)
    image  = block.call(image)
    result = image.instance_variable_get(:@tempfile)
  end

  FileUtils.mv result.path, current_path

  if File.extname(result.path) != File.extname(current_path)
    move_to = current_path.chomp(File.extname(current_path)) + File.extname(result.path)
    file.content_type = Marcel::Magic.by_path(move_to).try(:type)
    file.move_to(move_to, permissions, directory_permissions)
  end
rescue ::MiniMagick::Error, ::MiniMagick::Invalid => e
  raise e if e.message =~ /(You must have .+ installed|is not installed|executable not found)/
  message = I18n.translate(:"errors.messages.processing_error")
  raise CarrierWave::ProcessingError, message
end

#resize_and_pad(width, height, background = :transparent, gravity = 'Center', combine_options: {}, &block) ⇒ Object

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).

See www.imagemagick.org/script/command-line-options.php#gravity for gravity options.

Parameters

width (Integer)

the width to scale the image to

height (Integer)

the height to scale the image to

background (String, :transparent)

the color of the background as a hexcode, like “#ff45de”

gravity (String)

how to position the image

combine_options (Hash)

additional ImageMagick options to apply before resizing

Yields

MiniMagick::Image

additional manipulations to perform



208
209
210
211
212
213
214
215
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 208

def resize_and_pad(width, height, background=:transparent, gravity='Center', combine_options: {}, &block)
  width, height = resolve_dimensions(width, height)

  minimagick!(block) do |builder|
    builder.resize_and_pad(width, height, background: background, gravity: gravity)
      .apply(combine_options)
  end
end

#resize_to_fill(width, height, gravity = 'Center', combine_options: {}, &block) ⇒ Object

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.

Parameters

width (Integer)

the width to scale the image to

height (Integer)

the height to scale the image to

gravity (String)

the current gravity suggestion (default: ‘Center’; options: ‘NorthWest’, ‘North’, ‘NorthEast’, ‘West’, ‘Center’, ‘East’, ‘SouthWest’, ‘South’, ‘SouthEast’)

combine_options (Hash)

additional ImageMagick options to apply before resizing

Yields

MiniMagick::Image

additional manipulations to perform



178
179
180
181
182
183
184
185
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 178

def resize_to_fill(width, height, gravity = 'Center', combine_options: {}, &block)
  width, height = resolve_dimensions(width, height)

  minimagick!(block) do |builder|
    builder.resize_to_fill(width, height, gravity: gravity)
      .apply(combine_options)
  end
end

#resize_to_fit(width, height, combine_options: {}, &block) ⇒ Object

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.

Parameters

width (Integer)

the width to scale the image to

height (Integer)

the height to scale the image to

combine_options (Hash)

additional ImageMagick options to apply before resizing

Yields

MiniMagick::Image

additional manipulations to perform



153
154
155
156
157
158
159
160
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 153

def resize_to_fit(width, height, combine_options: {}, &block)
  width, height = resolve_dimensions(width, height)

  minimagick!(block) do |builder|
    builder.resize_to_fit(width, height)
      .apply(combine_options)
  end
end

#resize_to_limit(width, height, combine_options: {}, &block) ⇒ Object

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.

Parameters

width (Integer)

the width to scale the image to

height (Integer)

the height to scale the image to

combine_options (Hash)

additional ImageMagick options to apply before resizing

Yields

MiniMagick::Image

additional manipulations to perform



129
130
131
132
133
134
135
136
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 129

def resize_to_limit(width, height, combine_options: {}, &block)
  width, height = resolve_dimensions(width, height)

  minimagick!(block) do |builder|
    builder.resize_to_limit(width, height)
      .apply(combine_options)
  end
end

#width ⇒ Object

Returns the width of the image in pixels.

Returns

Integer

the image’s width in pixels



249
250
251
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 249

def width
  mini_magick_image[:width]
end