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)



101
102
103
104
105
106
107
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 101

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

#height ⇒ Object

Returns the height of the image in pixels.

Returns

Integer

the image’s height in pixels



231
232
233
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 231

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.



258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 258

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

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

  image.run_command("identify", current_path)
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
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.



292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 292

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



204
205
206
207
208
209
210
211
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 204

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



174
175
176
177
178
179
180
181
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 174

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



149
150
151
152
153
154
155
156
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 149

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



125
126
127
128
129
130
131
132
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 125

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



220
221
222
 
# File 'lib/carrierwave/processing/mini_magick.rb', line 220

def width
  mini_magick_image[:width]
end