1. pygame
  2. pygame
  3. pygame


pygame / docs / ref / mask.html

<title>mask - Pygame Documentation</title>
<body bgcolor=#aaeebb text=#000000 link=#331111 vlink=#331111>

<table cellpadding=0 cellspacing=0 border=0 style='border: 3px solid black;' width='100%'>
<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><br><b>pygame documentation</b></td>
<td bgcolor='#6aee28' style='border-left: 3px solid black; padding: 6px;' align=center valign=center>
	<a href=http://www.pygame.org>Pygame Home</a> &nbsp;||&nbsp;
	<a href=../index.html>Help Contents</a> &nbsp;||
	<a href=index.html>Reference Index</a> &nbsp;||
<a href="camera.html">Camera</a>&nbsp;||&nbsp;
<a href="cdrom.html">Cdrom</a>&nbsp;||&nbsp;
<a href="color.html">Color</a>&nbsp;||&nbsp;
<a href="cursors.html">Cursors</a>&nbsp;||&nbsp;
<a href="display.html">Display</a>&nbsp;||&nbsp;
<a href="draw.html">Draw</a>&nbsp;||&nbsp;
<a href="event.html">Event</a>&nbsp;||&nbsp;
<a href="examples.html">Examples</a>&nbsp;||&nbsp;
<a href="font.html">Font</a>&nbsp;||&nbsp;
<a href="freetype.html">Freetype</a>&nbsp;||&nbsp;
<a href="gfxdraw.html">Gfxdraw</a>&nbsp;||&nbsp;
<a href="image.html">Image</a>&nbsp;||&nbsp;
<a href="joystick.html">Joystick</a>&nbsp;||&nbsp;
<a href="key.html">Key</a>&nbsp;||&nbsp;
<a href="locals.html">Locals</a>&nbsp;||&nbsp;
<a href="mask.html">Mask</a>&nbsp;||&nbsp;
<a href="midi.html">Midi</a>&nbsp;||&nbsp;
<a href="mixer.html">Mixer</a>&nbsp;||&nbsp;
<a href="mouse.html">Mouse</a>&nbsp;||&nbsp;
<a href="movie.html">Movie</a>&nbsp;||&nbsp;
<a href="music.html">Music</a>&nbsp;||&nbsp;
<a href="overlay.html">Overlay</a>&nbsp;||&nbsp;
<a href="pixelarray.html">Pixelarray</a>&nbsp;||&nbsp;
<a href="pygame.html">Pygame</a>&nbsp;||&nbsp;
<a href="rect.html">Rect</a>&nbsp;||&nbsp;
<a href="scrap.html">Scrap</a>&nbsp;||&nbsp;
<a href="sndarray.html">Sndarray</a>&nbsp;||&nbsp;
<a href="sprite.html">Sprite</a>&nbsp;||&nbsp;
<a href="surface.html">Surface</a>&nbsp;||&nbsp;
<a href="surfarray.html">Surfarray</a>&nbsp;||&nbsp;
<a href="tests.html">Tests</a>&nbsp;||&nbsp;
<a href="time.html">Time</a>&nbsp;||&nbsp;
<a href="transform.html">Transform</a>

<a name="pygame.mask">
  <i>pygame module for image masks.</i><br>
  <tr><td><a href="mask.html#pygame.mask.from_surface">pygame.mask.from_surface</a> - <font size=-1>Returns a Mask from the given surface.</font></td><td>Returns a Mask from the given surface.</td></tr>
  <tr><td><a href="mask.html#pygame.mask.from_threshold">pygame.mask.from_threshold</a> - <font size=-1>Creates a mask by thresholding Surfaces</font></td><td>Creates a mask by thresholding Surfaces</td></tr>
  <tr><td><a href="mask.html#pygame.mask.Mask">pygame.mask.Mask</a> - <font size=-1>pygame object for representing 2d bitmasks</font></td><td>pygame object for representing 2d bitmasks</td></tr>
<p>Useful for fast pixel perfect collision detection. <tt>A</tt> Mask uses 1bit per pixel to store which parts collide. </p>
<p>New in pygame <tt>1.8</tt>. </p>
<!--COMMENTS:pygame.mask--> &nbsp;<br> 

<a name="pygame.mask.from_surface">
  <i>Returns a Mask from the given surface.</i><br>
  <tt>pygame.mask.from_surface(Surface, threshold = 127) -> Mask</tt><br>
<p>Makes the transparent parts of the Surface not set, and the opaque parts set. </p>
<p>The alpha of each pixel is checked to see if it is greater than the given threshold. </p>
<p>If the Surface is color keyed, then threshold is not used. </p>
<!--COMMENTS:pygame.mask.from_surface--> &nbsp;<br> 

<a name="pygame.mask.from_threshold">
  <i>Creates a mask by thresholding Surfaces</i><br>
  <tt>pygame.mask.from_surface(Surface, color, threshold = (0,0,0,255), othersurface = None, palette_colors = 1) -> Mask</tt><br>
<p>This is a more featureful method of getting a Mask from a Surface. If supplied with only one Surface, all pixels within the threshold of the supplied color are set in the Mask. If given the optional othersurface, all pixels in Surface that are within the threshold of the corresponding pixel in othersurface are set in the Mask. </p>
<!--COMMENTS:pygame.mask.from_threshold--> &nbsp;<br> 

<a name="pygame.mask.Mask">
  <i>pygame object for representing 2d bitmasks</i><br>
  <tt>pygame.Mask((width, height)): return Mask</tt><br>
  <tr><td><a href="mask.html#Mask.get_size">Mask.get_size</a> - <font size=-1>Returns the size of the mask.</font></td><td>Returns the size of the mask.</td></tr>
  <tr><td><a href="mask.html#Mask.get_at">Mask.get_at</a> - <font size=-1>Returns nonzero if the bit at (x,y) is set.</font></td><td>Returns nonzero if the bit at (x,y) is set.</td></tr>
  <tr><td><a href="mask.html#Mask.set_at">Mask.set_at</a> - <font size=-1>Sets the position in the mask given by x and y.</font></td><td>Sets the position in the mask given by x and y.</td></tr>
  <tr><td><a href="mask.html#Mask.overlap">Mask.overlap</a> - <font size=-1>Returns the point of intersection if the masks overlap with the given offset - or None if it does not overlap.</font></td><td>Returns the point of intersection if the masks overlap with the given offset - or None if it does not overlap.</td></tr>
  <tr><td><a href="mask.html#Mask.overlap_area">Mask.overlap_area</a> - <font size=-1>Returns the number of overlapping 'pixels'.</font></td><td>Returns the number of overlapping 'pixels'.</td></tr>
  <tr><td><a href="mask.html#Mask.overlap_mask">Mask.overlap_mask</a> - <font size=-1>Returns a mask of the overlapping pixels</font></td><td>Returns a mask of the overlapping pixels</td></tr>
  <tr><td><a href="mask.html#Mask.fill">Mask.fill</a> - <font size=-1>Sets all bits to 1</font></td><td>Sets all bits to 1</td></tr>
  <tr><td><a href="mask.html#Mask.clear">Mask.clear</a> - <font size=-1>Sets all bits to 0</font></td><td>Sets all bits to 0</td></tr>
  <tr><td><a href="mask.html#Mask.invert">Mask.invert</a> - <font size=-1>Flips the bits in a Mask</font></td><td>Flips the bits in a Mask</td></tr>
  <tr><td><a href="mask.html#Mask.scale">Mask.scale</a> - <font size=-1>Resizes a mask</font></td><td>Resizes a mask</td></tr>
  <tr><td><a href="mask.html#Mask.draw">Mask.draw</a> - <font size=-1>Draws a mask onto another</font></td><td>Draws a mask onto another</td></tr>
  <tr><td><a href="mask.html#Mask.erase">Mask.erase</a> - <font size=-1>Erases a mask from another</font></td><td>Erases a mask from another</td></tr>
  <tr><td><a href="mask.html#Mask.count">Mask.count</a> - <font size=-1>Returns the number of set pixels</font></td><td>Returns the number of set pixels</td></tr>
  <tr><td><a href="mask.html#Mask.centroid">Mask.centroid</a> - <font size=-1>Returns the centroid of the pixels in a Mask</font></td><td>Returns the centroid of the pixels in a Mask</td></tr>
  <tr><td><a href="mask.html#Mask.angle">Mask.angle</a> - <font size=-1>Returns the orientation of the pixels</font></td><td>Returns the orientation of the pixels</td></tr>
  <tr><td><a href="mask.html#Mask.outline">Mask.outline</a> - <font size=-1>list of points outlining an object</font></td><td>list of points outlining an object</td></tr>
  <tr><td><a href="mask.html#Mask.convolve">Mask.convolve</a> - <font size=-1>Return the convolution of self with another mask.</font></td><td>Return the convolution of self with another mask.</td></tr>
  <tr><td><a href="mask.html#Mask.connected_component">Mask.connected_component</a> - <font size=-1>Returns a mask of a connected region of pixels.</font></td><td>Returns a mask of a connected region of pixels.</td></tr>
  <tr><td><a href="mask.html#Mask.connected_components">Mask.connected_components</a> - <font size=-1>Returns a list of masks of connected regions of pixels.</font></td><td>Returns a list of masks of connected regions of pixels.</td></tr>
  <tr><td><a href="mask.html#Mask.get_bounding_rects">Mask.get_bounding_rects</a> - <font size=-1>Returns a list of bounding rects of regions of set pixels.</font></td><td>Returns a list of bounding rects of regions of set pixels.</td></tr>
<!--COMMENTS:pygame.mask.Mask--> &nbsp;<br> 

<a name="Mask.get_size">
  <i>Returns the size of the mask.</i><br>
  <tt>Mask.get_size() -> width,height</tt><br>
<!--COMMENTS:Mask.get_size--> &nbsp;<br> 

<a name="Mask.get_at">
  <i>Returns nonzero if the bit at (x,y) is set.</i><br>
  <tt>Mask.get_at((x,y)) -> int</tt><br>
<p>Coordinates start at (0,0) is top left - just like Surfaces. </p>
<!--COMMENTS:Mask.get_at--> &nbsp;<br> 

<a name="Mask.set_at">
  <i>Sets the position in the mask given by x and y.</i><br>
<!--COMMENTS:Mask.set_at--> &nbsp;<br> 

<a name="Mask.overlap">
  <i>Returns the point of intersection if the masks overlap with the given offset - or None if it does not overlap.</i><br>
  <tt>Mask.overlap(othermask, offset) -> x,y</tt><br>
<p>The overlap tests uses the following offsets (which may be negative): </p>
<pre>   +----+----------..
   |A   | yoffset
   |  +-+----------..
   |  |
   :  :
<!--COMMENTS:Mask.overlap--> &nbsp;<br> 

<a name="Mask.overlap_area">
  <i>Returns the number of overlapping 'pixels'.</i><br>
  <tt>Mask.overlap_area(othermask, offset) -> numpixels</tt><br>
<p>You can see how many pixels overlap with the other mask given. This can be used to see in which direction things collide, or to see how much the two masks collide. An approximate collision normal can be found by calculating the gradient of the overlap area through the finite difference. </p>
<pre> dx = Mask.overlap_area(othermask,(x+1,y)) - Mask.overlap_area(othermask,(x-1,y))
 dy = Mask.overlap_area(othermask,(x,y+1)) - Mask.overlap_area(othermask,(x,y-1))
<!--COMMENTS:Mask.overlap_area--> &nbsp;<br> 

<a name="Mask.overlap_mask">
  <i>Returns a mask of the overlapping pixels</i><br>
  <tt>Mask.overlap_mask(othermask, offset) -> Mask</tt><br>
<p>Returns a Mask the size of the original Mask containing only the overlapping pixels between Mask and othermask. </p>
<!--COMMENTS:Mask.overlap_mask--> &nbsp;<br> 

<a name="Mask.fill">
  <i>Sets all bits to 1</i><br>
<p>Sets all bits in a Mask to 1. </p>
<!--COMMENTS:Mask.fill--> &nbsp;<br> 

<a name="Mask.clear">
  <i>Sets all bits to 0</i><br>
<p>Sets all bits in a Mask to 0. </p>
<!--COMMENTS:Mask.clear--> &nbsp;<br> 

<a name="Mask.invert">
  <i>Flips the bits in a Mask</i><br>
<p>Flips all of the bits in a Mask, so that the set pixels turn to unset pixels and the unset pixels turn to set pixels. </p>
<!--COMMENTS:Mask.invert--> &nbsp;<br> 

<a name="Mask.scale">
  <i>Resizes a mask</i><br>
  <tt>Mask.scale((x, y)) -> Mask</tt><br>
<p>Returns a new Mask of the Mask scaled to the requested size. </p>
<!--COMMENTS:Mask.scale--> &nbsp;<br> 

<a name="Mask.draw">
  <i>Draws a mask onto another</i><br>
  <tt>Mask.draw(othermask, offset)</tt><br>
<p>Performs a bitwise <tt>OR</tt>, drawing othermask onto Mask. </p>
<!--COMMENTS:Mask.draw--> &nbsp;<br> 

<a name="Mask.erase">
  <i>Erases a mask from another</i><br>
  <tt>Mask.erase(othermask, offset)</tt><br>
<p>Erases all pixels set in othermask from Mask. </p>
<!--COMMENTS:Mask.erase--> &nbsp;<br> 

<a name="Mask.count">
  <i>Returns the number of set pixels</i><br>
  <tt>Mask.count() -> pixels</tt><br>
<p>Returns the number of set pixels in the Mask. </p>
<!--COMMENTS:Mask.count--> &nbsp;<br> 

<a name="Mask.centroid">
  <i>Returns the centroid of the pixels in a Mask</i><br>
  <tt>Mask.centroid() -> (x, y)</tt><br>
<p>Finds the centroid, the center of pixel mass, of a Mask. Returns a coordinate tuple for the centroid of the Mask. In the event the Mask is empty, it will return (0,0). </p>
<!--COMMENTS:Mask.centroid--> &nbsp;<br> 

<a name="Mask.angle">
  <i>Returns the orientation of the pixels</i><br>
  <tt>Mask.angle() -> theta</tt><br>
<p>Finds the approximate orientation of the pixels in the image from -90 to 90 degrees. This works best if performed on one connected component of pixels. It will return <tt>0.0</tt> on an empty Mask. </p>
<!--COMMENTS:Mask.angle--> &nbsp;<br> 

<a name="Mask.outline">
  <i>list of points outlining an object</i><br>
  <tt>Mask.outline(every = 1) -> [(x,y), (x,y) ...]</tt><br>
<p>Returns a list of points of the outline of the first object it comes across in a Mask. For this to be useful, there should probably only be one connected component of pixels in the Mask. The every option allows you to skip pixels in the outline. For example, setting it to 10 would return a list of every 10th pixel in the outline. </p>
<!--COMMENTS:Mask.outline--> &nbsp;<br> 

<a name="Mask.convolve">
  <i>Return the convolution of self with another mask.</i><br>
  <tt>Mask.convolve(othermask, outputmask = None, offset = (0,0)) -> Mask</tt><br>
<p>Returns a mask with the (i-offset[0],j-offset[1]) bit set if shifting othermask so that it's lower right corner pixel is at (i,j) would cause it to overlap with self. </p>
<p>If an outputmask is specified, the output is drawn onto outputmask and outputmask is returned. Otherwise a mask of size <tt>self.get_size()</tt> + <tt>othermask.get_size()</tt> - (1,1) is created. </p>
<!--COMMENTS:Mask.convolve--> &nbsp;<br> 

<a name="Mask.connected_component">
  <i>Returns a mask of a connected region of pixels.</i><br>
  <tt>Mask.connected_component((x,y) = None) -> Mask</tt><br>
<p>This uses the <tt>SAUF</tt> algorithm to find a connected component in the Mask. It checks 8 point connectivity. By default, it will return the largest connected component in the image. Optionally, a coordinate pair of a pixel can be specified, and the connected component containing it will be returned. In the event the pixel at that location is not set, the returned Mask will be empty. The Mask returned is the same size as the original Mask. </p>
<!--COMMENTS:Mask.connected_component--> &nbsp;<br> 

<a name="Mask.connected_components">
  <i>Returns a list of masks of connected regions of pixels.</i><br>
  <tt>Mask.connected_components(min = 0) -> [Masks]</tt><br>
<p>Returns a list of masks of connected regions of pixels. An optional minimum number of pixels per connected region can be specified to filter out noise. </p>
<!--COMMENTS:Mask.connected_components--> &nbsp;<br> 

<a name="Mask.get_bounding_rects">
  <i>Returns a list of bounding rects of regions of set pixels.</i><br>
  <tt>Mask.get_bounding_rects() -> Rects</tt><br>
<p>This gets a bounding rect of connected regions of set pixels. <tt>A</tt> bounding rect is one for which each of the connected pixels is inside the rect. </p>
<!--COMMENTS:Mask.get_bounding_rects--> &nbsp;<br>