Fall 2006»Python Media Image API

Python Media Image API

Python Media API

Image I/O

To input an external JPEG image into an internal Picture encoding.
Also, to write an internal encoding to an external JPEG image.

Function

Description

pickAFile()

Lets the user pick a file. Returns the complete path name as a string.

makePicture(filename)

Takes a filename as input, reads the external image stored in that file, and creates an internal Picture object from it. Returns the Picture object.

makeEmptyPicture(width, height)

Takes a width and height as input, and creates an empty (all black) Picture object from it. Returns the Picture object.

show(picture)

Displays the image stored in a Picture object.

repaint(picture)

Updates the display of a modified Picture object. (Note: This does NOT change the external JPEG image, only the internal encoding.)

writePictureTo(picture, filename)

Takes a Picture and a file name (string) as input, and saves the internal picture encoding to an external JPEG image. (Be sure to end the filename in ".jpg"!)

Definitions

Objects used internally to store external images:

  • Picture - an internal encoding of an image, typically coming

from am external JPEG file.

  • Pixel - a dot in the Picture. It has a color and an (x, y) position associated with it.
  • Pixels - a sequence of Pixel objects. It converts the two dimensional nature of a picture into a line-like sequence of pixels. For example, pixels[1] returns the leftmost pixel in a picture.
  • Color - a set of red, green, and blue values, each between 0 and 255.

Picture Functions

To access the internal Picture encoding:

getPixels(picture)

Returns a Pixels object from the picture.

getPixel(picture, x, y)

Takes a Picture, an x position and a y position (two numbers). Returns the Pixel object at that point in the picture.

getWidth(picture)

Takes a Picture as input. Returns its width, i.e., the number of pixels across a row in the picture.

getHeight(picture)

Takes a Picture as input and returns its length, i.e., the number of pixels down a column in the picture.

To modify the Picture encoding:

addText(picture, x, y, text)

Takes a Picture, an x position and a y position (two numbers), and some text as a string, which will get drawn into the picture.

addLine(picture, x1, y1, x2, y2)

Takes a Picture, a starting (x, y) position (two numbers), and an ending (x, y) position (two more numbers, four total) and draws a black line from the starting point to the ending point in the picture.

addRect(picture, x, y, width, height)

Takes a Picture, a starting (x, y) position (two numbers), and a width and height (two more numbers, four total) then draws a black rectangle in outline of the given width and height with the position (x, y) as the upper left corner.

addRectFilled(picture, x, y, width, height, color)

Exactly like addRect, but fills the rectangle with specified color.

Pixel Functions

To access the Pixel encoding:

getRed(pixel)
getGreen(pixel)
getBlue(pixel)

Each of these functions takes a Pixel object and returns the value (between 0 and 255) of the amount of redness, greenness, and blueness (respectively) in that pixel.

getColor(pixel)

Takes a Pixel object and returns the Color object at that pixel.

To modify the Pixel encoding:

setRed(pixel, value)
setGreen(pixel, value)
getBlue(pixel, value)

Each of these functions takes a Pixel object and a value (between 0 and 244) and sets the redness, greenness, or blueness (respectively) of that pixel to the given value.

setColor(pixel, color)

Takes a Pixel object and a Color object and sets the color for that pixel.

Color Function

To access the Color encoding:

getColor(pixel)

Takes a Pixel and returns the Color object at that pixel.

To modify the Color encoding:

setColor(pixel, color)

Takes a Pixel object and a Color object and sets the color for that pixel.

makeColor(red, green, blue)

Takes three values (between 0 and 255) for the red, green, and blue components (in order), then returns a Color object.

pickAColor()

It displays a color picker for the user to select a color. It returns the corresponding Color object.

makeDarker(color),
makeLighter(color)

Each take a Color object and return a slightly darker or lighter (respectively) Color. They do not modify the input Color object.

Predefined Color constants:

black, white, blue, red, green, gray, darkGray, lightGray, yellow, orange, pink, magenta, cyan.
(black, white, blue, red, green, gray, darkGray, lightGray, yellow, orange, pink, magenta, cyan.)

To get the distance between two Color objects:

distance(color1, color2)

Takes two Color objects. It treats the red, green, and blue values of the colors as a point in (x, y, z) space, and calculates the cartesian distance. Returns a single number representing their distance.