-- 'solid -- 'outline -- "solid" -- "outline"
This teachpack provides primitives for constructing and manipulating images. Vector shapes are created as outlines or solid shapes. Bitmaps can be created from files or from lists of colors. Additional primitives allow for the composition of images. This teachpacks is based on the PLT image teachpack and provides the same methods as well as some new ones. Much of this documentation is borrowed from PLT.
The image teachpack is designed so that it can be implemented on different systems. For example, the provided implementation runs, in conjunction with CommonLarceny, on the Microsoft .NET 2.0 Framework. Another implementation for a different scheme system or GUI framework could be developed, if one so desired.
To use the functions provided by the image teachpack, use Common Larceny's require facility: (require "TeachPacks/image").
Before diving into the list of functions provided by the teachpack, it is important to understand some of the teachpack's data definitions.
Mode is one of the following two symbols or strings:
-- 'solid -- 'outline -- "solid" -- "outline"
'solid is used for creating solid basic shapes; 'outline is used for creating outlines of basic shapes. Strings are used in an analogous manner.
A CS is a color structure: (make-color N N N) where N is between 0 and 255.
A Color is one of:
-- a color symbol, e.g., 'blue -- a color string, e.g., "blue" -- a CS, e.g., (make-color 0 0 255), which also denotes blue.
Color arguments are used to paint the shapes or their outlines. See below for more information about colors. Additionally, the following predicate precisely specifies what a valid image color is:
image-color? : anything -> boolean`
The image teachpack provides the following functions, which are also provided by the PLT image teachpack.
rectangle : Int Int Mode Color -> Image
Creates a rectangle using the given width, height, mode, and color
circle : Int Mode Color -> Image
Creates a circle using the given radius, mode, and color
ellipse : Int Int Mode Color -> Image
Creates an ellipse using the given width, height, and color
triangle : Int Mode Color -> Image
Creates an upward pointing equilateral triangle using the given edge size and color
star : Int[>=2] Int[>=1] Int[>=1] Mode Color -> Image
Creates a multi-pointed star; the first number specifies the number of points, the second specifies the radius where the points begin and the third specifies the radius where they end.
line : Int Int Color -> Image
Creates an image with a colored line from (0,0) to the point with the given coordinates
add-line : Image Int Int Int Int Color -> Image
Adds a line to an existing image, drawn between the two given points
text : String Size Color -> Image
Creates an image of the text in the given string, with the point size, and color specified by the last two arguments
Images have many properties. To understand how functions manipulate and create images, we need to understand one of these properties immediately: pinholes. Each image, including primitive shapes, come with a pinhole. Usually the pinhole is in the center of the shape except for those created from line and text, which have pinholes at the top left. When in doubt you can always find out where the pinhole is and even place it somewhere else:
pinhole-x : Image -> Int
Determines the x coordinate of the pinhole, measuring from the left of the image
pinhole-y : Image -> Int
Determines the y coordinate of the pinhole, measuring down from the top of the image
put-pinhole : Image Int Int -> Image
Puts the pinhole in the location specified by the arguments, counting from the left and down from the top, respectively.
move-pinhole : Image Int Int -> Image
Moves the pinhole down and to the right (by the specified amounts) of its current location. Use negative numbers to move it up or to the left.
The next group of functions build images from images:
overlay : Image Image Image … -> Image
Adds the pixels of the second Image onto the first image. The operation lines up the images via their pinholes.
overlay/xy : Image Int Int Image -> Image
Adds the pixels of the second image onto the first image. Instead of lining up on the pinhole, the second image's pinhole is lined up with an offset from the first image's pinhole. The two coordinates specify how far down and to the right the offset should be. The pinhole of the resulting image is the same place as the pinhole in the first image.
image-inside? : Image Image -> Boolean
Determines whether the pixels of the second image appear in the first.
find-image : Image Image -> Posn
Determines where the pixels of the second image appear in the first, with respect to the pinhole of the first image.
Two more properties of images are useful for image manipulations: their width and height. The two functions for extracting these properties are:
image-width : Image -> Int
Obtains an Image's width in pixels
image-height : Image -> Int
Obtains an image's height in pixels
Bitmap images can be constructed from existing files or from lists of colors.
A List-of-color is one of:
-- empty -- (cons Color List-of-color)
A List-of-color represents a sequence of colors. It is possible to extract an image's colors and pixels and to create images from a list of colors.
image->color-list : Image -> List-of-color Converts an image to a list of colors
color-list->image : List-of-color Nat Nat Nat Nat -> Image
Converts a list of colors to an image with the given width and height, and pinhole coordinates (the pinhole coordinates are with respect to the top-left of the image).
Additionally, images can be created from existing files.
image-from-file : string -> Image
Constructs a bitmap image from the given file path
The shrink functions trim an image by eliminating extraneous pixels.
shrink-tl : Image Int Int -> Image
Shrinks the image, starting from the top-left corner. The two numbers indicate how many pixels to save. The pinhole of the resulting image is in the middle of the image.
shrink-tr : Image Int Int -> Image
Shrinks the image, starting from the top-right corner. The two numbers indicate how many pixels to save. The pinhole of the resulting image is in the middle of the image.
shrink-bl : Image Int Int -> Image
Shrinks the image, starting from the bottom-left corner. The two numbers indicate how many pixels to save. The pinhole of the resulting image is in the middle of the image.
shrink-br : Image Int Int -> Image
Shrinks the image, starting from the bottom-right corner. The two numbers indicate how many pixels to save. The pinhole of the resulting image is in the middle of the image.
shrink : Image Int Int Int Int -> Image
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.
The following functions extract the consitiuent colors from an image and combine colors into an image, but the functions provide alpha-channel information as well. Alpha channels are a measure of transparency; 0 indicates fully opaque and 255 indicates fully transparent.
image->alpha-color-list : image -> list-of-alpha-color
Converts an image to a list of alpha colors
alpha-color-list->image : list-of-alpha-color int int int int -> image
Converts a list of alpha colors to an image with the given width and height, and pinhole coordinates (the pinhole coordinates are with respect to the top-left of the image).
make-alpha-color : int int int int -> color
Constructs an alpha color
alpha-color? : anything -> boolean
Determines if its input is a color
alpha-color-alpha : color -> int
Extracts the alpha value of a color
alpha-color-red : color -> int
Extract the red component of a color
alpha-color-green : color -> int
Extracts the green component of a color
alpha-color-blue : color -> int
Extract the blue component of a color