Module: CarrierWave::RMagick

Defined in:
lib/carrierwave/processing/rmagick.rb

Overview

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

require 'carrierwave/processing/rmagick'

And then include it in your uploader:

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

You can now use the provided helpers:

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

  process :resize_to_fit => [200, 200]
end

Or create your own helpers with the powerful manipulate! method. Check out the RMagick docs at www.imagemagick.org/RMagick/doc/ for more info

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

  process :do_stuff => 10.0

  def do_stuff(blur_factor)
    manipulate! do |img|
      img = img.sepiatone
      img = img.auto_orient
      img = img.radial_blur(blur_factor)
    end
  end
end

Note

You should be aware how RMagick handles memory. manipulate! takes care of freeing up memory for you, but for optimum memory usage you should use destructive operations as much as possible:

DON’T DO THIS:

img = img.resize_to_fit

DO THIS INSTEAD:

img.resize_to_fit!

Read this for more information why:

rubyforge.org/forum/forum.php?thread_id=1374&forum_id=1618

Defined Under Namespace

Modules: ClassMethods

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object 



72
73
74
75
 
# File 'lib/carrierwave/processing/rmagick.rb', line 72

def self.included(base)
  super
  base.extend(ClassMethods)
end

Instance Method Details

#convert(format) ⇒ Object

Changes the image encoding format to the given format

See even www.imagemagick.org/RMagick/doc/magick.html#formats

Parameters

format (#to_s)

an abreviation of the format

Yields

Magick::Image

additional manipulations to perform

Examples

image.convert(:png)



116
117
118
 
# File 'lib/carrierwave/processing/rmagick.rb', line 116

def convert(format)
  manipulate!(:format => format)
end

#manipulate!(options = {}) ⇒ Object

Manipulate the image with RMagick. 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.

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

Magick::Image

manipulations to perform

Raises

CarrierWave::ProcessingError

if manipulation failed.



250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/carrierwave/processing/rmagick.rb', line 250

def manipulate!(options={})
  image = ::Magick::Image.read(current_path)

  frames = if image.size > 1
    list = ::Magick::ImageList.new
    image.each do |frame|
      list << yield( frame )
    end
    list
  else
    frame = image.first
    frame = yield( frame ) if block_given?
    frame
  end

  if options[:format]
    frames.write("#{options[:format]}:#{current_path}")
  else
    frames.write(current_path)
  end
  destroy_image(frames)
rescue ::Magick::ImageMagickError => e
  raise CarrierWave::ProcessingError.new("Failed to manipulate with rmagick, maybe it is not an image? Original Error: #{e}")
end

#resize_and_pad(width, height, background = :transparent, gravity = ::Magick::CenterGravity) ⇒ 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).

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 (Magick::GravityType)

how to position the image

Yields

Magick::Image

additional manipulations to perform



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/carrierwave/processing/rmagick.rb', line 213

def resize_and_pad(width, height, background=:transparent, gravity=::Magick::CenterGravity)
  manipulate! do |img|
    img.resize_to_fit!(width, height)
    new_img = ::Magick::Image.new(width, height)
    if background == :transparent
      filled = new_img.matte_floodfill(1, 1)
    else
      filled = new_img.color_floodfill(1, 1, ::Magick::Pixel.from_color(background))
    end
    destroy_image(new_img)
    filled.composite!(img, gravity, ::Magick::OverCompositeOp)
    destroy_image(img)
    filled = yield(filled) if block_given?
    filled
  end
end

#resize_to_fill(width, height, gravity = ::Magick::CenterGravity) ⇒ Object

From the RMagick documentation: “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.”

See even www.imagemagick.org/RMagick/doc/image3.html#resize_to_fill

Parameters

width (Integer)

the width to scale the image to

height (Integer)

the height to scale the image to

Yields

Magick::Image

additional manipulations to perform



188
189
190
191
192
193
194
 
# File 'lib/carrierwave/processing/rmagick.rb', line 188

def resize_to_fill(width, height, gravity=::Magick::CenterGravity)
  manipulate! do |img|
    img.crop_resized!(width, height, gravity)
    img = yield(img) if block_given?
    img
  end
end

#resize_to_fit(width, height) ⇒ Object

From the RMagick documentation: “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.”

See even www.imagemagick.org/RMagick/doc/image3.html#resize_to_fit

Parameters

width (Integer)

the width to scale the image to

height (Integer)

the height to scale the image to

Yields

Magick::Image

additional manipulations to perform



164
165
166
167
168
169
170
 
# File 'lib/carrierwave/processing/rmagick.rb', line 164

def resize_to_fit(width, height)
  manipulate! do |img|
    img.resize_to_fit!(width, height)
    img = yield(img) if block_given?
    img
  end
end

#resize_to_limit(width, height) ⇒ 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

Yields

Magick::Image

additional manipulations to perform



135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/carrierwave/processing/rmagick.rb', line 135

def resize_to_limit(width, height)
  manipulate! do |img|
    geometry = Magick::Geometry.new(width, height, 0, 0, Magick::GreaterGeometry)
    new_img = img.change_geometry(geometry) do |new_width, new_height|
      img.resize(new_width, new_height)
    end
    destroy_image(img)
    new_img = yield(new_img) if block_given?
    new_img
  end
end