Fall2006.PythonMediaImageAPI History

Hide minor edits - Show changes to output

Added lines 1-177:
!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.

(:table border=1 width=80%:)
(:cell style='padding:5px;':)
'''''Function'''''
(:cell style='padding:5px;':)
'''''Description'''''
(:cellnr style='padding:5px;':)
pickAFile()
(:cell style='padding:5px;':)
Lets the user pick a file. Returns the complete
path name as a string.
(:cellnr style='padding:5px;':)
makePicture(''filename'')
(:cell style='padding:5px;':)
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.
(:cellnr style='padding:5px;':)
makeEmptyPicture(''width'', ''height'')
(:cell style='padding:5px;':)
Takes a width and height as input, and creates
an empty (all black) '''Picture''' object from it. Returns the '''Picture''' object.
(:cellnr style='padding:5px;':)
show(''picture'')
(:cell style='padding:5px;':)
Displays the image stored in a '''Picture''' object.
(:cellnr style='padding:5px;':)
repaint(''picture'')
(:cell style='padding:5px;':)
Updates the display of a modified '''Picture''' object. (Note: This does NOT change the external JPEG image, only the internal encoding.)
(:cellnr style='padding:5px;':)
writePictureTo(''picture'', ''filename'')
(:cell style='padding:5px;':)
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"!)
(:tableend:)

!!!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% red, %green% green, %% and %blue% blue %% values, each between 0 and 255.

!!!Picture Functions

To access the internal '''Picture''' encoding:

(:table border=1 width=80%:)
(:cellnr style='padding:5px;':)
getPixels(''picture'')
(:cell style='padding:5px;':)
Returns a '''Pixels''' object from the picture.
(:cellnr style='padding:5px;':)
getPixel(''picture'', ''x'', ''y'')
(:cell style='padding:5px;':)
Takes a '''Picture''', an x position and a y position (two numbers). Returns the '''Pixel''' object at that point in the picture.
(:cellnr style='padding:5px;':)
getWidth(''picture'')
(:cell style='padding:5px;':)
Takes a '''Picture''' as input. Returns its width, i.e., the number of pixels across a row in the picture.
(:cellnr style='padding:5px;':)
getHeight(''picture'')
(:cell style='padding:5px;':)
Takes a '''Picture''' as input and returns its length, i.e., the number of pixels down a column in the picture.
(:tableend:)

To modify the '''Picture''' encoding:

(:table border=1 width=80%:)
(:cell style='padding:5px;':)
addText(''picture'', ''x'', ''y'', ''text'')
(:cell style='padding:5px;':)
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.
(:cellnr style='padding:5px;':)
addLine(''picture'', ''x1'', ''y1'', ''x2'', ''y2'')
(:cell style='padding:5px;':)
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.
(:cellnr style='padding:5px;':)
addRect(''picture'', ''x'', ''y'', ''width'', ''height'')
(:cell style='padding:5px;':)
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.
(:cellnr style='padding:5px;':)
addRectFilled(''picture'', ''x'', ''y'', ''width'', ''height'', ''color'')
(:cell style='padding:5px;':)
Exactly like addRect, but fills the rectangle with specified color.
(:tableend:)

!!!Pixel Functions

To access the '''Pixel''' encoding:

(:table border=1 width=80%:)
(:cell style='padding:5px;':)
getRed(''pixel'')\\
getGreen(''pixel'')\\
getBlue(''pixel'')
(:cell style='padding:5px;':)
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.
(:cellnr style='padding:5px;':)
getColor(''pixel'')
(:cell style='padding:5px;':)
Takes a '''Pixel''' object and returns the '''Color''' object at that pixel.
(:tableend:)

To modify the '''Pixel''' encoding:

(:table border=1 width=80%:)
(:cell style='padding:5px;':)
setRed(''pixel'', ''value'')\\
setGreen(''pixel'', ''value'')\\
getBlue(''pixel'', ''value'')
(:cell style='padding:5px;':)
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.
(:cellnr style='padding:5px;':)
setColor(''pixel'', ''color'')
(:cell style='padding:5px;':)
Takes a '''Pixel''' object and a '''Color''' object and sets the color for that pixel.
(:tableend:)

!!!Color Function

To access the '''Color''' encoding:

(:table border=1 width=80%:)
(:cell style='padding:5px;':)
getColor(''pixel'')
(:cell style='padding:5px;':)
Takes a '''Pixel''' and returns the '''Color''' object at that pixel.
(:tableend:)

To modify the '''Color''' encoding:

(:table border=1 width=80%:)
(:cell style='padding:5px;':)
setColor(''pixel'', ''color'')
(:cell style='padding:5px;':)
Takes a '''Pixel''' object and a '''Color''' object and sets the color for that pixel.
(:cellnr style='padding:5px;':)
makeColor(''red'', ''green'', ''blue'')
(:cell style='padding:5px;':)
Takes three values (between 0 and 255) for the red, green, and blue components (in order), then returns a '''Color''' object.
(:cellnr style='padding:5px;':)
pickAColor()
(:cell style='padding:5px;':)
It displays a color picker for the user to select a color. It returns the corresponding '''Color''' object.
(:cellnr style='padding:5px;':)
makeDarker(''color''),\\
makeLighter(''color'')
(:cell style='padding:5px;':)
Each take a '''Color''' object and return a slightly darker or lighter (respectively) '''Color'''. They do not modify the input '''Color''' object.
(:tableend:)

Predefined '''Color''' ''constants'':

'''black''', %white%white, %blue% '''blue''', %red% '''red''', %green% '''green''', %gray% '''gray''', %color=#404040% '''darkGray''', %color=#c0c0c0% '''lightGray''', %yellow% '''yellow''', %color=#ffc800% '''orange''', %color=#ffafaf% '''pink''', %color=#ff00ff% '''magenta''', %color=#00ffff% '''cyan'''.\\
%black%(black, white, blue, red, green, gray, darkGray, lightGray, yellow, orange, pink, magenta, cyan.)

To get the distance between two '''Color''' objects:

(:table border=1 width=80%:)
(:cell style='padding:5px;':)
distance(''color1'', ''color2'')
(:cell style='padding:5px;':)
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.
(:tableend:)