Reading/Writing Region Files¶

The regions package provides a unified interface for reading, writing, parsing, and serializing regions data in different standard formats.

Regions I/O¶

The Regions class (which represents a list of Region objects) includes four methods, read(), write(), parse(), and serialize(), that make it possible to read, write, parse, and serialize region files or region data.

The Regions class has built-in support for various input and output formats. A full list of the supported formats and is shown in the table below. The Suffix column indicates the standard filename suffix for a particular format.

Format	Suffix	Description
crtf	.crtf	CASA Region Text Format
ds9	.reg, .ds9	DS9 Region Format
fits	.fits	FITS Region Binary Table

Use the get_formats() method to get the registered I/O formats as a Table:

>>> from regions import Regions
>>> print(Regions.get_formats())
Format Parse Serialize Read Write Auto-identify
------ ----- --------- ---- ----- -------------
  crtf   Yes       Yes  Yes   Yes           Yes
   ds9   Yes       Yes  Yes   Yes           Yes
  fits   Yes       Yes  Yes   Yes           Yes

Read¶

To read in a region file, first import the Regions class, then call the read() method with the name of the file and the file format, e.g.:

>>> from regions import Regions
>>> regions = Regions.read('my_regions.reg', format='ds9')

It is also possible to load regions directly from the internet using URLs, e.g.:

>>> regions = Regions.read('https://some.domain.edu/my_regions.reg', format='ds9')

If the format keyword is not set, the read() method will attempt to automatically determine the file format from the filename extension or the file contents:

>>> regions = Regions.read('my_regions.reg')

The underlying file handler will also automatically detect various compressed data formats and transparently uncompress them if supported by the Python installation (see get_readable_fileobj):

>>> regions = Regions.read('my_regions.reg.gz')

Write¶

Use the write() method to write regions to a region file. Like the read() method, the filename extension will be used to automatically define the format if unspecified.

>>> regions.write('my_regions.crtf', format='crtf')
>>> regions.write('my_regions.reg')

If the file already exists and you want to overwrite it, then set the overwrite keyword to True:

>>> regions.write('my_regions.reg', overwrite=True)

Parse¶

Region data in the form of a string or table may also be parsed into a Regions object by using the parse() method. The format keyword must be specified when parsing region data. A region string can be parsed for the crtf and ds9 formats, while a Table can be parsed for the fits format:

>>> from regions import Regions
>>> regions_str = '# Region file format: DS9\nimage\ncircle(147.10,254.17,3.1) # color=green\n'
>>> regions = Regions.parse(regions_str, format='ds9')
>>> print(regions)
[<CirclePixelRegion(center=PixCoord(x=146.1, y=253.17), radius=3.1)>]
>>> print(regions[0].visual)
{'default_style': 'ds9', 'facecolor': 'green', 'edgecolor': 'green'}

Serialize¶

Regions can be serialized to a string or table by using the serialize() method. The format keyword must be specified when serializing region data. Serializing regions to the crtf or ds9 format will produce a region string, while the fits format will produce a Table:

>>> regions_str = regions.serialize(format='ds9')

Region Classes I/O¶

Additionally, all of the Region classes (i.e., Region subclasses) support the write() and serialize() methods.

As an example, let’s create a CircleSkyRegion object:

>>> from astropy.coordinates import SkyCoord
>>> import astropy.units as u
>>> from regions import CircleSkyRegion
>>> coord = SkyCoord(202.469575, 47.19525833, unit='deg', frame='fk5')
>>> region = CircleSkyRegion(coord, radius=0.01 * u.deg)
>>> region
<CircleSkyRegion(center=<SkyCoord (FK5: equinox=J2000.000): (ra, dec) in deg
(202.469575, 47.19525833)>, radius=0.01 deg)>

To serialize the region:

>>> region.serialize(format='ds9', precision=8)
'# Region file format: DS9 astropy/regions\nj2000\ncircle(202.46957500,47.19525833,0.01000000)\n'

To write the region to a region file:

>>> region.write('my_region.ds9', format='ds9')

Use the get_formats() method to list all available formats and methods for the Region subclasses:

>>> print(region.get_formats())
Format Parse Serialize Read Write Auto-identify
------ ----- --------- ---- ----- -------------
  crtf    No       Yes   No   Yes           Yes
   ds9    No       Yes   No   Yes           Yes
  fits    No       Yes   No   Yes           Yes

Region File Format Limitations¶

Spherical Regions Limitations¶

Reading/writing and serializing SphericalSkyRegion objects is not currently implemented.

Navigation