DUIMGeometry Library¶
Overview¶
The DUIMGeometry library provides basic support for coordinate geometry. This allows the position of elements in a window object to be determined correctly. The library contains a single module, duimgeometry, from which all the interfaces described in this chapter are exposed. DUIMGeometry Module contains complete reference entries for each exposed interface.
The class hierarchy for DUIMGeometry¶
The base classes for classes in the DUIMGeometry library are <region>
and <transform>
, both of which are subclasses of <object>
. While
the <region>
class has a number of subclasses, <transform>
has no
direct subclasses.
<transform>
The superclass of all transforms. A transform describes the mapping of one set of points onto another. There are one or more subclasses of<transform>
that implement transforms. These subclasses have implementationdependent names which are explicitly unspecified. All of the instantiable transformation classes provided by DUIM are immutable.
In addition, there are a number of error classes which may be signalled.
These are all subclasses of <error>
.
The <region> class and its subclasses¶
The DUIMGeometry library exposes the <region> class and its subclasses as
shown in the following table . None of these subclasses have any further
subclasses exposed in the DUIMGeometry library, although the
DUIMExtendedGeometry library exposes some subclasses of <area>
and <path>
.
<region> 

<regionset> 

<point> 

<path> 

<area> 

<boundingbox> 
<region>
This class is used to represent any set of points. The:class:<region> class includes both bounded regions (that is, regions whose edges are known) and unbounded regions (that is, regions with no known edges).<regionset>
This class represents a region set, that is, a set of regions.<point>
This class is used to represent mathematical points (that is, regions with dimensionality 0).<path>
The class<path>
denotes bounded regions with a length, but no area (that is, they have dimensionality 1).<area>
This class denotes bounded regions that have an area (that is, they have dimensionality 2).<boundingbox>
A bounding box is an axis aligned rectangle that contains some region.
Error classes provided by DUIMGeometry¶
The DUIMGeometry library exposes a number of errors that can be signalled in
certain circumstances. They are shown in the following table . All the errors
shown are subclasses of the <error>
class. Note that the subclasses of
<transformerror>
are all specific to particular errors.
<transformerror> 

<transformunderspecified> 

<reflection<underspecified> 

<singulartransform> 
<transformerror>
The superclass of all error conditions signalled when there is an error with a transform.<transformunderspecified>
The error that is signalled whenmake3pointtransform
is given three colinear image points.<reflectionunderspecified>
The error that is signalled whenmakereflectiontransform
is given two coincident points.<singulartransform>
The error that is signalled wheninverttransform
is called on a singular transform, that is, a transform that has no inverse.
DUIMGeometry Module¶
This section contains a complete reference of all the interfaces that are exported from the duimgeometry module.
 =(<region>) Method¶
Tests if its arguments are equal.
 Signature:
= region1 region2 => boolean
 Parameters:
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Tests if its arguments are equal. Returns
#t
if the two regions are the same, otherwise returns#f
. Two regions are considered equal if they contain exactly the same set of points.
 =(<transform>) Method¶
Tests if its arguments are equal.
 Signature:
= transform1 transform2 => boolean
 Parameters:
transform1 – An instance of type
<transform>
.transform2 – An instance of type
<transform>
.
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Tests if its arguments are equal. Returns
#t
if the two transforms are the same, otherwise returns#f
. Two transforms are considered equal if they transform every region the same way.
 <area> Open Abstract Class¶
The class
<area>
denotes bounded regions that have dimensionality 2 (that is, have area). Superclasses:
 Discussion:
The class
<area>
denotes bounded regions that have dimensionality 2 (that is, have area).<area>
is a subclass of<region>
.Note that constructing an area object with no area (such as calling
makerectangle
with two coincident points, for example) may canonicalize it to$nowhere
. Operations:
 See also:
 area? Generic function¶
Returns
#t
if its argument is an area, otherwise returns#f
.
 <boundingbox> Open Abstract Instantiable Class¶
The class that represents a bounding box.
 Superclasses:
 InitKeywords:
 Discussion:
A bounding box is an axis aligned rectangle that contains some region. The representation of bounding boxes in DUIM is chosen to be efficient. This representation is not sufficient to represent the result of arbitrary transformations (such as rotations) of bounding boxes. The most general class of transformations that is guaranteed to transform a box into another box is the class of transformations that satisfy
rectilineartransformation?
.Bounding boxes are immutable, but since they reflect the live state of such mutable objects as sheets, bounding boxes are volatile. Therefore, programmers must not depend on the bounding box associated with a mutable object remaining constant.
 Operations:
 See also:
 boundingbox? Generic function¶
Returns true if its argument is a bounding box.
 boundingbox Generic function¶
Returns the bounding box of a region.
 Signature:
boundingbox region #key into => box
 Parameters:
region – An instance of type
<region>
.into – An instance of type
falseor(<boundingbox>)
.
 Values:
box – An instance of type
<boundingbox>
.
 Discussion:
The argument region must be either a bounded region (such as a line or an ellipse) or some other object that obeys the bounding box protocol, such as a sheet.
This function often returns an existing object, so you should not modify the returned result.
If into is supplied, it is a bounding box that might be destructively modified to contain the result.
 See also:
 boxbottom Function¶
Returns the y coordinate of the bottom right corner of the bounding box of a region.
 Signature:
boxbottom region => bottom
 Parameters:
region – An instance of type
<region>
.
 Values:
bottom – An instance of type
<integer>
.
 Discussion:
Returns the y coordinate of the bottom right corner of the bounding box of region. The argument region must be either a bounded region or some other object that obeys the bounding box protocol.
 See also:
 boxedges Generic function¶
Returns the bounding box of a region.
 Signature:
boxedges region => left top right bottom
 Parameters:
region – An instance of type
<region>
.
 Values:
 Discussion:
Returns the bounding box of region as four integers specifying the x and y coordinates of the top left point and the x and y coordinates of the bottom right point of the box
The argument region must be either a bounded region (such as a line or an ellipse) or some other object that obeys the bounding box protocol, such as a sheet.
The four returned values left, top, right, and bottom will satisfy the inequalities:
*left* <= *right* *top* <= *bottom*
 See also:
 boxheight Function¶
Returns the height of the bounding box of a region.
 Signature:
boxheight region => height
 Parameters:
region – An instance of type
<region>
.
 Values:
height – An instance of type
<integer>
.
 Discussion:
Returns the height of the bounding box region. The height of a bounding box is the difference between the maximum y coordinate and its minimum y coordinate. The argument region must be either a bounded region or some other object that obeys the bounding box protocol.
 See also:
 boxleft Function¶
Returns the x coordinate of the upper left corner of the bounding box of a region.
 Signature:
boxleft region => left
 Parameters:
region – An instance of type
<region>
.
 Values:
left – An instance of type
<integer>
.
 Discussion:
Returns the x coordinate of the upper left corner of the bounding box region. The argument region must be either a bounded region or some other object that obeys the bounding box protocol, such as a sheet.
 See also:
 boxposition Generic function¶
Returns the position of the bounding box of a region as two values.
 Signature:
boxposition region => x y
 Parameters:
region – An instance of type
<region>
.
 Values:
x – An instance of type <integer>.
y – An instance of type <integer>.
 Discussion:
Returns the position of the bounding box of region as two values. The position of a bounding box is specified by its top left point.
 See also:
 boxright Function¶
Returns the x coordinate of the bottom right corner of the bounding box of a region.
 Signature:
boxright region => right
 Parameters:
region – An instance of type
<region>
.
 Values:
right – An instance of type
<integer>
.
 Discussion:
Returns the x coordinate of the bottom right corner of the bounding box region. The argument region must be either a bounded region or some other object that obeys the bounding box protocol, such as a sheet.
 See also:
 boxsize Generic function¶
Returns the width and height of the bounding box of a region as two values
 Signature:
boxsize region => width height
 Parameters:
region – An instance of type
<region>
.
 Values:
 Discussion:
Returns the width and height of the bounding box of region as two values The argument region must be either a bounded region or some other object that obeys the bounding box protocol, such as a sheet.
 See also:
 boxtop Function¶
Returns the y coordinate of the upper left corner of the bounding box of a region.
 Signature:
boxtop region => top
 Parameters:
region – An instance of type
<region>
.
 Values:
top – An instance of type
<integer>
.
 Discussion:
Returns the y coordinate of the upper left corner of the bounding box region. The argument region must be either a bounded region or some other object that obeys the bounding box protocol.
 See also:
 boxwidth Function¶
Returns the width of the bounding box of a region.
 Signature:
boxwidth region => width
 Parameters:
region – An instance of type
<region>
.
 Values:
width – An instance of type
<integer>
.
 Discussion:
Returns the width of the bounding box region. The width of a bounding box is the difference between its maximum x coordinate (right) and its minimum x coordinate (left).The argument region must be either a bounded region or some other object that obeys the bounding box protocol, such as a sheet.
 See also:
 composerotationwithtransform Generic function¶
Creates a new transform by composing a transform with the given rotation
 Signature:
composerotationwithtransform transform angle #key origin => transform
 Parameters:
transform – An instance of type
<transform>
.angle – An instance of type
<real>
.origin (#key) – An instance of type
<point>
. Default value: (0, 0).
 Values:
transform – An instance of type
<transform>
.
 Discussion:
Creates a new transform by composing the transform transform with the given rotation The order of composition is that the rotation transform is applied first, followed by the argument transform.
Note that this function could be implemented by using
makerotationtransform
andcomposetransforms
. It is provided because it is common to build up a transform as a series of simple transforms. See also:
 composescalingwithtransform Generic function¶
Creates a new transform by composing a transform with the given scaling.
 Signature:
composescalingwithtransform transform scalex scaley #key origin => transform
 Parameters:
transform – An instance of type
<transform>
.scalex – An instance of type
<real>
.scaley – An instance of type
<real>
.origin (#key) – An instance of type
<point>
. Default value: (0, 0).
 Values:
transform – An instance of type
<transform>
.
 Discussion:
Creates a new transform by composing the transform transform with the given scaling. The order of composition is that the scaling transform is applied first, followed by the argument transform.
The argument scalex represents the scaling factor for the x direction.
The argument scaley represents the scaling factor for the y direction.
The argument origin represents the point around which scaling is performed. The default is to scale around the origin.
Note that this function could be implemented by using
makescalingtransform
andcomposetransforms
. It is provided because it is common to build up a transform as a series of simple transforms. See also:
 composetransforms Generic function¶
Returns a transform that is the mathematical composition of its arguments.
 Signature:
composetransforms transform1 transform2 => transform
 Parameters:
transform1 – An instance of type
<transform>
.transform2 – An instance of type
<transform>
.
 Values:
transform – An instance of type
<transform>
.
 Discussion:
Returns a transform that is the mathematical composition of its arguments. Composition is in righttoleft order, that is, the resulting transform represents the effects of applying the transform transform2 followed by the transform transform1.
 See also:
 composetransformwithrotation Generic function¶
Creates a new transform by composing a given rotation with a transform.
 Signature:
composetransformwithrotation transform angle #key origin => transform
 Parameters:
transform – An instance of type
<transform>
.angle – An instance of type
<real>
.origin (#key) – An instance of type
<point>
. Default value: (0,0).
 Values:
transform – An instance of type
<transform>
.
 Discussion:
Creates a new transform by composing a given rotation with the transform transform. The order of composition is transform first, followed by the rotation transform.
The argument angle represents the angle by which to rotate, in radians.
The argument origin represents the point about which to rotate. The default is to rotate around (0,0).
Note that this function could be implemented by using
makerotationtransform
andcomposetransforms
. It is provided because it is common to build up a transform as a series of simple transforms. See also:
 composetransformwithscaling Generic function¶
Creates a new transform by composing a given scaling with a transform.
 Signature:
composetransformwithscaling transform scalex scaley #key origin => transform
 Parameters:
transform – An instance of type
<transform>
.scalex – An instance of type
<real>
.scaley – An instance of type
<real>
.origin (#key) – An instance of type
<point>
. Default value: (0,0).
 Values:
transform – An instance of type
<transform>
.
 Discussion:
Creates a new transform by composing a given scaling with the transform transform. The order of composition is transform first, followed by the scaling transform.
The argument scalex represents the scaling factor for the x direction.
The argument scaley represents the scaling factor for the y direction.
The argument origin represents the point around which scaling is performed. The default is to scale around the origin.
Note that this function could be implemented by using
makescalingtransform
andcomposetransforms
. It is provided because it is common to build up a transform as a series of simple transforms. See also:
 composetransformwithtranslation Generic function¶
Creates a new transform by composing a given translation with a transform.
 Signature:
composetransformwithtranslation transform dx dy => transform
 Parameters:
transform – An instance of type
<transform>
.dx – An instance of type
<real>
.dy – An instance of type
<real>
.
 Values:
transform – An instance of type
<transform>
.
 Discussion:
Creates a new transform by composing a given translation with the transform transform. The order of composition is transform first, followed by the translation transform.
The argument dx represents the delta by which to translate the x coordinate.
The argument dy represents the delta by which to translate the y coordinate.
Note that this function could be implemented by using
maketranslationtransform
andcomposetransforms
. It is provided because it is common to build up a transform as a series of simple transforms. See also:
 composetranslationwithtransform Generic function¶
Creates a new transform by composing a transform with the given translation.
 Signature:
composetranslationwithtransform transform dx dy => transform
 Parameters:
transform – An instance of type
<transform>
.dx – An instance of type
<real>
.dy – An instance of type
<real>
.
 Values:
transform – An instance of type
<transform>
.
 Discussion:
Creates a new transform by composing the transform transform with the given translation. The order of composition is that the translation transform is applied first, followed by the argument transform.
The argument dx represents the delta by which to translate the x coordinate.
The argument dy represents the delta by which to translate the y coordinate.
Note that this function could be implemented by using
maketranslationtransform
andcomposetransforms
. It is provided, because it is common to build up a transform as a series of simple transforms. See also:
 docoordinates Function¶
Applies a function to each coordinate pair in its argument list.
 Signature:
docoordinates function coordinates => ()
 Parameters:
function – An instance of type
<function>
.coordinates – An instance of type
limited(<sequence>, of: <real>)
.
 Discussion:
Applies function to each coordinate pair in coordinates. The length of coordinates must be a multiple of 2. Function takes two arguments, the x and y value of each coordinate pair.
 doendpointcoordinates Function¶
Applies a function to each coordinate pair in its argument list.
 Signature:
doendpointcoordinates function coordinates => ()
 Parameters:
function – An instance of type
<function>
.coordinates – An instance of type
limited(<sequence>, of: <real>)
.
 Discussion:
Applies function to each pair of coordinate pairs in coordinates. The arguments coordinates represents a set of line segments rather than a set of points: The length of this sequence must therefore be a multiple of 4. Function takes 4 arguments, (x1, y1, x2, y2).
 doregions Generic function¶
Calls a function on each region in a set of regions.
 Signature:
doregions function region #key normalize? => ()
 Parameters:
function – An instance of type
<function>
.region – An instance of type
<region>
.normalize? (#key) – An instance of type
<boolean>
. Default value:#f
.
 Discussion:
Calls function on each region in the region set region. This is often more efficient than calling regionsetregions. function is a function of one argument, a region. Region can be either a region set or a simple region, in which case function is called once on region itself. If normalize is supplied, it must be either
#"xbanding"
or#"ybanding"
. If it is#"xbanding"
and all the regions in region are axisaligned rectangles, the result is normalized by merging adjacent rectangles with banding done in the x direction. If it is#"ybanding"
and all the regions in region are rectangles, the result is normalized with banding done in the y direction. Normalizing a region set that is not composed entirely of axisaligned rectangles using x or ybanding causes DUIM to signal the<regionsetnotrectangular>
error.
 evenscalingtransform? Generic function¶
Returns
#t
if the transform transform multiplies all x lengths and y lengths by the same magnitude, otherwise returns#f
. Signature:
evenscalingtransform? transform => boolean
 Parameters:
transform – An instance of type
<transform>
.
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Returns
#t
if the transform transform multiplies all x lengths and y lengths by the same magnitude, otherwise returns#f
.evenscalingtransform?
includes pure reflections through vertical and horizontal lines.
 $everywhere Constant¶
The region that includes all the points on the twodimensional infinite drawing plane.
 $identitytransform Constant¶
An instance of a transform that is guaranteed to be an identity transform, that is, the transform that does nothing.
 Type:
 Discussion:
An instance of a transform that is guaranteed to be an identity transform, that is, the transform that does nothing.
 See also:
 identitytransform? Generic function¶
Returns
#t
if a transform is equal (in the sense oftransformequal
) to the identity transform. Signature:
identitytransform? transform => boolean
 Parameters:
transform – An instance of type
<transform>
.
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Returns
#t
if the transform transform is equal (in the sense oftransformequal
) to the identity transform, otherwise returns#f
. See also:
 inverttransform Generic function¶
Returns a transform that is the inverse of the given transform.
 Signature:
inverttransform transform => transform
 Parameters:
transform – An instance of type
<transform>
.
 Values:
transform – An instance of type
<transform>
.
 Conditions:
If transform is singular,
inverttransform
signals the<singulartransform>
error.Note
With finiteprecision arithmetic there are several lowlevel conditions that might occur during the attempt to invert a singular or almost singular transform. (These include computation of a zero determinant, floatingpoint underflow during computation of the determinant, or floatingpoint overflow during subsequent multiplication.)
inverttransform
signals the<singulartransform>
error for all of these cases. Discussion:
Returns a transform that is the inverse of the transform transform. The result of composing a transform with its inverse is equal to the identity transform.
 See also:
 invertibletransform? Generic function¶
Returns
#t
if the given transform has an inverse. Signature:
invertibletransform? transform => boolean
 Parameters:
transform – An instance of type
<transform>
.
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Returns
#t
if the transform transform has an inverse, otherwise returns#f
. See also:
 $largestcoordinate Constant¶
The largest valid coordinate.
 Type:
<integer>
 Discussion:
The largest valid coordinate.
 See also:
 make3pointtransform Function¶
Returns a transform that takes points point1 into point1image, point2 into point2image and point3 into point3image.
 Signature:
make3pointtransform x1 y1 x2 y2 x3 y3 x1image y1image x2image y2image x3image y3image => transform
 Signature:
make3pointtransform* point1 point2 point3 point1image point2image point3image => transform
The following arguments are specific to
make3pointtransform
. Parameters:
x1 – An instance of type
<real>
.y1 – An instance of type
<real>
.x2 – An instance of type
<real>
.y2 – An instance of type
<real>
.x3 – An instance of type
<real>
.y3 – An instance of type
<real>
.x1image – An instance of type
<real>
.y1image – An instance of type
<real>
.x2image – An instance of type
<real>
.y2image – An instance of type
<real>
.x3image – An instance of type
<real>
.y3image – An instance of type
<real>
.
The following arguments are specific to
make3pointtransform*
. Parameters:
 Values:
transform – An instance of type
<transform>
.
 Conditions:
If point1, point2 and point3 are colinear, the
<transformunderspecified>
error is signalled. If point1image,*point2image* and point3image are colinear, the resulting transform will be singular (that is, will have no inverse) but this is not an error. Discussion:
Returns a transform that takes points point1 into point1image, point2 into point2image and point3 into point3image. Three noncolinear points and their images under the transform are enough to specify any affine transformation.
The function
make3pointtransform*
is identical tomake3pointtransform
, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance.
 makeboundingbox Function¶
Returns an object of the class
<boundingbox>
. Signature:
makeboundingbox x1 y1 x2 y2 => box
 Parameters:
 Values:
box – An instance of type
<boundingbox>
.
 Discussion:
Returns an object of the class
<boundingbox>
with the edges specified by x1, y1, x2, and y2. x1, y1, x2, and y2 are canonicalized in the following way. The min point of the box has an x coordinate that is the smaller of x1 and x2 and a y coordinate that is the smaller of y1 and y2. The max point of the box has an x coordinate that is the larger of x1 and x2 and a y coordinate that is the larger of y1 and y2. (Therefore, in a righthanded coordinate system the canonicalized values of x1, y1, x2, and y2 correspond to the left, top, right, and bottom edges of the box, respectively.)This is a convenient shorthand function for
make(<boundingbox>, left: top: right: bottom:)
.
 makereflectiontransform Function¶
Returns a transform that reflects every point through the line passing through the positions x1,y1 and x2,y2.
 Signature:
makereflectiontransform x1 y1 x2 y2 => transform
 Parameters:
 Values:
transform – An instance of type
<transform>
. The resultant transformation.
 Discussion:
Returns a transform that reflects every point through the line passing through the positions x1,y1 and x2,y2.
The arguments x1 and y1 represent the coordinates of the first point of reflection. The arguments x2 and y2 represent the coordinates of the second point of reflection.
A reflection is a transform that preserves lengths and magnitudes of angles, but changes the sign (or handedness) of angles. If you think of the drawing plane on a transparent sheet of paper, a reflection is a transformation that turns the paper over.
 See also:
 makereflectiontransform Function
Returns a transform that reflects every point through the line passing through the positions x1,y1 and x2,y2 or through the points point1 and point2.
 Signature:
makereflectiontransform* point1 point2 => transform
 Parameters:
 Values:
transform – An instance of type
<transform>
. The resultant transformation.
 Discussion:
Returns a transform that reflects every point through the line passing through the points point1 and point2.
A reflection is a transform that preserves lengths and magnitudes of angles, but changes the sign (or handedness) of angles. If you think of the drawing plane on a transparent sheet of paper, a reflection is a transformation that turns the paper over.
The function
makereflectiontransform*
is identical to :func:makereflectiontransform, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. See also:
 makerotationtransform Function¶
Returns a transform that rotates all points by angle around the point specified by coordinates originx and originy or the point object origin.
 Signature:
makerotationtransform angle #key originx originy => transform
 Signature:
makerotationtransform* angle #key origin => transform
 Parameters:
angle – An instance of type
<real>
.
The following arguments are specific to
makerotationtransform
. Parameters:
The following argument is specific to
makereflectiontransform*
. Parameters:
origin – An instance of type
<point>
. Default value: (0, 0).
 Values:
transform – An instance of type
<transform>
.
 Discussion:
Returns a transform that rotates all points by angle around the point specified by coordinates originx and originy or the point object origin. The angle must be expressed in radians.
A rotation is a transform that preserves length and angles of all geometric entities. Rotations also preserve one point (the origin) and the distance of all entities from that point.
The function makerotationtransform* is identical to makerotationtransform, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance.
 See also:
 makescalingtransform Function¶
Returns a transform that multiplies the x coordinate distance of every point from origin by scalex and the y coordinate distance of every point from origin by scaley.
 Signature:
makescalingtransform scalex scaley #key originx originy => transform
 Signature:
makescalingtransform* scalex scaley #key origin => transform
 Parameters:
The following arguments are specific to
makescalingtransform
. Parameters:
The following argument is specific to
makescalingtransform*
. Parameters:
origin – An instance of type
<point>
.
 Values:
transform – An instance of type
<transform>
. The resultant transformation.
 Discussion:
Returns a transform that multiplies the x coordinate distance of every point from origin by scalex and the y coordinate distance of every point from origin by scaley.
The argument scalex represents the scaling factor for the x direction.
The argument scaley represents the scaling factor for the y direction.
The arguments originx and originy represent the point around which scaling is performed. The default is to scale around the origin.
There is no single definition of a scaling transformation. Transforms that preserve all angles and multiply all lengths by the same factor (preserving the shape of all entities) are certainly scaling transformations. However, scaling is also used to refer to transforms that scale distances in the x direction by one amount and distances in the y direction by another amount.
The function makescalingtransform* is identical to makescalingtransform, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance.
 See also:
 maketransform Function¶
Returns a general affine transform.
 Signature:
maketransform mxx mxy myx myy tx ty => transform
 Parameters:
 Values:
transform – An instance of type
<transform>
.
 Discussion:
Returns a general transform whose effect is:
x'= *mxx* x + *mxy* y + *tx* y'= *myx* x + *myy* y + *ty*
where x and y are the coordinates of a point before the transform and x’ and y’ are the coordinates of the corresponding point after.
All of the arguments to
maketransform
must be real numbers.This is a convenient shorthand for
make(<transform>, ...)
. See also:
 maketranslationtransform Function¶
Returns a transform that translates all points by dx in the x direction and dy in the y direction.
 Signature:
maketranslationtransform dx dy => transform
 Parameters:
 Values:
transform – An instance of type
<transform>
.
 Discussion:
Returns a transform that translates all points by dx in the x direction and dy in the y direction.
The argument dx represents the delta by which to translate the x coordinate.
The argument dy represents the delta by which to translate the y coordinate.
A translation is a transform that preserves length, angle, and orientation of all geometric entities.
 See also:
 $nowhere Constant¶
The empty region, the opposite of
$everywhere
. Type:
 Discussion:
The empty region, the opposite of
$everywhere
. See also:
 <path> Open Abstract Class¶
The class
<path>
denotes bounded regions that have dimensionality 1 (that is, have length).
 path? Generic function¶
Returns
#t
if its argument is a path.
 <point> Open Abstract Instantiable Class¶
The class that corresponds to a mathematical point.
 Superclasses:
 InitKeywords:
 Discussion:
The class that corresponds to a mathematical point.
<point>
is a subclass of<region>
. Thex:
andy:
initkeywords correspond to the x and y coordinates, respectively. Operations:
 point? Generic function¶
Returns true if object is a point.
 pointposition Generic function¶
Returns both the x and y coordinates of a point.
 pointx Generic function¶
Returns the x coordinate of a point.
 pointy Generic function¶
Returns the y coordinate of a point.
 rectilineartransform? Generic function¶
Returns
#t
if a transform always transforms any axisaligned rectangle into another axisaligned rectangle. Signature:
rectilineartransform? transform => boolean
 Parameters:
transform – An instance of type
<transform>
.
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Returns
#t
if the transform transform always transforms any axisaligned rectangle into another axisaligned rectangle, otherwise returns#f
.This category includes scalings as a subset, and also includes 90 degree rotations.
Rectilinear transforms are the most general category of transforms for which the bounding rectangle of a transformed object can be found by transforming the bounding rectangle of the original object.
 reflectiontransform? Generic function¶
Returns
#t
if the transform inverts the handedness of the coordinate system. Signature:
reflectiontransform? transform => boolean
 Parameters:
transform – An instance of type
<transform>
.
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Returns
#t
if the transform transform inverts the handedness of the coordinate system, otherwise returns #f.Note that this is a very inclusive category — transforms are considered reflections even if they distort, scale, or skew the coordinate system, as long as they invert the handedness.
 <reflectionunderspecified> Concrete Sealed Class¶
The error that is signalled when
makereflectiontransform
is given two coincident points. Superclasses:
<transformunderspecified>
 InitKeywords:
points – Instances of type
<point>
.
 Discussion:
The error that is signalled when
makereflectiontransform
is given two coincident points. This condition handles thepoints:
initarg, which is used to supply the points that are in error. See also:
 <region> Open Abstract Class¶
The class that corresponds to a set of points.
 Superclasses:
<object>
 Discussion:
The class that corresponds to a set of points. The:class:<region> class includes both bounded and unbounded regions.
There is no
make
method for<region>
because of the impossibility of a uniform way to specify the arguments to such a function. Operations:
 See also:
 region? Generic function¶
Returns
#t
if its argument is a region.
 regioncontainsposition? Generic function¶
Returns
#t
if the point at x,y is contained in the region. Signature:
regioncontainsposition? region x y => boolean
 Parameters:
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Returns
#t
if the point at x,y is contained in the region region, otherwise returns#f
. Since regions in DUIM are closed, this returns#t
if the point at x,y is on the region’s boundary. See also:
 regioncontainsregion? Generic function¶
Returns
#t
if all points in the second region are members of the first region. Signature:
regioncontainsregion? region1 region2 => boolean
 Parameters:
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Returns
#t
if all points in the region region2 are members of the region region1, otherwise returns#f
.regioncontainsposition?
is a special case ofregioncontainsregion?
in which the region is the point x,y. See also:
 regiondifference Generic function¶
Returns a region that contains all points in the region region1 that are not in the region region2 (possibly plus additional boundary points to make the result closed).
 Signature:
regiondifference region1 region2 => region
 Parameters:
 Values:
region – An instance of type
<region>
.
 Discussion:
Returns a region that contains all points in the region region1 that are not in the region region2 (possibly plus additional boundary points to make the result closed).
The result of
regiondifference
has the same dimensionality as region1, or is$nowhere
. For example, the difference of an area and a path produces the same area; the difference of a path and an area produces the path clipped to stay outside of the area.Note
regiondifference
may return either a simple region or a region set.
 regionempty? Generic function¶
Returns
#t
if the region is empty.
 regionequal Generic function¶
Returns
#t
if the two regions region1 and region2 contain exactly the same set of points. Signature:
regionequal region1 region2 => boolean
 Parameters:
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Returns
#t
if the two regions region1 and region2 contain exactly the same set of points, otherwise returns#f
. There is a method on=
on<region>
and<region>
that callsregionequal
.
 regionintersection Generic function¶
Returns the intersection of two regions, as a region.
 Signature:
regionintersection region1 region2 => region
 Parameters:
 Values:
region – An instance of type
<region>
.
 Discussion:
Returns a region that contains all points that are in both of the regions region1 and region2 (possibly with some points removed in order to satisfy the dimensionality rule).
The result of
regionintersection
has dimensionality that is the minimum dimensionality of region1 and region2, or is$nowhere
. For example, the intersection of two areas is either another area or$nowhere
; the intersection of two paths is either another path or$nowhere
; the intersection of a path and an area produces the path clipped to stay inside of the area.Note
regionintersection
may return either a simple region or a region set. See also:
 regionintersectsregion? Generic function¶
Returns
#f
if two regions do not intersect*.* Signature:
regionintersectsregion? region1 region2 => boolean
 Parameters:
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Returns
#f
ifregionintersection
of the two regions region1 and region2 would be$nowhere
(that is, they do not intersect), otherwise returns #t.
 <regionset> Open Abstract Class¶
The class that represents a region set.
 Superclasses:
 Discussion:
The class that represents a region set; a subclass of
<region>
. Operations:
 See also:
 regionset? Generic function¶
Returns
#t
if its argument is a region set.
 regionsetfunction Generic function¶
Returns the function that composed the region.
 Signature:
regionsetfunction region => function
 Parameters:
region – An instance of type
<region>
.
 Values:
function – An instance of type
<function>
.
 Discussion:
Returns the function that composed the region,
regionintersection
,regionunion
, orregiondifference
.
 regionsetregions Generic function¶
Returns a sequence of the regions in the region set.
 Signature:
regionsetregions region #key normalize? => regions
 Parameters:
region – An instance of type
<region>
.normalize? –
oneof(#f, #"xbanding", #"ybanding")
. Default value:#f
.
 Values:
regions – An instance of type
limited(<sequence>, of: <region>)
.
 Conditions:
Normalizing a region set that is not composed entirely of axisaligned rectangles using x or ybanding causes DUIM to signal the
<regionsetnotrectangular>
error. Discussion:
Returns a sequence of the regions in the region set region. region can be either a region set or a simple region, in which case the result is simply a sequence of one element: region.
For the case of region sets that are unions of axisaligned rectangles, the rectangles returned by
regionsetregions
are guaranteed not to overlap. If normalize? is supplied, it must be either#"xbanding"
or#"ybanding"
. If it is#"xbanding"
and all the regions in region are axisaligned rectangles, the result is normalized by merging adjacent rectangles with banding done in the x direction. If it is#"ybanding"
and all the regions in region are rectangles, the result is normalized with banding done in the y direction.
 regionunion Generic function¶
Returns the union of two regions, as a region.
 Signature:
regionunion region1 region2 => region
 Parameters:
 Values:
region – An instance of type
<region>
.
 Discussion:
Returns a region that contains all points that are in either of the regions region1 or region2 (possibly with some points removed in order to satisfy the dimensionality rule)
The result of
regionunion
always has dimensionality that is the maximum dimensionality of region1 and region2. For example, the union of a path and an area produces an area; the union of two paths is a path.Note
regionunion may return either a simple region or a region set.
 See also:
 rigidtransform? Generic function¶
Returns
#t
if the transform transforms the coordinate system as a rigid object. Signature:
rigidtransform? transform => boolean
 Parameters:
transform – An instance of type
<transform>
.
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Returns
#t
if the transform transforms the coordinate system as a rigid object, that is, as a combination of translations, rotations, and pure reflections. Otherwise, it returns#f
.Rigid transforms are the most general category of transforms that preserve magnitudes of all lengths and angles.
 scalingtransform? Generic function¶
Returns
#t
if the transform transform multiplies all x lengths by one magnitude and all y lengths by another magnitude, otherwise returns#f
. Signature:
scalingtransform? transform => boolean
 Parameters:
transform – An instance of type
<transform>
.
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Returns
#t
if the transform transform multiplies all x lengths by one magnitude and all y lengths by another magnitude, otherwise returns#f
. This category includes even scalings as a subset.
 setboxedges Generic function¶
Sets the edges of a box and returns the bounding box.
 Signature:
setboxedges box left top right bottom => box
 Parameters:
box – An instance of type
<boundingbox>
.left – An instance of type
<integer>
.top – An instance of type
<integer>
.right – An instance of type
<integer>
.bottom – An instance of type
<integer>
.
 Values:
box – An instance of type
<boundingbox>
.
 Discussion:
Sets the edges of a box and returns the bounding box box. This might destructively modify box or it might not, depending on what class box is.
 setboxposition Generic function¶
Sets the position of the bounding box and returns a (possibly new) box.
 Signature:
setboxposition box x y => box
 Parameters:
box – An instance of type
<boundingbox>
.x – An instance of type
<real>
.y – An instance of type
<real>
.
 Values:
box – An instance of type
<boundingbox>
.
 Discussion:
Sets the position of the bounding box box and might or might not modify the box.
 setboxsize Generic function¶
Sets the size (width and height) of the bounding box box.
 Signature:
setboxsize box width height => box
 Parameters:
box – An instance of type
<boundingbox>
.width – An instance of type
<integer>
.height – An instance of type
<integer>
 Values:
box – An instance of type
<boundingbox>
.
 Discussion:
Sets the size (width and height) of the bounding box box.
 <singulartransform> Instantiable Sealed Class¶
The error that is signalled when
inverttransform
is called on a singular transform, that is, a transform that has no inverse. Superclasses:
<transformerror>
 InitKeywords:
transform – Used to supply the transform that is singular.
 Discussion:
The error that is signalled when
inverttransform
is called on a singular transform, that is, a transform that has no inverse.This condition handles the
transform:
initarg, which is used to supply the transform that is singular. See also:
 $smallestcoordinate Constant¶
The smallest valid coordinate.
 Type:
<integer>
 Discussion:
The smallest valid coordinate. Coordinates must be instances of type
<integer>
. See also:
 <transform> Open Abstract Instantiable Class¶
The superclass of all transforms.
 Superclasses:
<object>
 InitKeywords:
 Discussion:
The superclass of all transforms. There are one or more subclasses of
<transform>
with implementationdependent names that implement transforms. The exact names of these classes is explicitly unspecified. All of the instantiable transformation classes provided by DUIM are immutable. Operations:
=
 See also:
 transform? Generic function¶
Returns
#t
if its argument is a transform.
 transformangles Generic function¶
Applies the transform to the start and end angles of an object, and returns the transformed angles.
 Signature:
transformangles transform startangle endangle => newstart newend
 Parameters:
transform – An instance of type
<transform>
.startangle – An instance of type
<real>
.endangle – An instance of type
<real>
.
 Values:
 Discussion:
Applies the transform transform to the angles startangle and endangle of an object, and returns the transformed angles.
 transformbox Generic function¶
Applies the transform to the rectangle specified by the four coordinate arguments.
 Signature:
transformbox transform x1 y1 x2 y2 => left top right bottom
 Parameters:
transform – An instance of type
<transform>
.x1 – An instance of type
<real>
.y1 – An instance of type
<real>
.x2 – An instance of type
<real>
.y2 – An instance of type
<real>
.
 Values:
 Discussion:
Applies the transform transform to the rectangle specified by the four coordinate arguments. transformbox is the spread version of
transformregion
in the case where the transform is rectilinear and the region is a rectangle.The arguments x1, y1, x2, and y2 are canonicalized and the four return values specify the minimum and maximum points of the transformed rectangle in the order left, top, right, and bottom.
An error is signalled if transform does not satisfy
rectilineartransform?
.
 transformdistance Generic function¶
Applies a transform to a distance represented by the coordinate arguments and returns the transformed coordinates.
 Signature:
transformdistance transform dx dy => dx dy
 Parameters:
transform – An instance of type
<transform>
.dx – An instance of type
<real>
.dy – An instance of type
<real>
.
 Values:
 Discussion:
Applies the transform transform to the distance represented by dx and dy, and returns the transformed dx and dy. A distance represents the difference between two points. It does not transform like a point.
 <transformerror> Sealed Class¶
The superclass of all error conditions distributed when there is an error with a transform.
 Superclasses:
<error>
 Discussion:
The class that is the superclass of three error conditions,
<transformunderspecified>
,<reflectionunderspecified>
, and<singulartransform>
.
 transformposition Generic function¶
Applies a transform to the point whose coordinates are x and y.
 Signature:
transformposition transform x y => newx newy
 Parameters:
transform – An instance of type
<transform>
.x – An instance of type
<real>
y – An instance of type
<real>
 Values:
 Discussion:
Applies the transform transform to the point whose coordinates are x and y.
transformposition
is the spread version oftransformregion
in the case where the region is a point.
 transformregion Generic function¶
Applies a transform to a region, and returns the transformed region.
 Signature:
transformregion transform region => region
 Parameters:
transform – An instance of type
<transform>
.region – An instance of type
<region>
.
 Values:
region – An instance of type
<region>
.
 Discussion:
Applies transform to the region region, and returns the transformed region.
 <transformunderspecified> Concrete Sealed Class¶
The error that is signalled when
make3pointtransform
is given three colinear image points. Superclasses:
<transformerror>
 InitKeywords:
points – The points that are in error.
 Discussion:
The error that is signalled when
make3pointtransform
is given three colinear image points. This condition handles thepoints:
initarg, which is used to supply the points that are in error. See also:
 translationtransform? Generic function¶
Returns
#t
if a transform is a pure translation, that is, a transform such that there are two distance components transform dx and dy and every point (x,y) is moved to (x+dx,y+dy). Signature:
translationtransform? transform => boolean
 Parameters:
transform – An instance of type
<transform>
.
 Values:
boolean – An instance of type
<boolean>
.
 Discussion:
Returns
#t
if the transform transform is a pure translation, that is, a transform such that there are two distance components transform dx and dy and every point (x,y) is moved to (x+dx,y+dy). Otherwise, translationtransform? returns#f
.
 untransformangles Generic function¶
Undoes a transform and returns the original start and end angles of the object.
 Signature:
untransformangles transform startangle endangle => origstart origend
 Parameters:
transform – An instance of type
<transform>
.startangle – An instance of type
<real>
.endangle – An instance of type
<real>
.
 Values:
 Conditions:
<singulartransform>
cannot be inverted.
 Discussion:
Undoes the transform transform to the angles newstart and*newend,* returning the original origstart and origend. This is exactly equivalent to:
transformangles(inverttransform(*transform*))
 untransformbox Generic function¶
Undoes the previous transformation on the rectangle left, top and right, bottom, returning the original box.
 Signature:
untransformbox transform x1 y1 x2 y2 => left top right bottom
 Parameters:
transform – An instance of type
<transform>
.x1 – An instance of type
<real>
.y1 – An instance of type
<real>
.x2 – An instance of type
<real>
.y2 – An instance of type
<real>
.
 Values:
 Conditions:
<singulartransform>
cannot be inverted.
 Discussion:
Undoes the previous transformation on the rectangle toplefts, toplefty and bottomrightx, bottomrighty, returning the original box. This is exactly equivalent to:
transformbox(inverttransform(*transform*))
 untransformdistance Generic function¶
Undoes the previous transformation on the distance dx,dy, returning the original dx,dy.
 Signature:
untransformdistance transform dx dy => dx dy
 Parameters:
transform – An instance of type
<transform>
.dx – An instance of type
<real>
.dy – An instance of type
<real>
.
 Values:
 Conditions:
<singulartransform>
cannot be inverted.
 Discussion:
Undoes the previous transformation on the distance dx,dy, returning the original dx,dy. This is exactly equivalent to:
transformposition(inverttransform(*transform*))
 untransformposition Generic function¶
Undoes the previous transformation on the point x,y, returning the original point.
 Signature:
untransformposition transform x y => x y
:parameter transform* An instance of type
<transform>
. :parameter x: An instance of type<real>
. :parameter y: An instance of type<real>
. :value x: An instance of type<real>
. :value y: An instance of type<real>
. Conditions:
<singulartransform>
cannot be inverted.
 Discussion:
Undoes the previous transformation on the point x,y, returning the original point. This is exactly equivalent to:
transformposition(inverttransform(*transform*))
 untransformregion Generic function¶
Undoes the previous transformation on a region, returning the original region.
 Signature:
untransformregion transform region2 => region1
 Parameters:
transform – An instance of type
<transform>
.region2 – An instance of type
<region>
. The region to untransform.
 Values:
region1 – An instance of type
<region>
. The original region.
 Conditions:
<singulartransform>
cannot be inverted.
 Discussion:
Undoes the previous transformation on the region region, returning the original region. This is exactly equivalent to
transformregion(inverttransform(*transform region*))