Merge pull request #81 from mhardcastle/master

Update to document use with image cubes and fix typos etc.

docs/users/overview.rst

@@ -2,14 +2,14 @@
 Overview
 ========
 
-pyregion is a python module to parse ds9 region files. It also support
+pyregion is a python module to parse ds9 region files. It also supports
 ciao region files.
 
-Please note that my main emphasis is to read in the regions files
+Please note that the main emphasis of the package is to read in the regions files
 generated by ds9 itself. It reads most of the region files created by
 ds9. However, it may fail to read some of the user-created (or created
 by other programs) region files, even if they can be successfully read
-by ds9. Ruler, Compass and Projection type is ignored.
+by ds9. Ruler, Compass and Projection types are ignored.
 
 
 +----------------------------------------+----------------------------------------+
@@ -30,13 +30,13 @@ Read Region Files
 =================
 
 *pyregion.open* takes the region name as an argument and returns a
-ShapeList objects, which is basically a list of Shape objects. ::
+ShapeList object, which is basically a list of Shape objects. ::
 
     import pyregion
     region_name = "ds9.reg"
     r = pyregion.open(region_name)
 
-You may use *pyregion.parse* if you have a string of region deniition. ::
+You may use *pyregion.parse* if you have a string that defines a region ::
 
     region = 'fk5;circle(290.96388,14.019167,843.31194")'
     r = pyregion.parse(region)
@@ -64,20 +64,20 @@ And you have::
     >>> print r[1]
     Shape : box ( HMS(11:24:39.213),DMS(-59:16:53.91),Ang(42.804"),Ang(23.616"),Number(19.0384) )
 
-The shape object has following attributes,
+The shape object has the following attributes,
 
 * name : name of the shape. e.g., circle, box, etc.. ::
 
    >>> print r[0].name
    circle
 
-* coord_format : coordinates format. e.g., "fk5", "image", "physical", etc... ::
+* coord_format : coordinate format. e.g., "fk5", "image", "physical", etc... ::
 
    >>> print r[0].coord_format
    fk5
 
 * coord_list : list of coordinates in *coord_format*. The coordinate
-  value for sky coordinate is degree.  ::
+  value for sky coordinates is degree.  ::
 
    >>> print r[0].coord_list
    [171.10095833333332, -59.250611111111112, 0.0051418888888888886]
@@ -111,42 +111,51 @@ The shape object has following attributes,
      'width': '1 '}
 
 
-  Some attributes like "tag" allows multiple items and this is not
-  currently supported (the last definition override previous ones).
+  Some attributes like "tag" allow multiple items, but this is not
+  currently supported (the last definition overrides any previous ones).
 
 
-The ShapeList class have a few method that could be
+The ShapeList class have a few methods that could be
 useful. *ShapeList.as_imagecoord* returns a new ShapeList instance
-with the coordinates converted to the image coordinate. It
-requires the astropy.io.fits.Header instance.::
+with the coordinates converted to the image coordinate system. It
+requires an astropy.io.fits.Header instance.::
 
     from astropy.io import fits
     f = fits.open("t1.fits")
     r2 = pyregion.parse(region_string).as_imagecoord(f[0].header)
 
 The return value is a new ShapeList instance, but the coordinate is
-converted to the image coordinate. ::
+converted to image coordinates. ::
 
     >>> print r2[0].coord_format
     image
 
     >>> print r2[0].coord_list
     [482.27721401429852, 472.76641383805912, 18.811792596807045]
 
+*ShapeList.as_imagecoord* can take a WCS object instead of a header. This is useful
+if your fits file is not a simple 2D image, as you can then use only the celestial
+subset of the co-ordinates to parse the region: ::
 
+    from astropy.io import fits
+    from astropy.WCS import WCS
+    f = fits.open("t1.fits")
+    w = WCS(f[0].header)
+    w_im = w.celestial
+    r2 = pyregion.parse(region_string).as_imagecoord(w_im)
 
 Draw Regions with Matplotlib
 ============================
 
-pyregion can help you draw the ds9 region with
+pyregion can help you draw ds9 regions with
 matplotlib. *ShapeList.get_mpl_patches_texts* returns a list of
 matplotlib.Artist ::
 
     r2 = pyregion.parse(region_string).as_imagecoord(f[0].header)
     patch_list, artist_list = r2.get_mpl_patches_texts()
 
 The first item is a list of matplotlib.Patch, and the second one is
-other kind of artists (usually Text). It is your responsibility to add
+other kinds of artists (usually Text). It is your responsibility to add
 these to the axes. ::
 
     # ax is a mpl Axes object
@@ -161,7 +170,7 @@ The (optional) argument of the *get_mpl_patches_texts* method is a
 callable object that takes the shape object as an argument and returns
 a dictionary object that will be used as a keyword arguments (e.g.,
 colors and line width) for creating the mpl artists. By default, it
-uses pyregion.mpl_helper.properties_func_default, which try to respect
+uses pyregion.mpl_helper.properties_func_default, which tries to respect
 the ds9 attributes. However, the colors (and other attributes) of some
 complex shapes are not correctly handled as shown in above example,
 and you need to manually adjust the associated attributes of patches.
@@ -209,4 +218,7 @@ necessary).
 .. plot:: figures/demo_filter_mask.py
    :include-source:
 
+Note that this will fail if your template image is not a simple 2D image.
+To work around this you may use the *shape* optional argument of *get_mask*: ::
 
+    mymask = r2.get_mask(hdu=f[0],shape=(1024,1024))