2.2 Images: "image.ss"
The image teachpack provides a number of basic image construction functions, along with
combinators for building more complex images out of existing images. Basic images include
various polygons, ellipses and circles, and text, as well as bitmaps (typically bitmaps
come about via the Insert Image... menu item in DrScheme).
Existing images can be rotated, scaled, and overlaid on top of each other.
2.2.1 Basic Images
Constructs a circle with the given radius, height, mode, and color.
Examples: |
| > (circle 30 "outline" "red") |
 |
| > (circle 20 "solid" "blue") |
 |
Constructs an ellipsis with the given width, height, mode, and color.
Examples: |
| > (ellipse 40 20 "outline" "black") |
 |
| > (ellipse 20 40 "solid" "blue") |
 |
Constructs a upward-pointing equilateral triangle.
The side-length argument
determines the
length of the side of the triangle.
Constructs a triangle with a right angle where the two sides adjacent
to the right angle have lengths side-length1 and side-length2.
Creates a triangle with two equal-length sides, of length side-length
where the angle between those sides is angle. The third
leg is straight, horizontally. If the angle is less than
180, then the triangle will point up and if the angle
is more, then the triangle will point down.
Constructs a square.
Examples: |
| > (square 40 "solid" "slateblue") |
 |
| > (square 50 "outline" "darkmagenta") |
 |
Constructs a rectangle with the given width, height, mode, and color.
Constructs a four sided polygon with all equal sides and thus where opposite angles are equal to each
other. The top and bottom pair of angles is
angle and the left and right are
(- 180 angle).
Examples: |
| > (rhombus 40 45 "solid" "magenta") |
 |
| > (rhombus 80 150 "solid" "mediumpurple") |
 |
Constructs a regular polygon with side-count sides.
Constructs a star with five points. The side-length argument
determines the side length of the enclosing pentagon.
Example: |
| > (star 40 "solid" "gray") |
 |
Constructs an arbitrary regular star polygon (a generalization of the regular polygons).
The polygon is enclosed by a regular polygon with side-count sides each
side-length long. The polygon is actually constructed by going from vertex to
vertex around the regular polgon, but skipping over every step-count verticies.
For examples, if side-count is 5 and step-count is 2,
then this function produces a shape just like star.
Constructs a polygon connecting the given verticies.
Examples: |
|
 |
|
 |
Constructs an image representing a line segment that connects the points
(0,0) to (x1,y1).
Adds a line to the image image, starting from the point (x1,y1)
and going to the point (x2,y2).
Examples: |
|
 |
|
 |
Constructs an image that draws the given string, using the font size and color.
Examples: |
| > (text "Hello" 24 "olive") |
 |
| > (text "Goodbye" 36 "indigo") |
 |
| (text/font | | string | | | | | | | | font-size | | | | | | | | color | | | | | | | | face | | | | | | | | family | | | | | | | | style | | | | | | | | weight | | | | | | | | underline?) | | → | | image? |
|
| string : string? |
| font-size : (and/c integer? (<=/c 1 255)) |
| color : color? |
| face : (or/c string? #f) |
| family : (or/c 'default 'decorative 'roman 'script 'swiss 'modern 'symbol 'system) |
| style : (or/c 'normal 'italic 'slant) |
| weight : (or/c 'normal 'bold 'light) |
| underline? : any/c |
Constructs an image that draws the given string, using a complete font specification.
The face and the family combine to give the complete typeface. If
face is available on the system, it is used, but if not then a default typeface
based on the family is chosen. The style controls if the face is italic
or not (under Windows and Mac OS X, 'slant and 'italic are the same),
the weight controls if it is boldface (or light), and underline?
determines if the face is underlined. For more details on these arguments, see font%,
which ultimately is what this code uses to draw the font.
| (bitmap bitmap-spec) |
| |
| bitmap-spec | | = | | rel-string | | | | | | | id |
|
Loads the bitmap specified by bitmap-spec. If bitmap-spec is a string, it is treated as a
relative path. If it is an identifier, it is treated like a require spec and used to refer to a file
in a collection.
Examples: |
| > (bitmap icons/stop-16x16.png) |
 |
| > (bitmap icons/b-run.png) |
 |
2.2.2 Overlaying Images
Overlays all of its arguments building a single image. The first argument goes
on top of the second argument, which goes on top of the third argument, etc.
The images are all lined up on their upper-left corners.
Examples: |
|
 |
|
 |
Overlays all of its image arguments, much like the
overlay function, but using
x-place and
y-place to determine where the images are lined up. For example, if
x-place and
y-place are both
"middle", then the images are lined up
on their centers.
Examples: |
|
 |
|
 |
Constructs an image by overlaying i1 on top of i2 after
shifting i2 over by x pixels to the right and y
pixels down.
Constructs an image by placing all of the argument images in a
horizontal row, aligned along their top edges.
Example: |
|
 |
Constructs an image by placing all of the argument images in a horizontal row, lined
up as indicated by the y-place argument. For example, if y-place
is "middle", then the images are placed side by side with their centers
lined up with each other.
Constructs an image by placing all of the argument images in a
vertical row, aligned along their left edges.
Example: |
|
 |
Constructs an image by placing all of the argument images in a vertical row, lined
up as indicated by the x-place argument. For example, if x-place
is "middle", then the images are placed above each other with their centers
lined up.
Examples: |
|
 |
|
 |
2.2.3 Rotating, Scaling, and Framing Images
Rotates image by angle degrees in a counter-clockwise direction.
Scales image by factor.
Scales image by x-factor horizontally and by
y-factor vertically.
Examples: |
|
 |
| > (ellipse 60 60 "solid" "blue") |
 |
Returns an image just like image, except
with a black, single pixel frame drawn around the
bounding box of the image.
Generally speaking, this function is useful to
debug image constructions, i.e., to see where
certain sub-images appear within some larger image.
Example: |
|
 |
2.2.4 Image Properties
Returns the width of i.
Returns the height of i.
Returns the distance from the top of the image to its baseline.
Unless the image was constructed with
text or
text/font,
this will be the same as its height.
2.2.5 Image Predicates
This section lists predicates for the basic structures provided by the image library.
Additionally, images inserted into a DrScheme window are treated as
bitmap images, as are instances of image-snip% and bitmap%.
Determines if x is a mode suitable for
constructing images. It can be one of
'solid, "solid", 'outline,
or "outline", indicating if the shape is
filled in or not.
Determines if x represents a color. Both strings and symbols are allowed as colors.
For example,
"magenta", "black", 'orange, and 'purple
are allowed. Colors are not case-sensitive, so
"Magenta", "Black", 'Orange, and 'Purple
are also allowed, and are the same colors as in the previous sentence.
If a color is not recognized, black is used in its place.
The complete list of colors is available in the documentation for
color-database<%>.
Determines if x is a placement option
for the vertical direction. It can be one
of
"top",
'top,
"bottom",
'bottom,
"middle",
'middle,
"center",
'center,
"baseline", or
'baseline.
The baseline of an image is the place where the bottoms any letters line up, not counting descenders, e.g. the tail on “y” or “g” or “j”.
Determines if x is a placement option
for the horizontal direction. It can be one
of "left",
'left,
"right",
'right,
"middle",
'middle,
"center", or
'center.
Determines if x is an angle, namely
a real number between 0 (inclusive)
and 360 (exclusive).
Determines if x is an integer
greater than or equal to 3.
2.2.6 Equality Testing of Images
Image equality testing is done structurally, i.e., based on
the construction of the image,
although with certain, expected equivalences. For example,
two rectangles with the same width, height, color, and mode
are equal. Similarly, constructing a 20x10 rectangle and
then rotating it by 90 degress is equal to a 10x20 rectangle
(provided they have the same color and mode).
Equality testing may contain a few nuances, though:
Overlaying two images in opposite orders is never equal. For example,
these two images are not equal:
even thought they may appear to be the same when drawn.
The rationale for them being different is that, at some scale factor,
they will draw differently; specifically when they are scaled down
far enough, the first will appear to be a single red pixel and the second will appear to
be a single blue pixel.
When rotating images, the internal calculations involve real numbers, not just
rationals and thus must be approximated with Scheme’s inexact numbers, causing
small roundoff errors that make the images draw slightly differently.
To combat this problem, use equal~? to compare the images,
or check-within for test suites involving images.
Combining a series of line segments to form a polygon produces
an image that is different than the polygon.
In order to make equality on images created with
text and
text/font
work well, each string passed to either of those functions results
in a number of horizontally aligned images, one for each letter in the
string. This means that, for example
is true, but that subtle aspects of font drawing may be wrong, since
the underlying toolkit only gets a single letter at a time, instead
of the entire word (or sentence).
The most obvious way that this shows up is in the handling of ligatures.
For example, the letter combinations “ff” and “fi” and “fl” are
generally drawn intertwined when they appear together, and thus an “f”
drawn separately from an “i” looks different than the ligature “fi”.
For example, here is how 24 point Times font looks when the word “refill”
is drawn, first with ligatures and then without:
.
.