Source

pygame / doc / src / mask.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE module SYSTEM "api.dtd">

<module name="pygame2.mask">
  <short>image masks for fast pixel-perfect overlap checks</short>
  <desc>
    A module for image masks, suitable for fast pixel-perfect collision
    detections.
  </desc>

  <class name="Mask">
    <constructor>Mask (width, height) -> Mask
    Mask (size) -> Mask</constructor>
    <desc>
      Creates a new Mask object with the specified width and height.
    </desc>
    <attr name="angle">
      <desc>Gets the orientation of the pixels. 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 0.0 on an empty Mask.</desc>
    </attr>
    <attr name="centroid">
      <desc>
        Gets the centroid, the center of pixel mass, of the pixels
        in a Mask. Returns a coordinate tuple for the centroid
        of the Mask. If the Mask is empty, it will return (0, 0).
      </desc>
    </attr>
    <method name="clear">
      <call>clear () -> None</call>
      <desc>
        Clears all bits in the Mask.

        Resets the state of all bits in the Mask to 0.
      </desc>
    </method>
    <method name="copy">
      <call>copy () -> Mask</call>
      <desc>Creates an exact copy of the Mask.</desc>
    </method>
    <method name="connected_component">
      <call>connected_component ([x, y]) -> Mask
      connected_component ([point]) -> Mask</call>
      <desc>
        Returns a Mask of a connected region of pixels.

        This uses the SAUF 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.
      </desc>
    </method>
    <method name="connected_components">
      <call>connected_components ([min]) -> Mask</call>
      <desc>
        Returns a Mask of a connected region of pixels.

        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.
      </desc>
    </method>
    <method name="convolve">
      <call>convolve (mask[, outputmask, point]) -> Mask
        convolve (mask[, outputmask, x, y]) -> Mask</call>
      <desc>
        Return the convolution with another Mask.

        Returns a Mask with the [x-offset[0], y-offset[1]] bit
        set if shifting *mask* so that it's lower right corner pixel is
        at (*x*, *y*) would cause it to overlap with self.

        If an *outputmask* is specified, the output is drawn onto
        *outputmask* and *outputmask* is returned. Otherwise a mask of
        size :attr:`size` + :attr:`size` - (1, 1) is created.
      </desc>
    </method>
    <attr name="count">
      <desc>Gets the amount of set bits in the Mask.</desc>
    </attr>
    <method name="draw">
      <call>draw (mask, x, y) -> None
      draw (mask, point) -> None</call>
      <desc>
        Draws the passed Mask onto the Mask.
        
        This performs a bitwise OR operation upon the calling
        Mask. The passed *mask*'s start offset for the draw
        operation will be the *x* and *y* offset passed to the method.
      </desc>
    </method>
    <method name="erase">
      <call>erase (mask, x, y) -> None
      erase (mask, point) -> None</call>
      <desc>
        Erases the passed Mask from the Mask.

        This performs a bitwise NAND operation upon the calling
        Mask. The passed *mask*'s start offset for the erase
        operation will be the *x* and *y* offset passed to the method.
      </desc>
    </method>
    <method name="fill">
      <call>fill () -> None</call>
      <desc>
        Sets all bits to 1 within the Mask.
      </desc>
    </method>
    <method name="get_at">
      <call>get_at (x, y) -> int
      get_at (point) -> int</call>
      <desc>
        Gets the bit value at the desired location.
      </desc>
    </method>
    <method name="get_bounding_rects">
      <call>get_bounding_rects () -> [Mask, Mask, ...]</call>
      <desc>
        Returns a list of bounding rects of regions of set pixels.

        This gets a bounding rect of connected regions of set bits. A bounding
        rect is one for which each of the connected pixels is inside the rect.
      </desc>
    </method>
    <attr name="height">
      <desc>Gets the height of the Mask.</desc>
    </attr>
    <method name="invert">
      <call>invert () -> None</call>
      <desc>
        Inverts all bits in the Mask.
      </desc>
    </method>
    <method name="outline">
      <call>outline ([skip]) -> [(x1, y1), (x2, y2), ...]</call>
      <desc>
        Gets the points outlining an object on the mask.
        
        Returns a list of points of the outline of the first object it
        comes across in the Mask. For this to be useful, there
        should probably only be one connected component of pixels in the
        Mask. The *skip* 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.
      </desc>
    </method>
    <method name="overlap">
      <call>overlap (mask, x, y) -> int, int
      overlap (mask, point) -> int, int</call>
      <desc>
        Returns nonzero if the masks overlap with the given offset.

        The overlap tests uses the following offsets (which may be negative): ::

          +----+----------...
          |A   | yoffset
          |  +-+----------...
          +--|B
          |xoffset
          |  |
          |  |
          :  :
      </desc>
    </method>
    <method name="overlap_area">
      <call>overlap_area (mask, x, y) -> int
      overlap_area (mask, point) -> int</call>
      <desc>
        Returns the number of overlapping bits of two Masks.

        This returns how many pixels overlap with the other *mask* given. It
        can be used to see in which direction things collide, or to see how
        much the two masks collide.
      </desc>
    </method>
    <method name="overlap_mask">
      <call>overlap_mask (mask, x, y) -> Mask
      overlap_mask (mask, point) -> Mask</call>
      <desc>
        Returns a Mask with the overlap of two other masks. A bitwise
        AND.
      </desc>
    </method>
    <method name="scale">
      <call>scale (width, height) -> Mask
      scale (size) -> Mask</call>
      <desc>
        Creates a new scaled Mask with the given *width* and *height*.

        The quality of the scaling may not be perfect for all circumstances,
        but it should be reasonable. If either *width* or *height* is 0 a clear
        1x1 mask is returned.
      </desc>
    </method>
    <method name="set_at">
      <call>set_at (x, y) -> None
      set_at (point) -> None</call>
      <desc>
        Sets the bit value at the desired location.
      </desc>
    </method>
    <attr name="size">
      <desc>Gets the width and height of the Mask as tuple.</desc>
    </attr>
    <attr name="width">
      <desc>Gets the width of the Mask.</desc>
    </attr>
  </class>

  <func name="from_surface">
    <call>from_surface (surface, threshold) -> Mask</call>
    <desc>
      Returns a :class:`Mask` from the given :class:`pygame2.sdl.video.Surface`.

      Makes the transparent parts of the :class:`pygame2.sdl.video.Surface` not
      set, and the opaque parts set. The alpha of each pixel is checked to see
      if it is greater than the given *threshold*. If the
      :class:`pygame2.sdl.video.Surface` is color keyed, then *threshold* is not
      used.

      This requires pygame2 to be built with SDL support enabled.
    </desc>
  </func>
  <func name="from_threshold">
    <call>from_threshold (surface, color[, threshold, thressurface]) -> Mask</call>
    <desc>
      Creates a :class:`Mask` by thresholding surfaces.

      This is a more featureful method of getting a :class:`Mask` from a
      :class:`pygame2.sdl.video.Surface`. If supplied with only one
      :class:`pygame2.sdl.video.Surface`, all pixels within the *threshold* of
      the supplied *color* are set in the :class`Mask`. If given
      the optional *thressurface*, all pixels in *surface* that are within the
      *threshold* of the corresponding pixel in *thressurface* are set in the
      :class:`Mask`.
    </desc>
  </func>
</module>