FITS Region File Format Limitations

Region Shapes

• FITS regions are specified in pixel units, thus a SkyRegion cannot be serialized to the FITS region format. Regions are always parsed and serialized as 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 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 RectanglePixelRegion. In turn, RectanglePixelRegion is always serialized as a rotbox shape.

• The following PixelRegion classes do not have corresponding FITS shapes and therefore are not supported (a warning will be raised):

  • RectangleAnnulusPixelRegion

  • LinePixelRegion

  • TextPixelRegion

  • CompoundPixelRegion

• FITS regions are always parsed and serialized into separate regions. Shapes that have the COMPONENT column will have that value stored in the 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

• 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 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 PixelRegion object to a SkyRegion object, e.g.,:

>>> 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 Region objects when read back in again. In other words, read/write/read (or parse/serialize/parse) will exactly roundtrip Region objects.