Converting MIME types

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

  1. <?php
  2. 
  3. require_once 'tutorial_autoload.php';
  4. 
  5. $tutorialPath = dirname( __FILE__ );
  6. 
  7. $settings = new ezcImageConverterSettings(
  8.     array(
  9.         new ezcImageHandlerSettings( 'GD',          'ezcImageGdHandler' ),
 10.         new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ),
 11.     )
 12. );
 13. 
 14. $converter = new ezcImageConverter( $settings );
 15. 
 16. $converter->createTransformation( 'jpeg', array(), array( 'image/jpeg' ) );
 17. 
 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. }
 30. 
 31. 
 32. ?>

First the settings for the ezcImageConverter are defined (line 7-12), using the ezcImageConverterSettings struct. Whenever an ezcImageConverter is instantiated, it needs to know which handlers are available. The order in the array of ezcImageHandlerSettings defines the priority of the handlers. In this case, the 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 the ezcImageConverter is instantiated using the defined settings.

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

On the lines 21-24 you see how the transformation is applied. The first parameter to ezcImageConverter::transform() contains the name of the transformation to apply. The second one gives the file to transform, while the third one specifies the filename to save the transformed image to. Besides exceptions of the type ezcBaseFileException, the ezcImageTransformation::transform() method may only throw exceptions of the type ezcImageTransformationException, which we catch here to print out some 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 conversion to JPEG, has a filter to scale images:

  1. <?php
  2. 
  3. require_once 'tutorial_autoload.php';
  4. 
  5. $tutorialPath = dirname( __FILE__ );
  6. 
  7. $settings = new ezcImageConverterSettings(
  8.     array(
  9.         new ezcImageHandlerSettings( 'GD',          'ezcImageGdHandler' ),
 10.         new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ),
 11.     )
 12. );
 13. 
 14. $converter = new ezcImageConverter( $settings );
 15. 
 16. $filters = array( 
 17.     new ezcImageFilter( 
 18.         'scale',
 19.         array( 
 20.             'width'     => 320,
 21.             'height'    => 240,
 22.             'direction' => ezcImageGeometryFilters::SCALE_DOWN,
 23.         )
 24.     ),
 25. );
 26. 
 27. $converter->createTransformation( 'preview', $filters, array( 'image/jpeg' ) );
 28. 
 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. }
 41. 
 42. ?>

After instantiating the ezcImageConverter, a definition for filters to apply in a conversion is created. Only one filter is contained 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 on one of the filter interfaces:

• ezcImageGeometryFilters
• ezcImageColorspaceFilters
• ezcImageEffectFilters

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

• ezcImageGdFilters

• ezcImageGeometryFilters
• ezcImageColorspaceFilters

• ezcImageImagemagickFilters

• ezcImageGeometryFilters
• ezcImageColorspaceFilters
• ezcImageEffectFilters

The filter definition shown here makes ezcImageConverter scale images to fit in a box of 320x240 pixel. Images will only be scaled, if they are larger than the given box, 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 viewable on the web, 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 in combination with some other features:

  1. <?php
  2. 
  3. require_once 'tutorial_autoload.php';
  4. 
  5. $tutorialPath = dirname( __FILE__ );
  6. 
  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. );
 16. 
 17. $converter = new ezcImageConverter( $settings );
 18. 
 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. );
 42. 
 43. $converter->createTransformation( 'oldphoto', $filters, array( 'image/jpeg', 'image/png' ) );
 44. 
 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. }
 57. 
 58. ?>

In this example you see 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, this 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, too (line 43).

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

For convenience of viewing this tutorial, here a JPEG image is used as the source again:

Original image (400x300):

Converted image (330x250):