Bill Manaris : Fall 2006 / Python Media API

Python Media API

This is API documentation for the Mediacomp Software (JES, etc.) maintained by Mark Guzdial and his colleagues at Georgia Tech.

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:

from am external JPEG file.

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.


Sound I/O

To input an external WAV file into an internal Sound encoding.
Also, to output an internal encoding to an external WAV file.

The following functions manipulate a sound.

Function

Description

pickAFile()

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

makeSound(filename)

Takes a filename as input, reads the file, and creates a sound from it. Returns the sound.

makeEmptySound(length)

Creates an empty sound with length samples. Returns the sound.

play(sound)

Plays a sound provided as input. No return value.

blockingPlay(sound)

Plays a sound provided as input and makes sure that no other sound plays at the exact same time. No return value.

writeSoundTo(sound,"file.wav")

Writes sound to the file called "file.wav". Returns nothing.

Definitions

Objects used internally to store external sounds:

Sound Functions

To access the internal Sound encoding:

getLength(sound)

Returns the number of samples in sound.

getSamplingRate(sound)

Returns the number of samples per second in sound.

getSamples(sound)

Returns a list of samples from sound.

getSampleValueAt(sound,index)

Returns the sample of sound at index.

setSampleValueAt(sound,index,value)

Sets the sample of sound at index to value.

(Printable View of http://www.cs.cofc.edu/~manaris/?n=Fall2006.PythonMediaAPI)