DUIM-Geometry Library

Overview

The DUIM-Geometry 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, duim-geometry, from which all the interfaces described in this chapter are exposed. DUIM-Geometry Module contains complete reference entries for each exposed interface.

The class hierarchy for DUIM-Geometry

The base classes for classes in the DUIM-Geometry 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 implementation-dependent 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 DUIM-Geometry 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 DUIM-Geometry library, although the DUIM-Extended-Geometry library exposes some subclasses of <area> and <path>.

<region>

<region-set>

<point>

<path>

<area>

<bounding-box>

  • <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).

  • <region-set> 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).

  • <bounding-box> A bounding box is an axis aligned rectangle that contains some region.

Error classes provided by DUIM-Geometry

The DUIM-Geometry 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 <transform-error> are all specific to particular errors.

<transform-error>

<transform-underspecified>

<reflection-<underspecified>

<singular-transform>

DUIM-Geometry Module

This section contains a complete reference of all the interfaces that are exported from the duim-geometry module.

=(<region>) Method

Tests if its arguments are equal.

Signature:

= region1 region2 => boolean

Parameters:

  • region1 – An instance of type <region>.

  • region2 – An instance of type <region>.

Values:
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:
Values:
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:

<region>

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 make-rectangle 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.

Signature:

area? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if object is an area, otherwise returns #f.

See also:

<bounding-box> Open Abstract Instantiable Class

The class that represents a bounding box.

Superclasses:

<region>

Init-Keywords:
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 rectilinear-transformation?.

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:

bounding-box? Generic function

Returns true if its argument is a bounding box.

Signature:

bounding-box? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if object is a bounding box (that is, supports the bounding box protocol), otherwise returns #f.

See also:

bounding-box Generic function

Returns the bounding box of a region.

Signature:

bounding-box region #key into => box

Parameters:

  • region – An instance of type <region>.

  • into – An instance of type false-or(<bounding-box>).

Values:
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:

box-bottom Function

Returns the y coordinate of the bottom right corner of the bounding box of a region.

Signature:

box-bottom region => bottom

Parameters:

  • region – An instance of type <region>.

Values:
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:

box-edges Generic function

Returns the bounding box of a region.

Signature:

box-edges 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:

box-height Function

Returns the height of the bounding box of a region.

Signature:

box-height region => height

Parameters:

  • region – An instance of type <region>.

Values:
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:

box-left Function

Returns the x coordinate of the upper left corner of the bounding box of a region.

Signature:

box-left region => left

Parameters:

  • region – An instance of type <region>.

Values:
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:

box-position Generic function

Returns the position of the bounding box of a region as two values.

Signature:

box-position 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:

box-right Function

Returns the x coordinate of the bottom right corner of the bounding box of a region.

Signature:

box-right region => right

Parameters:

  • region – An instance of type <region>.

Values:
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:

box-size Generic function

Returns the width and height of the bounding box of a region as two values

Signature:

box-size 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:

box-top Function

Returns the y coordinate of the upper left corner of the bounding box of a region.

Signature:

box-top region => top

Parameters:

  • region – An instance of type <region>.

Values:
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:

box-width Function

Returns the width of the bounding box of a region.

Signature:

box-width region => width

Parameters:

  • region – An instance of type <region>.

Values:
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:

compose-rotation-with-transform Generic function

Creates a new transform by composing a transform with the given rotation

Signature:

compose-rotation-with-transform 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:
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 make-rotation-transform and compose-transforms. It is provided because it is common to build up a transform as a series of simple transforms.

See also:

compose-scaling-with-transform Generic function

Creates a new transform by composing a transform with the given scaling.

Signature:

compose-scaling-with-transform transform scale-x scale-y #key origin => transform

Parameters:

  • transform – An instance of type <transform>.

  • scale-x – An instance of type <real>.

  • scale-y – An instance of type <real>.

  • origin (#key) – An instance of type <point>. Default value: (0, 0).

Values:
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 scale-x represents the scaling factor for the x direction.

The argument scale-y 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 make-scaling-transform and compose-transforms. It is provided because it is common to build up a transform as a series of simple transforms.

See also:

compose-transforms Generic function

Returns a transform that is the mathematical composition of its arguments.

Signature:

compose-transforms transform1 transform2 => transform

Parameters:
Values:
Discussion:

Returns a transform that is the mathematical composition of its arguments. Composition is in right-to-left order, that is, the resulting transform represents the effects of applying the transform transform2 followed by the transform transform1.

See also:

compose-transform-with-rotation Generic function

Creates a new transform by composing a given rotation with a transform.

Signature:

compose-transform-with-rotation 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:
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 make-rotation-transform and compose-transforms. It is provided because it is common to build up a transform as a series of simple transforms.

See also:

compose-transform-with-scaling Generic function

Creates a new transform by composing a given scaling with a transform.

Signature:

compose-transform-with-scaling transform scale-x scale-y #key origin => transform

Parameters:

  • transform – An instance of type <transform>.

  • scale-x – An instance of type <real>.

  • scale-y – An instance of type <real>.

  • origin (#key) – An instance of type <point>. Default value: (0,0).

Values:
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 scale-x represents the scaling factor for the x direction.

The argument scale-y 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 make-scaling-transform and compose-transforms. It is provided because it is common to build up a transform as a series of simple transforms.

See also:

compose-transform-with-translation Generic function

Creates a new transform by composing a given translation with a transform.

Signature:

compose-transform-with-translation transform dx dy => transform

Parameters:

  • transform – An instance of type <transform>.

  • dx – An instance of type <real>.

  • dy – An instance of type <real>.

Values:
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 make-translation-transform and compose-transforms. It is provided because it is common to build up a transform as a series of simple transforms.

See also:

compose-translation-with-transform Generic function

Creates a new transform by composing a transform with the given translation.

Signature:

compose-translation-with-transform transform dx dy => transform

Parameters:

  • transform – An instance of type <transform>.

  • dx – An instance of type <real>.

  • dy – An instance of type <real>.

Values:
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 make-translation-transform and compose-transforms. It is provided, because it is common to build up a transform as a series of simple transforms.

See also:

do-coordinates Function

Applies a function to each coordinate pair in its argument list.

Signature:

do-coordinates 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.

do-endpoint-coordinates Function

Applies a function to each coordinate pair in its argument list.

Signature:

do-endpoint-coordinates 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).

do-regions Generic function

Calls a function on each region in a set of regions.

Signature:

do-regions 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 region-set-regions. 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 #"x-banding" or #"y-banding". If it is #"x-banding" and all the regions in region are axis-aligned rectangles, the result is normalized by merging adjacent rectangles with banding done in the x direction. If it is #"y-banding" 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 axis-aligned rectangles using x- or y-banding causes DUIM to signal the <region-set-not-rectangular> error.

even-scaling-transform? Generic function

Returns #t if the transform transform multiplies all x lengths and y lengths by the same magnitude, otherwise returns #f.

Signature:

even-scaling-transform? transform => boolean

Parameters:
Values:
Discussion:

Returns #t if the transform transform multiplies all x lengths and y lengths by the same magnitude, otherwise returns #f. even-scaling-transform? includes pure reflections through vertical and horizontal lines.

$everywhere Constant

The region that includes all the points on the two-dimensional infinite drawing plane.

Type:

<region>

Discussion:

The region that includes all the points on the two-dimensional infinite drawing plane.

See also:

fix-coordinate Function

Coerces the given coordinate into an <integer>.

Signature:

fix-coordinate coordinate => integer

Parameters:

  • coordinate – An instance of type <real>.

Values:
Discussion:

Coerces the given coordinate into an <integer>.

$identity-transform Constant

An instance of a transform that is guaranteed to be an identity transform, that is, the transform that does nothing.

Type:

<transform>

Discussion:

An instance of a transform that is guaranteed to be an identity transform, that is, the transform that does nothing.

See also:

identity-transform? Generic function

Returns #t if a transform is equal (in the sense of transform-equal) to the identity transform.

Signature:

identity-transform? transform => boolean

Parameters:
Values:
Discussion:

Returns #t if the transform transform is equal (in the sense of transform-equal) to the identity transform, otherwise returns #f.

See also:

invert-transform Generic function

Returns a transform that is the inverse of the given transform.

Signature:

invert-transform transform => transform

Parameters:
Values:
Conditions:

If transform is singular, invert-transform signals the <singular-transform> error.

Note

With finite-precision arithmetic there are several low-level conditions that might occur during the attempt to invert a singular or almost singular transform. (These include computation of a zero determinant, floating-point underflow during computation of the determinant, or floating-point overflow during subsequent multiplication.) invert-transform signals the <singular-transform> 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:

invertible-transform? Generic function

Returns #t if the given transform has an inverse.

Signature:

invertible-transform? transform => boolean

Parameters:
Values:
Discussion:

Returns #t if the transform transform has an inverse, otherwise returns #f.

See also:

$largest-coordinate Constant

The largest valid coordinate.

Type:

<integer>

Discussion:

The largest valid coordinate.

See also:

make-3-point-transform Function

Returns a transform that takes points point-1 into point-1-image, point-2 into point-2-image and point-3 into point-3-image.

Signature:

make-3-point-transform x1 y1 x2 y2 x3 y3 x1-image y1-image x2-image y2-image x3-image y3-image => transform

Signature:

make-3-point-transform* point-1 point-2 point-3 point-1-image point-2-image point-3-image => transform

The following arguments are specific to make-3-point-transform.

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>.

  • x1-image – An instance of type <real>.

  • y1-image – An instance of type <real>.

  • x2-image – An instance of type <real>.

  • y2-image – An instance of type <real>.

  • x3-image – An instance of type <real>.

  • y3-image – An instance of type <real>.

The following arguments are specific to make-3-point-transform*.

Parameters:

  • point-1 – An instance of type <point>.

  • point-2 – An instance of type <point>.

  • point-3 – An instance of type <point>.

  • point-1-image – An instance of type <point>.

  • point-2-image – An instance of type <point>.

  • point-3-image – An instance of type <point>.

Values:
Conditions:

If point-1, point-2 and point-3 are colinear, the <transform-underspecified> error is signalled. If point-1-image,*point-2-image* and point-3-image 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 point-1 into point-1-image, point-2 into point-2-image and point-3 into point-3-image. Three non-colinear points and their images under the transform are enough to specify any affine transformation.

The function make-3-point-transform* is identical to make-3-point-transform, 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.

make-bounding-box Function

Returns an object of the class <bounding-box>.

Signature:

make-bounding-box x1 y1 x2 y2 => box

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>.

Values:
Discussion:

Returns an object of the class <bounding-box> 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 right-handed 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(<bounding-box>, left: top: right: bottom:).

make-point Function

Returns an object of class <point>.

Signature:

make-point x y => point

Parameters:
Values:

  • point – An instance of type <point>.

Discussion:

Returns an object of class <point> whose coordinates are x and y.

make-reflection-transform Function

Returns a transform that reflects every point through the line passing through the positions x1,y1 and x2,y2.

Signature:

make-reflection-transform x1 y1 x2 y2 => transform

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>.

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:

make-reflection-transform 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:

make-reflection-transform* point-1 point-2 => transform

Parameters:

  • point1 – An instance of type <point>. The first point.

  • point2 – An instance of type <point>. The second point.

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 make-reflection-transform* is identical to :func:make-reflection-transform, 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:

make-rotation-transform Function

Returns a transform that rotates all points by angle around the point specified by coordinates origin-x and origin-y or the point object origin.

Signature:

make-rotation-transform angle #key origin-x origin-y => transform

Signature:

make-rotation-transform* angle #key origin => transform

Parameters:

  • angle – An instance of type <real>.

The following arguments are specific to make-rotation-transform.

Parameters:

  • origin-x – An instance of type <real>. Default value: 0.

  • origin-y – An instance of type <real>. Default value: 0.

The following argument is specific to make-reflection-transform*.

Parameters:

  • origin – An instance of type <point>. Default value: (0, 0).

Values:
Discussion:

Returns a transform that rotates all points by angle around the point specified by coordinates origin-x and origin-y 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 make-rotation-transform* is identical to make-rotation-transform, 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:

make-scaling-transform Function

Returns a transform that multiplies the x -coordinate distance of every point from origin by scale-x and the y -coordinate distance of every point from origin by scale-y.

Signature:

make-scaling-transform scale-x scale-y #key origin-x origin-y => transform

Signature:

make-scaling-transform* scale-x scale-y #key origin => transform

Parameters:

  • scale-x – An instance of type <real>.

  • scale-y – An instance of type <real>.

The following arguments are specific to make-scaling-transform.

Parameters:

  • origin-x – An instance of type <real>. Default value: 0.

  • origin-y – An instance of type <real>. Default value: 0.

The following argument is specific to make-scaling-transform*.

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 scale-x and the y -coordinate distance of every point from origin by scale-y.

The argument scale-x represents the scaling factor for the x direction.

The argument scale-y represents the scaling factor for the y direction.

The arguments origin-x and origin-y 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 make-scaling-transform* is identical to make-scaling-transform, 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:

make-transform Function

Returns a general affine transform.

Signature:

make-transform mxx mxy myx myy tx ty => transform

Parameters:

  • mxx – An instance of type <real>.

  • mxy – An instance of type <real>.

  • myx – An instance of type <real>.

  • myy – An instance of type <real>.

  • tx – An instance of type <real>.

  • ty – An instance of type <real>.

Values:
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 make-transform must be real numbers.

This is a convenient shorthand for make(<transform>, ...).

See also:

make-translation-transform Function

Returns a transform that translates all points by dx in the x direction and dy in the y direction.

Signature:

make-translation-transform dx dy => transform

Parameters:

  • dx – An instance of type <real>.

  • dy – An instance of type <real>.

Values:
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:

<region>

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).

Superclasses:

<region>

Discussion:

The class <path> denotes bounded regions that have dimensionality 1 (that is, have length).

<path> is a subclass of <region>.

Constructing a <path> object with no length (via make-line*, for example) may canonicalize it to $nowhere.

Operations:

See also:

path? Generic function

Returns #t if its argument is a path.

Signature:

path? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if object is a path, otherwise returns #f.

See also:

<point> Open Abstract Instantiable Class

The class that corresponds to a mathematical point.

Superclasses:

<region>

Init-Keywords:
Discussion:

The class that corresponds to a mathematical point. <point> is a subclass of <region>. The x: and y: init-keywords correspond to the x and y coordinates, respectively.

Operations:

point? Generic function

Returns true if object is a point.

Signature:

point? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if object is a point.

point-position Generic function

Returns both the x and y coordinates of a point.

Signature:

point-position point => x y

Parameters:

  • point – An instance of type <point>.

Values:

  • x – An instance of type <real>.

  • y – An instance of type <real>.

Discussion:

Returns both the x and y coordinates of the point point as two values.

See also:

point-x Generic function

Returns the x coordinate of a point.

Signature:

point-x point => x

Parameters:

  • point – An instance of type <point>.

Values:

  • x – An instance of type <real>.

Discussion:

Returns the x coordinate of point.

See also:

point-y Generic function

Returns the y coordinate of a point.

Signature:

point-y point => y

Parameters:

  • point – An instance of type <point>.

Values:

  • y – An instance of type <real>

Discussion:

Returns the y coordinate of point.

See also:

rectilinear-transform? Generic function

Returns #t if a transform always transforms any axis-aligned rectangle into another axis-aligned rectangle.

Signature:

rectilinear-transform? transform => boolean

Parameters:
Values:
Discussion:

Returns #t if the transform transform always transforms any axis-aligned rectangle into another axis-aligned 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.

reflection-transform? Generic function

Returns #t if the transform inverts the handedness of the coordinate system.

Signature:

reflection-transform? transform => boolean

Parameters:
Values:
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.

<reflection-underspecified> Concrete Sealed Class

The error that is signalled when make-reflection-transform is given two coincident points.

Superclasses:

<transform-underspecified>

Init-Keywords:

  • points – Instances of type <point>.

Discussion:

The error that is signalled when make-reflection-transform is given two coincident points. This condition handles the points: 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.

Signature:

region? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if object is a region, otherwise returns``#f``.

See also:

region-contains-position? Generic function

Returns #t if the point at x,y is contained in the region.

Signature:

region-contains-position? region x y => boolean

Parameters:

  • region – An instance of type <region>.

  • x – An instance of type <real>.

  • y – An instance of type <real>.

Values:
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:

region-contains-region? Generic function

Returns #t if all points in the second region are members of the first region.

Signature:

region-contains-region? region1 region2 => boolean

Parameters:

  • region1 – An instance of type <region>.

  • region2 – An instance of type <region>.

Values:
Discussion:

Returns #t if all points in the region region2 are members of the region region1, otherwise returns #f. region-contains-position? is a special case of region-contains-region? in which the region is the point x,y.

See also:

region-difference 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:

region-difference region1 region2 => region

Parameters:

  • region1 – An instance of type <region>.

  • region2 – An instance of type <region>.

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 region-difference 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

region-difference may return either a simple region or a region set.

region-empty? Generic function

Returns #t if the region is empty.

Signature:

region-empty? region => boolean

Parameters:

  • region – An instance of type <region>.

Values:
Discussion:

Returns #t if the region is empty, otherwise returns #f.

region-equal Generic function

Returns #t if the two regions region1 and region2 contain exactly the same set of points.

Signature:

region-equal region1 region2 => boolean

Parameters:

  • region1 – An instance of type <region>.

  • region2 – An instance of type <region>.

Values:
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 calls region-equal.

region-intersection Generic function

Returns the intersection of two regions, as a region.

Signature:

region-intersection region1 region2 => region

Parameters:

  • region1 – An instance of type <region>.

  • region2 – An instance of type <region>.

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 region-intersection 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

region-intersection may return either a simple region or a region set.

See also:

region-intersects-region? Generic function

Returns #f if two regions do not intersect*.*

Signature:

region-intersects-region? region1 region2 => boolean

Parameters:

  • region1 – An instance of type <region>.

  • region2 – An instance of type <region>.

Values:
Discussion:

Returns #f if region-intersection of the two regions region1 and region2 would be $nowhere (that is, they do not intersect), otherwise returns #t.

<region-set> Open Abstract Class

The class that represents a region set.

Superclasses:

<region>

Discussion:

The class that represents a region set; a subclass of <region>.

Operations:

See also:

region-set? Generic function

Returns #t if its argument is a region set.

Signature:

region-set? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if object is a region set, otherwise returns #f.

See also:

region-set-function Generic function

Returns the function that composed the region.

Signature:

region-set-function region => function

Parameters:

  • region – An instance of type <region>.

Values:
Discussion:

Returns the function that composed the region, region-intersection, region-union, or region-difference.

region-set-regions Generic function

Returns a sequence of the regions in the region set.

Signature:

region-set-regions region #key normalize? => regions

Parameters:

  • region – An instance of type <region>.

  • normalize? – one-of(#f, #"x-banding", #"y-banding"). Default value: #f.

Values:

  • regions – An instance of type limited(<sequence>, of: <region>).

Conditions:

Normalizing a region set that is not composed entirely of axis-aligned rectangles using x- or y-banding causes DUIM to signal the <region-set-not-rectangular> 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 axis-aligned rectangles, the rectangles returned by region-set-regions are guaranteed not to overlap. If normalize? is supplied, it must be either #"x-banding" or #"y-banding". If it is #"x-banding" and all the regions in region are axis-aligned rectangles, the result is normalized by merging adjacent rectangles with banding done in the x direction. If it is #"y-banding" and all the regions in region are rectangles, the result is normalized with banding done in the y direction.

region-union Generic function

Returns the union of two regions, as a region.

Signature:

region-union region1 region2 => region

Parameters:

  • region1 – An instance of type <region>.

  • region2 – An instance of type <region>.

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 region-union 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

region-union may return either a simple region or a region set.

See also:

rigid-transform? Generic function

Returns #t if the transform transforms the coordinate system as a rigid object.

Signature:

rigid-transform? transform => boolean

Parameters:
Values:
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.

scaling-transform? 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:

scaling-transform? transform => boolean

Parameters:
Values:
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.

set-box-edges Generic function

Sets the edges of a box and returns the bounding box.

Signature:

set-box-edges box left top right bottom => box

Parameters:
Values:
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.

set-box-position Generic function

Sets the position of the bounding box and returns a (possibly new) box.

Signature:

set-box-position box x y => box

Parameters:
Values:
Discussion:

Sets the position of the bounding box box and might or might not modify the box.

set-box-size Generic function

Sets the size (width and height) of the bounding box box.

Signature:

set-box-size box width height => box

Parameters:
Values:
Discussion:

Sets the size (width and height) of the bounding box box.

<singular-transform> Instantiable Sealed Class

The error that is signalled when invert-transform is called on a singular transform, that is, a transform that has no inverse.

Superclasses:

<transform-error>

Init-Keywords:

  • transform – Used to supply the transform that is singular.

Discussion:

The error that is signalled when invert-transform 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:

$smallest-coordinate 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>

Init-Keywords:

  • mxx – An instance of type <real>.

  • mxy – An instance of type <real>.

  • myx – An instance of type <real>.

  • myy – An instance of type <real>.

  • tx – An instance of type <real>.

  • ty – An instance of type <real>.

Discussion:

The superclass of all transforms. There are one or more subclasses of <transform> with implementation-dependent 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.

Signature:

transform? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if object is a transform, otherwise returns #f.

See also:

transform-angles Generic function

Applies the transform to the start and end angles of an object, and returns the transformed angles.

Signature:

transform-angles transform start-angle end-angle => new-start new-end

Parameters:

  • transform – An instance of type <transform>.

  • start-angle – An instance of type <real>.

  • end-angle – An instance of type <real>.

Values:

  • new-start – An instance of type <real>.

  • new-end – An instance of type <real>.

Discussion:

Applies the transform transform to the angles start-angle and end-angle of an object, and returns the transformed angles.

transform-box Generic function

Applies the transform to the rectangle specified by the four coordinate arguments.

Signature:

transform-box 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:

  • left – An instance of type <real>.

  • top – An instance of type <real>.

  • right – An instance of type <real>.

  • bottom – An instance of type <real>.

Discussion:

Applies the transform transform to the rectangle specified by the four coordinate arguments. transform-box is the spread version of transform-region 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 rectilinear-transform?.

transform-distance Generic function

Applies a transform to a distance represented by the coordinate arguments and returns the transformed coordinates.

Signature:

transform-distance 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:

  • dx – An instance of type <real>.

  • dy – An instance of type <real>.

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.

<transform-error> 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, <transform-underspecified>, <reflection-underspecified>, and <singular-transform>.

transform-position Generic function

Applies a transform to the point whose coordinates are x and y.

Signature:

transform-position transform x y => new-x new-y

Parameters:
Values:

  • new-x – An instance of type <real>

  • new-y – An instance of type <real>

Discussion:

Applies the transform transform to the point whose coordinates are x and y. transform-position is the spread version of transform-region in the case where the region is a point.

transform-region Generic function

Applies a transform to a region, and returns the transformed region.

Signature:

transform-region transform region => region

Parameters:
Values:

  • region – An instance of type <region>.

Discussion:

Applies transform to the region region, and returns the transformed region.

<transform-underspecified> Concrete Sealed Class

The error that is signalled when make-3-point-transform is given three colinear image points.

Superclasses:

<transform-error>

Init-Keywords:

  • points – The points that are in error.

Discussion:

The error that is signalled when make-3-point-transform is given three colinear image points. This condition handles the points: initarg, which is used to supply the points that are in error.

See also:

translation-transform? 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:

translation-transform? transform => boolean

Parameters:
Values:
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, translation-transform? returns #f.

untransform-angles Generic function

Undoes a transform and returns the original start and end angles of the object.

Signature:

untransform-angles transform start-angle end-angle => orig-start orig-end

Parameters:

  • transform – An instance of type <transform>.

  • start-angle – An instance of type <real>.

  • end-angle – An instance of type <real>.

Values:

  • orig-start – An instance of type <real>.

  • orig-end – An instance of type <real>.

Conditions:

Discussion:

Undoes the transform transform to the angles new-start and*new-end,* returning the original orig-start and orig-end. This is exactly equivalent to:

transform-angles(invert-transform(*transform*))

untransform-box Generic function

Undoes the previous transformation on the rectangle left, top and right, bottom, returning the original box.

Signature:

untransform-box 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:

  • left – An instance of type <real>.

  • top – An instance of type <real>.

  • right – An instance of type <real>.

  • bottom – An instance of type <real>.

Conditions:

Discussion:

Undoes the previous transformation on the rectangle top-left-s, top-left-y and bottom-right-x, bottom-right-y, returning the original box. This is exactly equivalent to:

transform-box(invert-transform(*transform*))

untransform-distance Generic function

Undoes the previous transformation on the distance dx,dy, returning the original dx,dy.

Signature:

untransform-distance 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:

  • dx – An instance of type <real>.

  • dy – An instance of type <real>.

Conditions:

Discussion:

Undoes the previous transformation on the distance dx,dy, returning the original dx,dy. This is exactly equivalent to:

transform-position(invert-transform(*transform*))

untransform-position Generic function

Undoes the previous transformation on the point x,y, returning the original point.

Signature:

untransform-position 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:

Discussion:

Undoes the previous transformation on the point x,y, returning the original point. This is exactly equivalent to:

transform-position(invert-transform(*transform*))

untransform-region Generic function

Undoes the previous transformation on a region, returning the original region.

Signature:

untransform-region 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:

Discussion:

Undoes the previous transformation on the region region, returning the original region. This is exactly equivalent to

transform-region(invert-transform(*transform region*))