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 DrRacket).
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.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Examples: |
| > (circle 30 "outline" "red") |
 |
| > (circle 20 "solid" "blue") |
 |
Constructs an ellipsis with the given width, height, mode, and color.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Examples: |
| > (ellipse 40 20 "outline" "black") |
 |
| > (ellipse 20 40 "solid" "blue") |
 |
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).
Unlike
scene+line, if the line passes outside of
image, the image
gets larger to accomodate the line.
Adds a curve to image, starting at the point
(x1,y1), and ending at the point
(x2,y2).
The angle1 and angle2 arguments specify the
angle that the curve has as it leaves the initial point and
as it reaches the final point, respectively.
The pull1 and pull2 arguments control how
long the curve tries to stay with that angle. Larger numbers
mean that the curve stays with the angle longer.
Unlike scene+curve, if the line passes outside of image, the image
gets larger to accomodate the curve.
Constructs an image that draws the given string, using the font size and color.
Examples: |
| > (text "Hello" 24 "olive") |
 |
| > (text "Goodbye" 36 "indigo") |
 |
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 Polygons
Constructs a upward-pointing equilateral triangle.
The side-length argument
determines the
length of the side of the triangle.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Constructs a triangle with a right angle where the two sides adjacent
to the right angle have lengths side-length1 and side-length2.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
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.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
To create a general triangle given known sides and angles the following
family of functions are useful: triangle/sss,
triangle/ass, triangle/sas, triangle/ssa,
triangle/sss, triangle/sss, and, triangle/sss.
They all construct a triangle oriented as follows:
Creates a triangle where the side lengths a, b, and, c are given by side-length-a,
side-length-b, and, side-length-c respectively.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Creates a triangle where the angle A and side length a and b, are given by angle-a,
side-length-b, and, side-length-c respectively.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Creates a triangle where the side length a, angle B, and, side length c given by side-length-a,
angle-b, and, side-length-c respectively.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Creates a triangle where the side length a, side length b, and, angle c given by side-length-a,
side-length-b, and, angle-c respectively.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Creates a triangle where the angle A, angle B, and, side length c given by angle-a,
angle-b, and, side-length-c respectively.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Creates a triangle where the angle A, side length b, and, angle C given by angle-a,
side-length-b, and, angle-c respectively.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Creates a triangle where the side length a, angle B, and, angle C given by side-length-a,
angle-b, and, angle-c respectively.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Constructs a square.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Examples: |
| > (square 40 "solid" "slateblue") |
 |
| > (square 50 "outline" "darkmagenta") |
 |
Constructs a rectangle with the given width, height, mode, and color.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-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).
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Examples: |
| > (rhombus 40 45 "solid" "magenta") |
 |
| > (rhombus 80 150 "solid" "mediumpurple") |
 |
Constructs a star with five points. The side-length argument
determines the side length of the enclosing pentagon.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
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 vertices.
For examples, if side-count is 5 and step-count is 2,
then this function produces a shape just like star.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Constructs a star-like polygon where the star is specified by two radii and a number of points.
The first radius determines where the points begin, the second determines where they end, and
the point-count argument determines how many points the star has.
Constructs a regular polygon with side-count sides.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
Constructs a polygon connecting the given vertices.
If the mode is 'outline or "outline", then the last
argument can be a pen struct or an image-color?, but if the mode
is 'solid or "solid", then the last argument must be an
image-color?.
2.2.3 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 centers.
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.
Underlays all of its arguments building a single image.
It behaves like overlay, but with the arguments in the reverse order.
That is, the first argument goes
underneath of the second argument, which goes underneath the third argument, etc.
The images are all lined up on their centers.
Examples: |
|
 |
|
 |
Underlays all of its image arguments, much like the
underlay 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 underlaying i1 underneath of i2 after
shifting i2 over by x pixels to the right and y
pixels down.
This is the same as (overlay/xy i2 (- x) (- y) i1).
Constructs an image by placing all of the argument images in a
horizontal row, aligned along their centers.
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 centers.
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.4 Placing Images & Scenes
Placing images into scenes is particularly useful when building worlds
and universes using 2htdp/universe.
Creates an empty scene, i.e., a rectangle with a black outline.
Places image onto scene with its center at the coordinates
(x,y) and crops the resulting image so that it has the
same size as scene. The coordinates are relative to the top-left
of scene.
Examples: |
|
 |
|
 |
Adds a line to the image
scene, starting from the point (
x1,
y1)
and going to the point (
x2,
y2); unlike
add-line, this function crops the resulting image to the size of
scene.
Adds a curve to scene, starting at the point
(x1,y1), and ending at the point
(x2,y2).
The angle1 and angle2 arguments specify the
angle that the curve has as it leaves the initial point and
as it reaches the final point, respectively.
The pull1 and pull2 arguments control how
long the curve tries to stay with that angle. Larger numbers
mean that the curve stays with the angle longer.
Unlike add-curve, this function crops the curve, only showing
the parts that fit onto scene.
2.2.5 Rotating, Scaling, Flipping, Cropping, and Framing Images
Rotates image by angle degrees in a counter-clockwise direction.
Scales image by factor.
The pen sizes are also scaled and thus draw thicker (or thinner)
lines than the original image, unless the pen was size
0. That pen size is treated specially to mean “the
smallest available line” and thus it always draws a one pixel
wide line; this is also the case for 'outline and "outline"
shapes that are drawn with an image-color? instead of
a pen.
Scales image by x-factor horizontally and by
y-factor vertically.
Examples: |
|
 |
| > (ellipse 60 60 "solid" "blue") |
 |
Flips image left to right.
Flipping images with text is not supported (so passing flip-horizontal an image
that contains a text or text/font image inside somewhere signals an error).
Example: |
|
 |
Flips image top to bottom.
Flipping images with text is not supported (so passing flip-horizontal an image
that contains a text or text/font image inside somewhere signals an error).
Example: |
|
 |
Crops image to the rectangle with the upper left at the point (x,y)
and with width and height.
The x and y arguments must be between 0 and
the width or height, respectively.
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.6 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.7 Image Predicates
This section lists predicates for the basic structures provided by the image library.
Additionally, images inserted into a DrRacket window are treated as
bitmap images, as are instances of image-snip% and bitmap%.
