convert_ds9_region_to_ciao_stack

Context: Tools::Region

Synopsis

Convert ds9 region file containing special shapes to CIAO stack.

Syntax

convert_ds9_region_to_ciao_stack  infile outfile [verbose] [clobber]

Description

ds9 region files may contain single shapes with multiple radii or multiple annuli. This includes the following shapes: annulus, ellipse, box, panda (pie and annulus), epanda (pie and elliptical annulus), and bpanda (pie and box annulus). These single shapes must be converted into a stack of CIAO shapes. For example a ds9 region file with an annulus with 2 sets of radii must be converted to a CIAO stack of regions with 2 single radii annuli. The more exotic panda-based shapes are converted into CIAO syntax using logical and (intersection) and logical or (union) operations.

Limitations

The ds9 region files must be saved in physical coordinates.
The output CIAO stack may not always be compatible with ds9; in particular if any of the panda, bpanda, or epanda shapes were used.
Only shapes compatible with CIAO are converted. Lines, vectors, compasses, and text shapes are omitted from the output.
CIAO regions do not support shape properties such as source|background, color, font, tags, widths, etc. These are omitted from the output.
Any excluded shapes are excluded from all previous shapes in the file.

Examples

Example 1

% cat ds9.reg
# Region file format: DS9 version 4.1
global color=green dashlist=8 3 width=1 font="helvetica 10 normal
roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1
include=1 source=1
physical
annulus(5286.5,5638.5,0,60,120)
% convert_ds9_region_to_ciao_stack ds9.reg ciao.lis
% cat ciao.lis
annulus(5286.5,5638.5,0,60)
annulus(5286.5,5638.5,60,120)

Converts an annulus with 2 set of radii into a stack of CIAO regions. The stack can then be used with tools such as dmextract to create a radial profile.

% dmextract img.fits[bin sky=@ciao.lis] radial.prof op=generic

Example 2

% cat ds9.reg
# Region file format: DS9 version 4.1
global color=green dashlist=8 3 width=1 font="helvetica 10 normal
roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1
include=1 source=1
physical
annulus(5286.5,5638.5,0,60,120)
-circle(5200,5638,30) # tag={ptsrc}
% convert_ds9_region_to_ciao_stack ds9.reg ciao.lis
% cat ciao.lis
annulus(5286.5,5638.5,0,60)*!circle(5200,5638,30)
annulus(5286.5,5638.5,60,120)*!circle(5200,5638,30)

Same as the previous example but includes an excluded circle. The output file shows the circle being excluded from each individual annulus using the explicit "*!" syntax ("and not"). The tag property attached to the circle shape has been dropped.

This file can be used with dmextract as before. However, this file cannot be used with ds9 since ds9 does not support the CIAO logic operations: and (*), or (+), and negation (!).

Example 3

% cat ds9.reg
# Region file format: DS9 version 4.1
global color=green dashlist=8 3 width=1 font="helvetica 10 normal
roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1
include=1 source=1
physical
epanda(4222.5,3518.5,0,360,2,100,50,200,100,2,0)
% convert_ds9_region_to_ciao_stack ds9.reg ciao.lis
% cat ciao.lis
ellipse(4222.5,3518.5,150,75,0)*sector(4222.5,3518.5,0,180)*!ellipse(422
2.5,3518.5,100,50,0)
ellipse(4222.5,3518.5,200,100,0)*sector(4222.5,3518.5,0,180)*!ellipse(42
22.5,3518.5,150,75,0)
ellipse(4222.5,3518.5,150,75,0)*sector(4222.5,3518.5,180,360)*!ellipse(4
222.5,3518.5,100,50,0)
ellipse(4222.5,3518.5,200,100,0)*sector(4222.5,3518.5,180,360)*!ellipse(
4222.5,3518.5,150,75,0)

This shows an example of the "epanda" shape. It is converted into a series of outer-ellipses with an excluded interior ellipse and intersected with a sector. The 4 elliptical sectors as shown below.

               2 2 2 2 2 2 2 2 2 2 2 2               
         2 2 2 2 2 2 2 1 1 1 1 2 2 2 2 2 2 2         
       2 2 2 2 1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2       
     2 2 2 1 1 1 1                 1 1 1 1 2 2 2     
   2 2 2 1 1 1 1                     1 1 1 1 2 2 2   
   2 2 2 1 1 1                         1 1 1 2 2 2   
   4 4 4 3 3 3                         3 3 3 4 4 4   
   4 4 4 3 3 3                         3 3 3 4 4 4   
   4 4 4 4 3 3 3 3                 3 3 3 3 4 4 4     
       4 4 4 4 3 3 3 3 3 3 3 3 3 3 3 3 4 4 4 4       
         4 4 4 4 4 4 3 3 3 3 3 3 4 4 4 4 4 4         
               4 4 4 4 4 4 4 4 4 4 4 4

As before, this file can be used as a stack of regions with CIAO tools, though it cannot be loaded directly into ds9.

Parameters

name	type	ftype	def	min	max	reqd
infile	file	input				yes
outfile	file	output				yes
verbose	integer		1	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input ds9 region file

The infile must be a ds9 format region file which has been saved using physical coordinates.

Parameter=outfile (file required filetype=output)

The output file name

The output file will be a stack of regions using CIAO syntax.

Parameter=verbose (integer default=1 min=0 max=5)

Amount of tool chatter

Parameter=clobber (boolean default=no)

Overwrite existing files?

Changes in the 4.11.3 (May 2019) release

This is the first release of the convert_ds9_region_to_ciao_stack script.

About Contributed Software

This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.

Bugs

See the bug pages on the CIAO website for an up-to-date listing of known bugs.

Refer to the CIAO bug pages for an up-to-date listing of known issues.