Author: Tobias Schlitt Date: 2006-01-27 10:14:41 +0100 (Fri, 27 Jan 2006) New Revision: 2048
Log: - Added tutorial. # Please review! Added: packages/ImageConversion/trunk/docs/img/ packages/ImageConversion/trunk/docs/img/imageconversion_example_01_after.jpg packages/ImageConversion/trunk/docs/img/imageconversion_example_01_before.bmp packages/ImageConversion/trunk/docs/img/imageconversion_example_02_after.jpg packages/ImageConversion/trunk/docs/img/imageconversion_example_02_before.jpg packages/ImageConversion/trunk/docs/img/imageconversion_example_03_after.jpg packages/ImageConversion/trunk/docs/img/imageconversion_example_03_before.jpg packages/ImageConversion/trunk/docs/tutorial.txt packages/ImageConversion/trunk/docs/tutorial_autoload.php packages/ImageConversion/trunk/docs/tutorial_example_01.php packages/ImageConversion/trunk/docs/tutorial_example_02.php packages/ImageConversion/trunk/docs/tutorial_example_03.php Added: packages/ImageConversion/trunk/docs/img/imageconversion_example_01_after.jpg =================================================================== (Binary files differ) Property changes on: packages/ImageConversion/trunk/docs/img/imageconversion_example_01_after.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: packages/ImageConversion/trunk/docs/img/imageconversion_example_01_before.bmp =================================================================== (Binary files differ) Property changes on: packages/ImageConversion/trunk/docs/img/imageconversion_example_01_before.bmp ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: packages/ImageConversion/trunk/docs/img/imageconversion_example_02_after.jpg =================================================================== (Binary files differ) Property changes on: packages/ImageConversion/trunk/docs/img/imageconversion_example_02_after.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: packages/ImageConversion/trunk/docs/img/imageconversion_example_02_before.jpg =================================================================== (Binary files differ) Property changes on: packages/ImageConversion/trunk/docs/img/imageconversion_example_02_before.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: packages/ImageConversion/trunk/docs/img/imageconversion_example_03_after.jpg =================================================================== (Binary files differ) Property changes on: packages/ImageConversion/trunk/docs/img/imageconversion_example_03_after.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: packages/ImageConversion/trunk/docs/img/imageconversion_example_03_before.jpg =================================================================== (Binary files differ) Property changes on: packages/ImageConversion/trunk/docs/img/imageconversion_example_03_before.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: packages/ImageConversion/trunk/docs/tutorial.txt =================================================================== --- packages/ImageConversion/trunk/docs/tutorial.txt 2006-01-26 16:07:25 UTC (rev 2047) +++ packages/ImageConversion/trunk/docs/tutorial.txt 2006-01-27 09:14:41 UTC (rev 2048) @@ -0,0 +1,208 @@ +eZ components - ImageConversion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. contents:: Table of Contents + :depth: 2 + +Introduction +============ + +The ImageConversion component provides image manipulation facilities. It +enables you to perform filter actions (filters are e.g. scaling, change of the +colorspace, adding a swirl effect) and to convert between different MIME types +of images (so called conversions). Filters and conversions are collected in +"transformations", which can be globally configured and accessed from anywhere +in the program. Conversions and filters can be performed through different +handlers (currently supported PHP's GD extension and the external ImageMagick +program). Image conversion is capable to select a fitting handler +automatically, while you can select handlers to be prioritized. + +Class overview +============== + +This section gives you an overview on all classes, that are intended to be +used directly. + +ezcImageConverter + This is the main class, that collects all transformations, communicates with + the handlers and applies filters and conversions. + +ezcImageFilter + This struct is used to represent the configuration of a filter. + +ezcImageTransformation + A transformation can contain any number of filters. Beside that, it + specifies, which output MIME types are acceptable by the transformation, so + that only these MIME types are output. + + +Installation +============ + +This tutorial assumes that you have set-up an eZ components environment. For +information on how to do this, please refer to the `Components Introduction`_. + +.. _`Components Introduction`: http://ez.no/community/articles/an_introduction_to_ez_components + + +Usage +===== + +Converting MIME types +--------------------- + +The following example creates a very simple transformation to convert any other +image type into JPEG: + +.. include:: tutorial_example_01.php + :literal: + +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 1 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 on gives the file to transform, while the +third one specifies the filename to save the transformed image to. Beside +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: + +=================== ==================== +|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 conversion to +JPEG, has a filter to scale images: + +.. include:: tutorial_example_02.php + :literal: + +After instantiating the ezcImageConverter, a definition for filters to apply in +a conversion is created. Only 1 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) +++++++++++++++++++++++++ + +.. 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. + +.. _`source EPS`: img/imageconversion_example_02.eps + +Complex transformations +----------------------- + +The next example shows a more advanced transformation in combination with some +other features: + +.. include:: tutorial_example_03.php + :literal: + +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, this time. Note, that the +order of the filter 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): ++++++++++++++++++++++++++ + +.. 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 + +More Information +================ + +For more information, see the ezcImageConverter API reference. + + +.. + Local Variables: + mode: rst + fill-column: 79 + End: + vim: et syn=rst tw=79 Property changes on: packages/ImageConversion/trunk/docs/tutorial.txt ___________________________________________________________________ Name: svn:eol-style + native Added: packages/ImageConversion/trunk/docs/tutorial_autoload.php =================================================================== --- packages/ImageConversion/trunk/docs/tutorial_autoload.php 2006-01-26 16:07:25 UTC (rev 2047) +++ packages/ImageConversion/trunk/docs/tutorial_autoload.php 2006-01-27 09:14:41 UTC (rev 2048) @@ -0,0 +1,17 @@ +<?php + +require_once 'Base/trunk/src/base.php'; + +/** + * Autoload ezc classes + * + * @param string $class_name + */ +function __autoload( $class_name ) +{ + if ( ezcBase::autoload( $class_name ) ) + { + return; + } +} +?> Property changes on: packages/ImageConversion/trunk/docs/tutorial_autoload.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/ImageConversion/trunk/docs/tutorial_example_01.php =================================================================== --- packages/ImageConversion/trunk/docs/tutorial_example_01.php 2006-01-26 16:07:25 UTC (rev 2047) +++ packages/ImageConversion/trunk/docs/tutorial_example_01.php 2006-01-27 09:14:41 UTC (rev 2048) @@ -0,0 +1,32 @@ +<?php + +require_once 'tutorial_autoload.php'; + +$tutorialPath = dirname( __FILE__ ); + +$settings = new ezcImageConverterSettings( + array( + new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ), + new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ), + ) +); + +$converter = new ezcImageConverter( $settings ); + +$converter->createTransformation( 'jpeg', array(), array( 'image/jpeg' ) ); + +try +{ + $converter->transform( + 'jpeg', + $tutorialPath.'/img/imageconversion_example_01_before.bmp', + $tutorialPath.'/img/imageconversion_example_01_after.jpg' + ); +} +catch ( ezcImageTransformationException $e) +{ + die( "Error transforming the image: <{$e->getMessage()}>" ); +} + + +?> Property changes on: packages/ImageConversion/trunk/docs/tutorial_example_01.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/ImageConversion/trunk/docs/tutorial_example_02.php =================================================================== --- packages/ImageConversion/trunk/docs/tutorial_example_02.php 2006-01-26 16:07:25 UTC (rev 2047) +++ packages/ImageConversion/trunk/docs/tutorial_example_02.php 2006-01-27 09:14:41 UTC (rev 2048) @@ -0,0 +1,42 @@ +<?php + +require_once 'tutorial_autoload.php'; + +$tutorialPath = dirname( __FILE__ ); + +$settings = new ezcImageConverterSettings( + array( + new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ), + new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ), + ) +); + +$converter = new ezcImageConverter( $settings ); + +$filters = array( + new ezcImageFilter( + 'scale', + array( + 'width' => 320, + 'height' => 240, + 'direction' => ezcImageGeometryFilters::SCALE_DOWN, + ) + ), +); + +$converter->createTransformation( 'preview', $filters, array( 'image/jpeg' ) ); + +try +{ + $converter->transform( + 'preview', + $tutorialPath.'/img/imageconversion_example_02_before.jpg', + $tutorialPath.'/img/imageconversion_example_02_after.jpg' + ); +} +catch ( ezcImageTransformationException $e) +{ + die( "Error transforming the image: <{$e->getMessage()}>" ); +} + +?> Property changes on: packages/ImageConversion/trunk/docs/tutorial_example_02.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/ImageConversion/trunk/docs/tutorial_example_03.php =================================================================== --- packages/ImageConversion/trunk/docs/tutorial_example_03.php 2006-01-26 16:07:25 UTC (rev 2047) +++ packages/ImageConversion/trunk/docs/tutorial_example_03.php 2006-01-27 09:14:41 UTC (rev 2048) @@ -0,0 +1,58 @@ +<?php + +require_once 'tutorial_autoload.php'; + +$tutorialPath = dirname( __FILE__ ); + +$settings = new ezcImageConverterSettings( + array( + new ezcImageHandlerSettings( 'GD', 'ezcImageGdHandler' ), + new ezcImageHandlerSettings( 'ImageMagick', 'ezcImageImagemagickHandler' ), + ), + array( + 'image/gif' => 'image/png', + ) +); + +$converter = new ezcImageConverter( $settings ); + +$filters = array( + new ezcImageFilter( + 'scale', + array( + 'width' => 320, + 'height' => 240, + 'direction' => ezcImageGeometryFilters::SCALE_DOWN, + ) + ), + new ezcImageFilter( + 'colorspace', + array( + 'space' => ezcImageColorspaceFilters::COLORSPACE_GREY, + ) + ), + new ezcImageFilter( + 'border', + array( + 'width' => 5, + 'color' => array( 240, 240, 240 ), + ) + ), +); + +$converter->createTransformation( 'oldphoto', $filters, array( 'image/jpeg', 'image/png' ) ); + +try +{ + $converter->transform( + 'oldphoto', + $tutorialPath.'/img/imageconversion_example_03_before.jpg', + $tutorialPath.'/img/imageconversion_example_03_after.jpg' + ); +} +catch ( ezcImageTransformationException $e) +{ + die( "Error transforming the image: <{$e->getMessage()}>" ); +} + +?> Property changes on: packages/ImageConversion/trunk/docs/tutorial_example_03.php ___________________________________________________________________ Name: svn:eol-style + native -- svn-components mailing list [email protected] http://lists.ez.no/mailman/listinfo/svn-components
