Render Images

Alchemy uses Dragonfly (a powerful image processing gem) to render images.

Images are stored as master images in the pictury library. The editor just assigns these master images to content elements you provide. You also set the image rendering bounderies. The max width and height values, or even the size an image should be cropped to. Alchemy even comes with a fancy Javascript based image cropper tool, so that your customer can define the mask to be used.

1 Configuration

  • output_image_jpg_quality [Integer]
    If image gets rendered as JPG this is the quality setting for it. (Default 85)
  • preprocess_image_resize [String]
    Example 1000x1000. If you are limited on diskspace use this option to downsize large images after upload. (Default nil)
  • image_output_format [String]
    The global image output format setting. (Default jpg)

You can always override the output format while rendering your essence with passing {:format => :png} to the render_essence helper.

The default configuration

output_image_jpg_quality: 85
image_output_format: jpg

2 Rendering

In most cases the render_essence helper is the perfect fit for rendering images. It handles all advanced stuff for you (Loading the image instance, setting all needed options and sets the correct security token).

It is highly recommended that you use this for your default image rendering.

2.1 Rendering Options

  • image_size String
    The dimensions the image should be resized to, while keeping the aspect ratio. Example "400x300".
  • crop Boolean
    Pass true to crop the image to the given size.
  • format Symbol
    The output format of the image. :jpg, :gif or :png.
  • quality Integer
    The quality of the rendered jpg image. Obviously only used on jpg images.

2.2 Advanced rendering

If you want to render an image on your own, please have a look at the show_alchemy_picture_url helper in the Alchemy documentation.

3 Caching

In production environments all rendered image get cached on disk.

If the picture request looks like this:

The image gets stored in this path:


All supported rendering options are reflected in the url schema. Even the quality of a rendered jpg image and all cropping options.

To let Apache serve the images directly, you have to set the DocumentRoot to the public folder of your Alchemy app.

4 Security

Alchemy has build in DDOS security for rendering images. So you have to pass a sh parameter and the pictures security token with every image rendering request.

You can get the security token from a picture with the security_token method on a Alchemy::Picture instance.

@picture.security_token(:image_size => "300x400", :crop => true)

The render_essence and show_alchemy_picture_params helpers set the security token for you.