Builtins and Libraries
3.1 Global Utilities
3.2 Numbers
3.3 Strings
3.4 Booleans
3.5 Raw  Array
3.6 Tables
3.7 lists
3.8 sets
3.9 arrays
3.10 string-dict
3.11 option
3.12 pick
3.13 either
3.14 srcloc
3.15 pprint
3.16 s-exp
3.17 s-exp-structs
3.18 image-structs
3.19 image
3.20 world
3.21 gdrive-sheets
3.22 data-source
3.23 reactors
3.24 chart
3.25 plot
3.26 statistics
3.27 math
On this page:
3.19.1 Data Types
Image
Scene
Image  Color
name-to-color
Mode
3.19.2 Basic Images
circle
ellipse
line
add-line
3.19.3 Text
text
text-font
Font  Family
Font  Style
Font  Weight
3.19.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
3.19.5 Overlaying Images
overlay
overlay-align
XPlace
YPlace
overlay-xy
underlay
underlay-align
underlay-xy
beside
beside-align
above
above-align
3.19.6 Placing Images & Scenes
empty-scene
put-image
place-image
place-image-align
scene-line
3.19.7 Rotating, Scaling, Flipping, Cropping and Framing Images
rotate
scale
scale-xy
flip-horizontal
flip-vertical
crop
frame
3.19.8 Bitmaps
open-image-url
image-url
bitmap-url
color-at-position
image-to-color-list
color-list-to-image
color-list-to-bitmap
3.19.9 Image Properties
image-width
image-height
image-baseline
3.19.10 Image Predicates
is-image
is-mode
is-image-color
is-y-place
is-x-place
is-angle
is-side-count
is-step-count
3.19.11 Image Equality
images-equal
images-difference

3.19 image

Usage:
include image
import image as ...
The functions in this module are used for creating, combining, and displaying images.

The Pyret images library is based on the images teachpack in HtDP, and borrows much of the language for documentation. You can find documentation for the teachpack here:

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

3.19.1 Data Types

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.
An ImageColor is either a string from the list in Predefined colors, or a Color, which you can use to construct colors other than the predefined ones, including making colors partially transparent by controlling their opacity.

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

Looks up the given string in the list of predefined colors.

A String that describes a style for a shape. Either the string "outline" or the string "solid".

3.19.2 Basic Images

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

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

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

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

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

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

add-line :: (
img :: Image,
x1 :: Number,
y1 :: Number,
x2 :: Number,
y2 :: Number,
color :: Color
)
-> 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.

3.19.3 Text

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

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

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.

A String that describes a family of fonts. The following strings are options:

  • "default"

  • "decorative"

  • "roman"

  • "script"

  • "swiss"

  • "modern"

  • "symbol"

  • "system"

A String that describes the style of a font. One of "normal", "italic", or "slant".
A String that describes the weight of a font. One of "normal", "bold", or "light".

3.19.4 Polygons

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

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

right-triangle :: (
side-length1 :: Number,
side-length2 :: Number,
mode :: Mode,
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.

isosceles-triangle :: (
side-length :: Number,
angle-c :: Number,
mode :: Mode,
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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

rhombus :: (
side-length :: Number,
angle :: Number,
mode :: String,
color :: Color
)
-> 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.

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

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

radial-star :: (
point-count :: Number,
outer :: Number,
inner :: Number,
mode :: String,
color :: Color
)
-> 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.

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

Same as radial-star.

star-polygon :: (
side-length :: Number,
point-count :: Number,
step :: Number,
mode :: String,
color :: Color
)
-> 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).

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

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

3.19.5 Overlaying Images

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

Constructs a new image where img1 overlays img2.

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 where the images should line up.

A String that represents a place to align an image on the x-axis. One of "left", "center", "middle", or "right".
A String that represents a place to align an image on the y-axis. One of "top", "bottom", "baseline", "center", or "middle".

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.

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

Constructs a new image by placing img1 under img2.

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.

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.

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

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

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.

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

Constructs an image by placing img1 above img2.

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.

3.19.6 Placing Images & Scenes

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

Construct an empty scene of given width and height.

put-image :: (
picture :: Image,
x :: Number,
y :: Number,
background :: Scene
)
-> 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.

place-image :: (
img :: Image,
x :: Number,
y :: Number,
background :: Scene
)
-> 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.

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

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

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

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.

3.19.7 Rotating, Scaling, Flipping, Cropping and Framing Images

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

Rotates img counter-clockwise by angle degrees.

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

Scales img by factor.

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

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

Flips img left to right.

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

Flips img top to bottom.

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.

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

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

3.19.8 Bitmaps

Loads the image specified by url.

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

Loads the image specified by url.

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

Loads the image specified by url.

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.

color-list-to-image :: (
list :: List<Color>,
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.

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

Given a list of colors, creates an image with the given width width and height height.

3.19.9 Image Properties

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

Returns the width of img.

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

Returns the height of img.

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".

3.19.10 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.

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.

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.

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.19.11 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 this 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).