www.aleph1.co.uk 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 * 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.
  17
  18 * The PHP configuration must allow invocation of proc_open() (which is
  19   security-wise identical to exec()).
  20
  21 Consult your server administrator or hosting provider if you are unsure about
  22 these requirements.
  23
  24
  25 -- INSTALLATION --
  26
  27 * Install as usual, see https://drupal.org/node/70151 for further information.
  28
  29
  30 -- CONFIGURATION --
  31
  32 * Go to Administration » Configuration » Media » Image toolkit and change the
  33   image toolkit to ImageMagick.
  34
  35 * Select the graphics package (ImageMagick or GraphicsMagick) you want to use
  36   with the toolkit.
  37
  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.
  40
  41 * Enable and/or disable the image formats that the toolkit needs to support,
  42   see below.
  43
  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.
  52
  53
  54 -- ENABLE/DISABLE SUPPORTED IMAGE FORMATS --
  55
  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
  61 extensions.
  62
  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.
  68
  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,
  71   like e.g.:
  72
  73     JPEG:
  74       mime_type: image/jpeg
  75       enabled: true
  76       weight: 0
  77       exclude_extensions: jpe, jpg
  78
  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.
  83   The variables are:
  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
  89   true.
  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
  97   mapping.
  98
  99
 100 -- IMAGEMAGICK AND DRUPAL'S IMAGE API REVEALED --
 101
 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.
 124
 125
 126 -- DEBUGGING IMAGEMAGICK COMMANDS --
 127
 128 The toolkit provides some of options to facilitate debugging the execution of
 129 ImageMagick commands.
 130
 131 - Display debugging information
 132
 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
 140   a shell window.
 141
 142   As an example, the following is logged when an image derivative is generated
 143   by the 'Thumbnail' image style:
 144
 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:
 150
 151 - Prepend -debug argument
 152
 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
 159   itself.
 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
 163
 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):
 167
 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'
 169    ImageMagick error:
 170       [...]
 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
 192       [...]
 193
 194
 195 -- CONTACT --
 196
 197 Current maintainers:
 198 * Daniel F. Kudwien 'sun' - https://www.drupal.org/u/sun
 199 * 'mondrake' - https://www.drupal.org/u/mondrake - for the Drupal 8 branch
 200   only.