Documentation

#PHPImageTools Documentation

###The ImageFactory Class

Creating an image from a local file:

use kingjerod\ImageTools\Image\ImageFactory;

$factory = new ImageFactory();
$image = $factory->createFromLocalFile('/path/to/file.png');

Creating an image from a remote file. This uses Guzzle to request the file.

use kingjerod\ImageTools\Image\ImageFactory;

$factory = new ImageFactory();
$image = $factory->createFromRemoteFile('http://www.google.com/logo.png');

Creating an array of images from a directory. The second parameter acts a regex, filtering only those files you want. It uses Symfony Finder to locate the files.

use kingjerod\ImageTools\Image\ImageFactory;

$factory = new ImageFactory();
$images = $factory->createFromDirectory('/path/to/images', '*.png'); //Only get png files
//$images[0] will be an Image, $images[1] will be another Image

Creating an image from scratch. Params are (width, height, background color). Use "none" for transparent background.

use kingjerod\ImageTools\Image\ImageFactory;

$factory = new ImageFactory();
$image = $factory->createEmptyImage(100, 200, '#FFF');

---

###The Image Class with Modifiers

The Image class contains the ImageMagick instance and will accept modifiers that alter it.

Scaling images and Filters

When scaling an image, different filters can be used. Each filter has pros and cons, some are better at shrinking images, others are better at enlarging. If no filter is provided to a scaling modifier, the Lanczos filter will be used when any dimension (width/height) is reduced. If both dimensions are being enlarged, then the Mitchell filter will be used. Both of these filters are "slow" but produce high quality images. For a faster filter, use the Scale::FILTER_GAUSSIAN. For more information on filters: http://www.imagemagick.org/Usage/filter/

Any of the scale modifiers adopt their filters from Imagick. Any Imagick filter can be used in the scale modifiers.

Scale

Scales an image to exact width/height ($width, $height, $filter)

use kingjerod\ImageTools\Modifier\Scale;
$scale = new Scale(200, 300);
$image->modify($scale);
$image->save('/tmp/myImage.png');

PercentScale

Scales an image using percentages. The percentages are in decimal form (0.5=50%) ($percentWidth, $percentHeight, $filter)

use kingjerod\ImageTools\Modifier\PercentScale;
use kingjerod\ImageTools\Image\ImageFactory;

$factory = new ImageFactory();
$image = $factory->createEmptyImage(600, 400, '#FFF');
$scale = new PercentScale(0.5, 0.25); //50% on width, 25% on height
$image->modify($scale); //New image will be 300x100
$image->save('/tmp/myImage.png');

MaxScale

Scales an image so that one side is a maximum size. ($maxWidth, $maxHeight, $filter) Calculates which side is furthest away from the max and scales the other side accordingly.

Here the starting image is 900x600, and the max desired size is 500 width or 200 height. The width is 1.8x as big, but the height is 3x as big, so it is scaled by height. The final image size will be 300x200

use kingjerod\ImageTools\Modifier\MaxScale;
use kingjerod\ImageTools\Image\ImageFactory;

$factory = new ImageFactory();
$image = $factory->createEmptyImage(900, 600, '#FFF');
$scale = new MaxScale(500, 200); //Max width is 500, max height is 200
$image->modify($scale);
$image->save('/tmp/myImage.png');

Here the starting image is 2000x600, and the max desired size is 500 width or 200 height. The width is 4x as big, and the height is 3x as big, so it is scaled by width now. The final image size will be 500x150

use kingjerod\ImageTools\Modifier\MaxScale;
use kingjerod\ImageTools\Image\ImageFactory;

$factory = new ImageFactory();
$image = $factory->createEmptyImage(2000, 600, '#FFF');
$scale = new MaxScale(500, 200); //Max width is 500, max height is 200
$image->modify($scale);
$image->save('/tmp/myImage.png');

Crop

Crops an image, essentially cutting out a part of it. The x/y are calculated from the top left corner. ($x, $y, $width, $height)

use kingjerod\ImageTools\Modifier\Crop;
//Starting from top left, 10 right, 20 down, chop out a piece 200x300
$crop= new Crop(10, 20, 200, 300); 
$image->modify($crop);
$image->save('/tmp/myImage.png');

GaussianBlur

Creates a gaussian blur on the image. ($radius, $sigma, $channel = \Imagick::CHANNEL_ALL)

use kingjerod\ImageTools\Modifier\GaussianBlur;
$blur= new GaussianBlur(100, 10); 
$image->modify($blur);
$image->save('/tmp/myImage.png');

Merge

Merges the image with another at the specified x/y coordinates. ($x, $y, Image $image)

use kingjerod\ImageTools\Modifier\Merge;
use kingjerod\ImageTools\Image\ImageFactory;

$factory = new ImageFactory();
$image = $factory->createEmptyImage(1000, 1000, '#FFF');
$redSquare = $factory->createEmptyImage(50, 50, '#F00');
$merge = new Merge(50, 50, $redSquare);
$image ->modify($merge);
$image ->save('/tmp/myImage.png'); //Will have a red square in the top left

Text

Draws text on the image. The y coordinate for the text is the bottom of the letters. The x coordinate of the text depends on the alignment option. Left aligning means the letters will start at the x coordinate. Center aligning means the middle letter will be at the x coordinate. Right aligning means the last letter will end on the x coordinate.($x, $y, $font, $color, $opacity, $size, $text, $alignment = self::LEFT, $imagickDraw = null)

use kingjerod\ImageTools\Modifier\Text;
use kingjerod\ImageTools\Image\ImageFactory;

$factory = new ImageFactory();
$image = $factory->createEmptyImage(1000, 1000, '#FFF');
$text = new Text(500, 500, "Arial.ttf", "#333", 0.5, 24, "Hello World", Text::CENTER);
$image->modify($text); //Text will be in center of image
$image ->save('/tmp/myImage.png');

Opacity

Changes the opacity of the image. Opacity is expressed from 0->1, 0 being transparent, and 1 being completely opaque. ($opacity)

use kingjerod\ImageTools\Modifier\Opacity;
use kingjerod\ImageTools\Image\ImageFactory;

$factory = new ImageFactory();
$image = $factory->createEmptyImage(1000, 1000, '#FFF');
$opacity = new Opacity(0.8); //Mostly visible
$image->modify($opacity);
$image ->save('/tmp/myImage.png');

Mirror

This mirrors the image over the x/y axis. To have the pixels on the left be flipped onto the right, set $horizontal=true. To have the pixels on the top be flipped onto the bottom, set $vertical=true. ($vertical, $horizontal)

use kingjerod\ImageTools\Modifier\Mirror;
use kingjerod\ImageTools\Image\ImageFactory;

$factory = new ImageFactory();
$image = $factory->createFromLocalFile('/data/image.png');
$mirror= new Mirror(true, false); //Vertical flip
$image->modify($mirror);
$image ->save('/tmp/myImage.png');

Multiple Modifiers

Multiple modifiers can be used to alter an image. The order in which you apply them matters.

use kingjerod\ImageTools\Modifier\Scale;
use kingjerod\ImageTools\Modifier\Crop;
use kingjerod\ImageTools\Modifier\Opacity;
use kingjerod\ImageTools\Image\ImageFactory;

$factory = new ImageFactory();
$image = $factory->createFromLocalFile('/data/image.png');
$opacity = new Opacity(0.8); //Mostly visible
$crop = new Crop(10, 10, 100, 100);
$scale = new Scale(200, 200);
$image->modify($opacity);
$image->modify($crop);
$image->modify($scale);
$image ->save('/tmp/myImage.png');

Writing your own modifiers

Writing your own modifiers is easy. Simply implement the ModifierInterface class and define the modify function:

public function modify(Image $image)