Reading/writing to DS9 region files¶
The regions package provides the functionality to serialise and de-serialise
Python lists of Region
objects to DS9 region strings.
De-serialisation is done using the DS9Parser
. It converts the DS9
string to ShapeList
object, which is a list of Shape
each
representing one DS9 region. The Shape
objects can be converted to
Region
objects.
>>> from regions import DS9Parser
>>> reg_string = 'galactic\ncircle(42,43,3) # color=green'
>>> parser = DS9Parser(reg_string)
>>> print(parser.shapes[0])
Shape
Type : reg
Coord sys : galactic
Region type : circle
Meta: {'color': 'green', 'include': True}
Composite: False
Include: True
>>> regions = parser.shapes.to_regions()
>>> print(regions[0])
Region: CircleSkyRegion
center: <SkyCoord (Galactic): (l, b) in deg
(42., 43.)>
radius: 3.0 deg
Serialisation is done using the ds9_objects_to_string
function
>>> from regions import ds9_objects_to_string
>>> ds9_objects_to_string(regions, coordsys='galactic')
'# Region file format: DS9 astropy/regions\ngalactic\ncircle(42.000000,43.000000,3.000000) # color=green\n'
There’s also write_ds9
and read_ds9
which write to and
read from a file in addition to doing the region serialisation and parsing.
>>> from regions import read_ds9, write_ds9
>>> filename = 'ds9.reg'
>>> write_ds9(regions, filename)
>>> regions = read_ds9(filename)
>>> regions
[<CircleSkyRegion(center=<SkyCoord (FK5: equinox=J2000.000): (ra, dec) in deg
(245.347655, 24.429081)>, radius=3.0 deg)>]
The visual
metadata includes items used for display, e.g.:
>>> print(regions[0].visual)
{'color': 'green'}
Some of these keyword may eventually be used by the plotting utilities and standardized, but they are not as of v0.3.