Either require 'dragonfly/rails/images' or Dragonfly[:images].configure_with(:imagemagick) gives us an ImageMagick Processor, Encoder, Analyser and Generator.

Given a Job object

image = app.fetch('some/uid')

...OR a Dragonfly model accessor...

image = @album.cover_image

we have the following:


image.thumb('40x30')              # same as image.process(:thumb, '40x30')
image.jpg                         # same as image.encode(:jpg)
image.png                         # same as image.encode(:png)
image.gif                         # same as image.encode(:gif)
image.strip                       # same as image.process(:strip)
image.convert('-scale 30x30')     # same as image.process(:convert, '-scale 30x30')

thumb and convert can optionally take a format (e.g. :gif) as the second argument. Bang methods like image.thumb!('40x30'), image.png! etc. will operate on self.

Below are some examples of geometry strings for thumb:

'400x300'            # resize, maintain aspect ratio
'400x300!'           # force resize, don't maintain aspect ratio
'400x'               # resize width, maintain aspect ratio
'x300'               # resize height, maintain aspect ratio
'400x300>'           # resize only if the image is larger than this
'400x300<'           # resize only if the image is smaller than this
'50x50%'             # resize width and height to 50%
'400x300^'           # resize width, height to minimum 400,300, maintain aspect ratio
'2000@'              # resize so max area in pixels is 2000
'400x300#'           # resize, crop if necessary to maintain aspect ratio (centre gravity)
'400x300#ne'         # as above, north-east gravity
'400x300se'          # crop, with south-east gravity
'400x300+50+100'     # crop from the point 50,100 with width, height 400,300


image.process(:crop, :width => 40, :height => 50, :x => 20, :y => 30)
image.process(:crop, :width => 40, :height => 50, :gravity => 'ne')

image.process(:flip)                         # flips it vertically
image.process(:flop)                         # flips it horizontally

image.process(:greyscale, :depth => 128)     # default depth 256

image.process(:resize, '40x40')
image.process(:resize_and_crop, :width => 40, :height=> 50, :gravity => 'ne')

image.process(:rotate, 45, :background_colour => 'transparent')   # default bg black

The method thumb takes a geometry string and calls resize, resize_and_crop or crop accordingly.

image.process(:thumb, '400x300')             # calls resize


The ImageMagick Encoder gives us:


and various other formats (see ImageMagick Encoder).

You can also pass additional options to the imagemagick command line:

image.encode(:jpg, '-quality 10')


The ImageMagick Analyser gives us these methods:

image.width               # => 280
image.height              # => 355
image.aspect_ratio        # => 0.788732394366197
image.portrait?           # => true
image.landscape?          # => false
image.depth               # => 8
image.number_of_colours   # => 34703
image.format              # => :png
image.image?              # => true - will return true or false for any content


The ImageMagick Generator gives us these methods:

image = app.generate(:plain, 600, 400, 'rgba(40,200,30,0.5)')
image = app.generate(:plain, 600, 400, '#ccc', :format => :gif)
                                                    # generate a 600x400 plain image
                                                    # any css-style colour should work

image = app.generate(:plasma, 600, 400, :gif)       # generate a 600x400 plasma image
                                                    # last arg defaults to :png

image = app.generate(:text, "Hello there")          # an image of the text "Hello there"

image = app.generate(:text, "Hello there",
  :font_size => 30,                                 # defaults to 12
  :font_family => 'Monaco',
  :stroke_color => '#ddd',
  :color => 'red',
  :font_style => 'italic',
  :font_stretch => 'expanded',
  :font_weight => 'bold',
  :padding => '30 20 10',
  :background_color => '#efefef',                   # defaults to transparent
  :format => :gif                                   # defaults to png

Note that the text generation options requires ghostscript (gs) to be installed.

Options are meant to resemble css as much as possible. You can also use, for example, 'font-family' instead of :font_family.

You can use padding-top, padding-left, etc., as well as the standard css shortcuts for padding (it assumes unit is px).

An alternative for :font_family is :font (see the imagemagick docs), which could be a complete filename. Available fonts are those available on your system.


There are some options that can be set, e.g. if the imagemagick convert command can't be found:

app.configure do |c|
  c.convert_command = "/opt/local/bin/convert"          # defaults to "convert"
  c.identify_command = "/opt/local/bin/identify"        # defaults to "identify"
  c.log_commands = true                                 # defaults to false