DUIM-Extended-Geometry Library

Overview

The DUIM-Extended-Geometry library builds on the features provided by the DUIM-Geometry library, and provides more extensive support for coordinate geometry that is only required for more specialist uses. The library contains a single module, duim-extended-geometry, from which all the interfaces described in this chapter are exposed. See DUIM-Extended-Geometry Module that contains complete reference entries for each exposed interface.

The class hierarchy for DUIM-Extended-Geometry

The DUIM-Extended-Geometry library defines no base classes itself, but instead subclasses two classes exposed in the DUIM-Geometry library: <area> and <path>. In each case, these subclasses provide more specialized geometrical tools.

Subclasses of <area>

Three subclasses of <area> are exposed in the DUIM-Extended-Geometry library, each of which provides the ability to create instances of particular shapes. Their usage is relatively obvious.

  • <rectangle> This class is used to create rectangular shapes on a drawable object.

  • <ellipse> This class is used to create elliptical shapes on a drawable object.

  • <polygon> This class is used to create more general polygon shapes on a drawable object.

Subclass of <path>

Three subclasses of <path> are exposed in the DUIM-Extended-Geometry library, each of which provides the ability to create instances of particular types of line. Their usage is relatively obvious.

  • <line> This class is used to create straight lines between two points on a drawable object.

  • <elliptical-arc> This class is used to create elliptical arcs (portions of an ellipse) on a drawable object.

  • <polyline> This class is used to create lines that pass through an arbitrary set of coordinates. It produces a jagged line with vertices at each coordinate.

DUIM-Extended-Geometry Module

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

do-polygon-coordinates Generic function

Applies a function to all of the coordinates of the vertices of a polygon.

Signature:

do-polygon-coordinates function polygon => ()

Parameters:
Discussion:

Applies function to all of the coordinates of the vertices of polygon. function is a function of two arguments, the x and y coordinates of the vertex. do-polygon-coordinates returns #f.

See also:

do-polygon-segments Generic function

Applies a function to the segments that compose a polygon.

Signature:

do-polygon-segments function polygon => ()

Parameters:
Discussion:

Applies function to the segments that compose polygon. function is a function of four arguments, the x and y coordinates of the start of the segment, and the x and y coordinates of the end of the segment. When do-polygon-segments is called on a closed polyline, it calls function on the segment that connects the last point back to the first point.

The function do-polygon-segments returns #f.

See also:

draw-design Generic function

Draws a design on a drawing surface.

Signature:

draw-design drawable design => ()

Parameters:

  • drawable – An instance of type type-union(<sheet>, <medium>).

  • design – A <region> to draw.

Discussion:

Draws design on the sheet medium drawable.

<ellipse> Abstract Instantiable Class

The class that corresponds to an ellipse.

Superclasses:

<area>

Init-Keywords:

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

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

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

  • radius-1-dx – An instance of type <real>

  • radius-1-dy – An instance of type <real>

  • radius-2-dx – An instance of type <real>

  • radius-2-dy – An instance of type <real>

  • start-angle – An instance of false-or(<real>).

  • end-angle – An instance of false-or(<real>).

Discussion:

An ellipse is an area that is the outline and interior of an ellipse. Circles are special cases of ellipses.

The center-x: init-keyword specifies the x coordinate of the center of the ellipse.

The center-y: init-keyword specifies the y coordinate of the center of the ellipse.

The center-point: init-keyword specifies the center of the ellipse as a point.

An ellipse is specified in a manner that is easy to transform, and treats all ellipses on an equal basis. An ellipse is specified by its center point and two vectors that describe a bounding parallelogram of the ellipse. y*c* -dx*1* + dx*2*

Note that several different parallelograms specify the same ellipse. One parallelogram is bound to be a rectangle — the vectors will be perpendicular and correspond to the semi-axes of the ellipse.

Operations:

The following operations are exported from the DUIM-Extended-Geometry module.

The following operations are exported from the DUIM-Geometry module.

See also:

ellipse? Generic function

Returns #t if an object is an ellipse.

Signature:

ellipse? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

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

See also:

ellipse-center-point Generic function

Returns the center point of an ellipse or an elliptical arc.

Signature:

ellipse-center-point elliptical-object => point

Parameters:
Values:

  • point – An instance of type <point>.

Discussion:

Returns the center point of ellipse-object as a <point> object.

See also:

ellipse-center-position Generic function

Returns the coordinates of the center point of an ellipse or an elliptical arc.

Signature:

ellipse-center-position* elliptical-object => x y

Parameters:
Values:

  • x – An instance of type <real>.

  • y – An instance of type <real>.

Discussion:

Returns the coordinates of the center point of elliptical-object.

The arguments x and y represent the x and y coordinates of the center of the elliptical object, respectively.

See also:

ellipse-end-angle Generic function

Returns the end angle of an ellipse or an elliptical-object.

Signature:

ellipse-end-angle elliptical-object => angle

Parameters:

  • elliptical-object – An instance of type type-union(<ellipse>, <elliptical-arc>).

Values:

  • angle – An instance of type false-or(<real>).

Discussion:

Returns the end angle of elliptical-object. If elliptical-object is a full ellipse or closed path then ellipse-end-angle returns #f ; otherwise the value is a number greater than zero, and less than or equal to 2p.

See also:

ellipse-radii Generic function

Returns four values corresponding to the two radius vectors of an elliptical arc.

Signature:

ellipse-radii elliptical-object => r1-dx r1-dy r2-dx d2-dy

Parameters:

  • elliptical-object – An instance of type type-union(<ellipse>, <elliptical-arc>).

Values:

  • r1-dx – An instance of type <real>.

  • r1-dy – An instance of type <real>.

  • r2-dx – An instance of type <real>.

  • d2-dy – An instance of type <real>.

Discussion:

Returns four values corresponding to the two radius vectors of elliptical-object. These values may be canonicalized in some way, and so may not be the same as the values passed to the constructor function.

See also:

ellipse-start-angle Generic function

Returns the start angle of an elliptical arc.

Signature:

ellipse-start-angle elliptical-object => angle

Parameters:

  • elliptical-object – An instance of type type-union(<ellipse>, <elliptical-arc>).

Values:

  • angle – An instance of type false-or(<real>).

Discussion:

Returns the start angle of elliptical-object. If elliptical-object is a full ellipse or closed path then ellipse-start-angle returns #f; otherwise the value will be a number greater than or equal to zero, and less than 2p.

See also:

<elliptical-arc> Abstract Instantiable Class

An elliptical arc is a path consisting of all or a portion of the outline of an ellipse.

Superclasses:

<path>

Init-Keywords:

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

  • center-y – An instance of <real>.

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

  • radius-1-dx – An instance of <real>.

  • radius-1-dy – An instance of <real>.

  • radius-2-dx – An instance of <real>.

  • radius-2-dy – An instance of <real>.

  • start-angle – An instance of false-or(<real>).

  • end-angle – An instance of false-or(<real>).

Discussion:

An elliptical arc is a path consisting of all or a portion of the outline of an ellipse. Circular arcs are special cases of elliptical arcs.

Operations:

The following operations are exported from the DUIM-Extended-Geometry module.

The following operations are exported from the DUIM-Geometry module.

See also:

elliptical-arc? Generic function

Returns #t if an object is an elliptical arc,

Signature:

elliptical-arc? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

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

See also:

<line> Abstract Instantiable Class

The class that corresponds to a line.

Superclasses:

<path>

Init-Keywords:

  • start-x – An instance of <real>.

  • start-y – An instance of <real>.

  • end-x – An instance of <real>.

  • end-y – An instance of <real>.

  • points – Instances of <point>.

Discussion:

The class that corresponds to a line. This is a subclass of <path>.

This is the instantiable class that implements a line segment. make-line instantiates an object of type <line>.

Operations:

The following operations are exported from the DUIM-Extended-Geometry module.

The following operations are exported from the DUIM-Geometry module.

See also:

line? Generic function

Returns #t if an object is a line.

Signature:

line? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

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

line-end-point Generic function

Returns the ending point of a line.

Signature:

line-end-point line => point

Parameters:

  • line – An instance of type <line>.

Values:

  • point – An instance of type <point>.

Discussion:

Returns the ending point of line as a <point> object.

See also:

line-end-position Generic function

Returns the ending point of a line.

Signature:

line-end-position line => x y

Parameters:

  • line – An instance of type <line>.

Values:

  • x – An instance of type <real>.

  • y – An instance of type <real>.

Discussion:

Returns two real numbers representing the x and y coordinates of the ending point of line.

The arguments x and y represent the x and y coordinates of the end of the line, respectively.

See also:

line-start-point Generic function

Returns the starting point of a line.

Signature:

line-start-point line => point

Parameters:

  • line – An instance of type <line>.

Values:

  • point – An instance of type <point>.

Discussion:

Returns the starting point of line as a <point> object.

See also:

line-start-position Generic function

Returns the starting point of a line.

Signature:

line-start-position line => x y

Parameters:

  • line – An instance of type <line>.

Values:

  • x – An instance of type <real>.

  • y – An instance of type <real>.

Discussion:

Returns two real numbers representing the x and y coordinates of the starting point of line.

The arguments x and y represent the x and y coordinates of the start of the line, respectively.

See also:

make-ellipse Function

Returns an object of class <ellipse>.

Signature:

make-ellipse center-x center-y radius-1-dx radius-1-dy radius-2-dx radius-2-dy #key start-angle end-angle => ellipse

Signature:

make-ellipse* center-point radius-1-dx radius-1-dy radius-2-dx radius-2-dy #key start-angle end-angle => ellipse

Parameters:

  • radius-1-dx – An instance of type <real>.

  • radius-1-dy – An instance of type <real>.

  • radius-2-dx – An instance of type <real>.

  • radius-2-dy – An instance of type <real>.

  • start-angle – An instance of type false-or(<real>).

  • end-angle – An instance of type false-or(<real>).

The following arguments are specific to make-ellipse.

Parameters:

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

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

The following argument is specific to make-ellipse.

Parameters:

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

Values:
Discussion:

Returns an object of class <ellipse>. The center of the ellipse is at the position center-x,*center-y* or the point center-point.

Two vectors, (radius-1-dx,radius-1-dy) and (radius-2-dx,radius-2-dy ) specify the bounding parallelogram of the ellipse. All of the radii are real numbers. If the two vectors are colinear, the ellipse is not well-defined and the ellipse-not-well-defined error is signalled. The special case of an ellipse with its axes aligned with the coordinate axes can be obtained by setting both radius-1-dy and radius-2-dx to 0.

If start-angle or end-angle are supplied, the ellipse is the pie slice area swept out by a line from the center of the ellipse to a point on the boundary as the boundary point moves from the angle start-angle to end-angle. Angles are measured counter-clockwise with respect to the positive x axis. If end-angle is supplied, the default for start-angle is 0 ; if start-angle is supplied, the default for end-angle is 2p ; if neither is supplied then the region is a full ellipse and the angles are meaningless.

The function make-ellipse* is identical to make-ellipse, 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-elliptical-arc Function

Returns an object of class <elliptical-arc>.

Signature:

make-elliptical-arc center-x center-y radius-1-dx radius-1-dy radius-2-dx radius-2-dy #key start-angle end-angle => arc

Signature:

make-elliptical-arc* center-point radius-1-dx radius-1-dy radius-2-dx radius-2-dy #key start-angle end-angle => arc

Parameters:

  • radius-1-dx – An instance of type <real>.

  • radius-1-dy – An instance of type <real>.

  • radius-2-dx – An instance of type <real>.

  • radius-2-dy – An instance of type <real>.

  • start-angle – An instance of type false-or(<real>).

  • end-angle – An instance of type false-or(<real>).

The following arguments are specific to make-elliptical-arc.

Parameters:

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

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

The following argument is specific to make-elliptical-arc*.

Parameters:

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

Values:
Discussion:

Returns an object of class <elliptical-arc>. The center of the ellipse is at the position center-x,center-y or the point center-point

Two vectors, (radius-1-dx,radius-1-dy) and (radius-2-dx,radius-2-dy ), specify the bounding parallelogram of the ellipse. All of the radii are real numbers. If the two vectors are colinear, the ellipse is not well-defined and the ellipse-not-well-defined error will be signalled. The special case of an elliptical arc with its axes aligned with the coordinate axes can be obtained by setting both radius-1-dy and radius-2-dx to 0.

If start-angle and end-angle are supplied, the arc is swept from start-angle to end-angle. Angles are measured counter-clockwise with respect to the positive x axis. If end-angle is supplied, the default for start-angle is 0 ; if start-angle is supplied, the default for end-angle is 2p ; if neither is supplied then the region is a closed elliptical path and the angles are meaningless.

The function make-elliptical-arc* is identical to make-elliptical-arc, 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-line Function

Returns an object of class <line>.t

Signature:

make-line start-x start-y end-x end-y => line

Signature:

make-line* start-point end-point => line

Parameters:

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

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

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

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

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

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

Values:

  • line – An instance of type <line>.

Discussion:

Returns an object of class <line> that connects the two positions (start-x,start-y) and (e*nd-x,end-y*) or the two points start-point and end-point.

make-polygon Function

Returns an object of class <polygon>.

Signature:

make-polygon coord-seq => polygon

Signature:

make-polygon* point-seq => polygon

The following argument is specific to make-polygon.

Parameters:

  • coord-seq – An instance of type limited(<sequence>, of: <real>).

The following argument is specific to make-polygon*.

Parameters:

  • point-seq – An instance of type limited(<sequence>, of: <point>).

Values:
Discussion:

Returns an object of class <polygon> consisting of the area contained in the boundary that is specified by the segments connecting each of the points in point-seq or the points represented by the coordinate pairs in coord-seq. point-seq is a sequence of points; coord-seq is a sequence of coordinate pairs, which are real numbers. It is an error if coord-seq does not contain an even number of elements.

The function make-polygon* is identical to make-polygon, 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-polyline Function

Returns an object of class <polyline>.

Signature:

make-polyline coord-seq #key closed? => polyline

Signature:

make-polyline* point-seq #key closed? => polyline

Parameters:

  • closed? – An instance of type <boolean>. Default value: #f.

The following argument is specific to make-polyline.

Parameters:

  • coord-seq – An instance of type limited(<sequence>, of: <real>).

The following argument is specific to make-polyline\*.

Parameters:

  • point-seq – An instance of type limited(<sequence>, of: <point>).

Values:
Discussion:

Returns an object of class <polyline> consisting of the segments connecting each of the points in point-seq or the points represented by the coordinate pairs in coord-seq. point-seq is a sequence of points; coord-seq is a sequence of coordinate pairs, which are real numbers. It is an error if coord-seq does not contain an even number of elements.

If closed? is #t, then the segment connecting the first point and the last point is included in the polyline. The default for closed? is** #f.

The function make-polyline\* is identical to make-polyline, 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-rectangle Function

Returns an object of class <rectangle>.

Signature:

make-rectangle x1 y1 x2 y2 => rectangle

Signature:

make-rectangle* min-point max-point => rectangle

The following arguments are specific to make-rectangle.

Parameters:

  • x1 – An instance of type <real>. The x coordinate of the left top of the rectangle.

  • y1 – An instance of type <real>. The y coordinate of the left top of the rectangle

  • x2 – An instance of type <real>. The x coordinate of the bottom right of the rectangle.

  • y2 – An instance of type <real>. The y coordinate of the bottom right of the rectangle.

The following arguments are specific to make-rectangle\*.

Parameters:

  • min-point – The minimum point (left top) of the rectangle.

  • max-point – The maximum point (bottom right) of the rectangle.

Values:
Discussion:

Returns an object of class <rectangle> whose edges are parallel to the coordinate axes. One corner is at the point point1 or the position*x1,y1* and the opposite corner is at the point point2 or the position x2,y2. There are no ordering constraints among point1 and point2 or x1 and x2, and y1 and y2.

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

<polygon> Abstract Instantiable Class

The class that corresponds to a polygon.

Superclasses:

<area>

Init-Keywords:

  • coordinates – An instance of type limited(<sequence>, of: <real>).

  • points – An instance of type limited(<sequence>, of: <real>).

Discussion:

The class that corresponds to a polygon. This is a subclass of <area>.

A polygon can be described either in terms of the individual x and y coordinates that constitute its vertices, or by using composite points. If the former is used, then they can be specified at the time of creation using the coordinates: init-keyword, which is a sequence of real numbers, with x and y coordinates alternating within the sequence.

To describe a polygon in terms of composite point objects, use the points: init-keyword, which is a sequence of instances of <point>. You should be aware that using composite points may lead to a loss of performance.

Exactly one of coordinates: and points: is required.

Operations:

The following operations are exported from the DUIM-Extended-Geometry module.

The following operations are exported from the DUIM-Geometry module.

See also:

polygon? Generic function

Returns #t if its argument is a polygon.

Signature:

polygon? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

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

See also:

polygon-coordinates Generic function

Returns a sequence of coordinate pairs that specify the segments in a polygon or a polyline.

Signature:

polygon-coordinates polygon-or-polyline => coordinates

Parameters:

  • polygon-or-polyline – An instance of type type-union(<polygon>, <polyline>).

Values:

  • coordinates – An instance of type limited(<sequence>, of: <real>).

Discussion:

Returns a sequence of coordinate pairs that specify the segments in polygon-or-polyline.

See also:

polygon-points Generic function

Returns a sequence of points that specify the segments in a polygon or a polyline.

Signature:

polygon-points polygon-or-polyline => points

Parameters:

  • polygon-or-polyline – An instance of type type-union(<polygon>, <polyline>).

Values:

  • points – An instance of type limited(<sequence>, of: <point>)

Discussion:

Returns a sequence of points that specify the segments in polygon-or-polyline.

See also:

<polyline> Abstract Instantiable Class

The protocol class that corresponds to a polyline.

Superclasses:

<path>

Init-Keywords:

  • coordinates – An instance of type limited(<sequence>, of: <real>). Required.

  • points – An instance of type limited(<sequence>, of: <real>). Required.

Discussion:

The protocol class that corresponds to a polyline.

A polyline can be described either in terms of the individual x and y coordinates that constitute its vertices, or by using composite points. If the former is used, then they can be specified at the time of creation using the coordinates: init-keyword, which is a sequence of real numbers, with x and y coordinates alternating within the sequence.

To describe a polyline in terms of composite point objects, use the points: init-keyword, which is a sequence of instances of <point>. You should be aware that using composite points may lead to a loss of performance.

Exactly one of coordinates: and points: is required.

Operations:

The following operations are exported from the DUIM-Extended-Geometry module.

The following operations are exported from the DUIM-Geometry module.

See also:

polyline? Generic function

Returns #t if an object is a polyline.

Signature:

polyline? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

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

See also:

polyline-closed? Generic function

Returns #t if the polyline is closed.

Signature:

polyline-closed? polyline => boolean

Parameters:
Values:
Discussion:

Returns #t if the polyline polyline is closed, otherwise returns #f. This function need be implemented only for polylines, not for polygons.

See also:

<rectangle> Abstract Instantiable Class

The protocol class that corresponds to a rectangle.

Superclasses:

<area>

Init-Keywords:

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

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

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

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

  • points – An instance of type limited(<sequence>, of: <point>).

Discussion:

The protocol class that corresponds to a rectangle. This is a subclass of <polygon>.

Rectangles whose edges are parallel to the coordinate axes are a special case of polygon that can be specified completely by four real numbers x1,y1,x2,y2). They are not closed under general affine transformations (although they are closed under rectilinear transformations).

Operations:

The following operations are exported from the DUIM-Extended-Geometry module.

The following operations are exported from the DUIM-Geometry module.

See also:

rectangle? Generic function

Returns #t if the object is a rectangle.

Signature:

rectangle? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

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

See also:

rectangle-edges Generic function

Returns the coordinates of the minimum and maximum of the rectangle.

Signature:

rectangle-edges rectangle => x1 y1 x2 y2

Parameters:
Values:

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

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

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

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

Discussion:

Returns the coordinates of the minimum x and y and maximum x and y of the rectangle rectangle as four values, min-x, min-y, max-x, and max-y.

The argument min-x represents the x coordinate of the top left of the rectangle.

The argument min-y represents the y coordinate of the top left of the rectangle.

The argument max-x represents the x coordinate of the bottom right of the rectangle.

The argument max-y represents the y coordinate of the bottom right of the rectangle.

See also:

rectangle-height Generic function

Returns height of the rectangle.

Signature:

rectangle-height rectangle => height

Parameters:
Values:

  • height – An instance of type <real>.

Discussion:

Returns the height of the rectangle, which is the difference between the maximum y and its minimum y.

See also:

rectangle-max-point Generic function

Returns the bottom right point of the rectangle.

Signature:

rectangle-max-point rectangle => point

Parameters:
Values:

  • point – An instance of type <point>.

Discussion:

Returns the bottom right point of the rectangle.

See also:

rectangle-max-position Generic function

Returns the x and y coordinates of the bottom right of the rectangle.

Signature:

rectangle-max-position rectangle => x2 y2

Parameters:
Values:

  • x2 – An instance of type <real>.

  • y2 – An instance of type <real>.

Discussion:

Returns the x and y coordinates of the bottom right of the rectangle.

See also:

rectangle-min-point Generic function

Returns the left top point of the rectangle.

Signature:

rectangle-min-point rectangle => point

Parameters:
Values:

  • point – An instance of type <point>.

Discussion:

Returns the left top point of the rectangle.

See also:

rectangle-min-position Generic function

Returns the x and y coordinates of the left top of the rectangle.

Signature:

rectangle-min-position rectangle => x1 y1

Parameters:
Values:

  • x1 – An instance of type <real>.

  • y1 – An instance of type <real>.

Discussion:

Returns the x and y coordinates of the left top of the rectangle.

See also:

rectangle-size Generic function

Returns the width and the height of the rectangle.

Signature:

rectangle-size rectangle => width height

Parameters:
Values:

  • width – An instance of type <real>.

  • height – An instance of type <real>.

Discussion:

Returns two values, the width and the height.

See also:

rectangle-width Generic function

Returns the width of the rectangle.

Signature:

rectangle-width rectangle => width

Parameters:
Values:

  • width – An instance of type <real>.

Discussion:

Returns the width of the rectangle rectangle, which is the difference between the maximum x and its minimum x.

See also: