README.imagemagick

   1 This is the imagemagick branch of Emacs. Imagemagick can now be used
   2 to load many new image formats, and also do useful transforms like
   3 scaling and rotation.
   4
   5 This file will attempt to contain draft NEWS, Changelog and manual
   6 entries for the new functionality.
   7
   8 You might need to regenerate the configure scripts:
   9 aclocal
  10 automake
  11 autoheader
  12 autoconf
  13 ./configure --with-imagemagick
  14
  15
  16 * TODO
  17
  18 - image-type-header-regexps priorities the jpeg loader over the
  19 imagemagick one. This is not wrong, but how should a user go about
  20 prefering the imagemagick loader? The user might like zooming etc in
  21 jpegs.
  22
  23 - For some reason its unbearably slow to look at a page in a large
  24   image bundle using the :index feature. The imagemagick "display"
  25   command is also a bit slow, but nowhere near as slow as the emacs
  26   code. It seems imagemagick tries to unpack every page when loading
  27   the bundle. This feature is not the primary usecase for the
  28   imagemagick patch though.
  29
  30   ImageMagick 6.6.2-8 introduced a bugfix for single page djvu load.
  31   To benefit from the bugfix, the loader code in image.c must be changed.
  32
  33 - optimize number of pages calculation for bundles as suggested by
  34   imagemagick forum: "set the density to something low like 2 and use
  35   MagickPingImage()"
  36
  37 - zooming the image like what is done for fonts in face-remap.el would
  38   be a useful and demo friendly addition. Some work has been done on
  39   image-mode.el to acihieve this.
  40
  41 - look for optimizations for handling images with low depth
  42
  43 - it would be neat if the graphicsmagick fork of imagemagick could
  44   optionaly be used.
  45
  46
  47
  48 * TODO
  49 #B _ complete documentation drafts below
  50
  51 #B X fix inconsistencys with spelling of imagemagick in the src
  52 #B X report number of images in image bundle types somehow
  53 Works like for "gif" support. Thanks to Juri Linkov.
  54 #B X probably add pdf to inhibited types
  55 #B X inhibit types is defconst should probably be defcustom
  56 #B _ decide what to do with some uncommitted imagemagick support
  57   functions for image size etc.
  58 #B _ Test with more systems
  59 Tested on Fedora 12 so far, and the libmagick that ships with it.
  60 Ubuntu 8.04 was also tested, but it seems it ships a broken ImageMagick.
  61 #B X Also need some way to handle render methods that only work on newer ImageMagicks
  62 Is handled by configure now
  63
  64 * Some nits from Stefan Monnier
  65 I just took a quick look at the code and I see the following nits to fix:
  66 #B _ obviously a merge will have to come with a good ChangeLog.
  67 #B X also the merge will need to come with documentation.  Maybe not in the
  68    Texinfo form yet, but at least in the etc/NEWS with enough info that
  69    describes the `scale' and other such arguments that someone can start
  70    using them.
  71 #B X the README talks about naming inconsistencies, I think these should be
  72   fixed before a first commit (should be straightforward).
  73
  74 #B X the "let" in image.el should not be followed by a line break and the while
  75    should be replaced by a dolist.
  76
  77 #B X the prototype of imagemagick_load_image has some odd indentation in ([[2010.06.14]])
  78    its args, not sure what happened.
  79 #B X a few lines in the C code break the 80columns limit.
  80 #B X please use ANSI style function declarations rather than K&R for new code. ([[2010.06.14]])
  81 #B X you can get rid of the prototypes by reordering the code. ([[2010.06.14]])
  82 #B X the docstrings in DEFUN should not be indented (they'll display ([[2010.06.14]])
  83    weirdly otherwise in C-h f).
  84 #B X Some "{" are at the end of a for/if rather than on their own line. ([[2010.06.14]])
  85 #B X why use "*( imtypes + i)" rather than "imtypes[i]"? ([[2010.06.14]])
  86 #B X some "," lack a space after them. ([[2010.06.14]])
  87 #B X several "=" and "==" lack spaces around them. ([[2010.06.14]])
  88
  89
  90 * NEWS entry
  91 ** ImageMagick support
  92 It is now possible to use the Imagemagick library to load many new
  93 image formats in Emacs.
  94
  95 To enable, use the following configure option:
  96 --with-imagemagick
  97
  98 The new function (imagemagick-types) returns a list of image file
  99 extensions that your installation of imagemagick supports.
 100
 101 The function (imagemagick-register-types) will enable the imagemagick
 102 support for the extensions in imagemagick-types minus the types listed
 103 in imagemagick-types-inhibit.
 104
 105 imagemagick-types-inhibit has the value  '(C HTML HTM TXT PDF) by default.
 106 This means imagemagick will be used also to load jpeg files, if you
 107 have both jpeg and imagemagick libraries linked. Add 'JPG to
 108 imagemagick-types-inhibit if you do not want this.
 109
 110 imagemagick-render-type is a new variable which can be set to choose
 111 between screen render methods.
 112
 113 - 0 is a conservative metod which works with older ImageMagick
 114   versions. It is a bit slow, but robust.
 115
 116 - 1 utilizes a newer ImageMagick method
 117
 118
 119 Images loaded with imagemagick will support a couple of new display
 120 specification behaviours:
 121
 122 - if the :width and :height keywords are specified, these values are
 123 used for scaling the image. If only one of :width or :height is
 124 specified, the other one will be calculated so as to preserve the
 125 aspect ratio.If both :width and :height are specified, aspect ratio
 126 will not be preserved.
 127
 128 - :rotation specifies a rotation angle in degrees.
 129
 130 - :index specifies which image inside an image bundle file format, such
 131 as TIFF or DJVM, to view.
 132
 133 The image-metadata function can be used to retrieve the total number
 134 of images in an image bundle. This is simmilar to how GIF files work.
 135
 136 * Changelog entry
 137 2010-06-12 Joakim Verona <joakim@verona.se>
 138            * image.c: Add support for ImageMagick. When HAVE_IMAGEMAGICK is
 139            defined:
 140            (imagemagick_image_p): New function to test for ImageMagic img.
 141            (imagemagick_load): New function to load ImageMagick img.
 142            (imagemagick_load_image): New function, helper for imagemagick_load
 143            (imagemagick-types): New function.
 144            (Qimagemagick): New Lisp_object.
 145            * image.el:
 146            (imagemagick-types-inhibit): New var.
 147            (imagemagick-register-types): New function.
 148            * config.in, Makefile.in, configure.in
 149
 150 * Manual entry
 151 nothing yet, but the NEWS entry could be adapted.