About Conclurer GIM

Basic Image Manipulations for ProcessWire

Category 1Development Tools
Modules that have more to do with assisting development of a site rather than managing its content.
Category 2Photo/Video/Audio
Modules that perform some function related to media such as photos and audio/video.
Release StateBeta
Close to stable, but users are advised to be cautious and test thoroughly.*
Authorconclurer
Module Version0.1.0
Class NamePageGIM
Compatibility2.4, 2.5, 2.6, 2.7
Date AddedJanuary 3, 2015
Recommended ByNew recommendations may take up to 1 day to appear.

Instructions

This module's files should be placed in /site/modules/PageGIM/
How to install or uninstall modules

README

Conclurer GIM

This module provides basic image manipulations for Pageimage objects. It uses Gregwar's Image class for all image operations and has a PageImageManipulator compatible syntax.

Usage

GIM can be loaded from every Pageimage to perform its operations. In this example, the image is loaded, grayscaled and saved.

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

The method save() returns a Pageimage object, therefore you can run the built-in ProcessWire image methods on it.

Methods

Note: GIM has a changed syntax to Gregwar's Image class for some operations to be compatible with PageImageManipulator.

GIM includes the following methods for your image manipulations:

Crop, Resize & Rotation

  • crop($x, $y, $width, $height) crops the image to a box located on the coordinates $x and $y and has the size $width by $height.
    Note: all coordinate axess start on the top-right side of the image
  • rotate($degree, $backgroundColor=127) rotates the image by $degree and applying the $backgroundColor
  • fillBackground($color=0xffffff) fills the background of the image with $color
  • flip($vertical=false) flips the image vertically or horizontally
  • resize($targetWidth, $targetHeight) resizes and preserves the scale of the image to match the given $targetWidth and $targetHeight. It will look like this:
    Image
  • scaleResize($width, $height, $background) will resize the image, preserves its scale but keeps the frame size. It will look like this (Note: $background is red in all examples):
    Image
  • forceResize($width, $height, $background) forces the image to be exactly $width by $height. It will look like this:
    Image
  • cropResize($width, $height, $background) alias to crop()
  • zoomCrop($width, $height, $background, $xPos, $yPos) resizes and crops the image to fit the given dimensions. It will look like this:
    Image
    You can also change the position of the resized image using $xPos (center, left or right) and $yPos (center, top or bottom):
    Image
  • width($targetWidht) like crop() but matches only to the given width
  • height($targetHeight) like crop() but matches only to the given height

Filters

  • negate() negates the image's colors
  • brightness($level) applies a brightness effect. $level must be between -255 and +255
  • contrast($level) applies a contrast effect. $level must be between -100 and +100
  • grayscale() converts the image to grayscale
  • emboss() embosses the image
  • smooth($level) smoothes the image by $level
  • sharp() sharpens the image
  • edge() applies an edge detection effect
  • colorize(array($r, $g, $b)) colorizes the image from -255 to +255 for each color
  • sepia() allies a sepia effect
  • fill($color, $x, $y) fills the image with the given color.
    Note: all colors shall be supplied in hexadecimal format

Text & Forms

  • write($font, $text, $x, $y, $size, $angle, $color, $orientation) overlays $text at position $x and $y using $font in a given $angle and $color at the $orientation (left, right or center)
  • rectangle($x1, $y1, $x2, $y2, $color, $filled=false) draws a rectangle between the position $x1, $y1 and $x2, $y2
  • roundedRectangle($x1, $y1, $x2, $y2, $radius, $color, $filled=false) draws a rounded rectangle using $radius (> 0) for the corners
  • line($x1, $y1, $x2, $y2, $color) draws a line
  • ellipse($centerX, $centerY, $width, $height, $color, $filled=false) draws a ellipse with the center at $centerX, $centerY
  • circle($centerX, $centerY, $r, $color, $filled=false) draws a circle

Image Merging

  • merge(Pageimage $image, $x, $y, $width, $height) merges the given Pageimage on top of the current page image, starting at position $x and $y with the dimensions of $width by $height.
    Note: if width and height aren't given, the source images widht and height is used.
    Note: if $x and $y aren't given, the coordinate 0,0 is used
  • mergePageImage(...) alias for merge()
  • mergeImagePath($path, ...) merges a image from a given absolute path. Other parameters are equivalent to merge()
  • overlayImageStretched($path) overlays $path and stretches it, matching the current image's size.

PageImageManipulator Compatibility

Conclurer GIM can replace PageImageManipulator easily. You can switch from PageImageManipulator to GIM 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

Method Compatibility

Since GIM uses Gregwar's Image class for all image operations, it can only perform operations that are available in this library. Therefore, some of PageImageManipulator's methods are non-functional or have a different behaviour.

GIM includes all of PageImageManipulator's methods and returns the expected values.

Non-functional Methods

The following methods do nothing:

  • getImageInfo()
  • getPimVariations()
  • removePimVariations()
  • getGimVariations()
  • removeGimVariations()
  • sharpen()
  • unsharpMask()
  • canvas()
  • getMemoryImage()
  • setMemoryImage()
  • watermarkLogo() (check the Image Merging section)
  • watermarkLogoTiled()
  • watermarkText() (check the Text & Forms section)

When migrating from PageImageManipulator, you can still call these methods, so they don't crash.

Different Behaviour

The following methods have different effects compared to PageImageManipulator:

  • setOptions() only the options 'outputFormat' and 'quality' are available, other options will be ignored.
  • getOptions() will only return 'outputFormat' and 'quality'.
  • stepResize() will only perform resize() and not sharpen the image in multiple steps
  • blur() will call smooth(200)
  • pixelate() will call smooth(200)

Migration Notices

  • GIM includes the same naming scheme for manipulated image files. Therefore, after a migration, existing image files from PageImageManipulator will not be replaced in Production Mode.
  • In Development Mode, every image is recreated on every page load. You can turn on and off Development Mode in GIM's module settings.

Change Log

Version 0.1 beta
December 31st, 2015

Initial release

Comments

  • Katherine Hepworth

    Katherine Hepworth 2 years ago 00

    Warning, adding this module broke my modules page, and returned the following error:

    https://www.dropbox.com/s/oby37twrtopsb61/Screenshot%202015-01-15%2013.00.45.png?dl=0

    I'm going to remove the module via FTP and cross my fingers that this error is fixed soon. This module looks so versatile, I'm excited to get it working.

  • Horst

    Horst 2 years ago 00

    @kathep: Regarding your error: PW needs PHP >= 5.3.8, but this module seems to need PHP >= 5.4. But it does not specify it in the requirements!

    Also there is not added a link to the supportboard in the forums where are also some comments and questions still pending unanswered for 4 weeks now:

    https://processwire.com/talk/topic/8687-conclurer-gim-performant-pageimagemanipulator/#entry84382

    I'm curious if this module comes without support?

Post a Comment

Your e-mail is kept confidential and not included with your comment. Website is optional.