Source

pygame / doc / src / mask.xml

Full commit
<?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 :class:`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 :class:`Mask`.</desc>
    </attr>
    <attr name="centroid">
      <desc>Gets the centroid, the center of pixel mass, of the pixels
      in a :class:`Mask`.  Returns a coordinate tuple for the centroid
      of the :class:`Mask`. if the :class:`Mask` is empty, it will
      return (0,0).</desc>
    </attr>
    <method name="clear">
      <call>clear () -> None</call>
      <desc>
        Clears all bits in the :class:`Mask`.

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

        This uses the SAUF algorithm to find a connected component in
        the :class:`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 :class:`Mask` will be empty. The :class:`Mask`
        returned is the same size as the original :class:`Mask`.
      </desc>
    </method>
    <method name="connected_components">
      <call>connected_components ([min]) -> Mask</call>
      <desc>
        Returns a :class:`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 :class:`Mask`.

        Returns a :class:`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` + *mask*.:attr:`size` - (1, 1) is created.
      </desc>
    </method>
    <attr name="count">
      <desc>Gets the amount of bits in the :class:`Mask`.</desc>
    </attr>
    <method name="draw">
      <call>draw (mask, x, y) -> None
      draw (mask, point) -> None</call>
      <desc>
        Draws the passed :class:`Mask` onto the :class:`Mask`.
        
        This performs a bitwise OR operation upon the calling
        :class:`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 :class:`Mask` from the :class:`Mask`.

        This performs a bitwise NAND operation upon the calling
        :class:`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 :class:`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 :class:`Mask`.</desc>
    </attr>
    <method name="invert">
      <call>invert () -> None</call>
      <desc>
        Inverts all bits in the :class:`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 :class:`Mask`.  For this to be useful, there
        should probably only be one connected component of pixels in the
        :class:`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 :class:`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 w or h 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 :class:`Mask` as tuple.</desc>
    </attr>
    <attr name="width">
      <desc>Gets the width of the :class:`Mask`.</desc>
    </attr>
  </class>

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

      Makes the transparent parts of the 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 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 mask by thresholding surfaces.


      This is a more featureful method of getting a :class:`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 *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>