Skip to content


Subversion checkout URL

You can clone with
Download ZIP
image manipulation as a (plugin-able) service
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

magickly Build Status

A service for image manipulation - built as a simple wrapper of Imagemagick which handles caching, c/o the Dragonfly gem.

Say the base URL is the hosted version of this app, The image URL is appended to the query string as a src=, followed by any of the supported operations below. Multiple operations can be combined, and will be applied in order.

If no query params are provided, a simple sandbox page is displayed. Try it here:


Requires Ruby 1.8.7 or 1.9.2, and Imagemagick >= v6.2.4.

$ gem install magickly

Running the App

For Ruby 1.9.2, you will need to use an Eventmachine-compatible server, i.e. Thin or Rainbows. A few options:

A. Run the app directly

# in the app directory:
$ gem install thin
$ thin start

The app can be accessed at http://localhost:3000. To deploy to Heroku's Cedar stack (or another server using Foreman), see the cedar branch.

B. Use as an endpoint in another Rack app

As an example, to have magickly accessible at /magickly in a Rails app:

# Gemfile
gem 'magickly', '~> 1.1'

# config/routes.rb
match '/magickly', :to => Magickly::App, :anchor => false

For more info, see Rails Routing from the Outside In or Michael Raidel's Mount Rails apps in Rails 3.

Processing Parameters

See the Dragonfly documentation for more details about the permitted geometry values.

src=url (required)

The URL of the original image.

brightness_contrast=brightness x contrast

brightness and contrast are percentage change, between -100 and 100. For example, to increase contrast by 20% but leave brightness unchanged, use brightness_contrast=0x20.

tanned imagemagick logo


flipped imagemagick logo


flopped imagemagick logo


where amount is a float >= 1.0, and softness is an int >= 0.

glowing imagemagick logo,20


flopped imagemagick logo


where threshold is a value between 0 and 100.

halftone imagemagick logo


JCN imagemagick logo


resized imagemagick logo


rotated imagemagick logo


percentage is the percentage of variation: a positive integer. 100 means no change. For example, to increase saturation by 50%, use saturation=150.

saturated imagemagick logo


tilt-shifted imagemagick logo


thumbnail of imagemagick logo

(note: the %23 in the geometry string above is an encoded '#', which tells Dragonfly to fill the dimensions and crop)


two color imagemagick logo

Alternate Syntax

Some CDNs are jerks and don't respect query params on resources (ahem CLOUDFRONT ahem) when caching. To use this syntax:

  • replace the question mark that starts the query string (?) with q/
  • replace the ampersands (&) and equals signs (=) with forward slashes (/)
  • make sure the src is encoded - this can be done in Javascript with encodeURIComponent()

Therefore, instead of

the new URL would be


Magickly v1.2.0 introduces the ability to retrieve image properties via a REST API. For example, to retrieve the number of colors in the photo, visit:

To get the list of available analyzers, visit


In addition to the available parameters listed above, custom "shortcuts" can be created to perform arbitrary imagemagick operations. For example, to create a shortcut called resize_with_blur:

# somewhere in your app configuration, i.e. config/initializers/magickly.rb for a Rails 3 app
Magickly.dragonfly.configure do |c|
  c.job :resize_with_blur do |size|
    process :convert, "-filter Gaussian -resize #{size}"

which can then be used with the query string ?src=...&resize_with_blur=200x. Note that magickly will pass the value of the query param to the block as a single string.

See the Dragonfly documentation for more info on "shortcuts", and the shortcuts.rb file for examples.


The hosted version of the app ( is a single app instance intended for demonstration purposes - if you are going to be making a large number of API calls to it or would like to use it in production, please let us know :-)

Contributing to magickly

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
  • Fork the project
  • Start a feature/bugfix branch
  • Commit and push until you are happy with your contribution
  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.


Created by Aidan Feldman at Thanks to Mark Evans for all his hard work on Dragonfly.

Something went wrong with that request. Please try again.