Reading/writing to FITS region filesΒΆ

The regions package provides the functionality to serialise and de-serialise Python lists of Region objects to FITS region file. A FITS Region Binary Table defines a spatial region of a two-dimensional image in pixels. The name of the header must be REGION for the read_fits_region to parse the table. The file is read using the read method which converts it into a Table object. FITSRegionParser parses this table. It converts the FITS region table to a ShapeList object, which is a list of Shape, each representing one FITS region in pixels. It should be noted that the regions are actually described in sky coordinates. It is converted explicitly to sky regions in the read_fits_region using the to_sky method. The WCS object is created with the help of FITS header of the file. The Shape objects can be converted to Region objects. Some of the regions such as rectangle, rotrectangle, pie, sector are not supported by this package.

>>> from regions import FITSRegionParser
>>> from astropy.table import Table
>>> from astropy.utils.data import get_pkg_data_filename
>>> filename = get_pkg_data_filename('data/fits_regions.fits',
...                                  package='regions.io.fits.tests')
>>> table = Table.read(filename)
>>> print(table)
     X [4]            Y [4]        SHAPE       R [4]         ROTANG  COMPONENT
      pix              pix                      pix           deg
---------------- ---------------- ------- ---------------- --------- ---------
   2896.5 .. 0.0    5056.5 .. 0.0  circle  381.9716 .. 0.0       0.0         1
5282.0541 .. 0.0 4854.5699 .. 0.0  ROTBOX 1303.4597 .. 0.0 28.395178         2
   2944.5 .. 0.0    3472.5 .. 0.0 ellipse     288.0 .. 0.0  337.4048         3
    341.0 .. 0.0     345.0 .. 0.0  ROTBOX      56.0 .. 0.0      65.0         4
    341.0 .. 0.0     345.0 .. 0.0 ANNULUS      56.0 .. 0.0       0.0         5
    341.0 .. 0.0     345.0 .. 0.0   point       0.0 .. 0.0       0.0         6
    341.0 .. 0.0     345.0 .. 0.0   point       0.0 .. 0.0       0.0         7
      1.0 .. 4.0       5.0 .. 8.0 polygon       0.0 .. 0.0       0.0         8

>>> parser = FITSRegionParser(table)
>>> print(parser.shapes[0])
Shape
Type : reg
Coord sys : physical
Region type : circle
Meta: {'tag': '1'}
Composite: False
Include: False

>>> regions = parser.shapes.to_regions() # pixel regions
>>> print(regions[0])
Region: CirclePixelRegion
center: PixCoord(x=2896.5, y=5056.5)
radius: 381.9716

>>> print(regions[0].meta)
{'tag': '1', 'include': False}

Serialisation is done using the fits_region_objects_to_table function

>>> from regions import fits_region_objects_to_table
>>> table_ouput = fits_region_objects_to_table(regions)
>>> print(table_ouput)
     X [4]            Y [4]        SHAPE       R [4]         ROTANG  COMPONENT
      pix              pix                      pix           deg
---------------- ---------------- ------- ---------------- --------- ---------
   2896.5 .. 0.0    5056.5 .. 0.0  circle  381.9716 .. 0.0       0.0         1
5282.0541 .. 0.0 4854.5699 .. 0.0  ROTBOX 1303.4597 .. 0.0 28.395178         2
   2944.5 .. 0.0    3472.5 .. 0.0 ellipse     288.0 .. 0.0  337.4048         3
    341.0 .. 0.0     345.0 .. 0.0  ROTBOX      56.0 .. 0.0      65.0         4
    341.0 .. 0.0     345.0 .. 0.0 ANNULUS      56.0 .. 0.0       0.0         5
    341.0 .. 0.0     345.0 .. 0.0   point       0.0 .. 0.0       0.0         6
    341.0 .. 0.0     345.0 .. 0.0   point       0.0 .. 0.0       0.0         7
      1.0 .. 4.0       5.0 .. 8.0 polygon       0.0 .. 0.0       0.0         8

The write_fits_region and read_fits_region functions write as well as read from a file in addition to doing the region serialisation and parsing.

>>> from astropy.io import fits
>>> from astropy.utils.data import get_pkg_data_filename
>>> from regions import read_fits_region, write_fits_region
>>> file_read = get_pkg_data_filename('data/fits_region.fits',
...                                   package='regions.io.fits.tests')
>>> hdul = fits.open(file_read)
>>> regions = read_fits_region(file_read) # sky regions
>>> print(regions[0])
Region: CircleSkyRegion
center: <SkyCoord (ICRS): (ra, dec) in deg
    (211.06231757, 54.49779926)>
radius: 0.052202298340895036 deg

>>> filename = 'region_ouput.fits'
>>> write_fits_region(filename, regions, hdul[1].header)