eZ Components - ImageConversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. contents:: Table of Contents
:depth: 2
Introduction
============
The ImageConversion component provides image manipulation tools. It
enables you to perform filter actions (such as scaling, changing the
colorspace, adding a swirl effect) and to convert between different MIME image
types. Filters and conversions are grouped as
"transformations", which can be globally configured and accessed from anywhere
in the application. Conversions and filters can be performed through different
handlers (currently supported are PHP's GD extension and the external ImageMagick
program). ImageConversion is capable of automatically selecting an appropriate
handler. You can also set handler priorities.
Class overview
==============
This section gives you an overview of the main classes.
ezcImageConverter
This is the main class that collects all transformations, communicates with
the handlers and applies filters and conversions.
ezcImageFilter
This class is used to represent the configuration of a filter.
ezcImageTransformation
A transformation can contain any number of filters. It also specifies which
output MIME types are acceptable for the transformation.
Usage
=====
Converting MIME types
---------------------
The following example creates a very simple transformation to convert any other
image type into JPEG:
.. include:: tutorial_example_01_simpleconvert.php
:literal:
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:
=================== ====================
|example_01_before| |example_01_after|
BMP version (92k) Converted JPEG (24k)
=================== ====================
.. |example_01_before| image:: img/imageconversion_example_01_before.bmp
:alt: Original BMP (92k).
.. |example_01_after| image:: img/imageconversion_example_01_after.jpg
:alt: 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:
.. include:: tutorial_example_02_simpletrans.php
:literal:
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)
++++++++++++++++++++++++
.. image:: img/imageconversion_example_02_before.jpg
:alt: Original JPEG image.
Converted image (320x175)
+++++++++++++++++++++++++
.. image:: img/imageconversion_example_02_after.jpg
:alt: Converted JPEG image.
Complex transformations
-----------------------
The next example shows a more advanced transformation and some other features:
.. include:: tutorial_example_03_complextrans.php
:literal:
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):
+++++++++++++++++++++++++
.. image:: img/imageconversion_example_03_before.jpg
:alt: Original JPEG image.
Converted image (330x250):
++++++++++++++++++++++++++
.. image:: img/imageconversion_example_03_after.jpg
:alt: Converted JPEG image.
.. _`downloaded here`: img/imageconversion_example_03.bmp
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:
.. include:: tutorial_example_04_watermark.php
:literal:
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):
+++++++++++++++++++++++++++++++++++
.. image:: img/imageconversion_example_04_before.jpg
:alt: Original JPEG image without watermark.
Converted image (with watermark):
+++++++++++++++++++++++++++++++++
.. image:: img/imageconversion_example_04_after.jpg
:alt: Converted JPEG 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:
.. include:: tutorial_example_05_thumbnail.php
:literal:
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):
+++++++++++++++++++++++++++++++
.. image:: img/imageconversion_example_05_before.jpg
:alt: Original JPEG image without watermark.
Converted image (thumbnail):
++++++++++++++++++++++++++++
.. image:: img/imageconversion_example_05_after.jpg
:alt: Converted JPEG image with watermark.
Troubleshooting
===============
In some cases, you might experience troubles, which result from PHP or one of
the drivers. Common problems and solutions are presented below.
Corrupt JPEG files
------------------
Some JPEG files contain small amounts of corrupt data, which might not result
in problems when viewing these images with your favorite image viewer. However,
GD and ImageMagick by default issue errors for these images. The
ImageConversion component throws an ezcImageFileNotProcessable exception in
this case.
You can avoid this issue in the GD driver, by setting the php.ini directive
"gd.jpeg_ignore_warning" to true. This can either happen in your php.ini
directly or by using the following code in your application, before you attempt
to load any image::
<?php
ini_set( "gd.jpeg_ignore_warning", true );
?>
However, it is not recommended to deal with corrupt images like this, since the
results are unpredictable. There is a good chance that the converted image will
be OK, but it is not guaranteed.
..
Local Variables:
mode: rst
fill-column: 79
End:
vim: et syn=rst tw=79
