You are here

README.txt in ImageCache Actions 7

README for the Imagecache Actions Drupal module
-----------------------------------------------

Project page: https://drupal.org/project/imagecache_actions

Current and past maintainers for Imagecache Actions:
- dman (https://drupal.org/user/33240)
- sidneyshan (https://drupal.org/user/652426)
- fietserwin (https://drupal.org/user/750928)


Release notes for 7.x-1.x-dev
-----------------------------
- Clear all caches after updating.


Release notes for 7.x-1.4
-------------------------
- This release supports image labels as introduced by Drupal 7.23.
- See CHANGELOG.txt for a full overview of changes.


Release notes for 7.x-1.1
-------------------------
- If you use the module:// notation anywhere in an image effect, you must now
  install the System Stream Wrapper module
  (https://drupal.org/project/system_stream_wrapper).
- Clear the cache after updating.


Release notes for 7.x-1.0
-------------------------
- Clear the (registry) cache after installing or updating to 7.x-1.0.
- If you use custom actions, run update.php.
- If you use custom actions, be sure to enable the 'PHP filter' module and give
  image style editors that may create custom actions the 'use PHP for settings'
  permission. The module must also be enabled on image creation.
- If you use custom actions, please read the README.txt from that sub-module to
  find out about how information and resources are available to you. You will
  probably have to change your code snippets.
- If you use effects that use files (mask, overlays, underlays, text fonts),
  check the way they are specified. From 7.x-1.0 on, you have to specify the
  location using one of the schemes private://, public://, module:// or
  temporary://. If no scheme is specified, the file is searched for as is, thus
  relative to the current directory or as an absolute path.
- Effects that use the transparency layer (e.g. mask, rounded corners) do not
  automatically convert to PNG anymore. Use the "Change file format" for that.
- There's no upgrade from D6. You will have to recreate your styles manually.

Warning:
  Ongoing development in the area of e.g. making the effects more consistent,
  adding and/or removing parameters or redefining their meaning, might cause
  backward incompatibilities between future versions and the current version.
  Thus, we cannot and do not guarantee backwards compatibility or automatic
  upgrade paths for future versions.


Introduction
------------
The Imagecache Actions module provides a suite of additional image effects that
can be added to image styles. Image styles let you create derivations of images
by applying (a series of) effect(s) to it. Think of resizing, desaturating,
masking, etc.

Furthermore, imagecache_actions extends the administrative interface for image
styles by providing additional features. It does so in the "Image styles admin"
sub module.

The additional effects that Imagecache Actions provides include:
- Watermark: place a image with transparency anywhere over a source picture.
- Overlay: add photo-corners etc to the image
- Text overlay: add e.g. a copyright notice to your image.
- Color-shifting: colorize images.
- Brighten/Darken.
- Alpha blending: use a gray scale image to define the transparency layer of an
  image.
- Canvas manipulation: resize the canvas and add a background color or image.
- File Format switcher: if you need transparency in JPGs, make them PNG. If your
  PNG thumbnails are 30K each, save them as JPGs.
- Rounded corners.
- TODO: complete list, check short descriptions

These effects are grouped in sub-modules. Just enable the ones you want to use.
TODO: list sub-modules and their sets of effects.

Imagecache Actions supports both the GD toolkit from Drupal core and the
Imagemagick toolkit. However, please note that Imagemagick support is not yet
complete. Please file an issue if you encounter problems in using Imagemagick.


What is imagecache_action not?
------------------------------
Imagecache Actions does not provide a new UI or new menu items. It hooks into
the already existing image styles system (from Drupal core). See
https://drupal.org/documentation/modules/image for more information about
working with images.


A note about the name of this module
------------------------------------
Image styles are part of Drupal 7 core and are the successor of the Drupal 6
imagecache module. In Drupal 6 image styles were called (imagecache) presets and
the separate effects that made up a style were called (imagecache) actions. In
porting to D7, that name has not been changed (yet).


Which toolkit to use?
---------------------
Personally, I (fietserwin) prefer the imagemagick toolkit:
- It is better in anti-aliasing. Try to rotate an image using both toolkits and
  you will see what I mean.
- It does not execute in the PHP memory space, so is not restricted by the
  memory_limit PHP setting.
- The GD toolkit will, at least on my Windows configuration, keep the font file
  open after a text operation, so you cannot delete, move or rename it anymore.

On the other hand: the GD toolkit is always available (in the correct version),
whereas imagemagick is not always present on shared hosting or may be present in
an antique version that might give problems.

Please note that effects may give different results depending on the
toolkit used.

Please also note that a 3rd image toolkit exists:
  Imagick (https://www.drupal.org/project/imagick)
This toolkit uses the Imagick extension and thus does not call the ImageMagick
binaries directly. However our module does not implement the toolkit specific
parts for the effects we provide for the Imagick toolkit, but the Imagick
toolkit comes with its own set of effects that partly covers our effects. So,
depending on the effects you require it may be a replacement for both our module
and the Imagemagick module or the core GD toolkit.

Hard Dependencies
-----------------
- Image module from Drupal core

At least 1 of the available image toolkits:
- GD toolkit from Drupal core.
- Imagemagick toolkit: https://drupal.org/project/imagemagick.


Soft Dependencies
-----------------
- System stream wrapper (https://drupal.org/project/system_stream_wrapper)
- Remote stream wrapper (https://drupal.org/project/remote_stream_wrapper)
These modules provide additional stream wrappers. Especially the system stream
wrapper is very handy as it provides, among others, a module:// and theme://
wrapper.


Installing
----------
As usual.


Usage
-----
After enabling the module:
- Assure that the Image module from core is enabled.
- Configure your toolkit and its settings at admin/config/media/image-toolkit.
- Define image styles at admin/config/media/image-styles and add 1 or more
  effects as defined by this module
- Use the image styles via e.g. the formatters of image fields.


Upgrading from D6
-----------------
There's no upgrade path defined for sites upgrading from D6 to D7. This means
that you will have to manually redefine your D6 imagecache presets as D7 image
styles. Note that actually an upgrade path would have to be defined by the
imagecache module, not this imagecache actions module. However, as there is no
D7 version of imagecache that provides an upgrade, users may post an upgrade
function to the issue queue and we will incorporate it.


Backwards compatibility
-----------------------
Future releases will not be guaranteed to be backwards compatible. Implementing
Imagemagick support e.g. might give unforeseen problems that can only be solved
by changing the details of what an effect does. We will document these kind of
incompatibilities in the changelog and the release notes.


File form fields
----------------
A number of effects have a file form field where the editor can define a file
name to use. This can be e.g. for overlays, masks or fonts. The file name should
be defined using either:
- 1 of the (enabled) scheme's:
  * public://
  * private:// Preferred for site specific masks, overlays, etc, that do not
    need to be shared publicly.
  * temporary:// Unlikely to be useful, but supported anyway as all schemes are
    supported.
  * module:// Introduced by the system stream wrapper module and preferred for
    module provided resources.
  * theme:// idem.
  * profile:// idem.
  * library:// idem.
- A relative (to the current directory, probably Drupal root) or absolute path.


Support
-------
Via the issue queue of this project at Drupal.org.


Known problems
--------------
These are better documented in the issue queue, but might be listed here (as
well).

- Underlay does not work in imagemagick if the dimensions of both images are not
  equal. As a workaround first add a canvas effect with a fully transparent
  background.
- Underlay/overlay: keywords in the x and y offset fields do not work.
- Underlay does still display a message about Imagemagick not being supported.
- Brightness values outside the -250 .. 250 range are accepted.
- Check color fields that allow a transparency component or allow to be empty to
  specify fully transparent.

Known problems: Imagemagick
---------------------------
- Define canvas using offsets may bot work on older versions. We have an error
  report for version 6.5.4.7 (2009-07) (https://drupal.org/node/888644).

File

README.txt
View source
  1. README for the Imagecache Actions Drupal module
  2. -----------------------------------------------
  3. Project page: https://drupal.org/project/imagecache_actions
  4. Current and past maintainers for Imagecache Actions:
  5. - dman (https://drupal.org/user/33240)
  6. - sidneyshan (https://drupal.org/user/652426)
  7. - fietserwin (https://drupal.org/user/750928)
  8. Release notes for 7.x-1.x-dev
  9. -----------------------------
  10. - Clear all caches after updating.
  11. Release notes for 7.x-1.4
  12. -------------------------
  13. - This release supports image labels as introduced by Drupal 7.23.
  14. - See CHANGELOG.txt for a full overview of changes.
  15. Release notes for 7.x-1.1
  16. -------------------------
  17. - If you use the module:// notation anywhere in an image effect, you must now
  18. install the System Stream Wrapper module
  19. (https://drupal.org/project/system_stream_wrapper).
  20. - Clear the cache after updating.
  21. Release notes for 7.x-1.0
  22. -------------------------
  23. - Clear the (registry) cache after installing or updating to 7.x-1.0.
  24. - If you use custom actions, run update.php.
  25. - If you use custom actions, be sure to enable the 'PHP filter' module and give
  26. image style editors that may create custom actions the 'use PHP for settings'
  27. permission. The module must also be enabled on image creation.
  28. - If you use custom actions, please read the README.txt from that sub-module to
  29. find out about how information and resources are available to you. You will
  30. probably have to change your code snippets.
  31. - If you use effects that use files (mask, overlays, underlays, text fonts),
  32. check the way they are specified. From 7.x-1.0 on, you have to specify the
  33. location using one of the schemes private://, public://, module:// or
  34. temporary://. If no scheme is specified, the file is searched for as is, thus
  35. relative to the current directory or as an absolute path.
  36. - Effects that use the transparency layer (e.g. mask, rounded corners) do not
  37. automatically convert to PNG anymore. Use the "Change file format" for that.
  38. - There's no upgrade from D6. You will have to recreate your styles manually.
  39. Warning:
  40. Ongoing development in the area of e.g. making the effects more consistent,
  41. adding and/or removing parameters or redefining their meaning, might cause
  42. backward incompatibilities between future versions and the current version.
  43. Thus, we cannot and do not guarantee backwards compatibility or automatic
  44. upgrade paths for future versions.
  45. Introduction
  46. ------------
  47. The Imagecache Actions module provides a suite of additional image effects that
  48. can be added to image styles. Image styles let you create derivations of images
  49. by applying (a series of) effect(s) to it. Think of resizing, desaturating,
  50. masking, etc.
  51. Furthermore, imagecache_actions extends the administrative interface for image
  52. styles by providing additional features. It does so in the "Image styles admin"
  53. sub module.
  54. The additional effects that Imagecache Actions provides include:
  55. - Watermark: place a image with transparency anywhere over a source picture.
  56. - Overlay: add photo-corners etc to the image
  57. - Text overlay: add e.g. a copyright notice to your image.
  58. - Color-shifting: colorize images.
  59. - Brighten/Darken.
  60. - Alpha blending: use a gray scale image to define the transparency layer of an
  61. image.
  62. - Canvas manipulation: resize the canvas and add a background color or image.
  63. - File Format switcher: if you need transparency in JPGs, make them PNG. If your
  64. PNG thumbnails are 30K each, save them as JPGs.
  65. - Rounded corners.
  66. - TODO: complete list, check short descriptions
  67. These effects are grouped in sub-modules. Just enable the ones you want to use.
  68. TODO: list sub-modules and their sets of effects.
  69. Imagecache Actions supports both the GD toolkit from Drupal core and the
  70. Imagemagick toolkit. However, please note that Imagemagick support is not yet
  71. complete. Please file an issue if you encounter problems in using Imagemagick.
  72. What is imagecache_action not?
  73. ------------------------------
  74. Imagecache Actions does not provide a new UI or new menu items. It hooks into
  75. the already existing image styles system (from Drupal core). See
  76. https://drupal.org/documentation/modules/image for more information about
  77. working with images.
  78. A note about the name of this module
  79. ------------------------------------
  80. Image styles are part of Drupal 7 core and are the successor of the Drupal 6
  81. imagecache module. In Drupal 6 image styles were called (imagecache) presets and
  82. the separate effects that made up a style were called (imagecache) actions. In
  83. porting to D7, that name has not been changed (yet).
  84. Which toolkit to use?
  85. ---------------------
  86. Personally, I (fietserwin) prefer the imagemagick toolkit:
  87. - It is better in anti-aliasing. Try to rotate an image using both toolkits and
  88. you will see what I mean.
  89. - It does not execute in the PHP memory space, so is not restricted by the
  90. memory_limit PHP setting.
  91. - The GD toolkit will, at least on my Windows configuration, keep the font file
  92. open after a text operation, so you cannot delete, move or rename it anymore.
  93. On the other hand: the GD toolkit is always available (in the correct version),
  94. whereas imagemagick is not always present on shared hosting or may be present in
  95. an antique version that might give problems.
  96. Please note that effects may give different results depending on the
  97. toolkit used.
  98. Please also note that a 3rd image toolkit exists:
  99. Imagick (https://www.drupal.org/project/imagick)
  100. This toolkit uses the Imagick extension and thus does not call the ImageMagick
  101. binaries directly. However our module does not implement the toolkit specific
  102. parts for the effects we provide for the Imagick toolkit, but the Imagick
  103. toolkit comes with its own set of effects that partly covers our effects. So,
  104. depending on the effects you require it may be a replacement for both our module
  105. and the Imagemagick module or the core GD toolkit.
  106. Hard Dependencies
  107. -----------------
  108. - Image module from Drupal core
  109. At least 1 of the available image toolkits:
  110. - GD toolkit from Drupal core.
  111. - Imagemagick toolkit: https://drupal.org/project/imagemagick.
  112. Soft Dependencies
  113. -----------------
  114. - System stream wrapper (https://drupal.org/project/system_stream_wrapper)
  115. - Remote stream wrapper (https://drupal.org/project/remote_stream_wrapper)
  116. These modules provide additional stream wrappers. Especially the system stream
  117. wrapper is very handy as it provides, among others, a module:// and theme://
  118. wrapper.
  119. Installing
  120. ----------
  121. As usual.
  122. Usage
  123. -----
  124. After enabling the module:
  125. - Assure that the Image module from core is enabled.
  126. - Configure your toolkit and its settings at admin/config/media/image-toolkit.
  127. - Define image styles at admin/config/media/image-styles and add 1 or more
  128. effects as defined by this module
  129. - Use the image styles via e.g. the formatters of image fields.
  130. Upgrading from D6
  131. -----------------
  132. There's no upgrade path defined for sites upgrading from D6 to D7. This means
  133. that you will have to manually redefine your D6 imagecache presets as D7 image
  134. styles. Note that actually an upgrade path would have to be defined by the
  135. imagecache module, not this imagecache actions module. However, as there is no
  136. D7 version of imagecache that provides an upgrade, users may post an upgrade
  137. function to the issue queue and we will incorporate it.
  138. Backwards compatibility
  139. -----------------------
  140. Future releases will not be guaranteed to be backwards compatible. Implementing
  141. Imagemagick support e.g. might give unforeseen problems that can only be solved
  142. by changing the details of what an effect does. We will document these kind of
  143. incompatibilities in the changelog and the release notes.
  144. File form fields
  145. ----------------
  146. A number of effects have a file form field where the editor can define a file
  147. name to use. This can be e.g. for overlays, masks or fonts. The file name should
  148. be defined using either:
  149. - 1 of the (enabled) scheme's:
  150. * public://
  151. * private:// Preferred for site specific masks, overlays, etc, that do not
  152. need to be shared publicly.
  153. * temporary:// Unlikely to be useful, but supported anyway as all schemes are
  154. supported.
  155. * module:// Introduced by the system stream wrapper module and preferred for
  156. module provided resources.
  157. * theme:// idem.
  158. * profile:// idem.
  159. * library:// idem.
  160. - A relative (to the current directory, probably Drupal root) or absolute path.
  161. Support
  162. -------
  163. Via the issue queue of this project at Drupal.org.
  164. Known problems
  165. --------------
  166. These are better documented in the issue queue, but might be listed here (as
  167. well).
  168. - Underlay does not work in imagemagick if the dimensions of both images are not
  169. equal. As a workaround first add a canvas effect with a fully transparent
  170. background.
  171. - Underlay/overlay: keywords in the x and y offset fields do not work.
  172. - Underlay does still display a message about Imagemagick not being supported.
  173. - Brightness values outside the -250 .. 250 range are accepted.
  174. - Check color fields that allow a transparency component or allow to be empty to
  175. specify fully transparent.
  176. Known problems: Imagemagick
  177. ---------------------------
  178. - Define canvas using offsets may bot work on older versions. We have an error
  179. report for version 6.5.4.7 (2009-07) (https://drupal.org/node/888644).