Merge pull request #444 from larrybradley/fits-io

Rewrite FITS region I/O

Author: larrybradley

CHANGES.rst

@@ -31,6 +31,9 @@ New Features
 - Added the ability to serialize multiple regions in the DS9 file format
   that have different coordinate frames. [#436]
 
+- Added the ability to parse FITS region ``rectangle`` and
+  ``rotrectangle`` shapes. [#444]
+
 
 Bug Fixes
 ---------
@@ -64,6 +67,12 @@ Bug Fixes
   consistently handling or preserving the region coordinate frame
   or region parameter units. [#436]
 
+- Fixed handling of FITS shapes that are preceded by an exclamation
+  mark. [#444]
+
+- Fixed a bug where written FITS region files could not be read back in.
+  [#444]
+
 
 API Changes
 -----------
@@ -104,6 +113,10 @@ API Changes
   ``matplotlib.artist.Artist`` object, which can be used in plot legends.
   [#441]
 
+- FITS region files are now always parsed and serialized as
+  ``PixelRegion`` objects. They can be converted to ``SkyRegion``
+  objects using a WCS object. [#444]
+
 
 0.5 (2021-07-20)
 ================
@@ -168,7 +181,7 @@ Bug Fixes
   space after the region name. [#271]
 
 - Fixed an issue where the CRTF file parser was too restrictive about
-  requiring the last and first poly coordinates to be the same.
+  requiring the last and first polynomial coordinates to be the same.
   [#359, #362]
 
 - Fixed a bug where an ``EllipsePixelRegion`` with zero height and/or

docs/fits_io.rst

@@ -0,0 +1,74 @@
+
+FITS Region File Format Limitations
+===================================
+
+Region Shapes
+-------------
+
+* FITS regions are specified in pixel units, thus a `~regions.SkyRegion`
+  cannot be serialized to the FITS region format. Regions are always
+  parsed and serialized as `~regions.PixelRegion` objects when using the
+  FITS region format.
+
+* When reading a ``elliptannulus``, the first ``ROTANG`` will be used
+  for both the inner and outer ellipse. The second ``ROTANG`` will be
+  ignored. In other words, you cannot have an elliptical annulus where the
+  inner and outer ellipse have different rotation angles.
+
+* Shapes where the value in the SHAPE column is preceded by an exclamation
+  mark (e.g., ``!circle``) will be read in as a `~regions.PixelRegion`
+  object and have ``include = 0`` in their ``meta`` dictionary. When
+  such objects are serialized, their shape will be prepended by ``!``.
+
+* The FITS ``box``, ``rotbox``, ``rectangle``, and ``rotrectangle``
+  shapes will all be parsed as a `~regions.RectanglePixelRegion`. In
+  turn, `~regions.RectanglePixelRegion` is always serialized as a
+  ``rotbox`` shape.
+
+* The following `~regions.PixelRegion` classes do not have corresponding
+  FITS shapes and therefore are not supported (a warning will be raised):
+
+    * `~regions.RectangleAnnulusPixelRegion`
+    * `~regions.LinePixelRegion`
+    * `~regions.TextPixelRegion`
+    * `~regions.CompoundPixelRegion`
+
+* FITS regions are always parsed and serialized into separate regions.
+  Shapes that have the ``COMPONENT`` column will have that value
+  stored in the `~regions.PixelRegion` ``meta`` dictionary with the
+  ``component`` key. Such regions will include the ``COMPONENT`` column
+  when serialized.
+
+* FITS parsing and serialization use only the ``include`` and
+  ``component`` metadata and no visual metadata.
+
+
+Coordinate Frames
+-----------------
+
+* `~regions.Region` objects represent abstract shapes that are not
+  tied to any particular image or WCS transformation. Therefore, any
+  WCS information in the FITS region file header will not be read.
+  Regions are always parsed and serialized as `~regions.PixelRegion`
+  objects when using the FITS region format. However, if desired you
+  can use the WCS information in the FITS region file to convert a
+  `~regions.PixelRegion` object to a `~regions.SkyRegion` object, e.g.,:
+
+.. doctest-skip::
+
+    >>> from astropy.io import fits
+    >>> from astropy.wcs import WCS
+    >>> header = fits.getheader('my_region.fits', 1)
+    >>> wcs = WCS(header, keysel=('image', 'binary', 'pixel'))
+    >>> sky_region = pix_region.to_sky(wcs)
+
+
+Other Limitations
+-----------------
+
+* Reading and then writing a FITS region file will not produce an
+  identical file to the original, but the encoded regions are identical.
+  Therefore, it will produce identical `~regions.Region` objects
+  when read back in again. In other words, read/write/read (or
+  parse/serialize/parse) will exactly roundtrip `~regions.Region`
+  objects.

docs/region_io.rst

@@ -180,3 +180,4 @@ Region File Format Limitations
     :maxdepth: 1
 
     ds9_io
+    fits_io

docs/shapes.rst

@@ -224,9 +224,9 @@ The text regions can be used to annotate a text string on an image.
     >>> from regions import PixCoord, TextSkyRegion, TextPixelRegion
 
     >>> center_sky = SkyCoord(42, 43, unit='deg', frame='fk5')
-    >>> point_sky = TextSkyRegion(center=center_sky, text='Demo Text')
-    >>> point_pix = TextPixelRegion(center=PixCoord(x=42, y=43),
-    ...                             text='Demo Text')
+    >>> region_sky = TextSkyRegion(center=center_sky, text='Demo Text')
+    >>> region_pix = TextPixelRegion(center=PixCoord(x=42, y=43),
+    ...                              text='Demo Text')
 
 
 Region Transformations

regions/core/metadata.py

@@ -53,11 +53,11 @@ class RegionMeta(Meta):
     A dictionary subclass that holds the meta attributes of the region.
     """
 
-    valid_keys = ['background', 'comment', 'composite', 'corr', 'delete',
-                  'edit', 'fixed', 'frame', 'highlite', 'include', 'label',
-                  'line', 'move', 'name', 'range', 'restfreq', 'rotate',
-                  'select', 'source', 'tag', 'text', 'textrotate', 'type',
-                  'veltype']
+    valid_keys = ['background', 'comment', 'component', 'composite', 'corr',
+                  'delete', 'edit', 'fixed', 'frame', 'highlite', 'include',
+                  'label', 'line', 'move', 'name', 'range', 'restfreq',
+                  'rotate', 'select', 'source', 'tag', 'text', 'textrotate',
+                  'type', 'veltype']
 
     key_mapping = {}
 

regions/io/__init__.py

@@ -2,8 +2,6 @@
 """
 This subpackage provides tools for reading and writing region files.
 """
-from .core import *  # noqa
-
 from .ds9.connect import *  # noqa
 from .ds9.core import *  # noqa
 from .ds9.read import *  # noqa

regions/io/core.py renamed to regions/io/crtf/io_core.py

@@ -5,25 +5,23 @@
 
 from astropy.coordinates import (Angle, SkyCoord, UnitSphericalRepresentation,
                                  frame_transform_graph)
-from astropy.table import Table
 import astropy.units as u
 from astropy.utils.exceptions import AstropyUserWarning
-import numpy as np
-
-from ..shapes import (CirclePixelRegion, CircleSkyRegion,
-                      EllipsePixelRegion, EllipseSkyRegion,
-                      RectanglePixelRegion, RectangleSkyRegion,
-                      PolygonPixelRegion, RegularPolygonPixelRegion,
-                      PolygonSkyRegion,
-                      CircleAnnulusPixelRegion, CircleAnnulusSkyRegion,
-                      EllipseAnnulusPixelRegion, EllipseAnnulusSkyRegion,
-                      RectangleAnnulusPixelRegion, RectangleAnnulusSkyRegion,
-                      LinePixelRegion, LineSkyRegion,
-                      PointPixelRegion, PointSkyRegion,
-                      TextPixelRegion, TextSkyRegion)
-from ..core.core import PixCoord, SkyRegion
-from ..core.metadata import RegionMeta, RegionVisual
-from .crtf.core import CRTFRegionParserWarning
+
+from ...shapes import (CirclePixelRegion, CircleSkyRegion,
+                       EllipsePixelRegion, EllipseSkyRegion,
+                       RectanglePixelRegion, RectangleSkyRegion,
+                       PolygonPixelRegion, RegularPolygonPixelRegion,
+                       PolygonSkyRegion,
+                       CircleAnnulusPixelRegion, CircleAnnulusSkyRegion,
+                       EllipseAnnulusPixelRegion, EllipseAnnulusSkyRegion,
+                       RectangleAnnulusPixelRegion, RectangleAnnulusSkyRegion,
+                       LinePixelRegion, LineSkyRegion,
+                       PointPixelRegion, PointSkyRegion,
+                       TextPixelRegion, TextSkyRegion)
+from ...core.core import PixCoord, SkyRegion
+from ...core.metadata import RegionMeta, RegionVisual
+from ..crtf.core import CRTFRegionParserWarning
 
 __all__ = []
 
@@ -44,20 +42,14 @@
 
 # Map the region names in the respective format to the ones available in
 # this package
-reg_mapping = {'CRTF': {x: x for x in regions_attributes},
-               'FITS_REGION': {x: x for x in regions_attributes}}
-
+reg_mapping = {'CRTF': {x: x for x in regions_attributes}}
 reg_mapping['CRTF']['rotbox'] = 'rectangle'
 reg_mapping['CRTF']['box'] = 'rectangle'
 reg_mapping['CRTF']['centerbox'] = 'rectangle'
 reg_mapping['CRTF']['poly'] = 'polygon'
 reg_mapping['CRTF']['symbol'] = 'point'
 reg_mapping['CRTF']['text'] = 'text'
 reg_mapping['CRTF']['annulus'] = 'circleannulus'
-reg_mapping['FITS_REGION']['annulus'] = 'circleannulus'
-reg_mapping['FITS_REGION']['box'] = 'rectangle'
-reg_mapping['FITS_REGION']['rotbox'] = 'rectangle'
-reg_mapping['FITS_REGION']['elliptannulus'] = 'ellipseannulus'
 
 # valid astropy coordinate frames in their respective formats
 valid_coordsys = {'CRTF': ['image', 'fk5', 'fk4', 'galactic',
@@ -271,78 +263,6 @@ def to_crtf(self, coordsys='fk5', fmt='.6f', radunit='deg'):
 
         return output
 
-    def to_fits(self):
-        """
-        Convert to a `~astropy.table.Table` object.
-        """
-        max_length_coord = 1
-        coord_x = []
-        coord_y = []
-        shapes = []
-        radius = []
-        rotangle_deg = []
-        components = []
-
-        reg_reverse_mapping = {value: key for key, value in
-                               reg_mapping['FITS_REGION'].items()}
-        reg_reverse_mapping['rectangle'] = 'ROTBOX'
-        reg_reverse_mapping['circleannulus'] = 'ANNULUS'
-        reg_reverse_mapping['ellipseannulus'] = 'ELLIPTANNULUS'
-
-        for num, shape in enumerate(self):
-            shapes.append(reg_reverse_mapping[shape.region_type])
-            if shape.region_type == 'polygon':
-                max_length_coord = max(len(shape.coord) / 2, max_length_coord)
-                coord = [x.value for x in shape.coord]
-                coord_x.append(coord[::2])
-                coord_y.append(coord[1::2])
-                radius.append(0)
-                rotangle_deg.append(0)
-            else:
-                coord_x.append(shape.coord[0].value)
-                coord_y.append(shape.coord[1].value)
-                if shape.region_type in ['circle', 'circleannulus', 'point']:
-                    radius.append([float(val) for val in shape.coord[2:]])
-                    rotangle_deg.append(0)
-                else:
-                    radius.append([float(x) for x in shape.coord[2:-1]])
-                    rotangle_deg.append(shape.coord[-1].to('deg').value)
-
-            tag = shape.meta.get('tag', '')
-            if tag.isdigit():
-                components.append(int(tag))
-            else:
-                components.append(num + 1)
-
-        # pad every value with zeros at the end to make sure that all
-        # values in the column have same length
-        for i in range(len(self)):
-            if np.isscalar(coord_x[i]):
-                coord_x[i] = np.array([coord_x[i]])
-            if np.isscalar(coord_y[i]):
-                coord_y[i] = np.array([coord_y[i]])
-            if np.isscalar(radius[i]):
-                radius[i] = np.array([radius[i]])
-
-            coord_x[i] = np.pad(coord_x[i],
-                                (0, int(max_length_coord - len(coord_x[i]))),
-                                'constant', constant_values=(0, 0))
-            coord_y[i] = np.pad(coord_y[i],
-                                (0, int(max_length_coord - len(coord_y[i]))),
-                                'constant', constant_values=(0, 0))
-            radius[i] = np.pad(radius[i], (0, 4 - len(radius[i])), 'constant',
-                               constant_values=(0, 0))
-
-        table = Table([coord_x, coord_y, shapes, radius, rotangle_deg,
-                       components],
-                      names=('X', 'Y', 'SHAPE', 'R', 'ROTANG', 'COMPONENT'))
-        table['X'].unit = 'pix'
-        table['Y'].unit = 'pix'
-        table['R'].unit = 'pix'
-        table['ROTANG'].unit = 'deg'
-
-        return table
-
 
 class _Shape:
     """

regions/io/crtf/read.py

@@ -11,7 +11,7 @@
 
 from ...core import Regions
 from ...core.registry import RegionsRegistry
-from ..core import _Shape, _ShapeList, reg_mapping
+from .io_core import _Shape, _ShapeList, reg_mapping
 from .core import (CRTFRegionParserError, CRTFRegionParserWarning,
                    valid_symbols)
 

regions/io/tests/test_core.py renamed to regions/io/crtf/tests/test_io_core.py

@@ -4,8 +4,8 @@
 from astropy.units.quantity import Quantity
 import pytest
 
-from ..core import _to_shape_list
-from ..crtf.read import _CRTFParser
+from ..io_core import _to_shape_list
+from ..read import _CRTFParser
 
 
 def test_shape_crtf():

regions/io/crtf/write.py

@@ -4,7 +4,7 @@
 
 from ...core import Region, Regions
 from ...core.registry import RegionsRegistry
-from ..core import _to_shape_list
+from .io_core import _to_shape_list
 
 __all__ = []