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.