Conclurer GIM - Performant PageImageManipulator

[Marvin Scharle]

Hello everybody,

our next module is an performant manipulator for Pageimages. It is called GIM.

GIM is basically a wrapper for the PHP library Gregwar's image class, which performs many image manipulations. The wrapper is written in a way that is compatible with Horst's PageImageManipulator's (PIM) syntax.

How does it work?

GIM extends ProcessWire's Pageimage objects. You can load every image with the method gim(), perform some operations and save the image with the save() method:

$image = $page->image->gim()->grayscale()->save();

The save() method returns another Pageimage object, so you can use it with other native ProcessWire methods and hooks.

Methods

GIM includes a lot of methods for image manipulations. You can find them in more detail on our module page.

• You can crop, resize, flip and rotate the image in several ways
• You can apply filters like sepia to the image
• You can add texts and shapes to the image
• You can merge multiple images in multiple ways

Compatibility with Horst's PageImageManipulator (PIM)

You can just use GIM instead of PIM by replacing pim with gim:

$image1 = $page->image->pimLoad('prefix')
    ->setOptions(array('outputFormat'=>'jpg'))
    ->brightness(-10)
    ->contrast(15)
    ->grayscale()
    ->width(600)
    ->pimSave();    // uses PageImageManipulator

$image2 = $page->image->gimLoad('prefix')
    ->setOptions(array('outputFormat'=>'jpg'))
    ->brightness(-10)
    ->contrast(15)
    ->grayscale()
    ->width(600)
    ->gimSave();    // uses GIM

GIM includes every method from PIM, so it just works. Also GIM and PIM share the same variation naming scheme, so when you start using GIM, the transition is seamless and does not need to recreate every image.

Having the same naming schemes means, that GIM and PIM can also work side-by-side.

For a full list of compatibility and migration notes, please check out our module page.

Performance

The reason why we created GIM is that we were looking for a more performant PHP image library for converting lots of images at once. After using Gregwar's image class for a few images, we thought that this library should find its way into ProcessWire.

After testing GIM on a few sites, this is what we found out:

• GIM handles already manipulated images around 40% faster
• GIM is able to heavily manipulate at least 15 large images (> 2000px) in one request (more weren't tested yet)
• GIM is slightly faster than PIM for single image operations

I hope this is a great addition to the ProcessWire module ecosystem and you can enjoy it.

Thanks in advance,

Marvin

P.S.: Horst, I hope you don't see this as offense. PIM is a great module!

[horst]

Wow! You have brought it a step further!

Very well done to use the same naming scheme and provide the same methods.

Edit:

At the GitRepo I have seen that the gregwar lib supports IMagick? I saw a GD.php and a Imagick.php. How can I force to use the Imagick.php?

Edited January 4, 2015 by horst

[Marvin Scharle]

At the GitRepo I have seen that the gregwar lib supports IMagick? I saw a GD.php and a Imagick.php. How can I force to use the Imagick.php?

We'll add a option in the module's settings page in the next update.

[teppo]

@Marvin: thanks for this, the module looks great! Would be interesting to see some sort of a comparison between GIM and PIM features, though, as it's not really obvious from a quick glance what the differences are

Would you mind adding a link to this support thread to the modules directory page, by the way?

[horst]

Hey @Marvin,

1) Please add a Supportboard-Link to this entry in the modules directory.

.

.

2) Is it right that you do not respect any of the sitewide PW default settings for images? Not those that optionally can be defined especially for ImageManipulator nor those that are defined for the ImageSizer?

•         // from core imageSizer
•         'autoRotation'
•         'upscaling'
•         'cropping'
•         'quality'
•         'sharpening'
•         'defaultGamma'
•         'useUSM'
•         // for manipulator only
•         'bgcolor'
•         'targetFilename'
•         'outputFormat'

.

.

3) In the description of Gim you say that the only options that can be specified and set are quality and outputFormat, but

• Quality seems not to work, I always get the same result in filesize.
   
• OutputFormat works partly, means: when I try to create a jpeg and a png from the same image, (what I can do with Pim), it does not create the second file without forcing a recreate! And when I force recreation, it overwrites my first image with the second rendering. This is because it does not reflect the outputFormat in the filename.

I use this test code:

    $image = $page->images->eq(0);

    $w = intval($image->width / 10 * 2);
    $h = intval($image->height / 10 * 2);

    echo "<p>test with defaults<br />";
    $gim = $image->gimLoad('gim1')->resize($w, $h)->save();
    echo filesize($gim->filename) . ' :: ' . $gim->url . '</p>';

    echo "<p>test with outputFormat PNG<br />";
    $gim = $image->gimLoad('gim1')->resize($w, $h);
    $gim = $gim->setOptions(array('outputFormat' => 'png'))->save();
    echo filesize($gim->filename) . ' :: ' . $gim->url . '</p>';

    echo "<p>test with quality 100<br />";
    $gim = $image->gimLoad('gim2')->resize($w, $h);
    $gim = $gim->setOptions(array('quality' => 100))->save();
    echo filesize($gim->filename) . ' :: ' . $gim->url . '</p>';

    echo "<p>test with quality 20<br />";
    $gim = $image->gimLoad('gim4')->resize($w, $h);
    $gim = $gim->setOptions(array('quality' => 20))->save();
    echo filesize($gim->filename) . ' :: ' . $gim->url . '</p>';

and get this result:

test with defaults
21235 :: /site/assets/files/1/pim_gim1_basename_02.jpg

test with outputFormat PNG (and not forcing recreation)
21235 :: /site/assets/files/1/pim_gim1_basename_02.jpg
or
test with outputFormat PNG forcing recreation (look filesize!!)
178060 :: /site/assets/files/1/pim_gim1_basename_02.jpg

test with quality 100
21235 :: /site/assets/files/1/pim_gim2_basename_02.jpg

test with quality 20
21235 :: /site/assets/files/1/pim_gim4_basename_02.jpg

.

Also there is no validation done. Not for supported filetypes nor typos, and also not for a valid range for quality.

.

.

4) Why do you not keep IPTC, what is (sort of) mandatory within PW? At least you should print a big warning at the very top of the announcement for those that rely on this. (because AFAIK it is supported by every other image related part in PW since Version 2.3, or do I miss something?)

.

.

5) Same with the big warning should be done in regard of sharpening! The lib you implemented does not support any sharpening method!

As a sidenote, one of the most timeconsuming image manipulations with GD / PHP is sharpening!

.

.

6) Also the lib does not support transparency in GIF, it renders them with black background. Detecting the need for AutoRotation is not supported too.

.

.

7) Ah, - regarding my post about the Imagick adapter I have seen there, this looks a bit like a stillbirth. (https://github.com/Gregwar/Image/pull/65)

.

.

.

When first reading your announcement here I was very happy because I have started a few times to rewrite the Pim to make it faster and more robust, but couldn't finish it, (lots of work to do). But now for me it sounds a bit more like a marketing strategy than a real chance for me to get my hands on a better Pim implementation in PW.

.

.

.

Besides the above mentioned, here is a list of not supported methods in Gim:

• getOptions           (very limited)
• setOptions           (very limited)
• getImageInfo        (returns nothing)
• getPimVariations
• removePimVariations

• sharpen
• unsharpMask
• stepResize

• watermarkLogo
• watermarkLogoTiled
• watermarkText

• canvas
• blur
• pixelate
• getMemoryImage
• setMemoryImage

.

The supported methods are:

• brightness
• colorize
• contrast
• edgedetect
• emboss
• flip
• grayscale
• negate
• rotate
• sepia
• smooth

.

New methods, that are in Gim, but not in Pim:

• mergePageImage          (can be used for watermarking)
• merge                            (can be used for watermarking)
• write                               (can be used for watermarking)
• overlayImageStretched  (can be used for watermarking)
  
  // drawing functions
• circle
• ellipse
• line
• rectangle
• roundedRectangle

.

And those are methods from Gim that could be used to emulate our PW crop and upscaling settings:

• crop
• zoomCrop
• cropResize
• forceResize
• scaleResize