Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/convert_ds9_region_to_ciao_stack.html
AHELP for CIAO 4.16

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


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.

See Also

concept
stack, subspace
dm
dmmasks, dmregions
tools::aspect
dither_region
tools::detect
get_src_region
tools::gratings
tg_create_mask
tools::image
dmimgdist, dmimgfilt
tools::region
bkg_fixed_counts, dmcontour, dmgroupreg, dmimghull, dmimglasso, dmmakereg, psf_contour, rank_roi, regphystocel, roi, splitroi
tools::stacks
stk_build, stk_count, stk_read_num, stk_where