4 Provides ImageMagick integration.
6 For a full description of the module, visit the project page:
7 https://drupal.org/project/imagemagick
8 To submit bug reports and feature suggestions, or to track changes:
9 https://drupal.org/project/issues/imagemagick
14 * Either ImageMagick (http://www.imagemagick.org) or GraphicsMagick
15 (http://www.graphicsmagick.org) need to be installed on your server
16 and the convert binary needs to be accessible and executable from PHP.
18 * The PHP configuration must allow invocation of proc_open() (which is
19 security-wise identical to exec()).
21 Consult your server administrator or hosting provider if you are unsure about
27 * Install as usual, see https://drupal.org/node/70151 for further information.
32 * Go to Administration » Configuration » Media » Image toolkit and change the
33 image toolkit to ImageMagick.
35 * Select the graphics package (ImageMagick or GraphicsMagick) you want to use
38 * If the convert binary cannot be found in the default shell path, you need to
39 enter the path to the executables, including the trailing slash/backslash.
41 * Enable and/or disable the image formats that the toolkit needs to support,
44 * Select a locale to be used when escaping command line arguments, in the
45 'Execution options' box, 'Locale' field. The default, 'en_US.UTF-8', should
46 work in most cases. If that is not available on the server, enter another
47 locale. On *nix servers, type 'locale -a' in a shell window to see a list of
48 all locales available. This is particularly needed if you are going to
49 process image files with non-ASCII characters in the file name: without a
50 locale defined, the non-ASCII characters will be dropped by the escape
51 function, leading to errors.
54 -- ENABLE/DISABLE SUPPORTED IMAGE FORMATS --
56 ImageMagick and GraphicsMagick support a wide range of image formats. The image
57 toolkits need to declare the image file extensions they support. This module
58 allows to configure the image file extensions the toolkit supports, by mapping
59 an 'internal' ImageMagick format code to its MIME type. The file extensions
60 associated to the MIME type are then used to built the full list of supported
63 * Go to Administration » Configuration » Media » Image toolkit and expand the
64 'Format list' section in the 'Image formats' box of the ImageMagick toolkit
65 configuration. This list shows the 'internal' image formats supported by the
66 *installed* ImageMagick package. Note that this list depends on the libraries
67 that are used when building the package.
69 * Enter the list of image formats you want to support in the 'Enable/Disable
70 Image Formats' box. Each format need to be typed following a YAML syntax,
77 exclude_extensions: jpe, jpg
79 The 'internal' format should be entered with no spaces in front, and with a
80 trailing colon. For each format there are more variables that can be
81 associated. Each variable should be entered with two leading spaces, followed
82 by a colon, followed by a space, followed by the variable's value.
84 'mime_type': (MUST) the MIME type of the image format. This will be used to
85 resolve the supported file extensions, i.e. ImageMagick 'JPEG' format is
86 mapped to MIME type 'image/jpeg' which in turn will be mapped to 'jpeg jpg
87 jpe' image file extensions.
88 'enabled': (OPTIONAL) if the format is enabled in the toolkit. Defaults to
90 'weight': (OPTIONAL), defaults to 0. This is used in edge cases where an
91 image file extension is mapped to more than one ImageMagick format. It is
92 needed in file format conversions, e.g. in conversion from 'png' to 'gif',
93 to decide if 'GIF' or 'GIF87' internal Imagemagick format be used.
94 'exclude_extensions': (OPTIONAL) it can be used to limit the file extensions
95 to be supported by the toolkit if the mapping MIME type <-> file extension
96 returns more extensions than needed and we do not want to alter the MIME type
100 -- IMAGEMAGICK AND DRUPAL'S IMAGE API REVEALED --
102 ImageMagick is a command line based image manipulation tool. It is executed
103 through calls to the operating system shell, rather than using PHP functions.
104 For this reason, the way the ImageMagick toolkit operates is very different
105 from, for example, the GD toolkit provided by Drupal core.
106 All the image manipulation performed by the operations provided by the Image
107 API (scale, resize, desaturate, etc.), in fact, have to be accumulated and
108 deferred to a single call of the 'convert' executable.
109 The way ImageMagick toolkit interacts with Drupal Image API is the following:
110 a) When an Image object is created, the toolkit calls ImageMagick's 'identify'
111 command to retrieve information about the image itself (e.g. format, width,
112 height, orientation).
113 b) When operations are applied to the Image object (typically as part of
114 creating an image style derivative), the toolkit *both* adds arguments to
115 the command line to be executed *and* keeps track of the changes occurring
116 to the width/height/orientation. It does so based purely on the information
117 retrieved sub (a), and the expected changes introduced by a specific
118 operation, because we do not have an object in memory that can be tested
119 against current values as we have in the GD toolkit.
120 c) When the Image object is 'saved' (typically at the end of the image style
121 derivative creation process), then the toolkit actually executes
122 ImageMagick's 'convert' command with the entire set of arguments that have
123 been added by effects/operations so far.
126 -- DEBUGGING IMAGEMAGICK COMMANDS --
128 The toolkit provides some of options to facilitate debugging the execution of
129 ImageMagick commands.
131 - Display debugging information
133 Go to Administration » Configuration » Media » Image toolkit and select the
134 'Display debugging information' tickbox in the 'Execution options' box. This
135 will result in logging all the parameters passed in input to the 'identify'
136 and 'convert' binaries, and all output/errors produced by the execution. The
137 same information will also be presented interactively to users with the
138 'Administer site configuration' permission. This can be used for debugging
139 purposes, as these entries can be used to execute separately the commands in
142 As an example, the following is logged when an image derivative is generated
143 by the 'Thumbnail' image style:
145 ImageMagick command: identify -format 'format:%m|width:%w|height:%h|exif_orientation:%[EXIF:Orientation]' 'core/modules/image/sample.png'
146 ImageMagick output: format:PNG|width:800|height:600|exif_orientation:
147 ImageMagick command: convert 'core/modules/image/sample.png' -resize 100x75! -quality 75 '/[...]/sites/default/files/styles/thumbnail/public/core/modules/image/sample.png'
148 ImageMagick command: identify -format 'format:%m|width:%w|height:%h|exif_orientation:%[EXIF:Orientation]' '/[...]/sites/default/files/styles/thumbnail/public/core/modules/image/sample.png'
149 ImageMagick output: format:PNG|width:100|height:75|exif_orientation:
151 - Prepend -debug argument
153 Go to Administration » Configuration » Media » Image toolkit and enter, for
154 example, '-debug All' in the 'Prepend arguments' text box. Also, enable
155 'Display debugging information' as described above. This will instruct
156 ImageMagick 'identify' and 'convert' binaries to produce a verbose log of
157 their internal operations execution, that can be checked in case of issues.
158 Also, a '-log' argument can be entered to specify how to format the log
160 For more details, see ImageMagick documentation online:
161 https://www.imagemagick.org/script/command-line-options.php#debug
162 https://www.imagemagick.org/script/command-line-options.php#log
164 This requires some trials before getting the required level of detail. A good
165 combination is "-debug All -log '%u: %d - %e'". Following on the example
166 above, this will log something like (extract):
168 ImageMagick command: convert 'core/modules/image/sample.png' -debug All -log '%u: %d - %e' -resize 100x75! -quality 75 '/[...]/sites/default/files/styles/thumbnail/public/core/modules/image/sample.png'
171 0.110u: Cache - destroy core/modules/image/sample.png[0]
172 0.110u: Resource - Memory: 3.84MB/58.6KiB/25.46GiB
173 0.110u: Policy - Domain: Coder; rights=Write; pattern="PNG" ...
174 0.110u: Coder - Enter WritePNGImage()
175 0.110u: Coder - Enter WriteOnePNGImage()
176 0.110u: Coder - storage_class=DirectClass
177 0.110u: Coder - Enter BUILD_PALETTE:
178 0.110u: Coder - image->columns=100
179 0.110u: Coder - image->rows=75
180 0.110u: Coder - image->matte=0
181 0.110u: Coder - image->depth=8
182 0.110u: Coder - image->colors=0
183 0.110u: Coder - (zero means unknown)
184 0.110u: Coder - Regenerate the colormap
185 0.110u: Coder - Check colormap for background (65535,65535,65535)
186 0.110u: Coder - No room in the colormap to add background color
187 0.110u: Coder - image has more than 256 colors
188 0.110u: Coder - image->colors=0
189 0.110u: Coder - number_transparent = 0
190 0.110u: Coder - number_opaque > 256
191 0.110u: Coder - number_semitransparent = 0
198 * Daniel F. Kudwien 'sun' - https://www.drupal.org/u/sun
199 * 'mondrake' - https://www.drupal.org/u/mondrake - for the Drupal 8 branch