:mod:`pygame2.mask` -- image masks for fast pixel-perfect overlap checks
========================================================================

A module for image masks, suitable for fast pixel-perfect collision
detections.


.. module:: pygame2.mask
   :synopsis: image masks for fast pixel-perfect overlap checks

Module Functions
----------------
.. function:: from_surface (surface, threshold) -> Mask

  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.



.. function:: from_threshold (surface, color[, threshold, thressurface]) -> Mask

  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`.



Mask
----
.. class:: Mask (width, height) -> Mask
    Mask (size) -> Mask

  Creates a new Mask object with the specified width and height.


Attributes
^^^^^^^^^^
.. attribute:: Mask.angle

  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.

.. attribute:: Mask.centroid

  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).


.. attribute:: Mask.count

  Gets the amount of set bits in the Mask.

.. attribute:: Mask.height

  Gets the height of the Mask.

.. attribute:: Mask.size

  Gets the width and height of the Mask as tuple.

.. attribute:: Mask.width

  Gets the width of the Mask.

Methods
^^^^^^^
.. method:: Mask.clear () -> None

  Clears all bits in the Mask.

  Resets the state of all bits in the Mask to 0.


.. method:: Mask.copy () -> Mask

  Creates an exact copy of the Mask.

.. method:: Mask.connected_component ([x, y]) -> Mask
            Mask.connected_component ([point]) -> Mask

  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.


.. method:: Mask.connected_components ([min]) -> Mask

  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.


.. method:: Mask.convolve (mask[, outputmask, point]) -> Mask
            Mask.convolve (mask[, outputmask, x, y]) -> Mask

  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.


.. method:: Mask.draw (mask, x, y) -> None
            Mask.draw (mask, point) -> None

  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.


.. method:: Mask.erase (mask, x, y) -> None
            Mask.erase (mask, point) -> None

  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.


.. method:: Mask.fill () -> None

  Sets all bits to 1 within the Mask.


.. method:: Mask.get_at (x, y) -> int
            Mask.get_at (point) -> int

  Gets the bit value at the desired location.


.. method:: Mask.get_bounding_rects () -> [Mask, Mask, ...]

  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.


.. method:: Mask.invert () -> None

  Inverts all bits in the Mask.


.. method:: Mask.outline ([skip]) -> [(x1, y1), (x2, y2), ...]

  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.


.. method:: Mask.overlap (mask, x, y) -> int, int
            Mask.overlap (mask, point) -> int, int

  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
            |  |
            |  |
            :  :


.. method:: Mask.overlap_area (mask, x, y) -> int
            Mask.overlap_area (mask, point) -> int

  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.


.. method:: Mask.overlap_mask (mask, x, y) -> Mask
            Mask.overlap_mask (mask, point) -> Mask

  Returns a Mask with the overlap of two other masks. A bitwise
  AND.


.. method:: Mask.scale (width, height) -> Mask
            Mask.scale (size) -> Mask

  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.


.. method:: Mask.set_at (x, y) -> None
            Mask.set_at (point) -> None

  Sets the bit value at the desired location.



