Re: Image transformations

[Alan Third <alan@idiocy.org>]

[-- Attachment #1: Type: text/plain, Size: 2254 bytes --]

On Tue, Jun 11, 2019 at 08:10:41AM +0300, Eli Zaretskii wrote:
>   . The :crop parameter of image specs doesn't seem to be documented anywhere.  We previously supported it without documenting only for ImageMagick, which was already a problem; now it's a much bigger problem.
>   . The ELisp manual doesn't mention that :rotation is generally supported only for multiples of 90 deg, except if ImageMagick is available.
>   . The transformation matrix used by the implementation is not described; one needs to guess what its components mean, or search the Internet for docs of XRender and/or Cairo, which are generally not helpful enough, especially the XRender one.

I hope the attached patch goes some way to solving these issues.

>   . There are no tests, AFAICT.  We should have a simple manual test
>   which could be used to exercise all of the transformations,
>   separately and in combinations.  I wonder how did the people who
>   worked on the implementations for different platforns verify that
>   the results are consistent, especially given the lack of
>   documentation (e.g., is rotation of 90 deg clockwise or
>   counter-clockwise?).

Is there some example of how to write a manual test like this?

>  . I question the wisdom of the current definition of
>  image-transforms-p. First, it returns a simple yes/no value, under
>  the assumption that either all of the transformations are supported
>  or none of them; IMO, it is better to return a list of supported
>  capabilities instead. Second, it doesn't distinguish between
>  capability to rotate by arbitrary angles and by 90 deg multiples
>  only, which will require Lisp programs to test for ImageMagick,
>  something that undermines the very raison d'etre of this function

My hope was that MS Windows support for affine transform matrices
would be forthcoming quite quickly in which case there would be no
need to differentiate between the different types of transform (if one
is supported, they all are), but perhaps that’s hoping for too much. :)

I’ve been thinking a bit about the idea of returning some sort of
capabilities list and it seems quite neat. We could perhaps roll some
of the imagemagick-types stuff into it.

I’ll look into it further.

-- 
Alan Third

[-- Attachment #2: 0001-Document-image-transforms.patch --]
[-- Type: text/plain, Size: 3127 bytes --]

From bb51fbf18d8e9fcb7f65afef49d802b9fc768149 Mon Sep 17 00:00:00 2001
From: Alan Third <alan@idiocy.org>
Date: Tue, 11 Jun 2019 20:31:24 +0100
Subject: [PATCH] Document image transforms

* doc/lispref/display.texi (Image Descriptors): Document :crop and
update :rotation.
* src/image.c: Describe the image transform matrix layout.
---
 doc/lispref/display.texi | 23 ++++++++++++++++++++++-
 src/image.c              | 16 ++++++++++++++++
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 93c5217c36..d29e98a8fd 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -5181,8 +5181,29 @@ Image Descriptors
 specified, the height/width will be adjusted by the specified scaling
 factor.
 
+@item :crop @var{geometry}
+This should be a list of the form @code{(@var{width} @var{height}
+@var{x} @var{y})}.  If @var{width} and @var{height} are positive
+numbers they specify the width and height of the cropped image.  If
+@var{x} is a positive number it specifies the offset of the cropped
+area from the left of the original image, and if negative the offset
+from the right. If @var{y} is a positive number it specifies the
+offset from the top of the original image, and if negative from the
+bottom. If @var{x} or @var{y} are @code{nil} or unspecified the crop
+area will be centred on the original image.
+
+If the crop area is outside or overlaps the edge of the image it will
+be reduced to exclude any areas outside of the image.  This means it
+is not possible to use @code{:crop} to increase the size of the image
+by entering large @var{width} or @var{height} values.
+
+Cropping is performed after scaling but before rotation.
+
 @item :rotation @var{angle}
-Specifies a rotation angle in degrees.
+Specifies a rotation angle in degrees.  Only multiples of 90 degrees
+are supported, unless the image type is @code{imagemagick}.  Positive
+values rotate clockwise, negative values anti-clockwise.  Rotation is
+performed after scaling and cropping.
 
 @item :index @var{frame}
 @xref{Multi-Frame Images}.
diff --git a/src/image.c b/src/image.c
index 86f8e8f4bb..12e35e4527 100644
--- a/src/image.c
+++ b/src/image.c
@@ -1967,6 +1967,22 @@ compute_image_size (size_t width, size_t height,
 }
 #endif /* HAVE_IMAGEMAGICK || HAVE_NATIVE_TRANSFORMS */
 
+/* image_set_rotation, image_set_crop, image_set_size and
+   image_set_transform use affine transformation matrices to perform
+   various transforms on the image.  The matrix is a 2D array of
+   doubles.  It is laid out like this:
+
+   m[0][0] = m11 | m[0][1] = m12 | m[0][2] = tx
+   --------------+---------------+-------------
+   m[1][0] = m21 | m[1][1] = m22 | m[1][2] = ty
+   --------------+---------------+-------------
+   m[2][0] = 0   | m[2][1] = 0   | m[2][2] = 1
+
+   tx and ty represent translations, m11 and m22 represent scaling
+   transforms and m21 and m12 represent shear transforms. Some
+   graphics toolkits don't require the third row, however it is
+   necessary for multiplication.  */
+
 typedef double matrix3x3[3][3];
 
 static void
-- 
2.21.0