### 5.3 The Transformation Protocol

• 5.3.1 Transformation Predicates
• 5.3.2 Composition of Transformations
• 5.3.3 Applying Transformations
• The following subsections describe the transformation protocol. All classes that are subclasses of transformation must implement methods for all of the generic functions in the following subsections. [annotate]

#### 5.3.1 Transformation Predicates

In all of the functions below, the argument named transformation must be a transformation. [annotate]

 transformation-equal transformation1 transformation2 [Generic Function]
 Returns true if the two transformations transformation1 and transformation2 have equivalent effects (that is, are mathematically equal), otherwise returns false. [annotate]Implementations are encouraged to allow transformations that are not numerically equal due to floating-point roundoff errors to be transformation-equal. An appropriate level of "fuzziness" is single-float-epsilon, or some small multiple of single-float-epsilon. [annotate]
 identity-transformation-p transformation [Generic Function]
 Returns true if the transformation transformation is equal (in the sense of transformation-equal) to the identity transformation, otherwise returns false. [annotate]
 invertible-transformation-p transformation [Generic Function]
 Returns true if the transformation transformation has an inverse, otherwise returns false. [annotate]
 translation-transformation-p transformation [Generic Function]
 Returns true if the transformation transformation is a pure translation, that is, a transformation such that there are two distance components dx and dy and every point (x,y) is moved to (x + dx,y + dy). Otherwise, translation-transformation-p returns false. [annotate]Note: Note that the identity transformation is a translation for dx = dy = 0. -- Alastair Bridgewater 2010-03-17 22:10Z
 reflection-transformation-p transformation [Generic Function]
 Returns true if the transformation transformation inverts the "handedness" of the coordinate system, otherwise returns false. Note that this is a very inclusive category---transformations are considered reflections even if they distort, scale, or skew the coordinate system, as long as they invert the handedness. [annotate]
 rigid-transformation-p transformation [Generic Function]
 Returns true if the transformation transformation transforms the coordinate system as a rigid object, that is, as a combination of translations, rotations, and pure reflections. Otherwise, it returns false. [annotate]Rigid transformations are the most general category of transformations that preserve magnitudes of all lengths and angles. [annotate]
 even-scaling-transformation-p transformation [Generic Function]
 Returns true if the transformation transformation multiplies all x lengths and y lengths by the same magnitude, otherwise returns false. It does include pure reflections through vertical and horizontal lines. [annotate]
 scaling-transformation-p transformation [Generic Function]
 Returns true if the transformation transformation multiplies all x lengths by one magnitude and all y lengths by another magnitude, otherwise returns false. This category includes even scalings as a subset. [annotate]
 rectilinear-transformation-p transformation [Generic Function]
 Returns true if the transformation transformation will always transform any axis-aligned rectangle into another axis-aligned rectangle, otherwise returns false. This category includes scalings as a subset, and also includes 90 degree rotations. [annotate]Rectilinear transformations are the most general category of transformations for which the bounding rectangle of a transformed object can be found by transforming the bounding rectangle of the original object. [annotate]Minor issue: Supply this figure. --- SWM [annotate]To be supplied.Figure 5.1: The predicates for analyzing the mathematical properties of a transformation.

#### 5.3.2 Composition of Transformations

If we transform from one coordinate system to another, then from the second to a third coordinate system, we can regard the resulting transformation as a single transformation resulting from composing the two component transformations. It is an important and useful property of affine transformations that they are closed under composition. Note that composition is not commutative; in general, the result of applying transformation A and then applying transformation B is not the same as applying B first, then A. [annotate]

Any arbitrary transformation can be built up by composing a number of simpler transformations, but that composition is not unique. [annotate]

 compose-transformations transformation1 transformation2 [Generic Function]
 Returns a transformation that is the mathematical composition of its arguments. Composition is in right-to-left order, that is, the resulting transformation represents the effects of applying the transformation transformation2 followed by the transformation transformation1. [annotate]
 invert-transformation transformation [Generic Function]
 Returns a transformation that is the inverse of the transformation transformation. The result of composing a transformation with its inverse is equal to the identity transformation. [annotate]If transformation is singular, invert-transformation will signal the singular-transformation error, with a named restart that is invoked with a transformation and makes invert-transformation return that transformation. This is to allow a drawing application, for example, to use a generalized inverse to transform a region through a singular transformation. [annotate]Note that with finite-precision arithmetic there are several low-level conditions that might occur during the attempt to invert a singular or "almost singular" transformation. (These include computation of a zero determinant, floating-point underflow during computation of the determinant, or floating-point overflow during subsequent multiplication.) invert-transformation must signal the singular-transformation error for all of these cases. [annotate]
 compose-translation-with-transformation transformation dx dy [Function]
 compose-scaling-with-transformation transformation sx sy &optional origin [Function]
 compose-rotation-with-transformation transformation angle &optional origin [Function]
 These functions create a new transformation by composing the transformation transformation with a given translation, scaling, or rotation, respectively. The order of composition is that the translation, scaling, or rotation "transformation" is first, followed by transformation. [annotate]dx and dy are as for make-translation-transformation. sx and sy are as for make-scaling-transformation. angle and origin are as for make-rotation-transformation. [annotate]Note that these functions could be implemented by using the various constructors and compose-transformations. They are provided, because it is common to build up a transformation as a series of simple transformations. [annotate]
 compose-transformation-with-translation transformation dx dy [Function]
 compose-transformation-with-scaling transformation sx sy &optional origin [Function]
 compose-transformation-with-rotation transformation angle &optional origin [Function]
 These functions create a new transformation by composing a given translation, scaling, or rotation, respectively, with the transformation transformation. The order of composition is transformation is first, followed by the translation, scaling, or rotation "transformation". [annotate]dx and dy are as for make-translation-transformation. sx and sy are as for make-scaling-transformation. angle and origin are as for make-rotation-transformation. [annotate]Note that these functions could be implemented by using the various constructors and compose-transformations. They are provided, because it is common to build up a transformation as a series of simple transformations. [annotate]

#### 5.3.3 Applying Transformations

Transforming a region applies a coordinate transformation to that region, thus moving its position on the drawing plane, rotating it, or scaling it. Note that transforming a region does not side-effect the region argument; it is free to either create a new region or return an existing (cached) region. [annotate]

These generic functions must be implemented for all classes of transformations. Furthermore, all subclasses of region and design must implement methods for transform-region and untransform-region. That is, methods for the following generic functions will typically specialize both the transformation and region arguments. [annotate]

Note that, if the extended region classes are not implemented, the following functions are not closed, that is, they may return results that are not CLIM regions. [annotate]

 transform-region transformation region [Generic Function]
 Applies transformation to the region region, and returns the transformed region. [annotate]
 untransform-region transformation region [Generic Function]
 This is exactly equivalent to `(transform-region (invert-transformation` transformation`)` region`)` . [annotate]CLIM provides a default method for untransform-region on the transformation protocol class that does exactly this. [annotate]
 transform-position transformation x y [Generic Function]
 Applies the transformation transformation to the point whose coordinates are the real numbers x and y, and returns two values, the transformed x coordinate and the transformed y coordinate. [annotate]transform-position is the spread version of transform-region in the case where the region is a point. [annotate]
 untransform-position transformation x y [Generic Function]
 This is exactly equivalent to `(transform-position (invert-transformation` transformation`)` x y`)` . [annotate]CLIM provides a default method for untransform-position on the transformation protocol class that does exactly this. [annotate]
 transform-distance transformation dx dy [Generic Function]
 Applies the transformation transformation to the distance represented by the real numbers dx and dy, and returns two values, the transformed dx and the transformed dy. [annotate]A distance represents the difference between two points. It does not transform like a point. [annotate]
 untransform-distance transformation dx dy [Generic Function]
 This is exactly equivalent to `(transform-distance (invert-transformation` transformation`)` dx dy`)` . [annotate]CLIM provides a default method for untransform-distance on the transformation protocol class that does exactly this. [annotate]
 transform-rectangle* transformation x1 y1 x2 y2 [Generic Function]
 Applies the transformation transformation to the rectangle specified by the four coordinate arguments, which are real numbers. The arguments x1, y1, x2, and y1 are canonicalized in the same way as for make-bounding-rectangle. Returns four values that specify the minimum and maximum points of the transformed rectangle in the order min-x, min-y, max-x, and max-y. [annotate]It is an error is transformation does not satisfy rectilinear-transformation-p. [annotate]Note: The second "is" should be "if". -- David 2009-03-22 02:59Z transform-rectangle* is the spread version of transform-region in the case where the transformation is rectilinear and the region is a rectangle. [annotate]
 untransform-rectangle* transformation x1 y1 x2 y2 [Generic Function]
 This is exactly equivalent to `(transform-rectangle* (invert-transformation` transformation`)` x1 y1 x2 y2`)` . [annotate]CLIM provides a default method for untransform-rectangle* on the transformation protocol class that does exactly this. [annotate]