ImageConversion/design/design.txt - zetacomponents - Git at Google

 eZ publish Enterprise Component: ImageConversion, Design
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Introduction
 ============

 Purpose of ImageConversion package
 ----------------------------------

 The ImageConversion package will be utilized to convert existing images
 in different ways:

 - Conversion between MIME types (e.g. image/BMP -> image/JPEG,...)
 - Resizing image files (e.g. scaling, cropping,...)
 - Filtering image content (e.g. change of color pallet, add noise,...)

 Current implementation
 ----------------------

 Currently the described functionality is implemented utilizing the following
 classes, inside the library lib/ezimage/:

 eZImageManager
     Controller for the other classes utilized in this library. Handles
     configuration, dispatches the necessary action to the different classes.

 eZImageHandler
     Baseclass for image handlers. Provides common methods between image
     handlers and defines a common API.

 eZImageGDHandler
     Image handler implementation for ext/GD2. Extends eZImageHandler.

 eZImageShellHandler
     Image handler implementation for Image Magick. Extends eZImageHandler.

 General notes
 -------------

 The idea behind the design chosen for this class is definitly the right one,
 but it could have been much more modulized to gain a more clean code layout
 and more flexibillities. Beside that, the user interface seems pretty unclear
 and needs some general revision.

 Requirenments
 =============

 Design goals
 ------------

 Several goals have to be kept in mind while re-designing the implemented
 functionality:

 - Do not reduce possibilities, but enhance them.
 - Create a more clean user interface and enhance usabillity.
 - Raise flexibillity regarding backends and filter definition.
 - Keep the code fast.

 Detailed requirenments
 ----------------------

 The ImageConversion component allows to deal with quite complex image
 conversions in an easy to use ways. Beside that it handles automatic
 conversions, if necessary, like converting incoming image formats to a range
 of range of wanted output formats. This paragraph tries to summarize, what
 exactly has to be done by ImageConversion:

 Conversion between image formats
     In general, ImageConversion should be able to convert images between MIME
     types utilizing it's backends. Conversions must be globally defineable to
     allow forcing of conversions (like for GIF -> PNG). Since some image
     formats have special cases, in which a conversion is not possible (like
     animated GIF), it must be possible to define exceptions for conversion.
     Beside the global conversion, it has to be possible, to convert images
     explicitly. Format conversions can ba parameterized (like the compression
     factor for JPEG, the colorpallet for GIF,...). The conversions possible
     depend on the image handlers available.


 Filtering of image contents
     Filtering of images can have a lot of incarnation in this case:

         Geometry manipulation
             down/up only, keep/change ratio, with/height only,...


         Attribute manipulation (was: colorspace)
             transform color space, change quality,...


         Content manipulation
             adding noise, swirrling, adding borders...


     Which filters are available depends highly on the available image
     handlers, their version and maybe other factors in respect to them (PHP
     version,...).

     Every filter can have a variaty of options and settings to influence its
     behaviour. Options and settings maybe completly different between filters.


 Definition of image formats
     To reduce the overhead of manually defining, which filters have to be
     applied to an image to achieve a certain goal (like "create a
     thumbnail", "create a preview", "make it look like an old photo",...), the
     definition of different image formats should be allowed. A format
     definition can include all of the above stated transformations.

     Beside that, it has to be possible to define, that a format is based on
     another format (like a thumbnail should be created from a preview, to
     reduce conversion ammount). If a format references another format, this
     reference format will be created first (if it does not exist) and
     conversion to the target format will take place afterwards. This allows to
     define a tree of format conversions. Every node of the tree should be
     saved for later utilization.

     Currently, this formats are called aliases.

 Design
 ======

 ezcImageConverter
 -----------------

 The main class of the component is the ezcImageConverter, which dispatches the
 actions performed on images, holds the ezcImageHandler's (which actually perform
 the actions) and manages / defines the ezcImageTransformations which hold
 conversions and filters.

 Since 1 filter/conversion can be performed by several ezcImageHandler's, the
 manager has a preference list, to determine, which ezcImageHandler to take for
 a conversion.

 ezcImageHandler
 ---------------

 This interface defines how the abstraction class for an image handler looks
 like. ezcImageHandler's utilize a given backend to perform conversion and
 filtering (using ezcImageFilter's). A ezcImageHandler knows by hisself, which
 filters he implements. The manager will ask it for supported filters to get an
 overview, which filters exist.

 To avoid reopening an image file for every operation the ezcImageHandler has
 load()/save() methods. An image must be saved before another ezcImageHandler
 can perform his actions on it.

 ezcImageFilters
 ---------------

 [[[------UPDATE NEEDED HERE!--------]]]

 This class implements a storage container for filters to keep them better
 consistant than an array could do. Filters are created by the ezcImageManager
 or directly through a ezcImageHandler. An ezcImageFilter knows, to which
 handler he belongs and dispatches itself to the right handler, when applied.

 ezcImageTransformation
 ----------------------

 ezcImageTransformation's abstract image types to allow the easy combination of
 conversions between MIME types and filters which are necessary to get a desired image type.
 For conversions only the target MIME type is necessary.

 ezcImageTransformation's will be created on the fly, when the user requests them and not
 during startup of the manager. A created ezcImageTransformation will be cached in the
 manager for possible later use. Same applies to the filters utilized by the
 ezcImageTransformation.

 Example 1
 ^^^^^^^^^

 ======================  =======================
 Transformation:         Preview
 MIME:                   image/JPEG

                         image/PNG
 Filters:                scale 400x400
 ======================  =======================

 Example 2
 ^^^^^^^^^

 ======================  =======================
 Transformation:         Thumbnail
 MIME:                   image/JPEG

                         image/PNG
 Filters:                scale 100x100

                         colorspace grey
 ======================  =======================

 Will scale down the image to 100x100 pixels and convert it to greyscale.

 Example 3
 ^^^^^^^^^

 ======================  =======================
 Transformation:         OldPhotos
 MIME:                   image/JPEG
 Filters:                colorspace grey

                         border 3
 ======================  =======================

 Will convert the inserted image to image/JPEG, reduce the colorspace to
 greyscale and add a border of 3 pixel.

 ^L
 ..
 Local Variables:
 mode: rst
 indent-tabs-mode: nil
 sentence-end-double-space: t
 fill-column: 79
 End:
 vim: et syn=rst tw=79 wrap
	eZ publish Enterprise Component: ImageConversion, Design
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	Introduction
	============

	Purpose of ImageConversion package
	----------------------------------

	The ImageConversion package will be utilized to convert existing images
	in different ways:

	- Conversion between MIME types (e.g. image/BMP -> image/JPEG,...)
	- Resizing image files (e.g. scaling, cropping,...)
	- Filtering image content (e.g. change of color pallet, add noise,...)

	Current implementation
	----------------------

	Currently the described functionality is implemented utilizing the following
	classes, inside the library lib/ezimage/:

	eZImageManager
	Controller for the other classes utilized in this library. Handles
	configuration, dispatches the necessary action to the different classes.

	eZImageHandler
	Baseclass for image handlers. Provides common methods between image
	handlers and defines a common API.

	eZImageGDHandler
	Image handler implementation for ext/GD2. Extends eZImageHandler.

	eZImageShellHandler
	Image handler implementation for Image Magick. Extends eZImageHandler.

	General notes
	-------------

	The idea behind the design chosen for this class is definitly the right one,
	but it could have been much more modulized to gain a more clean code layout
	and more flexibillities. Beside that, the user interface seems pretty unclear
	and needs some general revision.

	Requirenments
	=============

	Design goals
	------------

	Several goals have to be kept in mind while re-designing the implemented
	functionality:

	- Do not reduce possibilities, but enhance them.
	- Create a more clean user interface and enhance usabillity.
	- Raise flexibillity regarding backends and filter definition.
	- Keep the code fast.

	Detailed requirenments
	----------------------

	The ImageConversion component allows to deal with quite complex image
	conversions in an easy to use ways. Beside that it handles automatic
	conversions, if necessary, like converting incoming image formats to a range
	of range of wanted output formats. This paragraph tries to summarize, what
	exactly has to be done by ImageConversion:

	Conversion between image formats
	In general, ImageConversion should be able to convert images between MIME
	types utilizing it's backends. Conversions must be globally defineable to
	allow forcing of conversions (like for GIF -> PNG). Since some image
	formats have special cases, in which a conversion is not possible (like
	animated GIF), it must be possible to define exceptions for conversion.
	Beside the global conversion, it has to be possible, to convert images
	explicitly. Format conversions can ba parameterized (like the compression
	factor for JPEG, the colorpallet for GIF,...). The conversions possible
	depend on the image handlers available.


	Filtering of image contents
	Filtering of images can have a lot of incarnation in this case:

	Geometry manipulation
	down/up only, keep/change ratio, with/height only,...


	Attribute manipulation (was: colorspace)
	transform color space, change quality,...


	Content manipulation
	adding noise, swirrling, adding borders...


	Which filters are available depends highly on the available image
	handlers, their version and maybe other factors in respect to them (PHP
	version,...).

	Every filter can have a variaty of options and settings to influence its
	behaviour. Options and settings maybe completly different between filters.


	Definition of image formats
	To reduce the overhead of manually defining, which filters have to be
	applied to an image to achieve a certain goal (like "create a
	thumbnail", "create a preview", "make it look like an old photo",...), the
	definition of different image formats should be allowed. A format
	definition can include all of the above stated transformations.

	Beside that, it has to be possible to define, that a format is based on
	another format (like a thumbnail should be created from a preview, to
	reduce conversion ammount). If a format references another format, this
	reference format will be created first (if it does not exist) and
	conversion to the target format will take place afterwards. This allows to
	define a tree of format conversions. Every node of the tree should be
	saved for later utilization.

	Currently, this formats are called aliases.

	Design
	======

	ezcImageConverter
	-----------------

	The main class of the component is the ezcImageConverter, which dispatches the
	actions performed on images, holds the ezcImageHandler's (which actually perform
	the actions) and manages / defines the ezcImageTransformations which hold
	conversions and filters.

	Since 1 filter/conversion can be performed by several ezcImageHandler's, the
	manager has a preference list, to determine, which ezcImageHandler to take for
	a conversion.

	ezcImageHandler
	---------------

	This interface defines how the abstraction class for an image handler looks
	like. ezcImageHandler's utilize a given backend to perform conversion and
	filtering (using ezcImageFilter's). A ezcImageHandler knows by hisself, which
	filters he implements. The manager will ask it for supported filters to get an
	overview, which filters exist.

	To avoid reopening an image file for every operation the ezcImageHandler has
	load()/save() methods. An image must be saved before another ezcImageHandler
	can perform his actions on it.

	ezcImageFilters
	---------------

	[[[------UPDATE NEEDED HERE!--------]]]

	This class implements a storage container for filters to keep them better
	consistant than an array could do. Filters are created by the ezcImageManager
	or directly through a ezcImageHandler. An ezcImageFilter knows, to which
	handler he belongs and dispatches itself to the right handler, when applied.

	ezcImageTransformation
	----------------------

	ezcImageTransformation's abstract image types to allow the easy combination of
	conversions between MIME types and filters which are necessary to get a desired image type.
	For conversions only the target MIME type is necessary.

	ezcImageTransformation's will be created on the fly, when the user requests them and not
	during startup of the manager. A created ezcImageTransformation will be cached in the
	manager for possible later use. Same applies to the filters utilized by the
	ezcImageTransformation.

	Example 1
	^^^^^^^^^

	====================== =======================
	Transformation: Preview
	MIME: image/JPEG

	image/PNG
	Filters: scale 400x400
	====================== =======================

	Example 2
	^^^^^^^^^

	====================== =======================
	Transformation: Thumbnail
	MIME: image/JPEG

	image/PNG
	Filters: scale 100x100

	colorspace grey
	====================== =======================

	Will scale down the image to 100x100 pixels and convert it to greyscale.

	Example 3
	^^^^^^^^^

	====================== =======================
	Transformation: OldPhotos
	MIME: image/JPEG
	Filters: colorspace grey

	border 3
	====================== =======================

	Will convert the inserted image to image/JPEG, reduce the colorspace to
	greyscale and add a border of 3 pixel.

	^L
	..
	Local Variables:
	mode: rst
	indent-tabs-mode: nil
	sentence-end-double-space: t
	fill-column: 79
	End:
	vim: et syn=rst tw=79 wrap