On this page:
3.20.1 Data Types
Image
Scene
Image  Color
color-named
name-to-color
Point
point-xy
point
point-polar
Point2D
3.20.2 Basic Images
circle
ellipse
line
add-line
3.20.2.1 Data types for drawing basic images
Fill  Mode
mode-solid
mode-outline
mode-fade
3.20.3 Text
text
text-font
3.20.3.1 Data types for text images
Font  Family
ff-default
ff-decorative
ff-roman
ff-script
ff-swiss
ff-modern
ff-symbol
ff-system
Font  Style
fs-normal
fs-italic
fs-slant
Font  Weight
fw-normal
fw-bold
fw-light
3.20.4 Polygons
triangle
right-triangle
isosceles-triangle
triangle-sss
triangle-ass
triangle-sas
triangle-ssa
triangle-aas
triangle-asa
triangle-saa
square
rectangle
rhombus
star
radial-star
star-sized
star-polygon
regular-polygon
point-polygon
3.20.5 Other images
wedge
3.20.6 Overlaying Images
overlay
overlay-align
overlay-xy
overlay-onto-offset
underlay
underlay-align
underlay-xy
beside
beside-align
above
above-align
3.20.6.1 Data types for aligning images
XPlace
x-left
x-middle
x-center
x-pinhole
x-right
YPlace
y-top
y-center
y-middle
y-pinhole
y-baseline
y-bottom
3.20.7 Placing Images & Scenes
empty-scene
empty-color-scene
empty-image
put-image
place-image
place-image-align
scene-line
3.20.8 Rotating, Scaling, Flipping, Cropping and Framing Images
rotate
scale
scale-xy
flip-horizontal
flip-vertical
crop
frame
3.20.9 Bitmaps
image-url
color-at-position
image-to-color-list
color-list-to-image
color-list-to-bitmap
3.20.10 Pinholes
move-pinhole
place-pinhole
center-pinhole
draw-pinhole
3.20.11 Image Properties
image-width
image-height
image-baseline
image-pinhole-x
image-pinhole-y
3.20.12 Image Predicates
is-image
is-mode
is-image-color
is-y-place
is-x-place
is-angle
is-side-count
is-step-count
3.20.13 Image Equality
images-equal
images-difference

3.20 The image libraries

The Pyret images library is based on the images teachpack in How to Design Programs, a textbook whose pedagogy has heavily influenced Pyret’s design (see Why Pyret? for more information). Note: this original library is written in Racket, a different language than Pyret. The examples in that file therefore do not work with Pyret as written; however, analogous examples are shown here. If you’re curious, you can find documentation for the images teachpack here:

http://docs.racket-lang.org/teachpack/2htdpimage.html

Pyret supplies two modules for creating, combining, and displaying images. These two libraries supply the same set of functions, but with different signatures:

While you cannot include both versions of the library simultaneously, you can import them both, if you would like to migrate from one version of the library to the other. (Note: The essentials2021 context already includes the untyped image library, so if you are using that context and want to use the typed image library, you must import it.)

Note that most of the examples below use the image version of this library, with arguments as strings.

3.20.1 Data Types

This section defines the key data types used in both versions of the image library. Wherever possible, the types are identical between the two libraries. When different, we will display equivalent versions of the types side by side.

This is the return type of many of the functions in this module; it includes simple shapes, like circles and squares, and also combinations or transformations of existing shapes, like rotations, overlays, and scaling.
Like an Image but with a few special functions that crop any overhanging parts of images that are placed atop them, instead of stretching to accommodate.

The image library

    

The image-typed library

An ImageColor can be a string describing a color name, for example "red" or "sea-green". The collection of names Pyret understands is shown here: each name can be used as a string (see color-named below).

    

    

An ImageColor can be one of the predefined colors themselves. To use these colors with the image library, you can write

include color include image circle(50, "solid", sea-green)

    

An ImageColor can be one of the predefined colors, which are included automatically when using the image-typed library

    

An ImageColor can be a Color, which you can use to construct colors other than the predefined ones, including making colors partially transparent by controlling their opacity. To use this constructor with the image library, you need to include the color library as above.

    

An ImageColor can be a Color, which you can use to construct colors other than the predefined ones, including making colors partially transparent by controlling their opacity.

color-named :: (
name :: String
)
-> Color

Looks up the given string in the list of predefined colors. The names are treated case-insensitively. Hyphens in the names can be replaced with spaces, or can be dropped altogether. Unknown color names produce an error.

Examples:

color-named("red")

red

color-named("blue")

blue

color-named("bLUE")

blue

color-named("sea-green")

sea-green

color-named("sea green")

sea-green

color-named("seagreen")

sea-green

color-named("transparent")

transparent

color-named("UNKNOWN")

Unknown color name ’UNKNOWN’

Looks up the given string in the list of predefined colors. Names are simplified as in color-named. If the color is known, then some Color value is returned; if the color is unknown, the function returns none.

Examples:

name-to-color("red")

some(red)

name-to-color("blue")

some(blue)

name-to-color("transparent")

some(transparent)

color-named("UNKNOWN")

none

data Point:
| point-xy(x :: Number, y :: Number)
| point-polar(r :: Number, theta :: Number)
end

Points represent two-dimensional coordinates on a plane. Points can be defined using either Cartesian or polar coordinates.

point-xy :: (x :: Number, y :: Number) -> Point

This constructor defines standard two-dimensional Cartesian coordinates.

point :: (x :: Number, y :: Number) -> Point

A convenient synonym for point-xy.

point-polar :: (r :: Number, theta :: Number) -> Point

This constructor defines two-dimensional polar coordinates. The angle theta should be specified in radians.

A convenient synonym for Point.

3.20.2 Basic Images

circle :: (
radius :: Number,
mode :: FillMode,
color :: ImageColor
)
-> Image

Constructs a circle with the given radius, mode and color.

Examples:

circle(30, "outline", "red")

image

circle(20, "solid", "red")

image

ellipse :: (
width :: Number,
height :: Number,
mode :: FillMode,
color :: ImageColor
)
-> Image

Constructs an ellipse with the given width, height, mode and color.

Examples:

ellipse(60, 30, "outline", "black")

image

ellipse(30, 60, "solid", "blue")

image

line :: (
x :: Number,
y :: Number,
color :: ImageColor
)
-> Image

Draws an image of a line that connects the point (0,0) to the point (x,y).

Examples:

line(60, 30, "black")

image

line(30, 60, "blue")

image

line(-30, 20, "red")

image

line(30, -20, "red")

image

add-line :: (
img :: Image,
x1 :: Number,
y1 :: Number,
x2 :: Number,
y2 :: Number,
color :: ImageColor
)
-> Image

Creates a new image like img with a line added starting from the point (x1,y1) and going to the point (x2,y2). Unlike scene-line, if the line passes outside of img, the image gets larger to accommodate the line.

Examples:

add-line(circle(20, "outline", "maroon"), 0, 40, 40, 0, "orange")

image

add-line(rectangle(40, 40, "outline", "maroon"), -10, 50, 50, -10, "orange")

image

3.20.2.1 Data types for drawing basic images

FillModes describe the style for a shape.

The image library

    

The image-typed library

FillModes can be one of a fixed set of Strings, or a Number

    

FillModes are an enumerated data definition:

    

The string "solid"

    

Shapes should be drawn solidly filled in

    

The string "outline"

    

Shapes should only be drawn in outline

    

A number between 0 and 1

    

Shapes should be drawn semi-transparently, where n is an opacity between 0 (transparent) and 1 (fully opaque)

3.20.3 Text

text :: (
string :: String,
font-size :: Number,
color :: ImageColor
)
-> Image

Constructs an image of string, using the given font size and color.

Examples:

text("Hello", 24, "olive")

image

text("Goodbye", 36, "indigo")

image

font-face is system-dependent because different computers and operating systems have different fonts installed. You can try different options for the names of fonts on your machine, and text-font will fall back to a default in the given family if it can’t find the one provided.

text-font :: (
string :: String,
size :: Number,
color :: ImageColor,
font-face :: String,
font-family :: FontFamily,
style :: FontStyle,
weight :: FontWeight,
underline :: Boolean
)
-> Image

Like text, constructs an image that draws the given string, but makes use of a complete font specification. The various style options are described below.

Examples:

text-font("Hello", 24, "green", "Gill Sans", "swiss", "italic", "normal", true)

image

text-font("Goodbye", 36, "turquoise", "Treasure Map Deadhand", "decorative", "normal", "normal", false)

image

3.20.3.1 Data types for text images

The image library

    

The image-typed library

A FontFamily can be one of a fixed set of Strings

    

A FontFamily is an enumerated data definition:

    

"default"

    

    

"decorative"

    

    

"roman"

    

    

"script"

    

    

"swiss"

    

    

"modern"

    

    

"symbol"

    

    

"system"

    

The image library

    

The image-typed library

A FontStyle can be one of a fixed set of Strings

    

A FontStyle is an enumerated data definition:

    

"normal"

    

    

"italic"

    

    

"slant"

    

The image library

    

The image-typed library

A FontWeight can be one of a fixed set of Strings

    

A FontWeight is an enumerated data definition:

    

"normal"

    

    

"bold"

    

    

"light"

    

3.20.4 Polygons

triangle :: (
side-length :: Number,
mode :: FillMode,
color :: ImageColor
)
-> Image

Constructs an image of an upward-pointing equilateral triangle. Each side will be of length side-length.

Examples:

triangle(40, "solid", "tan")

image

right-triangle :: (
side-length1 :: Number,
side-length2 :: Number,
mode :: FillMode,
color :: ImageColor
)
-> Image

Constructs an image of a triangle with a right angle at the bottom-left corner and where the two sides adjacent to the right angle have lengths side-length1 and side-length2.

Examples:

right-triangle(36, 48, "solid", "steel blue")

image

isosceles-triangle :: (
side-length :: Number,
angle-c :: Number,
mode :: FillMode,
color :: ImageColor
)
-> Image

Constructs an image of a triangle with two equal-length sides, of length side-length where the angle between those two sides is angle-c. if the angle is less than 180, then the triangle will point up; otherwise, the triangle will point down.

Examples:

isosceles-triangle(200, 170, "solid", "sea-green")

image

isosceles-triangle(60, 30, "solid", "royal-blue")

image

isosceles-triangle(60, 330, "solid", "dark-magenta")

image

triangle-sss :: (
side-a :: Number,
side-b :: Number,
side-c :: Number,
mode :: FillMode,
color :: ImageColor
)
-> Image

Constructs an image of a triangle using the three given sides.

Examples:

triangle-sss(40, 60, 80, "solid", "sea-green")

image

triangle-sss(80, 40, 60, "solid", "royal-blue")

image

triangle-sss(80, 80, 40, "solid", "dark-magenta")

image

triangle-ass :: (
angle-a :: Number,
side-b :: Number,
side-c :: Number,
mode :: FillMode,
color :: ImageColor
)
-> Image

Constructs an image of a triangle using the given angle and two sides.

Examples:

triangle-ass(10, 60, 100, "solid", "sea-green")

image

triangle-ass(90, 60, 100, "solid", "royal-blue")

image

triangle-ass(130, 60, 100, "solid", "dark-magenta")

image

triangle-sas :: (
side-a :: Number,
angle-b :: Number,
side-c :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Constructs an image of a triangle using the given angle and two sides.

Examples:

triangle-sas(60, 10, 100, "solid", "sea-green")

image

triangle-sas(60, 90, 100, "solid", "royal-blue")

image

triangle-sas(60, 130, 100, "solid", "dark-magenta")

image

triangle-ssa :: (
side-a :: Number,
side-b :: Number,
angle-c :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Constructs an image of a triangle using the given angle and two sides.

Examples:

triangle-ssa(60, 100, 10, "solid", "sea-green")

image

triangle-ssa(60, 100, 90, "solid", "royal-blue")

image

triangle-ssa(60, 100, 130, "solid", "dark-magenta")

image

triangle-aas :: (
angle-a :: Number,
angle-b :: Number,
side-c :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Constructs an image of a triangle using the two given angles and side.

Examples:

triangle-aas(10, 40, 200, "solid", "sea-green")

image

triangle-aas(90, 40, 200, "solid", "royal-blue")

image

triangle-aas(130, 40, 40, "solid", "dark-magenta")

image

triangle-asa :: (
angle-a :: Number,
side-b :: Number,
angle-c :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Constructs an image of a triangle using the two given angles and side.

Examples:

triangle-asa(10, 200, 40, "solid", "sea-green")

image

triangle-asa(90, 200, 40, "solid", "royal-blue")

image

triangle-asa(130, 40, 40, "solid", "dark-magenta")

image

triangle-saa :: (
side-a :: Number,
angle-b :: Number,
angle-c :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Constructs an image of a triangle using the two given angles and sides.

Examples:

triangle-saa(200, 10, 40, "solid", "sea-green")

image

triangle-saa(200, 90, 40, "solid", "royal-blue")

image

triangle-saa(40, 130, 40, "solid", "dark-magenta")

image

square :: (
side-length :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Constructs an image of a square with the given side length, mode and color.

Examples:

square(40, "solid", "slate-blue")

image

square(50, "outline", "light-steel-blue")

image

rectangle :: (
width :: Number,
height :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Constructs an image of a rectangle with the given side width, height, mode and color.

Examples:

rectangle(60, 30, "outline", "black")

image

rectangle(30, 60, "solid", "blue")

image

rhombus :: (
side-length :: Number,
angle :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Constructs a four-sided polygon whose sides are of length side-length and thus has angles equal to their opposites. The top and bottom pair of angles is angle and the left and right pair is 180 - angle.

Examples:

rhombus(40, 45, "solid", "magenta")

image

rhombus(80, 150, "solid", "medium-purple")

image

star :: (
side-length :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Constructs a five-pointed star with sides of length side-length, and with the given mode and color.

Examples:

star(40, "solid", "gray")

image

radial-star :: (
point-count :: Number,
outer :: Number,
inner :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Constructs a star with point-count points. The outer points will lie a distance of outer from the center of the star, while the inner points will lie a distance of inner from the center.

Examples:

radial-star(8, 28, 64, "solid", "dark-green")

image

radial-star(32, 30, 40, "outline", "black")

image

star-sized :: (
point-count :: Number,
outer :: Number,
inner :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Same as radial-star.

star-polygon :: (
side-length :: Number,
point-count :: Number,
step :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Constructs an image of an arbitrary regular star polygon. 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-count - 1 vertices).

Examples:

star-polygon(40, 5, 2, "solid", "sea-green")

image

star-polygon(40, 7, 3, "outline", "dark-red")

image

star-polygon(40, 8, 3, "outline", "goldenrod")

image

star-polygon(20, 10, 3, "solid", "cornflower-blue")

image

regular-polygon :: (
length :: Number,
count :: Number,
mode :: String,
color :: ImageColor
)
-> Image

Constructs an image of a regular polygon with side-count sides.

Examples:

regular-polygon(40, 5, "solid", "sea-green")

image

regular-polygon(40, 7, "outline", "dark-red")

image

regular-polygon(40, 8, "outline", "goldenrod")

image

regular-polygon(20, 8, "solid", "cornflower-blue")

image

point-polygon :: (
points :: List<Point>,
mode :: FillMode,
color :: ImageColor
)
-> Image

Creates a polygon whose corners are specified by the given list of points.

Examples:

point-polygon( [list: point(0, 0), point(-10, 20), point(60, 0), point(-10, -20)], "solid", "burlywood")

image

fun deg-to-rad(t): t * (~3.14159265358979323 / 180) end points = for map(n from [list: 0, 1, 2, 3, 4, 5]): point-polar(30, deg-to-rad(60 * n)) end draw-pinhole(point-polygon(points, "outline", "steel-blue"))

image

3.20.5 Other images

wedge :: (
radius :: Number,
angle :: Number,
mode :: FillMode,
color :: ImageColor
)
-> Image

Draws a pie-shaped section of a circle. The pinhole of the resulting image is at the center of the circle from which this wedge is cut. The angle is measured in degrees, measured counterclockwise from the positive x-axis.

Examples:

wedge(100, 60, "solid", "sea-green")

image

3.20.6 Overlaying Images

overlay :: (
img1 :: Image,
img2 :: Image
)
-> Image

Constructs a new image where img1 overlays img2. The two images are aligned at their pinholes, so overlay(img1, img2) behaves like overlay-align("pinhole", "pinhole", img1, img2).

Examples:

overlay(rectangle(30, 60, "solid", "orange"), ellipse(60, 30, "solid", "purple"))

image

overlay-align :: (
place-x :: XPlace,
place-y :: YPlace,
img1 :: Image,
img2 :: Image
)
-> Image

Overlays img1 on img2 like overlay, but uses place-x and place-y to determine the alignment point in each image. A call to overlay-align(place-x, place-y, img1, img2) behaves the same as overlay-onto-offset(img1, place-x, place-y, 0, 0, img2, place-x, place-y)

Examples:

overlay-align("left", "bottom", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

overlay-align("center", "top", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

overlay-align("right", "middle", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

overlay-xy :: (
img1 :: Image,
dx :: Number,
dy :: Number,
img2 :: Image
)
-> Image

Overlays img1 on img2 like overlay, but initially lines up the two images upper-left corners and then shifts img2 to the right by dx pixels, and then down by dy pixels. A call to overlay-xy(img1, dx, dy, img2) behaves the same as overlay-onto-offset(img1, "left", "top", dx, dy, img2, "left", "top").

Examples:

overlay-xy(square(30, "solid", "bisque"), 0, 0, square(50, "solid", "dark-green"))

image

overlay-xy(square(30, "solid", "bisque"), 30, 20, # Move green square right 30 and down 20 square(50, "solid", "dark-green"))

image

overlay-xy(square(30, "solid", "bisque"), -10, -20, # Move green square left 10 and up 20 square(50, "solid", "dark-green"))

image

overlay-onto-offset :: (
img1 :: Image,
place-x1 :: XPlace,
place-y1 :: YPlace,
offset-x :: Number,
offset-y :: Number,
img2 :: Image,
place-x2 :: XPlace,
place-y2 :: YPlace
)
-> Image

Overlays img1 on img2 like overlay, but uses place-x1 and place-y1 to choose the reference point for the first image, place-x2 and place-y2 to choose the reference point for the second image, and slides the second image’s reference point down and to the right by offset-x and offset-y.

underlay :: (
img1 :: Image,
img2 :: Image
)
-> Image

Constructs a new image by placing img1 under img2. This is the reverse of overlay.

Examples:

underlay(rectangle(30, 60, "solid", "orange"), ellipse(60, 30, "solid", "purple"))

image

underlay-align :: (
place-x :: XPlace,
place-y :: YPlace,
img1 :: Image,
img2 :: Image
)
-> Image

Underlays img1 beneath img2 like underlay, but uses place-x and place-y to determine where the images should line up. This is the reverse of overlay-align.

Examples:

underlay-align("left", "top", square(50, "solid", "bisque"), square(30, "solid", "dark-green"))

image

underlay-align("center", "top", square(50, "solid", "bisque"), square(30, "solid", "dark-green"))

image

underlay-align("middle", "top", square(50, "solid", "bisque"), square(30, "solid", "dark-green"))

image

underlay-align("right", "top", square(50, "solid", "bisque"), square(30, "solid", "dark-green"))

image

underlay-align("left", "top", square(50, "solid", "bisque"), square(30, "solid", "dark-green"))

image

underlay-align("left", "middle", square(50, "solid", "bisque"), square(30, "solid", "dark-green"))

image

underlay-align("left", "center", square(50, "solid", "bisque"), square(30, "solid", "dark-green"))

image

underlay-align("left", "bottom", square(50, "solid", "bisque"), square(30, "solid", "dark-green"))

image

underlay-align("left", "baseline", rectangle(140, 3, "solid", "bisque"), text("Pyret", 50, "dark-green"))

image

underlay-align("left", "bottom", rectangle(140, 3, "solid", "bisque"), text("Pyret", 50, "dark-green"))

image

underlay-xy :: (
img1 :: Image,
dx :: Number,
dy :: Number,
img2 :: Image
)
-> Image

Underlays img1 beneath img2 like underlay, but initially lines up the two images upper-left corners and then shifts img2 to the right by x pixels, and then down by y pixels. This is the reverse of overlay-xy.

Examples:

underlay-xy(square(50, "solid", "bisque"), 0, 0, square(30, "solid", "dark-green"))

image

underlay-xy(square(50, "solid", "bisque"), 50, 20, # Move green square right 50 and down 20 square(30, "solid", "dark-green"))

image

underlay-xy(square(50, "solid", "bisque"), -10, -20, # Move green square left 10 and up 20 square(30, "solid", "dark-green"))

image

beside :: (
img1 :: Image,
img2 :: Image
)
-> Image

Constructs an image by placing img1 to the left of img2.

Examples:

beside(rectangle(30, 60, "solid", "orange"), ellipse(60, 30, "solid", "purple"))

image

beside-align :: (
place-y :: YPlace,
img1 :: Image,
img2 :: Image
)
-> Image

Constructs an image by placing img1 to the left of img2, and aligning the two images as indicated by place-y.

Examples:

beside-align("top", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

beside-align("middle", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

beside-align("center", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

beside-align("bottom", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

beside-align("baseline", text("Hello", 30, "dark-green"), text(" Pyret", 18, "lawn-green"))

image

above :: (
img1 :: Image,
img2 :: Image
)
-> Image

Constructs an image by placing img1 above img2.

Examples:

above(rectangle(30, 60, "solid", "orange"), ellipse(60, 30, "solid", "purple"))

image

above-align :: (
place-x :: XPlace,
img1 :: Image,
img2 :: Image
)
-> Image

Constructs an image by placing img1 above img2, and aligning the two images as indicated by place-x.

Examples:

above-align("left", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

above-align("center", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

above-align("middle", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

above-align("right", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

3.20.6.1 Data types for aligning images

XPlaces describe a landmark to align an image along the x-axis.

The image library

    

The image-typed library

XPlaces can be one of a fixed set of Strings

    

XPlaces are an enumerated data definition:

    

"left"

    

Shape should be aligned along its left edge.

    

"center" or "middle" (these are synonyms)

    

Shape should be aligned at its horizontal midpoint. For convenience, you can also write x-center as a synonym.

    

"pinhole"

    

Shape should be aligned by its pinhole.

    

"right"

    

Shape should be aligned along its right edge.

Examples:

overlay-align("left", "top", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

overlay-align("center", "top", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

overlay-align("middle", "top", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

overlay-align("right", "top", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

YPlaces describe a landmark to align an image along the y-axis.

The image library

    

The image-typed library

YPlaces can be one of a fixed set of Strings

    

YPlaces are an enumerated data definition:

    

"top"

    

Shape should be aligned along its top edge.

    

"middle" or "center" (these are synonyms)

    

Shape should be aligned at its vertical midpoint. For convenience, you can also write y-middle as a synonym.

    

"pinhole"

    

Shape should be aligned by its pinhole.

    

"baseline"

    

Shape should be aligned by its basline. This option only makes sense with text images. It allows aligning multiple images of text at their baseline, as if they were part of a single image, or to appear to underline text. For all other images, their baseline is the same as their bottom.

    

"bottom"

    

Shape should be aligned along its bottom edge.

Examples:

overlay-align("left", "top", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

overlay-align("left", "middle", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

overlay-align("left", "center", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

overlay-align("left", "bottom", square(30, "solid", "bisque"), square(50, "solid", "dark-green"))

image

overlay-align("left", "baseline", rectangle(140, 3, "solid", "bisque"), text("Pyret", 50, "dark-green"))

image

overlay-align("left", "bottom", rectangle(140, 3, "solid", "bisque"), text("Pyret", 50, "dark-green"))

image

3.20.7 Placing Images & Scenes

empty-scene :: (
width :: Number,
height :: Number
)
-> Image

Construct an empty scene of given width and height. The background is transparent, and a black frame is drawn around the outside of the scene.

Examples:

empty-scene(30, 40)

image

empty-color-scene :: (
width :: Number,
height :: Number,
color :: ImageColor
)
-> Image

Construct an empty scene of given width and height. The background is the given color, and a black frame is drawn around the outside of the scene.

Examples:

empty-color-scene(30, 40, "red")

image

An empty image of zero size. Equivalent to empty-scene(0, 0).

Examples:

empty-image # Not much to see here!

image

put-image :: (
picture :: Image,
x :: Number,
y :: Number,
background :: Image
)
-> Image

Places the image img on the scene background so that its center is located at the coordinates (x,y), cropping the resulting image as necessary to maintain the size of background. The coordinates are relative to the bottom-left of background (i.e., Quadrant I of the Cartesian plane).

Examples:

put-image( circle(10, "solid", "red"), 10, 20, empty-scene(80, 50))

image

put-image( circle(10, "solid", "red"), 80, 50, empty-scene(80, 50))

image

place-image :: (
img :: Image,
x :: Number,
y :: Number,
background :: Image
)
-> Image

Places the image img on the scene background so that its center is located at the coordinates (x,y), cropping the resulting image as necessary to maintain the size of background. The coordinates are relative to the top-left of background (i.e. standard screen coordinates).

Examples:

place-image( circle(10, "solid", "red"), 10, 20, empty-scene(80, 50))

image

place-image( circle(10, "solid", "red"), 80, 50, empty-scene(80, 50))

image

place-image-align :: (
img :: Image,
x :: Number,
y :: Number,
place-x :: XPlace,
place-y :: YPlace,
background :: Image
)
-> Image

Behaves similar to place-image, but uses place-x and place-y to determine where to anchor img, instead of always using the center.

Examples:

place-image-align( star(15, "solid", "red"), 80, 50, "center", "center" empty-scene(80, 50))

image

place-image-align( star(15, "solid", "red"), 80, 50, "right", "bottom", empty-scene(80, 50))

image

scene-line :: (
img :: Image,
x1 :: Number,
y1 :: Number,
x2 :: Number,
y2 :: Number,
background :: Image
)
-> Image

Draws a line from (x1,y1) to (x2,y2) on the scene background. Unlike add-line, this function crops the resulting image to be the same size as background.

Examples:

scene-line(circle(20, "outline", "maroon"), 0, 40, 40, 0, "orange")

image

scene-line(rectangle(40, 40, "outline", "maroon"), -10, 50, 50, -10, "orange")

image

3.20.8 Rotating, Scaling, Flipping, Cropping and Framing Images

rotate :: (
angle :: Number,
img :: Image
)
-> Image

Rotates img counter-clockwise by angle degrees.

Examples:

rotate(40, ellipse(60, 20, "solid", "olive-drab"))

image

rotate(5, square(50, "outline", "black"))

image

rotate(45, beside-align("center", rectangle(40, 20, "solid", "dark-sea-green"), rectangle(20, 100, "solid", "light-sea-green")))

image

scale :: (
factor :: Number,
img :: Image
)
-> Image

Scales img by factor.

Examples:

scale(2, ellipse(20, 30, "solid", "blue"))

image

ellipse(40, 60, "solid", "blue")

image

scale-xy :: (
x-factor :: Number,
y-factor :: Number,
img :: Image
)
-> Image

Scales by x-factor horizontally and by y-factor vertically.

Examples:

scale-xy(2, 3, circle(10, "solid", "blue"))

image

ellipse(40, 60, "solid", "blue")

image

Flips img left to right.

Examples:

flip-horizontal(text("Hello", 40, "darkgreen"))

image

beside( rotate(30, square(50, "solid", "red")), flip-horizontal(rotate(30, square(50, "solid", "blue"))))

image

flip-vertical :: (
img :: Image
)
-> Image

Flips img top to bottom.

Examples:

flip-vertical(text("Hello", 40, "darkgreen"))

image

above( star(40, "solid", "fire-brick"), scale-xy(1, 1/2, (flip-vertical(star(40, "solid", "gray")))))

image

crop :: (
x :: Number,
y :: Number,
width :: Number,
height :: Number,
img :: Image
)
-> Image

Crops img to the rectangle with the upper left at the point (x,y) and with width width and height height.

Examples:

crop(0, 0, 40, 40, circle(40, "solid", "chocolate"))

image

crop(40, 60, 40, 60, ellipse(80, 120, "solid", "dodger-blue"))

image

above( beside( crop(40, 40, 40, 40, circle(40, "solid", "pale-violet-red")), crop(0, 40, 40, 40, circle(40, "solid", "light-coral"))), beside( crop(40, 0, 40, 40, circle(40, "solid", "light-coral")), crop(0, 0, 40, 40, circle(40, "solid", "pale-violet-red"))))

image

frame :: (
img :: Image
)
-> Image

Construct an image similar to img, but with a black, single pixel frame drawn around the bounding box of the image.

Examples:

frame(ellipse(40, 60, "solid", "gray"))

image

frame(beside(circle(20, "solid", "red"), circle(10, "solid", "blue")))

image

3.20.9 Bitmaps

image-url :: (
url :: String
)
-> Image

Loads the image specified by url.

Examples:

image-url("https://www.pyret.org/img/pyret-banner.png")

color-at-position :: (
image :: Image,
x :: Number,
y :: Number
)
-> Color

Returns the color at the pixel given by x and y coordinates. The coordinates are 0-based, with 0, 0 in the top-left corner of the image.

Returns a list of colors that correspond to the colors in the image, reading from left to right, top to bottom.

Examples:

image-to-color-list(rectangle(2, 2, "solid", "black"))

[list:black, black, black, black]

image-to-color-list(above( beside(square(1, "solid", "red"), square(1, "solid", "blue")), beside(square(1, "solid", "green"), square(1, "solid", "yellow"))))

[list:red, blue, green, yellow]

color-list-to-image :: (
list :: List<ImageColor>,
width :: Number,
height :: Number,
pinhole-x :: Number,
pinhole-y :: Number
)
-> Image

Given a list of colors, creates an image with the given width width and height height. The pinhole arguments specify where to place the pinhole of the image.

Examples:

scale(20, color-list-to-image([list: "red", "blue", "green", "yellow"], 2, 2, 1, 1))

image

scale(20, color-list-to-image([list: "red", "blue", "green", "yellow"], 4, 1, 1, 1))

image

color-list-to-bitmap :: (
list :: List<Color>,
width :: Number,
height :: Number
)
-> Image

Same as color-list-to-image, but places the pinhole at the center of the image (i.e. width / 2 and height / 2).

3.20.10 Pinholes

When combining images with overlay-align or related functions, we need to specify which reference point in each image to bring into alignment. Using the various XPlace and YPlace options, we can easily refer to the four corners, the four midpoints of the edges, or the center of the image. But frequently, the "obvious" alignment point is not quite any of those. Suppose we wanted to create a six-pointed star by overlaying two equilateral triangles:

Examples:

overlay-align("middle", "center", triangle(50, "solid", "red"), rotate(180, triangle(50, "solid", "blue")))

image

Unfortunately, the center of our triangles isn’t the visual center of our triangles, but instead is exactly half the triangles’ heights. To fix this, Pyret defines a notion of a pinhole, which lets us specify one more point in our images, where we’d like to pin images together. By default, Pyret’s pinhole of polygon images is at the centroid of the polygon, which is the average of the coordinates of each corner.

If we use our pinholes to align these triangles, we get the more intuitive result:

Examples:

overlay-align("pinhole", "pinhole", triangle(50, "solid", "red"), rotate(180, triangle(50, "solid", "blue")))

image

When two images are overlaid, the pinhole of the resulting image is the pinhole of the second image.

move-pinhole :: (
dx :: Number,
dy :: Number,
img :: Image
)
-> Image

Produces a new image just like the original, but where the pinhole has been offset down and to the right by dx and dy.

place-pinhole :: (
x :: Number,
y :: Number,
img :: Image
)
-> Image

Produces a new image just like the original, but where the pinhole has been placed at x and y, relative to the top-left corner of the image.

center-pinhole :: (
img :: Image
)
-> Image

Produces a new image just like the original, but where the pinhole has been placed at the geometric center of the image (exactly at half its width and half its height).

draw-pinhole :: (
img :: Image
)
-> Image

Produces a new image just like the original, but draws a small crosshatch at the location of the pinhole. Useful for debugging where the pinholes of images currently are.

Examples:

draw-pinhole(triangle(50, "solid", "red"))

image

draw-pinhole(center-pinhole(triangle(50, "solid", "tan")))

image

This last one looks strange, but it is an optical illusion. Flipping the image vertically reveals that the pinhole really is centered:

Examples:

beside( draw-pinhole(center-pinhole(triangle(50, "solid", "tan"))), draw-pinhole(rotate(180, center-pinhole(triangle(50, "solid" , "tan")))))

image

3.20.11 Image Properties

image-width :: (
img :: Image
)
-> Number

Returns the width of img.

Examples:

image-width(circle(30, "solid", "red"))

60

image-width(text("Pyret", 30, "green"))

82

image-height :: (
img :: Image
)
-> Number

Returns the height of img.

Examples:

image-height(rectangle(30, 40, "solid", "red"))

40

image-height(text("Pyret", 30, "green"))

36

Returns the distance from the top of img to its baseline. The baseline of an image is the place where the bottoms of letters line up, without counting the descender, such as the tails on "y", "g" or "j".

Examples:

image-baseline(rectangle(30, 40, "solid", "red"))

40

image-baseline(text("Pyret", 30, "green"))

30

Returns the distance from the left of img to its pinhole.

Examples:

image-pinhole-x(circle(30, "solid", "red"))

30

image-pinhole-x(text("Pyret", 30, "green"))

40.5

Returns the distance from the top of img to its pinhole.

Examples:

image-pinhole-y(circle(30, "solid", "red"))

30

image-height(star(40, "solid", "green"))

62

image-pinhole-y(star(40, "solid", "green"))

34 # NOTE: lower than the center, which would be (62 / 2) == 31

3.20.12 Image Predicates

is-image :: (
maybe-image :: Any
)
-> Boolean

Checks if maybe-image is an image.

is-mode :: (
maybe-mode :: Any
)
-> Boolean

Checks if maybe-mode is a mode.

is-image-color :: (
maybe-color :: Any
)
-> Boolean

Checks if maybe-color can be used as a color. Strings, if names of colors (e.g. "red" or "green") can also be used, if they exist in the color database. This function is only defined in the image library.

is-y-place :: (
maybe-y-place :: Any
)
-> Boolean

Checks if maybe-y-place can be used as y-place in appropriate functions. Valid strings are "top", "bottom", "middle", "center", "baseline" and "pinhole". This function is only defined in the image library.

is-x-place :: (
maybe-x-place :: String
)
-> Boolean

Checks if maybe-x-place can be used as x-place in appropriate functions. Valid strings are "left", "right", "middle", "center" and "pinhole". This function is only defined in the image library.

is-angle :: (
maybe-angle :: Number
)
-> Boolean

Checks if maybe-angle is an angle, namely a real number. All angles in the library are in degrees.

is-side-count :: (
side-count :: Any
)
-> Boolean

Checks if maybe-side-count is an integer greater than or equal to 3.

is-step-count :: (
step-count :: Number
)
-> Boolean

Checks if maybe-step-count is an integer greater than or equal to 1.

3.20.13 Image Equality

images-equal :: (
image1 :: Image,
image2 :: Image
)
-> Boolean

Compares two images for equality.

images-difference :: (
image1 :: Image,
image2 :: Image
)
-> Either<String, Number>

Compares two images for approximate equality. Returns left if they aren’t the same size (and are thus incomparable). Returns right otherwise, with a number representing how far off they are.

Numbers range from 0-255, where around 255 indicates completely different images, and numbers below 20 or so are very difficult to distinguish at a glance. Useful for testing against reference images (especially cross-browser).