The images API

 

The images module includes a single class named Image. Each Image object represents an image. The programmer can supply the file name of an image on disk when Image is instantiated. The resulting Image object contains pixels loaded from an image file on disk. If a file name is not specified, a height and width must be. The resulting Image object contains the specified number of pixels with a single default color.

When the programmer imports the Image class and instantiates it, no window pops up. At that point, the programmer can run various methods with this Image object to access or modify its pixels, as well as save the image to a file. At any point in your code, you may run the draw method with an Image object. At this point, a window will pop up and display the image. The program will then wait for you to close the window before allowing you, either in the shell or in a script, to continue running more code.

The positions of pixels in an image are the same as screen coordinates for display in a window. That is, the origin (0, 0) is in the upper left corner of the image, and its (width, height) is in the lower right corner.

Images can be manipulated either interactively within a Python shell or from a Python script. Once again, we recommend that the shell or script by launched from a system terminal rather than from IDLE.

Unlike Turtle objects, Image objects cannot be viewed in multiple windows at the same time from the same script. If you want to view two or more Image objects simultaneously, you can create separate scripts for them and launch these in separate terminal windows.

There are two versions of the images module. One version, contained in the file images.py, supports the use of GIF files only, and works with Python 2 and 3. The other, contained in the file pilimages.py, supports the use of several common image file formats, such as GIF, JPEG, and PNG, and works with Python 2 only. Depsite these differences, the Image class in both versions has the same interface. Here is a list of the

Image Methods

Image(filename) Loads an image from the file named fileName and returns an Image object that represents this image. The file must exist in the current working directory.

Image(width, height) Returns an Image object of the specified width and height with a single default color.

getWidth() Returns the width of the image in pixels.

getHeight() Returns the width of the image in pixels.

getPixel() Returns the pixel at the specified coordinates. A pixel is of the form (r, g, b), where the letters are integers representing the red, green, and blue values of a color in the RGB system.

setPixel(x, y, (r, g, b)) Resets the pixel at position (x, y) to the color value represented by (r, g, b). The coordinates must be in the range of the image's coordinates and the RGB values must range from 0 through 255.

draw() Pops up a window and displays the image. The user must close the window to continue the program.

clone() Returns an Image object that is an exact copy of the original object.

save() Saves the image to its current file, if it has one. Otherwise, does nothing.

save(filename) Saves the image to the given file and makes it the current file. This is similar to the Save As option in most File menus.