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.In the context of this
documentation, a bitmap denotes a special form of
image?, namely a collection of pixels associated with an image. It
does not refer to the bitmap% class. Typically such image-bitmaps
come about via the Insert Image... menu item in DrRacket
Existing images can be rotated, scaled, flipped, and overlaid on top of each other.
In some situations images are rendered into bitmaps (e.g. when being shown in
the DrRacket Interactions window) In order to avoid bad performance
penalties, the rendering process limits the area of the images to
about 25,000,000 pixels (which requires about 100 MB of storage).
Constructs a circle with the given radius, mode, and color.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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 an ellipse with the given width, height, mode, and color.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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?.
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 accommodate 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 accommodate the curve.
The text size is measured in pixels, not points, so passing 24
to text should result in an image whose height is 24
(which might not be the case if the size were measured in points).
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 (on 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.
Constructs a upward-pointing equilateral triangle.
The side-length argument
determines the
length of the side of the triangle.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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 lengths a, b, and, c are given by side-length-a,
side-length-b, and, side-length-c respectively.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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.
See above for a diagram showing where which sides and which angles are which.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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.
See above for a diagram showing where which sides and which angles are which.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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.
See above for a diagram showing where which sides and which angles are which.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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.
See above for a diagram showing where which sides and which angles are which.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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.
See above for a diagram showing where which sides and which angles are which.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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.
See above for a diagram showing where which sides and which angles are which.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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?.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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 rectangle with the given width, height, mode, and color.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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 (-180angle).
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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 with five points. The side-length argument
determines the side length of the enclosing pentagon.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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 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 polygon, but connecting every step-count-th vertex
(i.e., skipping every (-step-count1) vertices).
For example, if side-count is 5 and step-count is 2,
then this function produces a shape just like star.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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 regular polygon with side-count sides where each side
is curved according to the pull and angle arguments. The
angle argument controls the angle at which the curved version of
polygon edge makes with the original edge of the polygon. Larger the pull
arguments mean that the angle is preserved more at each vertex.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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?.
Adds a closed polygon to the image image, with vertices as specified in posns
(relative to the top-left corner of image). Unlike scene+polygon,
if the polygon goes outside the bounds of image, the result is enlarged to accommodate both.
Note that when the mode is 'outline or "outline", the shape
may draw outside of its bounding box and thus parts of the image may disappear
when it is cropped. See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful explanation of the ramifications of this fact.
If the mode argument 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?.
Adds a closed polygon to the image image, with vertices as specified in posns
(relative to the top-left corner of image). Unlike add-polygon, if the
polygon goes outside the bounds of image, the result is clipped to image.
Some shapes (notably those with 'outline or "outline" as
the mode argument) draw outside of their bounding boxes and thus
cropping them may remove part of them (often the lower-left and lower-right
edges). See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful discussion of this issue.
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.
Just like overlay, this function lines up its image arguments on top of
each other. Unlike overlay, it moves i2 by x pixels to
the right and y down before overlaying them.
Overlays image i1 on top of i2, using x-place and y-place
as the starting points for the overlaying, and then adjusts i2 by x to the
right and y pixels down.
Constructs an image by overlaying i1 on top of i2.
The images are initially lined up on their upper-left corners and
then i2 is shifted to the right
by x pixels to and down by y pixels.
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.
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.
Just like underlay, this function lines up its first image argument
underneath the second. Unlike underlay, it moves i2 by
x pixels to the right and y down before underlaying them.
Underlays image i1 underneath i2, using x-place and y-place
as the starting points for the combination, and then adjusts i2 by x to the
right and y pixels down.
Constructs an image by underlaying i1 underneath i2.
The images are initially lined up on their upper-left corners and
then i2 is shifted to the right
by x pixels to and down by y pixels.
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, 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.
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.
Some shapes (notably those with 'outline or "outline" as
the mode argument) draw outside of their bounding boxes and thus
cropping them may remove part of them (often the lower-left and lower-right
edges). See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful discussion of this issue.
Like place-image, but uses image’s x-place and
y-place to anchor the image. Also, like
place-image, place-image/align
crops the resulting image so that it has the
same size as scene.
Some shapes (notably those with 'outline or "outline" as
the mode argument) draw outside of their bounding boxes and thus
cropping them may remove part of them (often the lower-left and lower-right
edges). See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful discussion of this issue.
Places each of images into scene like
place-image would, using the coordinates
in posns as the x
and y arguments to place-image.
Some shapes (notably those with 'outline or "outline" as
the mode argument) draw outside of their bounding boxes and thus
cropping them may remove part of them (often the lower-left and lower-right
edges). See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful discussion of this issue.
Like place-images, except that it places the images
with respect to x-place and y-place.
Some shapes (notably those with 'outline or "outline" as
the mode argument) draw outside of their bounding boxes and thus
cropping them may remove part of them (often the lower-left and lower-right
edges). See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful discussion of this issue.
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.
Some shapes (notably those with 'outline or "outline" as
the mode argument) draw outside of their bounding boxes and thus
cropping them may remove part of them (often the lower-left and lower-right
edges). See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful discussion of this issue.
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.
Some shapes (notably those with 'outline or "outline" as
the mode argument) draw outside of their bounding boxes and thus
cropping them may remove part of them (often the lower-left and lower-right
edges). See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful discussion of this issue.
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.
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).
Flipping images with text is not supported (so passing flip-vertical an image
that contains a text or text/font image inside somewhere signals an error).
Crops image to the rectangle with the upper left at the point (x,y)
and with width and height.
Some shapes (notably those with 'outline or "outline" as
the mode argument) draw outside of their bounding boxes and thus
cropping them may remove part of them (often the lower-left and lower-right
edges). See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful discussion of this issue.
Crops image to a rectangle whose size is width and height
and is positioned based on x-place and y-place.
Some shapes (notably those with 'outline or "outline" as
the mode argument) draw outside of their bounding boxes and thus
cropping them may remove part of them (often the lower-left and lower-right
edges). See The Nitty Gritty of Pixels, Pens, and Lines (in the Image Guide)
for a more careful discussion of this issue.
DrRacket’s Insert Image ...
menu item allows you to insert images into your program text, and those images are treated
as images for this library.
Unlike all of the other images in this library, those images (and the other images created
by functions in this section of the documentation)
are represented as bitmaps, i.e., an array of colors (that can be quite large in some cases).
This means that scaling and rotating them loses fidelity in the image and is significantly
more expensive than with the other shapes.
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.
Goes out on the web and downloads the image at url.
Downloading the image happens each time this function is called, so
you may find it simpler to download the image once with a browser
and then paste it into your program or download it and use bitmap.
If ps is a relative path, the file is relative to
the current directory. (When running in DrRacket, the current
directory is set to the place where the definitions window is
saved, but in general this can be an arbitrary directory.)
Freezing an image internally builds a bitmap, crops the image, draws the cropped image
into the bitmap and then
uses the bitmap to draw that image afterwards. Typically this is used as a performance
hint. When an image both contains many sub-images and is going to be drawn many times
(but not scaled or rotated),
using freeze on the image can substantially improve performance without changing how
the image draws (assuming it draws only inside its bounding box; see also The Nitty Gritty of Pixels, Pens, and Lines).
If freeze is passed only the image argument, then it crops the image to its bounding
box. If it is given three arguments, the two numbers are used as the width and height and
the five argument version fully specifies where to crop the image.
Returns the distance from the top of the image to its baseline.
The baseline of an image is the place where the bottoms any letters line up,
but without counting the descenders, e.g. the tail on “y” or “g” or “j”.
Unless the image was constructed with text, text/font
or, in some cases, crop, this will be the same as its height.
A cropped image’s baseline is the same as the image’s baseline, if the
cropping stays within the original image’s bounding box. But if the cropping actually
enlarges the image, then the baseline can end up being smaller.
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.
It can also be an integer between 0 and 255 (inclusive)
indicating the transparency of the image. The integer 255 is
fully opaque, and is the same as "solid" (or 'solid).
The integer 0 means fully transparent.
Determines if x represents a color. Strings, symbols,
and color structs 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 string or symbol color name is not recognized, black is used in its place.
The complete list of colors is the same as the colors allowed in
color-database<%>, plus the color "transparent", a transparent
color.
The color struct defines a color with red,
green, blue, and alpha components
that range from 0 to 255.
The red, green, and blue fields
combine to make a color, with the higher values meaning more of the given color.
For example, (make-color25500) makes a
bright red color and (make-color2550255) makes a bright purple.
The alpha field controls the transparency of the color. A value of 255 means
that the color is opaque and 0 means the color is fully transparent.
The constructor, make-color, also accepts only three arguments, in which case
the three arguments are used for the red, green, and blue fields, and the
alpha field defaults to 255.
The pulled-point struct defines a point with
x and y coordinates, but also with
two angles (langle and rangle) and
two pulls (lpull and rpull).
These points are used with the polygon function
and control how the edges can be curved.
The first two pull and angle arguments indicate
how an edge coming into this point should be curved.
The angle argument indicates the angle as the edge
reaches (x,y) and a larger pull argument
means that the edge should hold the angle longer.
The last two are the same, except they apply to
the edge leaving the point.
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",
'baseline,
"pinhole", or
'pinhole.
Using "pinhole" or 'pinhole is only allowed when all of the
image arguments have pinholes.
See also image-baseline for more discussion of baselines.
Determines if x is a placement option
for the horizontal direction. It can be one
of "left",
'left,
"right",
'right,
"middle",
'middle,
"center",
'center,
"pinhole", or
'pinhole.
Using "pinhole" or 'pinhole is only allowed when all of the image
arguments have pinholes.
The pen struct specifies how the drawing library draws lines.
A good default for style is "solid", and
good default values for the cap and join fields
are "round".
Using 0 as a width is special; it means to always draw the
smallest possible, but visible, pen. This means that the pen will always
be one pixel in size, no matter how the image is scaled.
The cap determines how the ends of a curve is drawn.
Determines if x is a valid pen style.
It can be one of
"solid", 'solid,
"dot", 'dot,
"long-dash", 'long-dash,
"short-dash", 'short-dash,
"dot-dash", or 'dot-dash.
Determines if x is a valid pen join.
It can be one of
"round", 'round,
"bevel", 'bevel,
"miter", or 'miter.
2.3.9Equality Testing of Images
Two images are equal? if they draw exactly the same way at their current size
(not necessarily at all sizes) and, if there are pinholes, the pinholes are
in the same place.
This can lead to some counter-intuitive results. For example,
two completely different shapes that are the same size and are
drawn with the transparent color are equal:
A pinhole is an optional property of an image that identifies a point somewhere
in the image. The pinhole can then be used to facilitate overlaying images by
lining them up on the their pinholes.
When an image has a pinhole, the pinhole
is drawn with crosshairs on the image.
The crosshairs are drawn with two one-pixel wide black lines (one horizontal and one vertical)
and two one-pixel wide white lines,
where the black lines is drawn .5 pixels to the left and above the pinhole, and the
white lines are drawn .5 pixels to the right and below the pinhole.
Accordingly, when the pixel is on an integral coordinate, then black and white lines all
take up a single pixel and in the center of their intersections is the actual pinholes.
See The Nitty Gritty of Pixels, Pens, and Lines for more details about pixels.
When images are overlay’d, underlay’d (or the variants of those functions),
placed beside, or above each other,
the pinhole of the resulting image is the pinhole of
the first image argument passed to the combining
operation. When images are combined with place-image
(or the variants of place-image),
then the scene argument’s pinhole is preserved.
In order to use an image as an input to another program (e.g., Photoshop or
a web browser), it is necessary to represent it in a format that these programs
can understand.
The save-image function provides this functionality,
writing an image to disk using the PNG format. Since this
format represents an image using a set of pixel values, an image written to disk
generally contains less information than the image that was written, and cannot be scaled
or manipulated as cleanly (by any image program).
The save-svg-image function writes an SVG file format
representation of the file to the disk that, unlike save-image produces
an image that can still be scaled arbitrarily look as good as scaling the
image directly via scale.
Writes an image to the path specified by filename, using the
PNG format.
The last two arguments are optional. If present, they determine the width
and height of the save image file. If absent, the width and height of the image is used.
Writes an image to the path specified by filename, using the
SVG format.
The last two arguments are optional. If present, they determine the width
and height of the save image file. If absent, the width and height of the image is used.
