README.imagemagick

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