1.1 Manipulating Images: image.ss

The teachpack provides primitives for constructing and manipulating images. Basic, colored images are created as outlines or solid shapes. Additional primitives allow for the composition of images.

1.1.1 Images

(image? x) → boolean?

x : any/c

Is x an image?

1.1.2 Modes and Colors

Mode (one-of/c 'solid 'outline "solid" "outline")

A Mode is used to specify whether painting a shape fills or outlines the form.}

(struct   color   (red green blue))

red : (and/c natural-number/c (<=/c 255))

green : (and/c natural-number/c (<=/c 255))

blue : (and/c natural-number/c (<=/c 255))

RGB color?

An RGB describes a color via share of red, blue, and green colors (e.g., (make-color 100 200 30)).

Color (or/c symbol? string? color?)

A Color is a color-symbol (e.g., 'blue) or a color-string (e.g., "blue") or an RGB structure.

(image-color? x) → boolean?

x : any

Determines if the input is a valid image Color.

1.1.3 Creating Basic Shapes

In DrScheme, you can insert images from your file system. Use PNG images instead whenever possible for insertions. In addition, you can create basic shapes with the following functions.

(rectangle w h m c) → image?

w : number?

h : number?

m : Mode

c : Color

Creates a w by h rectangle, filled in according to m and painted in color c

(circle r m c) → image?

r : number?

m : Mode

c : Color

Creates a circle or disk of radius r, filled in according to m and painted in color c

(ellipse w h m c) → image?

w : number?

h : number?

m : Mode

c : Color

Creates a w by h ellipse, filled in according to m and painted in color c

(triangle s m c) → image?

s : number?

m : Mode

c : Color

Creates an upward pointing equilateral triangle whose side is s pixels long, filled in according to m and painted in color c

(star n outer inner m c) → image?

n : (and/c number? (>=/c 2))

outer : (and/c number? (>=/c 1))

inner : (and/c number? (>=/c 1))

m : Mode

c : Color

Creates a multi-pointed star with n points, an outer radius for the max distance of the points to the center, and an inner radius for the min distance to the center.

(regular-polygon s r m c [angle]) → image?

s : side

r : number?

m : Mode

c : Color

angle : real? = 0

Creates a regular polygon with s sides inscribed in a circle of radius r, using mode m and color c. If an angle is specified, the polygon is rotated by that angle.

(line x y c) → image?

x : number?

y : number?

c : Color

Creates a line colored c from (0,0) to (x ,y). See add-line below.

(text s f c) → Image

s : (and/c string? (lambda (s) (not (string=? s ""))))

f : (and/c number? positive?)

c : Color

Creates an image of the text s at point size f and painted in color c.

The string s must have at least one character.

1.1.4 Basic Image Properties

To understand how images are manipulated, you need to understand the basic properties of images.

(image-width i) → integer?

i : image?

Obtain i’s width in pixels

(image-height i) → integer?

i : image?

Obtain i’s height in pixels

For the composition of images, you must know about pinholes. Each image, including primitive ones, come with a pinhole. For images created with the above primitives, the pinhole is at the center of the shape except for those created from line and text, which have pinholes at the top left. The pinhole can be moved, of course, and compositions locate pinholes according to their own rules. When in doubt you can always find out where the pinhole is and place it where convenient.

(pinhole-x i) → integer?

i : image?

Determines the x coordinate of the pinhole, measuring from the left of the image.

(pinhole-y i) → integer?

i : image?

Determines the y coordinate of the pinhole, measuring from the top (down) of the image.

(put-pinhole i x y) → image?

i : image?

x : number?

y : number?

Creates a new image with the pinhole in the location specified by x and y, counting from the left and top (down), respectively.

(move-pinhole i delta-x delta-y) → image?

i : image?

delta-x : number?

delta-y : number?

Creates a new image with the pinhole moved down and right by delta-x and delta-y with respect to its current location. Use negative numbers to move it up or left.

1.1.5 Composing Images

Images can be composed, and images can be found within compositions.

(add-line i x y z u c) → image?

i : image?

x : number?

y : number?

z : number?

u : number?

c : Color

Creates an image by adding a line (colored c) from (x ,y) to (z ,u) to image i.

(overlay img img2 img* ...) → image?

img : image?

img2 : image?

img* : image?

Creates an image by overlaying all images on their pinholes. The pinhole of the resulting image is the same place as the pinhole in the first image.

(overlay/xy img delta-x delta-y other) → image?

img : image?

delta-x : number?

delta-y : number?

other : image?

Creates an image by adding the pixels of other to img. Instead of lining up on the pinhole, other’s pinhole is lined up with an offset of (delta-x,delta-y) from the pinhole of img. The pinhole of the resulting image is the same place as the pinhole in the first image.

(image-inside? img other) → boolean?

img : image?

other : image?

Determines whether the pixels of the second image appear in the first.

Be careful when using this function with jpeg images. If you use an image-editing program to crop a jpeg image and then save it, image-inside? does not recognize the cropped image, due to standard compression applied to JPEG images.

(find-image img other) → posn?

img : image?

other : image?

Determines where the pixels of the second image appear in the first, with respect to the pinhole of the first image. If (image-inside? img other) isn’t true, find-image signals an error.

1.1.6 Manipulating Images

Images can also be shrunk. These “shrink” functions trim an image by eliminating extraneous pixels.

(shrink-tl img width height) → image?

img : image?

width : number?

height : number?

Shrinks the image to a width by height image, starting from the top-left corner. The pinhole of the resulting image is in the center of the image.

(shrink-tr img width height) → image?

img : image?

width : number?

height : number?

Shrinks the image to a width by height image, starting from the top-right corner. The pinhole of the resulting image is in the center of the image.

(shrink-bl img width height) → image?

img : image?

width : number?

height : number?

Shrinks the image to a width by height image, starting from the bottom-left corner. The pinhole of the resulting image is in the center of the image.

(shrink-br img width height) → image?

img : image?

width : number?

height : number?

Shrinks the image to a width by height image, starting from the bottom-right corner. The pinhole of the resulting image is in the center of the image.

(shrink img left above right below) → image?

img : image?

left : number?

above : number?

right : number?

below : number?

Shrinks an image around its pinhole. The numbers are the pixels to save to left, above, to the right, and below the pinhole, respectively. The pixel directly on the pinhole is always saved.

1.1.7 Miscellaneous Image Manipulation and Creation

The last group of functions extracts the constituent colors from an image and converts a list of colors into an image.

List-of-color : list?

is one of:

; -- empty

; -- (cons Color List-of-color)

; Interpretation: represents a list of colors.

(image->color-list img) → List-of-color

img : image?

Converts an image to a list of colors.

(color-list->image l width height x y) → image?

l : List-of-color

width : natural-number/c

height : natural-number/c

x : natural-number/c

y : natural-number/c

Converts a list of colors l to an image with the given width and height and pinhole (x,y) coordinates, specified with respect to the top-left of the image.

The remaining functions provide alpha-channel information as well. Alpha channels are a measure of transparency; 0 indicates fully opaque and 255 indicates fully transparent.

(struct   alpha-color   (alpha red green blue))

alpha : (and/c natural-number/c (<=/c 255))

red : (and/c natural-number/c (<=/c 255))

green : (and/c natural-number/c (<=/c 255))

blue : (and/c natural-number/c (<=/c 255))

A structure representing an alpha color.

(image->alpha-color-list img) → (list-of alpha-color?)

img : image?

to convert an image to a list of alpha colors

(alpha-color-list->image l width height x y) → image?

l : (list-of alpha-color?)

width : integer?

height : integer?

x : integer?

y : integer?

Converts a list of alpha-colors l to an image with the given width and height and pinhole (x,y) coordinates, specified with respect to the top-left of the image.