yaffs.net Git - yaffs-website/blob - web/modules/contrib/imagemagick/README.txt

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