Converting MIME types

The following example creates a very simple transformation to convert any other image type into JPEG:

1. <?php
3. require_once 'tutorial_autoload.php';
5. $tutorialPath = dirname( __FILE__ );
7. $settings = new ezcImageConverterSettings(
8. array(
9. new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ),
10. new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ),
11. )
12. );
14. $converter = new ezcImageConverter( $settings );
16. $converter->createTransformation( 'jpeg', array(), array( 'image/jpeg' ) );
18. try
19. {
20. $converter->transform(
21. 'jpeg',
22. $tutorialPath.'/img/imageconversion_example_01_before.bmp',
23. $tutorialPath.'/img/imageconversion_example_01_after.jpg'
24. );
25. }
26. catch ( ezcImageTransformationException $e)
27. {
28. die( "Error transforming the image: <{$e->getMessage()}>" );
29. }
32. ?>

First, the settings for ezcImageConverter are defined (lines 7 to 12) using ezcImageConverterSettings. Whenever ezcImageConverter is instantiated, it needs to know which handlers are available. The order in the ezcImageHandlerSettings array defines the priority of the handlers. In this case, ezcImageConverter will check if a given filter or conversion can be performed by the GD handler. If not, it will check the ImageMagick handler. On line 14, ezcImageConverter is instantiated using the defined settings.

Line 16 shows how a transformation is created. The first parameter to ezcImageConverter::createTransformation() defines the name of the transformation, while the second parameter would usually contain filters (which are not used here). Instead, just one output MIME type is defined as the third parameter. As a result, this transformation returns images of the type "image/jpeg".

On lines 21 to 24, the transformation is applied. The first parameter to ezcImageConverter::transform() contains the name of the transformation to apply. The second one specifies the file to transform, while the third one specifies the desired output filename. Aside from exceptions of the type ezcBaseFileException, the ezcImageTransformation::transform() method can only throw exceptions of the type ezcImageTransformationException, which we catch here to print out an error message.

The input and output images are shown below:

BMP version (92k)	Converted JPEG (24k)

Simple filtering

The next example shows a transformation that, in addition to the converting to JPEG, uses a filter to scale images:

1. <?php
3. require_once 'tutorial_autoload.php';
5. $tutorialPath = dirname( __FILE__ );
7. $settings = new ezcImageConverterSettings(
8. array(
9. new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ),
10. new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ),
11. )
12. );
14. $converter = new ezcImageConverter( $settings );
16. $filters = array(
17. new ezcImageFilter(
18. 'scale',
19. array(
20. 'width' => 320,
21. 'height' => 240,
22. 'direction' => ezcImageGeometryFilters::SCALE_DOWN,
23. )
24. ),
25. );
27. $converter->createTransformation( 'preview', $filters, array( 'image/jpeg' ) );
29. try
30. {
31. $converter->transform(
32. 'preview',
33. $tutorialPath.'/img/imageconversion_example_02_before.jpg',
34. $tutorialPath.'/img/imageconversion_example_02_after.jpg'
35. );
36. }
37. catch ( ezcImageTransformationException $e)
38. {
39. die( "Error transforming the image: <{$e->getMessage()}>" );
40. }
42. ?>

After instantiating ezcImageConverter, we define the filters to apply. We apply only one filter in this example. Each filter definition must be an instance of ezcImageFilter. The first parameter to the constructor of ezcImageFilter (ezcImageFilter::__construct()) is the name of the filter to use. The second parameter is an array of settings for the filter. The filter name must correspond to a method name for one of the filter interfaces:

• ezcImageGeometryFilters
• ezcImageColorspaceFilters
• ezcImageEffectFilters

The settings array must contain all parameters that the specific filter method expects and the array keys must correspond to the names of the parameters. For example, the scale filter used here is defined in ezcImageGeometryFilters::scale(). The available image handlers support the following filters:

• ezcImageGdFilters

• ezcImageGeometryFilters
• ezcImageColorspaceFilters

• ezcImageImagemagickFilters

• ezcImageGeometryFilters
• ezcImageColorspaceFilters
• ezcImageEffectFilters

The filter definition shown here makes ezcImageConverter scale images to a box of 320x240 pixels. Images will only be scaled if they are larger than the given size, but not if they are already smaller or fit exactly.

The rest of the example is pretty much the same as example 1. To keep the example images web-friendly, we use a JPEG image as the source file here:

Original image (450x246)

Converted image (320x175)

Complex transformations

The next example shows a more advanced transformation and some other features:

1. <?php
3. require_once 'tutorial_autoload.php';
5. $tutorialPath = dirname( __FILE__ );
7. $settings = new ezcImageConverterSettings(
8. array(
9. new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ),
10. new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ),
11. ),
12. array(
13. 'image/gif' => 'image/png',
14. )
15. );
17. $converter = new ezcImageConverter( $settings );
19. $filters = array(
20. new ezcImageFilter(
21. 'scale',
22. array(
23. 'width' => 320,
24. 'height' => 240,
25. 'direction' => ezcImageGeometryFilters::SCALE_DOWN,
26. )
27. ),
28. new ezcImageFilter(
29. 'colorspace',
30. array(
31. 'space' => ezcImageColorspaceFilters::COLORSPACE_GREY,
32. )
33. ),
34. new ezcImageFilter(
35. 'border',
36. array(
37. 'width' => 5,
38. 'color' => array( 240, 240, 240 ),
39. )
40. ),
41. );
43. $converter->createTransformation( 'oldphoto', $filters, array( 'image/jpeg', 'image/png' ) );
45. try
46. {
47. $converter->transform(
48. 'oldphoto',
49. $tutorialPath.'/img/imageconversion_example_03_before.jpg',
50. $tutorialPath.'/img/imageconversion_example_03_after.jpg'
51. );
52. }
53. catch ( ezcImageTransformationException $e)
54. {
55. die( "Error transforming the image: <{$e->getMessage()}>" );
56. }
58. ?>

In this example, there is a second parameter to the constructor of ezcImageConverterSettings::__construct(), which defines explicit conversions between MIME types (line 13). In this case, we define that GIF images should be converted to PNG. When the transformation takes place, it will first check if an explicit conversion has been defined for the input MIME type. If this is the case, the explicit conversion will be performed. If not, the first available output MIME type will be chosen. Note that you have to add the new MIME output type "image/png" to the allowed output types of the transformation (see line 43).

In the transformation definition we define 3 filters. Note that the order of filters is important here. The first filter is "scale" again, after which the colorspace of the image is reduced to greyscale. The last filter adds a 5-pixel border with a near-white grey value to the image.

For this web tutorial, a JPEG image is once again used as the source:

Original image (400x300):

Converted image (330x250):

Adding watermarks

A very convenient filter is the watermark filter, which allows you to place a your personal sign onto an image to ensure your copyright being kept:

1. <?php
3. require_once 'tutorial_autoload.php';
5. $tutorialPath = dirname( __FILE__ );
7. $settings = new ezcImageConverterSettings(
8. array(
9. new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ),
10. new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ),
11. ),
12. array(
13. 'image/gif' => 'image/png',
14. )
15. );
17. $converter = new ezcImageConverter( $settings );
19. $filters = array(
20. new ezcImageFilter(
21. 'watermarkAbsolute',
22. array(
23. 'image' => $tutorialPath . '/img/watermark.png',
24. 'posX' => -52,
25. 'posY' => -25,
26. )
27. )
28. );
30. $converter->createTransformation( 'watermark', $filters, array( 'image/jpeg', 'image/png' ) );
32. try
33. {
34. $converter->transform(
35. 'watermark',
36. $tutorialPath.'/img/imageconversion_example_04_before.jpg',
37. $tutorialPath.'/img/imageconversion_example_04_after.jpg'
38. );
39. }
40. catch ( ezcImageTransformationException $e)
41. {
42. die( "Error transforming the image: <{$e->getMessage()}>" );
43. }
45. ?>

This code snippet creates a simple transformation to place the watermark. The 'image' parameter contains the path to the watermark image, while posX and posY define, where the watermark will be placed on the converted image. The positions are defined from the bottom left corner, so in this case therer will be 10 pixel left between the watermark and the image border.

Original image (without watermark):

Converted image (with watermark):

It is also possible to get the size of the watermark image adjusted on the fly and a second filter is available, which allows to define all values as percentage values, in respect to the destination image.

Creating thumbnails

The following example shows how to create a thumbnail from an image very easily:

1. <?php
3. require_once 'tutorial_autoload.php';
5. $tutorialPath = dirname( __FILE__ );
7. $settings = new ezcImageConverterSettings(
8. array(
9. new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ),
10. new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ),
11. ),
12. array(
13. 'image/gif' => 'image/png',
14. )
15. );
17. $converter = new ezcImageConverter( $settings );
19. $filters = array(
20. new ezcImageFilter(
21. 'filledThumbnail',
22. array(
23. 'width' => 100,
24. 'height' => 100,
25. 'color' => array(
26. 200,
27. 200,
28. 200,
29. ),
30. )
31. )
32. );
34. $converter->createTransformation( 'thumbnail', $filters, array( 'image/jpeg', 'image/png' ) );
36. try
37. {
38. $converter->transform(
39. 'thumbnail',
40. $tutorialPath.'/img/imageconversion_example_05_before.jpg',
41. $tutorialPath.'/img/imageconversion_example_05_after.jpg'
42. );
43. }
44. catch ( ezcImageTransformationException $e)
45. {
46. die( "Error transforming the image: <{$e->getMessage()}>" );
47. }
49. ?>

While there is also a 'croppedThumbnail' filter available, which croppes overhead from the scaled image, this filter fills the overhead from scaling with the given fill color. The image is automatically scaled down to fit the given thumbnail size.

Original image (original size):

Converted image (thumbnail):