materio-base-legacy/sites/all/modules/contrib/files/imagecache_actions/README.txt

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

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

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


Release notes for 7.x-1.0
-------------------------
- If you use custom actions, run update.php.
- 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 specfiy 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
  forward incompatibilities with future versions. 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.

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 grayscale image to define the transparency layer of an
  image.
- Canvas manipulation: resize the canvas and add a backgroundcolor or image.
- File Format switcher: if you need tranparency in JPGs, make them PNG. If your
  PNG thumbnails are 30K each, save them as JPGs.
- Rounded corners.
- TODO: complete list, check short descrptions

These effects are grouped in submodules. Just enable the ones you want to use.
TODO: list submodules 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
http://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).


Augmenting the Drupal core image module
---------------------------------------
This module might also provide additional features to the Drupal core image
module. Currently no such features are implemented, but they might be in the
future, think e.g. of adding a "copy image style" feature. This allows to test
D8 image module features in real life.

Solving errors in the core image handling:
- [#1554074]: scale does not work with imagemagick when dimensions are unknown?


Which toolkit to use?
---------------------
Personally, I (fieterwin) 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 also note that effects may give different results depending on the
toolkit used.


Dependencies
------------
- Drupal 7.x
- Image module from Drupal core

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


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
imageacache 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. furhtermore current behavior of
the image mask effect is to also change the file format to png. This effect
should not do so, and thus will probably be changed in a future release. 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 canbe 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, overlay's, etc, that do not need
    to be shared publicly.
- module://{module_name}/{resource-name} Introduced by the imagecache_actions
    module and preferred for module provided resources, like the button overlay
    of the Video Embed Field Overlay module
    (http://drupal.org/project/video_embed_field_overlay).
- temporary:// Unlikely to be useful, but supported anyway as all schemes are
    supported.

or 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 Iamgemagick not being supported.
- Brightness values outside the -250 .. 250 range are accepted.
- Check colorfields that allow a transparency component or allow to be empty to
  specify fully tranparent.