~ubuntu-branches/ubuntu/maverick/pygame/maverick

<td bgcolor='#c2fc20' style='padding: 6px;' align=center valign=center><a href='http://www.pygame.org/'><img src='../pygame_tiny.gif' border=0 width=200 height=60></a> pygame documentation</td>

<a href=http://www.pygame.org>Pygame Home</a>  ||

<a href=../index.html>Help Contents</a>  ||

<a href=index.html>Reference Index</a>  ||

<a href="cdrom.html">Cdrom</a> ||

<a href="color.html">Color</a> ||

<a href="cursors.html">Cursors</a> ||

<a href="display.html">Display</a> ||

<a href="draw.html">Draw</a> ||

<a href="event.html">Event</a> ||

<a href="font.html">Font</a> ||

<a href="image.html">Image</a> ||

<a href="joystick.html">Joystick</a> ||

<a href="key.html">Key</a> ||

<a href="mask.html">Mask</a> ||

<a href="mixer.html">Mixer</a> ||

<a href="mouse.html">Mouse</a> ||

<a href="movie.html">Movie</a> ||

<a href="music.html">Music</a> ||

<a href="overlay.html">Overlay</a> ||

<a href="pixelarray.html">Pixelarray</a> ||

<a href="pygame.html">Pygame</a> ||

<a href="rect.html">Rect</a> ||

<a href="scrap.html">Scrap</a> ||

<a href="sndarray.html">Sndarray</a> ||

<a href="sprite.html">Sprite</a> ||

<a href="surface.html">Surface</a> ||

<a href="surfarray.html">Surfarray</a> ||

<a href="time.html">Time</a> ||

<a href="transform.html">Transform</a>

</td></tr></table>

<big>pygame.PixelArray</big> <ul>

pygame object for direct pixel access of surfaces

<tt>pygame.PixelArray(Surface): return PixelArray</tt>

<tr><td><a href="pixelarray.html#PixelArray.surface">PixelArray.surface</a> - Gets the Surface the PixelArray uses.</td><td>Gets the Surface the PixelArray uses.</td></tr>

<tr><td><a href="pixelarray.html#PixelArray.make_surface">PixelArray.make_surface</a> - Creates a new Surface from the current PixelArray.</td><td>Creates a new Surface from the current PixelArray.</td></tr>

<tr><td><a href="pixelarray.html#PixelArray.replace">PixelArray.replace</a> - Replaces the passed color in the PixelArray with another one.</td><td>Replaces the passed color in the PixelArray with another one.</td></tr>

<tr><td><a href="pixelarray.html#PixelArray.extract">PixelArray.extract</a> - Extracts the passed color from the PixelArray.</td><td>Extracts the passed color from the PixelArray.</td></tr>

<tr><td><a href="pixelarray.html#PixelArray.compare">PixelArray.compare</a> - Compares the PixelArray with another one.</td><td>Compares the PixelArray with another one.</td></tr>

</table></ul>

The PixelArray wraps up a Surface and provides a direct <tt>2D</tt> array access to its pixels using the surface its rows as first and its columns as second axis. It supports slicing, row and pixel manipluation, slicing and slice assignments while inplace operations such as addition, subtraction, multiplication, division and so forth are not allowed.

While it is possible to assign both, integer color values and <tt>RGB(A)</tt> color tuples, the PixelArray will only use integers for the color representation. Thus, checking for certain colors has to be done using the <tt><a href="surface.html#Surface.map_rgb">Surface.map_rgb</a> - convert a color into a mapped color value</tt> method of the surface, the PixelArray was created for.

<pre> pxarray = pygame.PixelArray (surface)

# Check, if the first pixel at the topleft corner is blue

if pxarray[0][0] == surface.map_rgb ((0, 0, 255)):

...

</pre>Pixels can be manipulated using integer values or color tuples.

<pre> pxarray[x][y] = 0xFF00FF

pxarray[x][y] = (255, 0, 255)

</pre>If you operate on a slice, you also can use arbitrary sequences or other PixelArray objects to modify the pixels. They have to match the size of the PixelArray however.

<pre> pxarray[a:b] = 0xFF00FF # set all pixels to 0xFF00FF

pxarray[a:b] = (0xFF00FF, 0xAACCEE, ... ) # first pixel = 0xFF00FF,

# second pixel = 0xAACCEE, ...

pxarray[a:b] = ((255, 0, 255), (170, 204, 238), ...) # same as above

pxarray[a:b] = ((255, 0, 255), 0xAACCEE, ...) # same as above

pxarray[a:b] = otherarray[x:y] # slice sizes must match

</pre>Note, that something like

<pre> pxarray[2:4][3:5] = ...

</pre>will not cause a rectangular manipulation. Instead it will be first sliced to a two-column array, which then shall be sliced by columns once more, which will fail due an IndexError. This is caused by the slicing mechanisms in python and an absolutely correct behaviour. Create a single columned slice first, which you can manipulate then:

<pre> pxarray[2][3:5] = ...

pxarray[3][3:5] = ...

</pre>If you want to make a rectangular manipulation or create a view of a part of the PixelArray, you also can use the subscript abilities. You can easily create different view by creating 'subarrays' using the subscripts.

<pre> # Create some new PixelArray objects providing a different view

# of the original array/surface.

newarray = pxarray[2:4,3:5]

otherarray = pxarray[::2,::2]

</pre>Subscripts also can be used to do fast rectangular pixel manipulations instead of iterating over the x or y axis as above.

<pre> pxarray[::2,:] = (0, 0, 0) # Make each second column black.

</pre>During its lifetime, the PixelArray locks the surface, thus you explicitly have to delete it once its not used anymore and the surface should perform operations in the same scope.

New in pygame <tt>1.8</tt>. Subscript support is new in pygame <tt>1.8.1</tt>.

<big>PixelArray.surface</big> <ul>

Gets the Surface the PixelArray uses.

<tt>PixelArray.surface: Return Surface</tt>

The Surface, the PixelArray was created for.

</ul>

100

101

<big>PixelArray.make_surface</big> <ul>

102

Creates a new Surface from the current PixelArray.

103

<tt>PixelArray.make_surface (): Return Surface</tt>

104

Creates a new Surface from the current PixelArray. Depending on the current PixelArray the size, pixel order etc. will be different from the original Surface.

105

<pre> # Create a new surface flipped around the vertical axis.

106

sf = pxarray[:,::-1].make_surface ()

107

</pre>New in pygame <tt>1.8.1</tt>.

108

109

</ul>

110

111

112

113

<big>PixelArray.replace</big> <ul>

114

Replaces the passed color in the PixelArray with another one.

115

<tt>PixelArray.replace (color, repcolor, distance=0, weights=(0.299, 0.587, 0.114)): Return None</tt>

116

Replaces the pixels with the passed color in the PixelArray by changing them them to the passed replacement color.

117

It uses a simple weighted euclidian distance formula to calculate the distance between the colors. The distance space ranges from <tt>0.0</tt> to <tt>1.0</tt> and is used as threshold for the color detection. This causes the replacement to take pixels with a similar, but not exactly identical color, into account as well.

118

This is an in place operation that directly affects the pixels of the PixelArray.

119

New in pygame <tt>1.8.1</tt>.

120

121

</ul>

122

123

124

125

<big>PixelArray.extract</big> <ul>

126

Extracts the passed color from the PixelArray.

127

<tt>PixelArray.extract (color, distance=0, weights=(0.299, 0.587, 0.114)): Return PixelArray</tt>

128

Extracts the passed color by changing all matching pixels to white, while non-matching pixels are changed to black. This returns a new PixelArray with the black/white color mask.

129

It uses a simple weighted euclidian distance formula to calculate the distance between the colors. The distance space ranges from <tt>0.0</tt> to <tt>1.0</tt> and is used as threshold for the color detection. This causes the extraction to take pixels with a similar, but not exactly identical color, into account as well.

130

New in pygame <tt>1.8.1</tt>.

131

132

</ul>

133

134

135

136

<big>PixelArray.compare</big> <ul>

137

Compares the PixelArray with another one.

138

<tt>PixelArray.compare (array, distance=0, weights=(0.299, 0.587, 0.114)): Return PixelArray</tt>

139

Compares the contents of the PixelArray with those from the passed PixelArray. It returns a new PixelArray with a black/white color mask that indicates the differences (white) of both arrays. Both PixelArray objects must have indentical bit depths and dimensions.

140

It uses a simple weighted euclidian distance formula to calculate the distance between the colors. The distance space ranges from <tt>0.0</tt> to <tt>1.0</tt> and is used as threshold for the color detection. This causes the comparision to mark pixels with a similar, but not exactly identical color, as black.

141

New in pygame <tt>1.8.1</tt>.

142

143

</ul>

144

</ul>

145

146

</body></html>

<html>

<title>pixelarray - Pygame Documentation</title>

<tr>

<a href=http://www.pygame.org>Pygame Home</a>  ||

<a href=../index.html>Help Contents</a>  ||

<a href=index.html>Reference Index</a>  ||

<a href="camera.html">Camera</a> ||

<a href="cdrom.html">Cdrom</a> ||

<a href="color.html">Color</a> ||

<a href="cursors.html">Cursors</a> ||

<a href="display.html">Display</a> ||

<a href="draw.html">Draw</a> ||

<a href="event.html">Event</a> ||

<a href="examples.html">Examples</a> ||

<a href="font.html">Font</a> ||

<a href="gfxdraw.html">Gfxdraw</a> ||

<a href="image.html">Image</a> ||

<a href="joystick.html">Joystick</a> ||

<a href="key.html">Key</a> ||

<a href="locals.html">Locals</a> ||

<a href="mask.html">Mask</a> ||

<a href="midi.html">Midi</a> ||

<a href="mixer.html">Mixer</a> ||

<a href="mouse.html">Mouse</a> ||

<a href="movie.html">Movie</a> ||

<a href="music.html">Music</a> ||

<a href="overlay.html">Overlay</a> ||

<a href="pixelarray.html">Pixelarray</a> ||

<a href="pygame.html">Pygame</a> ||

<a href="rect.html">Rect</a> ||

<a href="scrap.html">Scrap</a> ||

<a href="sndarray.html">Sndarray</a> ||

<a href="sprite.html">Sprite</a> ||

<a href="surface.html">Surface</a> ||

<a href="surfarray.html">Surfarray</a> ||

<a href="tests.html">Tests</a> ||

<a href="time.html">Time</a> ||

<a href="transform.html">Transform</a>

</td></tr></table>

<big>pygame.PixelArray</big> <ul>

pygame object for direct pixel access of surfaces

<tt>pygame.PixelArray(Surface): return PixelArray</tt>

<tr><td><a href="pixelarray.html#PixelArray.surface">PixelArray.surface</a> - Gets the Surface the PixelArray uses.</td><td>Gets the Surface the PixelArray uses.</td></tr>

</table></ul>

<pre> pxarray = pygame.PixelArray (surface)

# Check, if the first pixel at the topleft corner is blue

if pxarray[0][0] == surface.map_rgb ((0, 0, 255)):

...

</pre>Pixels can be manipulated using integer values or color tuples.

<pre> pxarray[x][y] = 0xFF00FF

pxarray[x][y] = (255, 0, 255)

</pre>If you operate on a slice, you also can use arbitrary sequences or other PixelArray objects to modify the pixels. They have to match the size of the PixelArray however.

<pre> pxarray[a:b] = 0xFF00FF # set all pixels to 0xFF00FF

pxarray[a:b] = (0xFF00FF, 0xAACCEE, ... ) # first pixel = 0xFF00FF,

# second pixel = 0xAACCEE, ...

pxarray[a:b] = ((255, 0, 255), (170, 204, 238), ...) # same as above

pxarray[a:b] = ((255, 0, 255), 0xAACCEE, ...) # same as above

pxarray[a:b] = otherarray[x:y] # slice sizes must match

</pre>Note, that something like

<pre> pxarray[2:4][3:5] = ...

<pre> pxarray[2][3:5] = ...

pxarray[3][3:5] = ...

<pre> # Create some new PixelArray objects providing a different view

# of the original array/surface.

newarray = pxarray[2:4,3:5]

otherarray = pxarray[::2,::2]

</pre>Subscripts also can be used to do fast rectangular pixel manipulations instead of iterating over the x or y axis as above.

<pre> pxarray[::2,:] = (0, 0, 0) # Make each second column black.

</pre>During its lifetime, the PixelArray locks the surface, thus you explicitly have to delete it once its not used anymore and the surface should perform operations in the same scope.

New in pygame <tt>1.8</tt>. Subscript support is new in pygame <tt>1.8.1</tt>.

<big>PixelArray.surface</big> <ul>

Gets the Surface the PixelArray uses.

100

<tt>PixelArray.surface: Return Surface</tt>

101

The Surface, the PixelArray was created for.

102

103

</ul>

104

105

106

107

<big>PixelArray.make_surface</big> <ul>

108

Creates a new Surface from the current PixelArray.

109

<tt>PixelArray.make_surface (): Return Surface</tt>

110

Creates a new Surface from the current PixelArray. Depending on the current PixelArray the size, pixel order etc. will be different from the original Surface.

111

<pre> # Create a new surface flipped around the vertical axis.

112

sf = pxarray[:,::-1].make_surface ()

113

</pre>New in pygame <tt>1.8.1</tt>.

114

115

</ul>

116

117

118

119

<big>PixelArray.replace</big> <ul>

120

Replaces the passed color in the PixelArray with another one.

121

<tt>PixelArray.replace (color, repcolor, distance=0, weights=(0.299, 0.587, 0.114)): Return None</tt>

122

Replaces the pixels with the passed color in the PixelArray by changing them them to the passed replacement color.

123

124

This is an in place operation that directly affects the pixels of the PixelArray.

125

New in pygame <tt>1.8.1</tt>.

126

127

</ul>

128

129

130

131

<big>PixelArray.extract</big> <ul>

132

Extracts the passed color from the PixelArray.

133

<tt>PixelArray.extract (color, distance=0, weights=(0.299, 0.587, 0.114)): Return PixelArray</tt>

134

Extracts the passed color by changing all matching pixels to white, while non-matching pixels are changed to black. This returns a new PixelArray with the black/white color mask.

135

It uses a simple weighted euclidian distance formula to calculate the distance between the colors. The distance space ranges from <tt>0.0</tt> to <tt>1.0</tt> and is used as threshold for the color detection. This causes the extraction to take pixels with a similar, but not exactly identical color, into account as well.

136

New in pygame <tt>1.8.1</tt>.

137

138

</ul>

139

140

141

142

<big>PixelArray.compare</big> <ul>

143

Compares the PixelArray with another one.

144

<tt>PixelArray.compare (array, distance=0, weights=(0.299, 0.587, 0.114)): Return PixelArray</tt>

145

146

It uses a simple weighted euclidian distance formula to calculate the distance between the colors. The distance space ranges from <tt>0.0</tt> to <tt>1.0</tt> and is used as threshold for the color detection. This causes the comparision to mark pixels with a similar, but not exactly identical color, as black.

147

New in pygame <tt>1.8.1</tt>.

148

149

</ul>

150

</ul>

151

152

</body></html>

Older »