Rename Mask class and add origin arg to plot methods

docs/plot_compound.py

@@ -56,8 +56,8 @@
 ax.scatter(skycoords_and.l.value, skycoords_and.b.value, color='magenta',
            label='and', transform=ax.get_transform('galactic'))
 
-circle1.to_pixel(wcs=wcs).plot(ax, edgecolor='green', facecolor='none', alpha=0.8, lw=3)
-circle2.to_pixel(wcs=wcs).plot(ax, edgecolor='red', facecolor='none', alpha=0.8, lw=3)
+circle1.to_pixel(wcs=wcs).plot(ax=ax, edgecolor='green', facecolor='none', alpha=0.8, lw=3)
+circle2.to_pixel(wcs=wcs).plot(ax=ax, edgecolor='red', facecolor='none', alpha=0.8, lw=3)
 
 ax.legend(loc='lower right')
 

docs/plot_example.py

@@ -27,6 +27,6 @@
     region = CircleSkyRegion(center=center, radius=radius)
     pix_region = region.to_pixel(wcs=wcs)
 
-    pix_region.plot(ax, edgecolor='yellow', facecolor='yellow', alpha=0.5, lw=3)
+    pix_region.plot(ax=ax, edgecolor='yellow', facecolor='yellow', alpha=0.5, lw=3)
 
 plt.show()

docs/plot_example_pix.py

@@ -9,5 +9,5 @@
 
 data = np.arange(10 * 15).reshape((10, 15))
 ax.imshow(data, cmap='gray', interpolation='nearest', origin='lower')
-region.plot(ax, color='red')
+region.plot(ax=ax, color='red')
 plt.show()

docs/plot_reg.py

@@ -19,6 +19,6 @@
 regs = read_ds9('plot_image.reg')
 
 for i, reg in enumerate(regs):
-    reg.plot(ax)
+    reg.plot(ax=ax)
 
 plt.show()

docs/plotting.rst

@@ -21,6 +21,8 @@ To draw a matplotlib patch object, add it to an `matplotlib.axes.Axes` object.
     axes = plt.gca()
     axes.set_aspect('equal')
     axes.add_patch(patch)
+    axes.set_xlim([-0.5, 1])
+    axes.set_ylim([-0.5, 1])
 
     plt.show()
 
@@ -29,10 +31,27 @@ The :meth:`~regions.PixelRegion.plot`, a convenience method just does these two
 steps at once (creating a matplotlib patch and adding it to an axis),
 and calls ``plt.gca()`` if no axis is passed in.
 
-Note that not all pixel regions have ``as_patch()`` methods, e.g.
-the `~regions.CircleAnnulusRegion`, `~regions.PointPixelRegion` and
-`~regions.CompundPixelRegion` don't have because there are no equivalent classes
-in `matplotlib.patches`.
+You can shift the origin of the region very conveniently while plotting by simply
+supplying the ``origin`` pixel coordinates to :meth:`~regions.PixelRegion.plot`
+and :meth:`~regions.PixelRegion.as_patch`. The ``**kwargs`` argument takes any
+keyword argument that the `~matplotlib.patches.Patch` object accepts. For e.g.:
+
+.. plot::
+   :include-source:
+
+    from regions import PixCoord, BoundingBox
+    import matplotlib.pyplot as plt
+
+    bbox = BoundingBox(ixmin=-1, ixmax=1, iymin=-2, iymax=2)
+    # shifting the origin to (1, 1) pixel position
+    ax = bbox.plot(origin=(1, 1), edgecolor='yellow', facecolor='red', fill=True)
+    ax.set_xlim([-4, 2])
+    ax.set_ylim([-4, 2])
+    plt.show()
+
+Pixel regions such as `~regions.TextPixelRegion` and
+`~regions.CompoundPixelRegion` don't have ``as_patch()`` method as
+there are no equivalent classes in `matplotlib.patches`.
 
 Here's a full example how to plot a `~regions.CirclePixelRegion` on an image.
 

regions/core/bounding_box.py

@@ -188,7 +188,7 @@ def as_patch(self, **kwargs):
 
         Parameters
         ----------
-        kwargs
+        kwargs : `dict`
             Any keyword arguments accepted by
             `matplotlib.patches.Patch`.
 
@@ -216,3 +216,44 @@ def as_patch(self, **kwargs):
 
         return Rectangle(xy=(self.extent[0], self.extent[2]),
                          width=self.shape[1], height=self.shape[0], **kwargs)
+
+    def to_region(self):
+        """
+        Return a `~regions.RectanglePixelRegion` that
+        represents the bounding box.
+        """
+
+        from ..shapes import RectanglePixelRegion
+        from .pixcoord import PixCoord
+
+        xpos = (self.extent[1] + self.extent[0]) / 2.
+        ypos = (self.extent[3] + self.extent[2]) / 2.
+        xypos = PixCoord(xpos, ypos)
+        h, w = self.shape
+
+        return RectanglePixelRegion(center=xypos, width=w, height=h)
+
+    def plot(self, origin=(0, 0), ax=None, **kwargs):
+        """
+        Plot the `BoundingBox` on a matplotlib `~matplotlib.axes.Axes`
+        instance.
+
+        Parameters
+        ----------
+        origin : array_like, optional
+            The ``(x, y)`` position of the origin of the displayed
+            image.
+        ax : `matplotlib.axes.Axes` instance, optional
+            If `None`, then the current `~matplotlib.axes.Axes` instance
+            is used.
+        kwargs : `dict`
+            Any keyword arguments accepted by `matplotlib.patches.Patch`.
+
+        Returns
+        -------
+        ax : `~matplotlib.axes.Axes`
+            Axes on which the patch is added.
+        """
+
+        reg = self.to_region()
+        return reg.plot(origin=origin, ax=ax, **kwargs)

regions/core/compound.py

@@ -5,9 +5,9 @@
 
 import numpy as np
 
-from . import PixelRegion, SkyRegion, BoundingBox, Mask
+from . import PixelRegion, SkyRegion, BoundingBox, RegionMask
 from ..core.attributes import (CompoundRegionPix, CompoundRegionSky,
-                               RegionVisual, RegionMeta)
+                               RegionMeta, RegionVisual)
 
 __all__ = ['CompoundPixelRegion', 'CompoundSkyRegion']
 
@@ -91,7 +91,7 @@ def to_mask(self, mode='center', subpixels=1):
                                       'constant'))
 
         data = self.operator(*np.array(padded_data, dtype=np.int))
-        return Mask(data=data, bbox=bbox)
+        return RegionMask(data=data, bbox=bbox)
 
     def to_sky(self, wcs):
         skyreg1 = self.region1.to_sky(wcs=wcs)
@@ -129,13 +129,29 @@ def _make_annulus_path(patch_inner, patch_outer):
 
         return mpath.Path(verts, codes)
 
-    def as_patch(self, **kwargs):
+    def as_patch(self, origin=(0, 0), **kwargs):
+        """
+        Matplotlib patch object for annulus region (`matplotlib.patches.PathPatch`).
+
+        Parameters
+        ----------
+        origin : array_like, optional
+            The ``(x, y)`` pixel position of the origin of the displayed image.
+            Default is (0, 0).
+        kwargs : `dict`
+            All keywords that a `~matplotlib.patches.PathPatch` object accepts
+
+        Returns
+        -------
+        patch : `~matplotlib.patches.PathPatch`
+            Matplotlib patch object
+        """
 
         if self.region1.center == self.region2.center and self.operator == op.xor:
             import matplotlib.patches as mpatches
 
-            patch_inner = self.region1.as_patch()
-            patch_outer = self.region2.as_patch()
+            patch_inner = self.region1.as_patch(origin=origin)
+            patch_outer = self.region2.as_patch(origin=origin)
             path = self._make_annulus_path(patch_inner, patch_outer)
             patch = mpatches.PathPatch(path, **kwargs)
             return patch

regions/core/core.py

@@ -236,10 +236,19 @@ def _validate_mode(mode, subpixels):
                                  " a strictly positive integer)".format(subpixels))
 
     @abc.abstractmethod
-    def as_patch(self, **kwargs):
+    def as_patch(self, origin=(0, 0), **kwargs):
         """
         Convert to mpl patch
 
+        Parameters
+        ----------
+        origin : array_like, optional
+            The ``(x, y)`` pixel position of the origin of the displayed image.
+            Default is (0, 0).
+
+        kwargs: `dict`
+            keywords that a `~matplotlib.patches.Patch` accepts
+
         Returns
         -------
         patch : `~matplotlib.patches.Patch`
@@ -279,31 +288,32 @@ def mpl_properties_default(self, shape='patch'):
 
         return kwargs
 
-    def plot(self, ax=None, **kwargs):
+    def plot(self, origin=(0, 0), ax=None, **kwargs):
         """
         Calls ``as_patch`` method forwarding all kwargs and adds patch
         to given axis.
 
         Parameters
         ----------
+        origin : array_like, optional
+            The ``(x, y)`` pixel position of the origin of the displayed image.
+            Default is (0, 0).
         ax : `~matplotlib.axes`, optional
             Axis
         kwargs: `dict`
-            keywords that a `~matplotlib.text.Text` accepts
+            keywords that a `~matplotlib.patches.Patch` accepts
 
         Returns
         -------
         ax: `~matplotlib.axes`
-            Axis on which the patch is added.
+            Axes on which the patch is added.
         """
         import matplotlib.pyplot as plt
 
         if ax is None:
             ax = plt.gca()
 
-        mpl_params = self.mpl_properties_default('patch')
-        mpl_params.update(kwargs)
-        patch = self.as_patch(**mpl_params)
+        patch = self.as_patch(origin=origin, **kwargs)
         ax.add_patch(patch)
 
         return ax

regions/core/mask.py

@@ -6,10 +6,10 @@
 import astropy.units as u
 
 
-__all__ = ['Mask']
+__all__ = ['RegionMask']
 
 
-class Mask(object):
+class RegionMask(object):
     """
     Class for a region mask.
 

regions/core/tests/test_mask.py

@@ -7,7 +7,7 @@
 import pytest
 
 from ..bounding_box import BoundingBox
-from ..mask import Mask
+from ..mask import RegionMask
 from ..pixcoord import PixCoord
 from ...shapes import CirclePixelRegion
 
@@ -25,21 +25,21 @@ def test_mask_input_shapes():
     with pytest.raises(ValueError):
         mask_data = np.ones((10, 10))
         bbox = BoundingBox(5, 10, 5, 10)
-        Mask(mask_data, bbox)
+        RegionMask(mask_data, bbox)
 
 
 def test_mask_array():
     mask_data = np.ones((10, 10))
     bbox = BoundingBox(5, 15, 5, 15)
-    mask = Mask(mask_data, bbox)
+    mask = RegionMask(mask_data, bbox)
     data = np.array(mask)
     assert_allclose(data, mask.data)
 
 
 def test_mask_cutout_shape():
     mask_data = np.ones((10, 10))
     bbox = BoundingBox(5, 15, 5, 15)
-    mask = Mask(mask_data, bbox)
+    mask = RegionMask(mask_data, bbox)
 
     with pytest.raises(ValueError):
         mask.cutout(np.arange(10))

regions/shapes/circle.py

@@ -7,7 +7,7 @@
 from astropy.coordinates import Angle, SkyCoord
 from astropy.wcs.utils import pixel_to_skycoord
 
-from ..core import PixCoord, PixelRegion, SkyRegion, Mask, BoundingBox
+from ..core import PixCoord, PixelRegion, SkyRegion, RegionMask, BoundingBox
 from .._utils.wcs_helpers import skycoord_to_pixel_scale_angle
 from .._geometry import circular_overlap_grid
 from ..core.attributes import (ScalarSky, ScalarPix, QuantityLength,
@@ -121,14 +121,33 @@ def to_mask(self, mode='center', subpixels=1):
         fraction = circular_overlap_grid(xmin, xmax, ymin, ymax, nx, ny,
                                          self.radius, use_exact, subpixels)
 
-        return Mask(fraction, bbox=bbox)
-
-    def as_patch(self, **kwargs):
-        """Matplotlib patch object for this region (`matplotlib.patches.Circle`)"""
+        return RegionMask(fraction, bbox=bbox)
+
+    def as_patch(self, origin=(0, 0), **kwargs):
+        """
+        Matplotlib patch object for this region (`matplotlib.patches.Circle`)
+
+        Parameters:
+        -----------
+        origin : array_like, optional
+            The ``(x, y)`` pixel position of the origin of the displayed image.
+            Default is (0, 0).
+        kwargs: dict
+            All keywords that a `~matplotlib.patches.Circle` object accepts
+
+        Returns
+        -------
+        patch : `~matplotlib.patches.Circle`
+            Matplotlib circle patch
+        """
         from matplotlib.patches import Circle
-        xy = self.center.x, self.center.y
+        xy = self.center.x - origin[0], self.center.y - origin[1]
         radius = self.radius
-        return Circle(xy=xy, radius=radius, **kwargs)
+
+        mpl_params = self.mpl_properties_default('patch')
+        mpl_params.update(kwargs)
+
+        return Circle(xy=xy, radius=radius, **mpl_params)
 
 
 class CircleSkyRegion(SkyRegion):

regions/shapes/ellipse.py

@@ -8,7 +8,7 @@
 from astropy.coordinates import Angle
 from astropy.wcs.utils import pixel_to_skycoord
 
-from ..core import PixCoord, PixelRegion, SkyRegion, Mask, BoundingBox
+from ..core import PixCoord, PixelRegion, SkyRegion, RegionMask, BoundingBox
 from .._geometry import elliptical_overlap_grid
 from .._utils.wcs_helpers import skycoord_to_pixel_scale_angle
 from ..core.attributes import (ScalarPix, ScalarLength, QuantityLength,
@@ -180,17 +180,38 @@ def to_mask(self, mode='center', subpixels=5):
             use_exact, subpixels,
         )
 
-        return Mask(fraction, bbox=bbox)
+        return RegionMask(fraction, bbox=bbox)
 
-    def as_patch(self, **kwargs):
-        """Matplotlib patch object for this region (`matplotlib.patches.Ellipse`)."""
+    def as_patch(self, origin=(0, 0), **kwargs):
+        """
+        Matplotlib patch object for this region (`matplotlib.patches.Ellipse`).
+
+        Parameters:
+        -----------
+        origin : array_like, optional
+            The ``(x, y)`` pixel position of the origin of the displayed image.
+            Default is (0, 0).
+        kwargs: dict
+            All keywords that a `~matplotlib.patches.Ellipse` object accepts
+
+        Returns
+        -------
+        patch : `~matplotlib.patches.Ellipse`
+            Matplotlib ellipse patch
+
+        """
         from matplotlib.patches import Ellipse
-        xy = self.center.x, self.center.y
+        xy = self.center.x - origin[0], self.center.y - origin[1]
         width = self.width
         height = self.height
         # From the docstring: MPL expects "rotation in degrees (anti-clockwise)"
         angle = self.angle.to('deg').value
-        return Ellipse(xy=xy, width=width, height=height, angle=angle, **kwargs)
+
+        mpl_params = self.mpl_properties_default('patch')
+        mpl_params.update(kwargs)
+
+        return Ellipse(xy=xy, width=width, height=height, angle=angle,
+                       **mpl_params)
 
 
 class EllipseSkyRegion(SkyRegion):