« back to all changes in this revision
Viewing changes to docs/tut/SurfarrayIntro.html
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Ed Boraas
- Date: 2002-02-20 06:39:24 UTC
- Revision ID: james.westby@ubuntu.com-20020220063924-amlzj7tqkeods4eq
Tags: upstream-1.4
Import upstream version 1.4
- files added:
- docs
- docs/ref
- docs/tut
- docs/util
- examples
- examples/data
- lib
- src
- test
added
removed
docs/tut/SurfarrayIntro.html
1
<!--
2
TUTORIAL:Introduction to the surfarray module
3
--><html><head>
4
5
<title>Pygame Tutorials - Surfarray Introduction</title>
6
</head><body>
7
8
<h1 align=center><font size=-1>Pygame Tutorials</font><br>Surfarray Introduction</h1>
9
<h2 align=center>by Pete Shinners<br><font size=-1>pete@shinners.org</font></h2>
10
<h3 align=center>Revision 1.01, May 4, 2001</h3>
11
<br><br>
12
13
14
<h2>Introduction</h2>
15
16
This tutorial will attempt to introduce users to both Numeric and the pygame
17
Surfarray module. To beginners, the code that uses surfarray can be quite
18
intimidating. But actually there are only a few concepts to understand and
19
you will be up and running. Using the surfarray module, it becomes possible
20
to perform pixel level operations from straight python code. The performance
21
can become quite close to the level of doing the code in C.
22
<br> <br>
23
You may just want to jump down to the <i>"Examples"</i> section to get an
24
idea of what is possible with this module, then start at the beginning here
25
to work your way up.
26
<br> <br>
27
Now I won't try to fool you into thinking everything is very easy. To get
28
more advanced effects by modifying pixel values is very tricky. Just mastering
29
Numeric Python takes a lot of learning. In this tutorial I'll be sticking with
30
the basics and using a lot of examples in an attempt to plant seeds of wisdom.
31
After finishing the tutorial you should have a basic handle on how the surfarray
32
works.
33
34
35
<br>
36
<h2>Numeric Python</h2>
37
If you do not have the python Numeric
38
package installed, you will need to do that now. You can download the package
39
from the <a href=http://sourceforge.net/project/showfiles.php?group_id=1369>
40
Numeric Downloads Page</a>. To make sure Numeric is working for you, you should
41
get something like this from the interactive python prompt.
42
<br><table bgcolor=#ddcc88><tr><td><pre>
43
>>> <b>from Numeric import *</b> <i>#import numeric</i>
44
>>> <b>a = array((1,2,3,4,5))</b> <i>#create an array</i>
45
>>> <b>a</b> <i>#display the array</i>
46
array([1, 2, 3, 4, 5])
47
>>> <b>a[2]</b> <i>#index into the array</i>
48
3
49
>>> <b>a*2</b> <i>#new array with twiced values</i>
50
array([ 2, 4, 6, 8, 10])
51
</td></tr></table><br>
52
53
As you can see, the Numeric module gives us a new data type, the <i>array</i>.
54
This object holds an array of fixed size, and all values inside are of the same
55
type. The arrays can also be multidimensional, which is how we will use them
56
with images. There's a bit more to it than this, but it is enough to get us
57
started.
58
<br> <br>
59
If you look at the last command above, you'll see that mathematical operations
60
on Numeric arrays apply to all values in the array. This is called "elementwise
61
operations". These arrays can also be sliced like normal lists. The slicing
62
syntax is the same as used on standard python objects. <i>(so study up if you
63
need to :] )</i>.
64
Here are some more examples of working with arrays.
65
66
<br><table bgcolor=#ddcc88><tr><td><pre>
67
>>> <b>len(a)</b> <i>#get array size</i>
68
5
69
>>> <b>a[2:]</b> <i>#elements 2 and up</i>
70
array([3, 4, 5])
71
>>> <b>a[:-2]</b> <i>#all except last 2</i>
72
array([1, 2, 3])
73
>>> <b>a[2:] + a[:-2]</b> <i>#add first and last</i>
74
array([4, 6, 8])
75
>>> <b>array((1,2,3)) + array((3,4))</b> <i>#add arrays of wrong sizes</i>
76
Traceback (innermost last):
77
File "<interactive input>", line 1, in ?
78
ValueError: frames are not aligned
79
</td></tr></table><br>
80
81
We get an error on the last commend, because we try add together two arrays
82
that are different sizes. In order for two arrays two operate with each other,
83
including comparisons and assignment, they must have the same dimensions. It is
84
very important to know that the new arrays created from slicing the original all
85
reference the same values. So changing the values in a slice also changes the
86
original values. It is important how this is done.
87
<br><table bgcolor=#ddcc88><tr><td><pre>
88
>>> <b>a</b> <i>#show our starting array</i>
89
array([1, 2, 3, 4, 5])
90
>>> <b>aa = a[1:3]</b> <i>#slice middle 2 elements</i>
91
>>> <b>aa</b> <i>#show the slice</i>
92
array([2, 3])
93
>>> <b>aa[1] = 13</b> <i>#chance value in slice</i>
94
>>> <b>a</b> <i>#show change in original</i>
95
array([ 1, 2, 13, 4, 5])
96
>>> <b>aaa = array(a)</b> <i>#make copy of array</i>
97
>>> <b>aaa</b> <i>#show copy</i>
98
array([ 1, 12, 13, 4, 5])
99
>>> <b>aaa[1:4] = 0</b> <i>#set middle values to 0</i>
100
>>> <b>aaa</b> <i>#show copy</i>
101
array([1, 0, 0, 0, 5])
102
>>> <b>a</b> <i>#show original again</i>
103
array([ 1, 2, 13, 4, 5])
104
</td></tr></table><br>
105
106
107
Now we will look at small arrays with two
108
dimensions. Don't be too worried, getting started it is the same as having a
109
two dimensional tuple <i>(a tuple inside a tuple)</i>. Let's get started with
110
two dimensional arrays.
111
112
<br><table bgcolor=#ddcc88><tr><td><pre>
113
>>> <b>row1 = (1,2,3)</b> <i>#create a tuple of vals</i>
114
>>> <b>row2 = (3,4,5)</b> <i>#another tuple</i>
115
>>> <b>(row1,row2)</b> <i>#show as a 2D tuple</i>
116
((1, 2, 3), (3, 4, 5))
117
>>> <b>b = array((row1, row2))</b> <i>#create a 2D array</i>
118
>>> <b>b</b> <i>#show the array</i>
119
array([[1, 2, 3],
120
[3, 4, 5]])
121
>>> <b>array(((1,2),(3,4),(5,6)))</b> <i>#show a new 2D array</i>
122
array([[1, 2],
123
[3, 4],
124
[5, 6]])
125
</td></tr></table><br>
126
127
Now with this two
128
dimensional array <i>(from now on as "2D")</i> we can index specific values
129
and do slicing on both dimensions. Simply using a comma to separate the indices
130
allows us to lookup/slice in multiple dimensions. Just using "<b>:</b>" as an
131
index <i>(or not supplying enough indices)</i> gives us all the values in
132
that dimension. Let's see how this works.
133
134
<br><table bgcolor=#ddcc88><tr><td><pre>
135
>>> <b>b</b> <i>#show our array from above</i>
136
array([[1, 2, 3],
137
[3, 4, 5]])
138
>>> <b>b[0,1]</b> <i>#index a single value</i>
139
2
140
>>> <b>b[1,:]</b> <i>#slice second row</i>
141
array([3, 4, 5])
142
>>> <b>b[1]</b> <i>#slice second row (same as above)</i>
143
array([3, 4, 5])
144
>>> <b>b[:,2]</b> <i>#slice last column</i>
145
array([3, 5])
146
>>> <b>b[:,:2]</b> <i>#slice into a 2x2 array</i>
147
array([[1, 2],
148
[3, 4]])
149
</td></tr></table><br>
150
151
Ok, stay with me here, this is about as hard as it gets. When using Numeric
152
there is one more feature to slicing. Slicing arrays also allow you to specify
153
a <i>slice increment</i>. The syntax for a slice with increment is
154
<b>start_index : end_index : increment</b>.
155
156
<br><table bgcolor=#ddcc88><tr><td><pre>
157
>>> <b>c = arange(10)</b> #like range, but makes an array
158
>>> <b>c</b> #show the array
159
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
160
>>> <b>c[1:6:2]</b> #slice odd values from 1 to 6
161
array([1, 3, 5])
162
>>> <b>c[4::4]</b> #slice every 4th val starting at 4
163
array([4, 8])
164
>>> <b>c[8:1:-1]</b> #slice 1 to 8, reversed
165
array([8, 7, 6, 5, 4, 3, 2])
166
</td></tr></table><br>
167
168
Well that is it. There's enough information there to get you started using
169
Numeric with the surfarray module. There's certainly a lot more to Numeric, but
170
this is only an introduction. Besides, we want to get on to the fun stuff,
171
correct?
172
173
174
175
176
177
<br> <br>
178
<h2>Import Surfarray</h2>
179
180
In order to use the surfarray module we need to import it. Since both surfarray
181
and Numeric are optional components for pygame, it is nice to make sure they
182
import correctly before using them. In these examples I'm going to import
183
Numeric into a variable named <i>N</i>. This will let you know which functions
184
I'm using are from the Numeric package. <i>(and is a lot shorter than typing
185
Numeric before each function)</i>
186
187
188
<br><table bgcolor=#ddcc88><tr><td><pre>
189
try:
190
import Numeric as N
191
import pygame.surfarray as surfarray
192
except ImportError:
193
raise ImportError, "Numeric and Surfarray are required."
194
</td></tr></table><br>
195
196
<br> <br>
197
<h2>Surfarray Introduction</h2>
198
199
There are two main types of functions in surfarray. One set of functions for
200
creating an array that is a copy of a surface pixel data. The other functions
201
create a referenced copy of the array pixel data, so that changes to the array
202
directly effect the original surface. There are other functions that allow you
203
to access any per-pixel alpha values as arrays along with a few other helpful
204
functions. We will look at these other functions later on.
205
<br> <br>
206
When working with these surface arrays, there are two ways of representing the
207
pixel values. First, they can be represented as mapped integers. This type of
208
array is a simple 2D array with a single integer representing the surface's
209
mapped color value. This type of array is good for moving parts of an image
210
around. The other type of array uses three RGB values to represent each pixel
211
color. This type of array makes it extremely simple to do types of effects that
212
change the color of each pixel. This type of array is also a little trickier to
213
deal with, since it is essentially a 3D numeric array. Still, once you get your
214
mind into the right mode, it is not much harder than using the normal 2D arrays.
215
<br> <br>
216
The Numeric module uses a machine's natural number types to represent the data
217
values, so a Numeric array can consist of integers that are 8bits, 16bits, and 32bits.
218
<i>(the arrays can also use other types like floats and doubles, but for our image
219
manipulation we mainly need to worry about the integer types)</i>.
220
Because of this limitation of integer sizes, you must take a little extra care
221
that the type of arrays that reference pixel data can be properly mapped to a
222
proper type of data. The functions create these arrays from surfaces are:
223
<dl>
224
<dt><b>surfarray.pixels2d(surface)</b></dt><dd>Creates a 2D array <i>(integer pixel
225
values)</i> that reference the original surface data. This will work for all
226
surface formats except 24bit.</dd>
227
228
<dt><b>surfarray.array2d(surface)</b><dd></dd>Creates a 2D array <i>(integer pixel
229
values)</i> that is copied from any type of surface.</dt>
230
231
<dt><b>surfarray.pixels3d(surface)</b></dt><dd>Creates a 3D array <i>(RGB pixel
232
values)</i> that reference the original surface data. This will only work
233
on 24bit and 32bit surfaces that have RGB or BGR formatting.</dd>
234
235
<dt><b>surfarray.array3d(surface)</b><dd></dd>Creates a 3D array <i>(RGB pixel
236
values)</i> that is copied from any type of surface.</dt>
237
238
</dl>
239
Here is a small chart that might better illustrate what types of functions
240
should be used on which surfaces. As you can see, both the arrayXD functions
241
will work with any type of surface.
242
<table bgcolor=#ddcc88 cellpadding=8 align=center>
243
<tr align=center><td></td><th>32bit</th><th>24bit</th><th>16bit</th><th>8bit(c-map)</th></tr>
244
<tr align=center><th>pixel2d</th><td>yes</td><td></td><td>yes</td><td>yes</td></tr>
245
<tr align=center><th>array2d</th><td>yes</td><td>yes</td><td>yes</td><td>yes</td></tr>
246
<tr align=center><th>pixel3d</th><td>yes</td><td>yes</td><td></td><td></td></tr>
247
<tr align=center><th>array3d</th><td>yes</td><td>yes</td><td>yes</td><td>yes</td></tr>
248
</table>
249
250
251
<br> <br>
252
<h2>Examples</h2>
253
254
With this information, we are equipped to start trying things with surface
255
arrays. The following are short little demonstrations that create a Numeric
256
array and display them in pygame. These different tests are found in the
257
<i>arraydemo.py</i> example. There is a simple function named <i>surfdemo_show</i>
258
that displays an array on the screen.
259
260
<br> <br><table border=1 cellpadding=5>
261
262
<tr><td><img align=left src=allblack.jpg alt=allblack width=128 height=128>
263
<table bgcolor=#ddcc88><tr><td><pre>
264
allblack = N.zeros((128, 128))
265
surfdemo_show(allblack, 'allblack')
266
</td></tr></table>
267
Our first example creates an all black array. Whenever you need
268
to create a new numeric array of a specific size, it is best to use the
269
<b>zeros</b> function. Here we create a 2D array of all zeros and display
270
it.
271
</td></tr>
272
273
<tr><td><img align=left src=striped.jpg alt=striped width=128 height=128>
274
<table bgcolor=#ddcc88><tr><td><pre>
275
striped = N.zeros((128, 128, 3))
276
striped[:] = (255, 0, 0)
277
striped[:,::3] = (0, 255, 255)
278
surfdemo_show(striped, 'striped')
279
</td></tr></table>
280
Here we are dealing with a 3D array. We start by creating an all red image.
281
Then we slice out every third row and assign it to a blue/green color. As you
282
can see, we can treat the 3D arrays almost exactly the same as 2D arrays, just
283
be sure to assign them 3 values instead of a single mapped integer.
284
<i>(grr, jpg kind of wrecked the colors)</i>
285
</td></tr>
286
287
<tr><td><img align=left src=imgarray.jpg alt=imgarray width=200 height=128>
288
<table bgcolor=#ddcc88><tr><td><pre>
289
imgsurface = pygame.image.load('surfarray.jpg')
290
imgarray = surfarray.array2d(imgsurface)
291
surfdemo_show(imgarray, 'imgarray')
292
</td></tr></table>
293
Here we load an image with the image module, then convert it to a 2D
294
array of integers. We will use this image in the rest of the samples.
295
</td></tr>
296
297
<tr><td><img align=left src=flipped.jpg alt=flipped width=200 height=128>
298
<table bgcolor=#ddcc88><tr><td><pre>
299
flipped = imgarray[:,-1:0:-1]
300
surfdemo_show(flipped, 'flipped')
301
</td></tr></table>
302
Here we flip the image vertically. All we need to do is take the original
303
image array and slice it using a negative increment.
304
</td></tr>
305
306
<tr><td><img align=left src=scaledown.jpg alt=scaledown width=64 height=64>
307
<table bgcolor=#ddcc88><tr><td><pre>
308
scaledown = imgarray[::2,::2]
309
surfdemo_show(scaledown, 'scaledown')
310
</td></tr></table>
311
Based on the last example, scaling an image down is pretty logical. We just
312
slice out all the pixels using an increment of 2 vertically and horizontally.
313
</td></tr>
314
315
316
<tr><td><img align=left src=scaleup.jpg alt=scaleup width=400 height=256>
317
<table bgcolor=#ddcc88><tr><td><pre>
318
size = N.array(imgarray.shape)*2
319
scaleup = N.zeros(size)
320
scaleup[::2,::2] = imgarray
321
scaleup[1::2,::2] = imgarray
322
scaleup[:,1::2] = scaleup[:,::2]
323
surfdemo_show(scaleup, 'scaleup')
324
</td></tr></table>
325
Scaling the image up is a little more work, but is similar to the previous
326
scaling down, we do it all with slicing. First we create an array that is
327
double the size of our original. First we copy the original array into every
328
other pixel of the new array. Then we do it again for every other pixel doing
329
the odd columns. At this point we have the image scaled properly going across,
330
but every other row is black, so we simply need to copy each row to the one
331
underneath it. Then we have an image doubled in size.
332
</td></tr>
333
334
335
<tr><td><img align=left src=redimg.jpg alt=redimg width=200 height=128>
336
<table bgcolor=#ddcc88><tr><td><pre>
337
rgbarray = surfarray.array3d(imgsurface)
338
redimg = N.array(rgbarray)
339
redimg[:,:,1:] = 0
340
surfdemo_show(redimg, 'redimg')
341
</td></tr></table>
342
Now we are getting back to using 3D arrays to change the colors. Here we
343
simple make a 3D array from the original loaded image and set all the values
344
in green and blue to zero. This leaves us with just the red channel.
345
</td></tr>
346
347
348
<tr><td><img align=left src=soften.jpg alt=soften width=200 height=128>
349
<table bgcolor=#ddcc88><tr><td><pre>
350
soften = N.array(rgbarray)
351
soften[1:,:] += rgbarray[:-1,:]*8
352
soften[:-1,:] += rgbarray[1:,:]*8
353
soften[:,1:] += rgbarray[:,:-1]*8
354
soften[:,:-1] += rgbarray[:,1:]*8
355
soften /= 33
356
surfdemo_show(soften, 'soften')
357
</td></tr></table>
358
Here we perform a 3x3 convolution filter that will soften our image.
359
It looks like a lot of steps here, but what we are doing is shifting
360
the image 1 pixel in each direction and adding them all together (with some
361
multiplication for weighting). Then average all the values. It's no gaussian,
362
but it's fast.
363
</td></tr>
364
365
366
<tr><td><img align=left src=xfade.jpg alt=xfade width=200 height=128>
367
<table bgcolor=#ddcc88><tr><td><pre>
368
src = N.array(rgbarray)
369
dest = N.zeros(rgbarray.shape)
370
dest[:] = 20, 50, 100
371
diff = (dest - src) * 0.50
372
xfade = src + diff.astype(N.Int)
373
surfdemo_show(xfade, 'xfade')
374
</td></tr></table>
375
Lastly, we are cross fading between the original image and a solid blue-ish
376
image. Not exciting, but the dest image could be anything, and changing the 0.50
377
multiplier will let you choose any step in a linear crossfade between two images.
378
</td></tr>
379
</table><br>
380
381
Hopefully by this point you are starting to see how surfarray can be used to
382
perform special effects and transformations that are only possible at the pixel
383
level. At the very least, you can use the surfarray to do a lot of Surface.set_at()
384
Surface.get_at() type operations very quickly. But don't think you are finished
385
yet, there is still much to learn.
386
387
388
<br> <br>
389
<h2>Surface Locking</h2>
390
Like the rest of pygame, surfarray will lock any Surfaces it needs to
391
automatically when accessing pixel data. There is one extra thing to be aware
392
of though. When creating the <i>pixel</i> arrays, the original surface will
393
be locked during the lifetime of that pixel array. This is important to remember.
394
Be sure to <i>"del"</i> the pixel array or let it go out of scope <i>(ie, when
395
the function returns, etc)</i>.
396
<br> <br>
397
Also be aware that you really don't want to be doing much <i>(if any)</i>
398
direct pixel access on hardware surfaces <i>(HWSURFACE)</i>. This is because
399
the actual surface data lives on the graphics card, and transferring pixel
400
changes over the PCI/AGP bus is not fast.
401
402
403
404
<br> <br>
405
<h2>Transparancy</h2>
406
The surfarray module has several methods for accessing a Surface's alpha/colorkey
407
values. None of the alpha functions are effected by overal transparancy of a
408
Surface, just the pixel alpha values. Here's the list of those functions.
409
<dl>
410
<dt><b>surfarray.pixels_alpha(surface)</b></dt><dd>Creates a 2D array <i>(integer
411
pixel values)</i> that reference the original surface alpha data. This will only
412
work on 32bit images with an 8bit alpha component.</dd>
413
414
<dt><b>surfarray.array_alpha(surface)</b><dd></dd>Creates a 2D array <i>(integer pixel
415
values)</i> that is copied from any type of surface. If the surface has no alpha
416
values, the array will be fully opaque values <i>(255)</i>.</dt>
417
418
<dt><b>surfarray.array_colorkey(surface)</b><dd></dd>Creates a 2D array
419
<i>(integer pixel values)</i> that is set to transparent <i>(0)</i> wherever
420
that pixel color matches the Surface colorkey.</dt>
421
422
</dl>
423
424
425
<br> <br>
426
<h2>Other Surfarray Functions</h2>
427
There are only a few other functions available in surfarray. You can get a better
428
list with more documentation on the
429
<a href=http://pygame.seul.org/docs/ref/pygame_surfarray.html>surfarray
430
reference page</a>. There is one very useful function though.
431
<dl>
432
<dt><b>surfarray.blit_array(surface, array)</b></dt><dd>This will transfer
433
any type of 2D or 3D surface array onto a Surface of the same dimensions.
434
This surfarray blit will generally be faster than assigning an array to a
435
referenced pixel array. Still, it should not be as fast as normal Surface
436
blitting, since those are very optimized.
437
</dd>
438
</dl>
439
440
441
442
<br> <br>
443
<h2>More Advanced Numeric</h2>
444
There's a couple last things you should know about Numeric arrays. When dealing
445
with very large arrays, like the kind that are 640x480 big, there are some extra
446
things you should be careful about. Mainly, while using the operators like + and
447
* on the arrays makes them easy to use, it is also very expensive on big arrays.
448
These operators must make new temporary copies of the array, that are then
449
usually copied into another array. This can get very time consuming. Fortunately,
450
all the Numeric operators come with special functions that can perform the
451
operation <i>"in place"</i>. For example, you would want to replace
452
<b>screen[:] = screen + brightmap</b> with the much faster <b>add(screen,
453
brightmap, screen)</b>. Anyways, you'll want to read up on the Numeric UFunc
454
documentation for more about this. It is important when dealing with the arrays.
455
<br> <br>
456
When dealing with the 16bit pixel arrays, Numeric doesn't offer an unsigned 16bit
457
datatype, so some values will be treated as signed. Hopefully this does not
458
present a problem.
459
<br> <br>
460
Another thing to be aware of when working with Numeric arrays is the datatype
461
of the array. Some of the arrays (especially the mapped pixel type) often return
462
arrays with an unsigned 8bit value. These arrays will easily overflow if you are
463
not careful. Numeric will use the same coercion that you find in C programs, so
464
mixing an operation with 8bit numbers and 32bit numbers will give a result as
465
32bit numbers. You can convert the datatype of an array, but definitely be
466
aware of what types of arrays you have, if Numeric gets in a situation where
467
precision would be ruined, it will raise an exception.
468
<br> <br>
469
Lastly, be aware that when assigning values into the 3D arrays, they must be
470
between 0 and 255, or you will get some undefined truncating.
471
472
473
<br> <br>
474
<h2>Graduation</h2>
475
Well there you have it. My quick primer on Numeric python and surfarray.
476
Hopefully now you see what is possible, and even if you never use them for
477
yourself, you do not have to be afraid when you see code that does. Look into
478
the vgrade example for more numeric array action. There are also some <i>"flame"</i>
479
demos floating around that use surfarray to create a realtime fire effect.
480
<br> <br>
481
Best of all, try some things on your own. Take it slow at first and build up,
482
I've seen some great things with surfarray already like radial gradients and
483
more. Good Luck.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1