README.md 9.66 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
# Image Effects module

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


## Introduction

The Image Effects module provides a suite of additional image effects that can
be added to image styles and UI components that can be used in the image effects
configuration forms.

Image styles let you create derivations of images by applying (a series of)
effect(s) to it. Think of resizing, desaturating, masking, etc.

15 16 17 18 19
Image Effects tries to support both the GD toolkit from Drupal core and the
ImageMagick toolkit. However, please note that there may be effects that are
not supported by all toolkits, or that provide different results with different
toolkits.

20
The effects that this module provides include:
mondrake's avatar
mondrake committed
21

22 23
Effect name              | Description                                                                                  | GD toolkit | [ImageMagick](https://drupal.org/project/imagemagick) toolkit<sup>1</sup> |
-------------------------|----------------------------------------------------------------------------------------------|:----------:|:-------------------:|
24
Aspect switcher          | Choose image styles to apply based on source image orientation (portrait or landscape).      | X          | X                   |
25 26 27 28 29 30 31 32 33 34 35 36 37 38
Auto orientation         | Uses EXIF Orientation tags to determine the image orientation.                               | X          | X                   |
Background               | Places the source image anywhere over a selected background image.                           | X          | IM only             |
Brightness               | Supports changing brightness settings of an image. Also supports negative values (darkening).| X          | IM only             |
Color shift              | Colorizes image.                                                                             | X          | IM only             |
Contrast                 | Supports changing contrast settings of an image. Also supports negative values.              | X          | IM only             |
Convolution              | Allows to build custom image filters like blur, emboss, sharpen and others (see http://docs.gimp.org/en/plug-in-convmatrix.html). | X          | IM only             |
Gaussian blur            | Uses the Gaussian function to blur the image.                                                | X          | X                   |
ImageMagick arguments    | Directly enter ImageMagick command line arguments.                                           |            | X                   |
Interlace                | Used to specify the type of interlacing scheme for raw image formats.                        | X          | IM only             |
Invert                   | Replace each pixel with its complementary color.                                             | X          | X                   |
Mask                     | Apply a mask to the image.                                                                   | X          | IM only             |
Mirror                   | Mirror the image horizontally and/or vertically.                                             | X          | X                   |
Opacity                  | Change overall image transparency level.                                                     | X          | IM only             |
Resize percentage        | Resize the image by percentage of its width/height.                                          | X          | X                   |
39
Scale and Smart Crop     | Similar to Scale and Crop, but preserves the portion of the image with the most entropy.     | X          | X                |
40 41
Set canvas               | Places the source image over a colored or a transparent background of a defined size.        | X          | IM only             |
Set transparent color    | Defines the color to be used for transparency in GIF images.                                 | X          | IM only             |
42
Smart Crop               | Similar to Crop, but preserves the portion of the image with the most entropy.               | X          | X                |
43 44 45 46
Sharpen                  | Sharpens an image (using convolution).                                                       | X          | IM only             |
Strip metadata           | Strips all EXIF metadata from image.                                                         | X          | X                   |
Text overlay<sup>2</sup> | Overlays text on an image, defining text font, size and positioning.                         | X          | IM only<sup>3</sup> |
Watermark                | Place a image with transparency anywhere over a source picture.                              | X          | X<sup>4</sup>       |
47

48
Notes:
49

50 51 52 53
<sup>1</sup> Effect support for ImageMagick also depends on the package in
use, ImageMagick or GraphicsMagick. 'X' identifies effects that can be executed
with both IM and GM, 'IM only' effects that can only be executed with
ImageMagick.
54

55 56 57
<sup>2</sup> The [Textimage](https://drupal.org/project/textimage) module, if
installed, allows this effect's configuration UI to present a preview of the
text overlay.
58

59 60 61 62 63
<sup>3</sup> The ImageMagick toolkit actually requires the GD toolkit to build
the text overlay.

<sup>4</sup> GraphicsMagick does not support setting transparency level
(opacity) of the watermark image.
64 65 66 67 68


## What Image Effects is not?

Image Effects does not provide a separate UI. It hooks into the Drupal core's
mondrake's avatar
mondrake committed
69 70
image styles system. See [Working with images in Drupal 7 and 8](https://drupal.org/documentation/modules/image) for more
information.
71 72 73 74 75


## Requirements

1. Image module from Drupal core
mondrake's avatar
mondrake committed
76
1. One of the supported image toolkits:
77
  - GD toolkit from Drupal core.
mondrake's avatar
mondrake committed
78
  - [ImageMagick](https://drupal.org/project/imagemagick) toolkit.
79 80 81 82


## Installing

83
__Versions 8.x-1.x:__ Install as usual, see the [official documentation](https://www.drupal.org/documentation/install/modules-themes/modules-8)
84 85
for further information.

86 87 88
__Versions 8.x-2.x:__ The module requires [using Composer to manage Drupal site dependencies](https://www.drupal.org/node/2718229). Require the module via
```composer require drupal/image_effects:~2.0```, then enable the module as usual.

89 90 91

## Configuration

mondrake's avatar
mondrake committed
92
- Go to _Manage > Configuration > Media > Image toolkit_ and configure your
93
  toolkit and its settings.
mondrake's avatar
mondrake committed
94 95
- Check Image Effects configuration page (_Manage > Configuration > Media >
  Image Effects_), and choose the UI components that effects provided by this
96
  module should use:
97 98
  - _Color selector_ - allows to specify a UI component to select colors in the
    image effects. It can use a 'color' HTML element, or a color picker
mondrake's avatar
mondrake committed
99 100 101
    provided by the Farbtastic library, or a JQuery Colorpicker (if the [_JQuery
    Colorpicker_](https://www.drupal.org/project/jquery_colorpicker) module is
    installed). Additional selectors may be added by other modules.
mondrake's avatar
mondrake committed
102
  - _Image selector_ - some effects (e.g. Watermark) require to define an image
103 104 105
    file to be used. This setting allows to use either a basic text field where
    the URI/path to the image can be entered, or a 'dropdown' select that will
    list all the image files stored in a directory specified in configuration.
mondrake's avatar
mondrake committed
106
    Additional selectors may be added by other modules.
mondrake's avatar
mondrake committed
107
  - _Font selector_ - some effects require to define a font file to be used.
108 109
    This setting allows to use either a basic text field where the URI/path to
    the font can be entered, or a 'dropdown' select that will list all the font
mondrake's avatar
mondrake committed
110
    files stored in a directory specified in configuration. Additional
111 112 113 114 115
    selectors may be added by other modules.


## Usage

mondrake's avatar
mondrake committed
116 117
- Define image styles at _Manage > Configuration > Media > Image styles_ and add
  one or more effects defined by this module.
118 119 120 121 122 123 124 125 126 127 128
- Use the image styles via e.g. the formatters of image fields.


## Support

File bugs, feature requests and support requests in the [Drupal.org issue queue
of this project](https://www.drupal.org/project/issues/image_effects).


## A note about the origin of this module

mondrake's avatar
mondrake committed
129
This module is the Drupal 8 successor of the [ImageCache Actions](https://www.drupal.org/project/imagecache_actions) module.
mondrake's avatar
mondrake committed
130
It also incorporates image effects that were part of the Drupal 7 versions of the
131
[ImageMagick](https://drupal.org/project/imagemagick), [Textimage](https://drupal.org/project/textimage), [FiltersIE](https://www.drupal.org/project/filtersie), [Smart Crop](https://www.drupal.org/project/smartcrop)
132
and [ImageMagick Raw Effect](https://www.drupal.org/project/im_raw) modules.
133 134 135 136


## Which toolkit to use?

mondrake's avatar
mondrake committed
137
[ImageMagick](https://drupal.org/project/imagemagick) toolkit comes with few advantages:
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152
- It is better in anti-aliasing. Try to rotate an image using both toolkits and
  you will see for yourself.
- 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 Windows configurations, keep the font file
  open after a text operation, so you cannot delete, move or rename it until PHP
  process is running.

Advantages of GD toolkit on the other hand:
- GD is always available, whereas ImageMagick is not always present on shared
  hosting or may be present in an antique version that might give problems.
- Simpler architecture stack.

Please also note that effects may give different results depending on the
toolkit used.
mondrake's avatar
mondrake committed
153 154


155 156 157 158 159
## Developing

Contributions to the module are welcome! Please read carefully the [DEVELOPING.md](DEVELOPING.md) file for developers' instructions.


mondrake's avatar
mondrake committed
160 161 162 163 164 165 166 167 168 169 170
## Maintainers

Current and past maintainers for Image Effects:
- [Berdir](https://www.drupal.org/u/Berdir)
- [fietserwin](https://www.drupal.org/u/fietserwin)
- [mondrake](https://www.drupal.org/u/mondrake)
- [slashsrsm](https://www.drupal.org/u/slashrsm)

Past maintainers for Imagecache Actions:
- [dman](https://drupal.org/user/33240)
- [sidneyshan](https://drupal.org/user/652426)