[Magick-bugs] Various bugs and complaints

[Mario Rosso]

Hello imagemagick team & users,

(imagemagick version = 6.4.5 from ubuntu jaunty)

I am mad at imagemagick because I just spent at least 3 hours trying for 
the N-th time in my life to understand how imagemagick works, and I 
failed. This app just feels brain damaged or buggy as hell!

Firstly my complaint is on the manual, and then I have an working (or 
nonworking) example for you.

The manual is almost impossible to understand because 1) it never 
defines the terms it is using and 2) the description for many options is 
simply too short to understand what they do.
   Read -resize: 
http://www.imagemagick.org/script/command-line-options.php#resize
this option would have required no explanation at all once the meaning 
of "size" was known. The problem is that the meaning of size is the only 
thing you won't find in the manual. Is it the size in millimeters, the 
size in inches, the size in pixels...??
   Read -resample: 
http://www.imagemagick.org/script/command-line-options.php#resample
I admit this entry was almost clear, except that imagemagick doesn't 
work like that. If it worked as the manual says, rendering on the *same* 
device using "-resample 200" i should obtain a larger rendered image (in 
millimeters) (because there are more pixels on the same device) than 
with "-resample 100", or at least equal size (in case you carry on 
density information), while in fact 200 results in a *smaller* image 
than 100. If you want to try, take my example below here, remove the 
-density and -resize options, add a -resample and see.
   Read -extent: 
http://www.imagemagick.org/script/command-line-options.php#extent
Oh ok, so what is the difference to resize?
   Read -geometry: 
http://www.imagemagick.org/script/command-line-options.php#geometry
Oh great! now we have ANOTHER option that specifies the size. Now what 
is the difference to "-extent" and "-resize"?
   Read -page: 
http://www.imagemagick.org/script/command-line-options.php#page
In what the h*ll of measurement unit are the width and height that are 
specified in this table? I had to google for various minutes to 
understand that you implicitly intend the width/height size of the page 
in pixels, but with an implicit dpi of 72! How is the user supposed to 
figure this out!?!?

Apart from these problems, the manual really needs a section where the 
terms are defined. After reading the manual for a lot of time ('cause I 
already had tried hard in the past) it seems to me that you use the 
following definitions:
   size = size in pixels
   dimensions = same as size
   resolution = resolution in dpi
   rendered size = size in millimeters/inches
well then... *please write it*! For most of us "resolution" means 
pixel-size and "size" means size in millimeters, and what you call 
"resolution" we call it "dpi", so the manual becomes almost undecipherable.

And now it's example time.
I have a few photographs made by a Canon SX100 in one directory (Linux). 
The photograps are jpg, 3264x2448 pixels and at 180dpi.
I wanted to rotate them 90 deg, resize them to 50% pixels, fit them to 
A4 pages and put them into a PDF.

After hours of trial and errors (the manual has been pratically useless 
if not misleading), this is the command that turned out to do what I 
wanted:

   convert IMG_156[123].JPG -density 72 -resize 50% -rotate 90 -adjoin 
-compress jpeg -quality 90 -page A4 june.pdf

Now... why does it work? It is very unclear.

Firstly, the -density option: if you have an image with horizontal size 
2448 pixels and density 180 and you re-set it to density 72, the size 
should enlarge, ok, but not of the correct amount to fit onto an A4 
page: 2448/180*72=979.2 pixels while A4 has a width of 595 pixels at 
72dpi so it should come out too large and be cropped, while 72 is 
*exactly* the DPI that fits the image to the A4 page for me. Please note 
that I am positive that the density of 180 is read by convert because 
writing "-density 180" produces the same rendered size as skipping the 
option. (To check the rendered size reliably open the pdf with 
KGhostView or do a print preview from KPDF because the standard view of 
kpdf is too good to you and tries to enlarge images to fit the page, but 
then when you print it it's not what you get)

Now the -resize option: it does not appear to alter the rendered size 
(in millimeters)... did you guess that from the manual? No, huh? Well 
ok, good to know, so I guess it must work by adapting the density in a 
manner inversely proportional to the resize factor. Well, NO! Actually 
it doesn't do that, because if it did do that, moving the -density 
option to after the -resize option would result in a dramatically 
different output, while if you try by yourself you will see that moving 
the density option anywhere on the command line does not alter the output.

Extent option: I have tried to put "-extent 595x842" towards the end of 
the command line, with -density 72 placed just before it, thinking that 
it should have been perfect for setting the rendered size of the image 
exactly to fit the A4 page (except the pixelsize of the image being 
maybe too low for my purposes), but it did not work. The image becomes 
too big and it is cropped on the boundaries of the A4 page. Why is that?

And then I feel there is real need for one more option in convert: a 
"-rendersize <size_in_mm/inches>" which acts on the density value only, 
and sets it so that the rendered size of the image turns out to be what 
you specified. So this is a feature request.

Thanks for your time. I know it's a free app and I can have my money back.

Mario Rosso