Graphical displays with Python and Pygame

Pygame Surfaces

Surfaces are Pygame's variables. You can create a surface, draw to it, change its size and characteristics, and perhaps at some point draw it to the screen – but you don't have to. Often, it can be easier to create a surface, perform drawing operations on it, and then draw the end result to the screen.

In fact, the screen variable I created earlier is also a surface and shares all of its capabilities. It has the special property that anything drawn to it will eventually show up in the graphics window.

Rects represent subareas of a screen or surface and are used throughout Pygame whenever a screen region needs to be referenced. Pygame also uses them to define a region for drawing functions or to select a smaller region of a surface to blit. For most functions that ask for a rect, you can also pass a four-part tuple. The first two parts are the (x, y) coordinates of the upper left corner of the region. The third and fourth parts are the width (extending to the right of x) and height (extending below y).

Show an Image

In nine lines of actual code, Listing 1 shows a simple program that looks to the command line for an image file name, loads it, and displays it in an identically sized window. Then, it waits for the user to press Enter to exit. Here, I'll look at the Pygame-specific information. All line numbers refer to Listing 1.

01 import pygame
02 import sys
03
04 pygame.display.init()
05
06 imgSurf = pygame.image.load ( sys.argv [ 1 ] )
07 screen = pygame.display.set_mode ( imgSurf.get_size() )
08 screen.blit ( imgSurf, ( 0, 0 ) )
09 pygame.display.flip()
10
11 raw_input()
12 pygame.quit()

As I discussed above, line 4 initializes the display. Because my script's entire purpose in life is to show a single image, I next load an external file with the pygame.image module (line 6). Its load method takes the file name provided at the command line and loads that file. imgSurf is then a Pygame surface with all of the rights and privileges therein.

In line 7, I create a Pygame window the same size as imgSurf by calling set_mode. imgSurf.get_size() returns a tuple with the width and height of imgSurf.

One of the most common surface operations is blitting, or copying one surface onto another. Line 8 shows the basic syntax, which calls blit on the destination surface. The first argument is the surface to copy – in my case, the image I loaded in line 6. The second argument is where to put the surface on the destination, provided as an (x, y) tuple. An optional third argument (not used here) is a rect specifying what portion of the surface to copy.

So far, just about everything has happened in memory. Although set_mode in line 7 makes a window appear, it remains blank until the display is flipped. Line 9, with pygame.display.flip(), does the job, and the image is displayed. The raw_input() command (line 11) waits for the user to finish viewing the picture, and line 12 shuts down Pygame. Now I have a simple image viewer script, which I can add to my shell scripts to view photos, show graphs, or display those reports my logging analyzer generates. The command

python simpleImage.py network.png

creates the window shown in Figure 1.

Figure 1: The simpleImage.py program creates a graphics window and displays network.png [2].