Mercurial > pygame

annotate src/pixelarray.doc @ 1849:301bc61643a9 math_module

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merged changes from trunk
author lorenz
date Mon, 16 Nov 2009 18:31:40 +0000
parents 3473707f449c
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
1 pygame.PixelArray
1024
3473707f449c typo fix
marcus
parents: 1007
diff changeset
2 pygame object for direct pixel access of surfaces
873
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
3 pygame.PixelArray(Surface): return PixelArray
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
4
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
5 The PixelArray wraps up a Surface and provides a direct 2D array access
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
6 to its pixels using the surface its rows as first and its columns as
982
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
7 second axis. It supports slicing, row and pixel manipluation, slicing
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
8 and slice assignments while inplace operations such as addition,
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
9 subtraction, multiplication, division and so forth are not allowed.
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
10
873
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
11 While it is possible to assign both, integer color values and RGB(A)
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
12 color tuples, the PixelArray will only use integers for the color
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
13 representation. Thus, checking for certain colors has to be done using
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
14 the Surface.map_rgb() method of the surface, the PixelArray was created
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
15 for.
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
16
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
17 pxarray = pygame.PixelArray (surface)
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
18 # Check, if the first pixel at the topleft corner is blue
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
19 if pxarray[0][0] == surface.map_rgb ((0, 0, 255)):
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
20 ...
5f702ba03cc1 Minor PixelArray doc improvements. Updated WHATSNEW list.
marcus
parents: 870
diff changeset
21
877
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
22 Pixels can be manipulated using integer values or color tuples.
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
23
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
24 pxarray[x][y] = 0xFF00FF
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
25 pxarray[x][y] = (255, 0, 255)
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
26
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
27 If you operate on a slice, you also can use arbitrary sequences or other
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
28 PixelArray objects to modify the pixels. They have to match the size of
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
29 the PixelArray however.
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
30
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
31 pxarray[a:b] = 0xFF00FF # set all pixels to 0xFF00FF
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
32
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
33 pxarray[a:b] = (0xFF00FF, 0xAACCEE, ... ) # first pixel = 0xFF00FF,
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
34 # second pixel = 0xAACCEE, ...
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
35 pxarray[a:b] = ((255, 0, 255), (170, 204, 238), ...) # same as above
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
36 pxarray[a:b] = ((255, 0, 255), 0xAACCEE, ...) # same as above
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
37
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
38 pxarray[a:b] = otherarray[x:y] # slice sizes must match
982
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
39
877
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
40 Note, that something like
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
41
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
42 pxarray[2:4][3:5] = ...
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
43
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
44 will not cause a rectangular manipulation. Instead it will be first
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
45 sliced to a two-column array, which then shall be sliced by columns once
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
46 more, which will fail due an IndexError. This is caused by the slicing
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
47 mechanisms in python and an absolutely correct behaviour.
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
48 Create a single columned slice first, which you can manipulate then:
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
49
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
50 pxarray[2][3:5] = ...
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
51 pxarray[3][3:5] = ...
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
52
982
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
53 If you want to make a rectangular manipulation or create a view of a
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
54 part of the PixelArray, you also can use the subscript abilities. You
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
55 can easily create different view by creating 'subarrays' using the
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
56 subscripts.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
57
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
58 # Create some new PixelArray objects providing a different view
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
59 # of the original array/surface.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
60 newarray = pxarray[2:4,3:5]
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
61 otherarray = pxarray[::2,::2]
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
62
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
63 Subscripts also can be used to do fast rectangular pixel manipulations
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
64 instead of iterating over the x or y axis as above.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
65
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
66 pxarray[::2,:] = (0, 0, 0) # Make each second column black.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
67
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
68 During its lifetime, the PixelArray locks the surface, thus you
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
69 explicitly have to delete it once its not used anymore and the surface
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
70 should perform operations in the same scope.
877
b46c37340132 Improved PixelArray docs, unittests and example
marcus
parents: 873
diff changeset
71
989
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
72 New in pygame 1.8. Subscript support is new in pygame 1.8.1.
870
31fa129efd0f Fixed Mask documentation. Added write() method to BufferProxy.
marcus
parents: 866
diff changeset
73 <SECTION>
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
74
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
75 surface
870
31fa129efd0f Fixed Mask documentation. Added write() method to BufferProxy.
marcus
parents: 866
diff changeset
76 Gets the Surface the PixelArray uses.
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
77 PixelArray.surface: Return Surface
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
78
870
31fa129efd0f Fixed Mask documentation. Added write() method to BufferProxy.
marcus
parents: 866
diff changeset
79 The Surface, the PixelArray was created for.
852
4db78800a93a A PixelArray class, which is meant to replace surfarray.
Rene Dudfield <renesd@gmail.com>
parents:
diff changeset
80 <END>
982
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
81
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
82 make_surface
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
83 Creates a new Surface from the current PixelArray.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
84 PixelArray.make_surface (): Return Surface
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
85
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
86 Creates a new Surface from the current PixelArray. Depending on the
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
87 current PixelArray the size, pixel order etc. will be different from the
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
88 original Surface.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
89
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
90 # Create a new surface flipped around the vertical axis.
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
91 sf = pxarray[:,::-1].make_surface ()
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
92
1007
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
93 New in pygame 1.8.1.
982
2c37905a2091 Added subscript support and make_surface() method to PixelArray.
marcus
parents: 975
diff changeset
94 <END>
989
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
95
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
96 replace
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
97 Replaces the passed color in the PixelArray with another one.
997
46a786465642 Added weight support to PixelArray.extract() and PixelArray.replace().
marcus
parents: 993
diff changeset
98 PixelArray.replace (color, repcolor, distance=0, weights=(0.299, 0.587, 0.114)): Return None
989
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
99
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
100 Replaces the pixels with the passed color in the PixelArray by changing
992
1577bcf02ed5 Added threshold recognition using weighted euclideance distances to PixelArray.replace() and PixelArray.extract(). Fixed slice assignment issue.
marcus
parents: 991
diff changeset
101 them them to the passed replacement color.
1577bcf02ed5 Added threshold recognition using weighted euclideance distances to PixelArray.replace() and PixelArray.extract(). Fixed slice assignment issue.
marcus
parents: 991
diff changeset
102
1577bcf02ed5 Added threshold recognition using weighted euclideance distances to PixelArray.replace() and PixelArray.extract(). Fixed slice assignment issue.
marcus
parents: 991
diff changeset
103 It uses a simple weighted euclidian distance formula to calculate the
993
78ab04b73064 Changed distance range to 0-1.
marcus
parents: 992
diff changeset
104 distance between the colors. The distance space ranges from 0.0 to 1.0
992
1577bcf02ed5 Added threshold recognition using weighted euclideance distances to PixelArray.replace() and PixelArray.extract(). Fixed slice assignment issue.
marcus
parents: 991
diff changeset
105 and is used as threshold for the color detection. This causes the
1007
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
106 replacement to take pixels with a similar, but not exactly identical
992
1577bcf02ed5 Added threshold recognition using weighted euclideance distances to PixelArray.replace() and PixelArray.extract(). Fixed slice assignment issue.
marcus
parents: 991
diff changeset
107 color, into account as well.
1577bcf02ed5 Added threshold recognition using weighted euclideance distances to PixelArray.replace() and PixelArray.extract(). Fixed slice assignment issue.
marcus
parents: 991
diff changeset
108
1577bcf02ed5 Added threshold recognition using weighted euclideance distances to PixelArray.replace() and PixelArray.extract(). Fixed slice assignment issue.
marcus
parents: 991
diff changeset
109 This is an in place operation that directly affects the pixels of the
1577bcf02ed5 Added threshold recognition using weighted euclideance distances to PixelArray.replace() and PixelArray.extract(). Fixed slice assignment issue.
marcus
parents: 991
diff changeset
110 PixelArray.
990
404e3a0be4f8 Added PixelArray.extract() method.
marcus
parents: 989
diff changeset
111
1007
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
112 New in pygame 1.8.1.
990
404e3a0be4f8 Added PixelArray.extract() method.
marcus
parents: 989
diff changeset
113 <END>
404e3a0be4f8 Added PixelArray.extract() method.
marcus
parents: 989
diff changeset
114
404e3a0be4f8 Added PixelArray.extract() method.
marcus
parents: 989
diff changeset
115 extract
991
684d96c73d0d Changed PixelArray.extract() to return a new PixelArray mask instead of performing an in place operation.
marcus
parents: 990
diff changeset
116 Extracts the passed color from the PixelArray.
997
46a786465642 Added weight support to PixelArray.extract() and PixelArray.replace().
marcus
parents: 993
diff changeset
117 PixelArray.extract (color, distance=0, weights=(0.299, 0.587, 0.114)): Return PixelArray
990
404e3a0be4f8 Added PixelArray.extract() method.
marcus
parents: 989
diff changeset
118
404e3a0be4f8 Added PixelArray.extract() method.
marcus
parents: 989
diff changeset
119 Extracts the passed color by changing all matching pixels to white,
991
684d96c73d0d Changed PixelArray.extract() to return a new PixelArray mask instead of performing an in place operation.
marcus
parents: 990
diff changeset
120 while non-matching pixels are changed to black. This returns a new
684d96c73d0d Changed PixelArray.extract() to return a new PixelArray mask instead of performing an in place operation.
marcus
parents: 990
diff changeset
121 PixelArray with the black/white color mask.
989
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
122
992
1577bcf02ed5 Added threshold recognition using weighted euclideance distances to PixelArray.replace() and PixelArray.extract(). Fixed slice assignment issue.
marcus
parents: 991
diff changeset
123 It uses a simple weighted euclidian distance formula to calculate the
1577bcf02ed5 Added threshold recognition using weighted euclideance distances to PixelArray.replace() and PixelArray.extract(). Fixed slice assignment issue.
marcus
parents: 991
diff changeset
124 distance between the colors. The distance space ranges from 0.0 to
993
78ab04b73064 Changed distance range to 0-1.
marcus
parents: 992
diff changeset
125 1.0 and is used as threshold for the color detection. This causes the
1007
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
126 extraction to take pixels with a similar, but not exactly identical
992
1577bcf02ed5 Added threshold recognition using weighted euclideance distances to PixelArray.replace() and PixelArray.extract(). Fixed slice assignment issue.
marcus
parents: 991
diff changeset
127 color, into account as well.
1577bcf02ed5 Added threshold recognition using weighted euclideance distances to PixelArray.replace() and PixelArray.extract(). Fixed slice assignment issue.
marcus
parents: 991
diff changeset
128
1007
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
129 New in pygame 1.8.1.
989
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
130 <END>
1007
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
131
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
132 compare
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
133 Compares the PixelArray with another one.
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
134 PixelArray.compare (array, distance=0, weights=(0.299, 0.587, 0.114)): Return PixelArray
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
135
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
136 Compares the contents of the PixelArray with those from the passed PixelArray.
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
137 It returns a new PixelArray with a black/white color mask that indicates the
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
138 differences (white) of both arrays. Both PixelArray objects must have indentical
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
139 bit depths and dimensions.
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
140
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
141 It uses a simple weighted euclidian distance formula to calculate the
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
142 distance between the colors. The distance space ranges from 0.0 to
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
143 1.0 and is used as threshold for the color detection. This causes the
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
144 comparision to mark pixels with a similar, but not exactly identical
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
145 color, as black.
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
146
9e42170b0f2e Added PixelArray.compare().
marcus
parents: 997
diff changeset
147 New in pygame 1.8.1.
989
1bbdc02af359 Added PixelArray.replace() method. Moved pixelarray methods into an own source file.
marcus
parents: 982
diff changeset
148 <END>
1024
3473707f449c typo fix
marcus
parents: 1007
diff changeset
149 <END>