Skip to main content

How to use Imager with ImageMagick to get cool image effects

Darkroom

If you've ever had the opportunity to spend any time in a real darkroom or with an old-school photographer, you know how difficult it was to achieve interesting results. There were a variety of methods you could use to modify your printed images – bleach bypassing, cross processing, redscale shooting, platinum printing and more. There were techniques like dodging and burning which involved using a variety of hand made tools and your hands to darken or lighten parts of your prints. The chemicals involved in the process were dangerous to inhale, toxic and even flammable. Darkroom work was a combination of passion, obsession, vision and long hours. Oddly enough, I miss the darkroom.

In our digital world we no longer need to spend countless hours in the darkroom to achieve great results, nor do you need to understand the historical context behind photo manipulation. But I strongly encourage you to do some research into the subject for inspiration.

Dodge burn tools
Dodge and burn tools were used to lighten or darken very specific parts of your print.

Occasionally you may want to modify the appearance of an image or set of images. Imagine an image gallery where the thumbnails are all in black and white, and the full size image is full color. You could set things up in the CMS so that for each gallery image you're required to upload a black and white thumb and a full color image, but that would be way too much work for you and/or your client. What if your client later decides that the thumbnails should be sepia toned with blue? Now you must go back and replace every thumb! 😔 To produce cool image effects on the fly without the need to manually manage images, you must start using Imager plugin with ImageMagick software!

Note that I cannot possibly cover all of the amazing transformations you can make with Imager and ImageMagick. In this article, I will focus on the modulate effect in ImageMagick. At the end of this article, I provide one example using even more features!

The Imager plugin

By default Craft CMS allows you to do a variety of image transforms including mode, width, height, quality and position. These transforms are ok, but in my experience they do not go far enough. Instead of using Craft's vanilla transforms, I've made the Imager plugin a standard with every site install. It's a free plugin written and maintained by André Elvan, so if you plan on using it please show thanks by buying him a beer!

The Imager plugin does everything that a standard Craft transform does, but the plugin allows us to unlock features that are only available with an image transformer like ImageMagick. So, before you can accomplish below, you must install the Imager plugin.

ImageMagick Software

ImageMagick is a free software that also must to be installed before you can achieve the cool effect below. ImageMagick is not installed through Craft CMS, it must be installed directly on your web server. If you're not familiar with installing a ready-to-run binary on your server, you may need to reach out to your server admin. I do my own server administration and I'm running an NGINX web server on Digital Ocean. If you're running a similar configuration, you'll need to SSH into your server and run this (make sure to follow the install with a PHP and NGINX restart):

sudo apt-get update && sudo apt-get install -y imagemagick php-imagick
sudo service php7.3-fpm restart
sudo service nginx restart

If everything went as planned, you should now have ImageMagick installed on your web server. You can verify this through your Craft CMS control panel by going to Utilities > PHP Info and searching for "imagick". My install indicates imagick module version 3.4.3.

The next step is to tell Craft CMS that you want to use ImageMagick by default for your transformations. This is done through the general config file found in your Craft install. This file can be found at to top level of your install > config/general.php. Add the following to your global settings:

'*' => [
    // YOUR OTHER SETTINGS HERE
    // ...
    
    // Make sure to install ImageMagick on your server first
    'imageDriver' => 'imagick'
],

Let the Magick happen!

Now that you've installed both Imager and ImageMagick, it's time to have some fun. This is a quick snippet you can use to retrieve a single asset from your Craft install:

{% set myImage = craft.assets()
    .id({...INSERT AN IMAGE ID...})
    .one() %}

{% set myTransform = craft.imager.transformImage(myImage,
    {
        width: 800,
        jpegQuality: 80,
    }
) %}

<img src="{{ myTransform.url }}">
Melissa 2019 240b62cf9eb67fe203d15067047501a2
Original image, 800px wide, 80 jpg quality

Now, let's do a basic black and white transform:

{% set myTransform = craft.imager.transformImage(myImage,
    {
        width: 800,
        jpegQuality: 80,
        effects: {
            grayscale: true
        }
    }
) %}
Melissa 2019 904d52e8f344321014bb6f81c21f9f61
grayscale: true

That looks cool, but the contrast is a bit much. Let's improve that by adding gamma:

{% set myTransform = craft.imager.transformImage(myImage,
    {
        width: 800,
        jpegQuality: 80,
        effects: {
            grayscale: true,
            gamma: 1.5
        }
    }
) %}
Melissa 2019 e593eeef624839c00f28c922d27dc5a4
grayscale: true, gamma: 1.5

You can also use gamma on color images. For example, let's drain the color out of the image by setting a high gamma:

{% set myTransform = craft.imager.transformImage(myImage,
    {
        width: 800,
        jpegQuality: 80,
        effects: {
            gamma: 3
        }
    }
) %}
Melissa 2019 aaa765faa9b69e1c5b9b2730c9a293ba
gamma: 3

Let's play around with color more! If you're a Photoshop user, you're most likely familiar with brightness, saturation and hue. The order I presented them here B, S, and H is important because these modifiers map in that order to our next ImageMagick effect – modulation.

Modulation is tricky to wrap your head around if you're not experienced in color manipulation. To make this easier, I opened up an image the Photoshop and I added three adjustment layers, one for each of the modulation effects:

Photoshop sample file
Adjustment layers added to simulate the modulation effects

In Photoshop, take the brightness slider and move it the right as far as it will go – 150. If your slider only goes to 100, make sure to uncheck "Use legacy".

Photoshop sample 150 brightness
Brightness adjustment layer set to 150

Theoretically, the following settings in ImageMagick should give the same effect as the Photoshop test:

{% set myTransform = craft.imager.transformImage(myImage,
    {
        width: 800,
        jpegQuality: 80,
        effects: {
            modulate: [150, 100, 100]
        }
    }
) %}
Melissa 2019 307acf72c966b4de7c27667ec509ec0b
modulate [150, 100, 100]

Not perfect, but it's pretty darn close! I find that using the Photoshop file to simulate the modulation effects in ImageMagick can save you a bunch of time because it's simple to move around sliders in Photoshop.

Before we try any tricky effect modulations, let's do a little dissecting of the the upper and lower values and see how those compare to the Photoshop simulator. There's full documentation of ImageMagick features, but I find it difficult to wrap my brain around, so this is my caveman understanding.

Brightness

This is a multiplier of the overall image brightness with a range from 0-200. A value of 100 means no change. Setting the brightness value to 0 will produce a black image, whereas 200 will produce an image that is 2X brighter than the original.

RangeNo ChangeEquiv MinEquiv Max
ImageMagick0 to 20010050150
Photoshop-150 to 1500-150150

In our Photoshop simulator, I found that -150 in the brightness slider is equal to about 50 in ImageMagick. When brightening an image, 150 in Photoshop is equal to about 150 in ImageMagick. Photoshop doesn't allow us to simulate the full range you can get in ImageMagick, and I suspect this is because Adobe is trying to help you preserve (not destroy) your images.

Why does a value of 0 produce a black image, while a value of 200 does not produce a white image? The documentation on ImageMagick puts it like this: "Note that as the brightness and saturation are percentage multipliers, you would need to multiply by a very large number to change almost all the image color values to near maximum. That is you would need to use a brightness factor of close to one million, to make all colors except pure black, white."

Saturation

Saturation is also a multiplier that adjusts the overall amount of color present in the image with a range from 0-200. A value of 100 means no change, whereas a value of 200 is 2X more saturated than the original.

RangeNo ChangeEquiv MinEquiv Max
ImageMagick0 to 2001000200
Photoshop-100 to 1000-100100

In our Photoshop simulator, I found that the full range of the slider is equivalent to the full range available in ImageMagick.

Hue

The final value, Hue, rotates the colors of the image, in a cyclic manner. To achieve this the Hue value given produces a modulus addition, rather than a multiplication. This is the most difficult of the modulate effects to understand, so I created this handy hue wheel to make it easier to understand:

Hue wheel im ps
IM = ImageMagick value, PS = Photoshop equivalent

I hope this chart makes sense to you?! Basically, the IM value is the hue value you should enter in your ImageMagick modulate effect to get that color. Note that a value of 100 in ImageMagick does nothing to the image.

In order to simulate the ImageMagick effect in Photoshop, you need to activate your hue adjustment layer, and toggle the "Colorize" button at the bottom of the hue panel:

Photoshop sample hue 180
Hue value = 180 with Colorize toggled

In case you're wondering if the equivalent ImageMagick hue setting of 0 matches the Photoshop setting of 180:

Melissa 2019 a655b1f4d5e390f662545aed147716b3
modulate [100, 100, 0]

Again, not perfect, but not bad! So, let's mix things up a bit and create another image using all of the ImageMagick modulation values (brightness, saturation, hue). This is a Photoshop simulation I want to achieve followed by the ImageMagick transform:

Photoshop sample all mods
50 brightness, 100 saturation, 300 hue
Melissa 2019 f2a730ba932430c24110f01b81e578ea
modulate: [120, 200, 66.6]

We should not expect a perfect match between these two samples. After all, these are two completely different systems for handling color. Conceptually, they share things in common, but they will never produce a pixel-to-pixel match. For me, comparing what I already know about Photoshop to what ImageMagick is capable of doing, is simply an exercise in learning.

Ok, I cannot resist doing one final transformation with ImageMagick. I'm pulling out all the stops!

{% set myTransform = craft.imager.transformImage(myImage,
    {
        width: 800,
        jpegQuality: 80,
        effects: {
            modulate: [120, 200, 66.6],
            clut: 'gradient:rgba(255,0,255,0.5)-rgba(255,255,0,1)',
            posterize: [128, 'floydsteinberg']
        }
    }
) %}
Melissa 2019 9c389315c0cea35cd63d9a758efbf015
Get creative!

I could go on for days creating different image transformations. The possibilities are endless!

I hope you enjoyed this article. I urge you to explore the Imager plugin page as well as the ImageMagick documentation. And last, but not least, thanks to my beautiful wife Melissa for offering her headshot for this article.