|
|
Translates DS9 regions and groups to CIAO format.
dmgroupreg infile srcoutfile bkgoutfile [exclude] [verbose] [clobber]
dmgroupreg reads region files in DS9 format and converts
them to region files which may be understood by CIAO tools.
As the name implies, dmgroupreg is a tool to handle
grouping; to that end, it will only translate the DS9 region
file if it contains grouping information (see DS9 release notes).
Many CIAO tools allow
for source and background information to be input, but until
now the source and background regions were associated with
each other in the order in which they were defined within
DS9. (Ie, defining sources A, B and C and then backgrounds
D, E and F would associate A with D, B with E and C with F
without regard to what the user actually wanted.) By using
the grouping capabilities of DS9 and dmgroupreg, users can
now create multitudes of srcs and
backgrounds which can be explicitly flagged as belonging
together.
Users may optionally remove the source regions from
the background (within each group) which can lead to some fairly
complicated logic with sufficiently complex included/excluded shapes.
An example DS9 region file might look like this:
physical;circle(1,2,3) # tag={Group1}
physical;circle(3,2,1) # background tag={Group1}
This is pretty straightforward, but it defines circle(1,2,3) as
a source region in group `Group1' and circle(3,2,1) as a background
region in the same group. The first few lines of the actual
DS9 output file contain some information which is ignored by
dmgroupreg.
Region types and how they translate between DS9 and CIAO.
|
circle
|
circle
|
verbatim
|
|
ellipse
|
ellipse
|
verbatim
|
|
polygon
|
polygon
|
verbatim
|
|
point
|
point
|
verbatim
|
|
box
|
rotbox
|
different name, same arguments
|
|
panda
|
pie
|
not yet supported; will translate as multiple pies
|
|
annulus
|
annulus
|
not yet supported; will translate as multiple annuli
|
|
line
|
n/a
|
none
|
|
ruler
|
n/a
|
none
|
|
compass
|
n/a
|
none
|
|
projection
|
n/a
|
none
|
|
text
|
n/a
|
none
|
Furthermore, DS9 allows you to specify regions as `excluded'
(aka subtracted or negated).
(Eg, region A excluded is `-A'.) dmgroupreg recognizes this
and will translate appropriately by subtracting the excluded
region from its `included' counterparts. Note that this is a
trait of particular regions and does not relate to the
dmgroupreg `exclude' parameter or the behavior affected by
that parameter.
dmgroupreg ds9.reg ciao.src ciao.bkg exclude=no
Given that `ds9.reg' has only two lines which read:
physical;circle(1,2,3) # tag={Group1}
physical;circle(3,2,1) # background tag={Group1}
This command will generate the following output in `ciao.src':
and the following in `ciao.bkg':
dmgroupreg ds9.reg ciao.src ciao.bkg exclude=yes
Changing exclude to yes otherwise w/ the same inputs and
parameters as the previous example, `ciao.bkg' will this time contain
the following:
# Group1
circle(3,2,1)*!circle(1,2,3)
dmgroupreg ds9.reg ciao.src ciao.bkg exclude=yes
Given that `ds9.reg' contains only the following:
physical;circle(1,2,3) # tag={Group1}
physical;polygon(4,5,6,7,8,9) # tag={Group2}
physical;box(10,11,12,13) # background tag={Group1} tag={Group2}
This command will generate the following output in `ciao.src':
# Group1
circle(1,2,3)
# Group2
polygon(4,5,6,7,8,9)
and the following in `ciao.bkg':
# Group1
rotbox(10,11,12,13)*!circle(1,2,3)
# Group2
rotbox(10,11,12,13)*!polygon(4,5,6,7,8,9)
dmgroupreg ds9.reg ciao.src ciao.bkg exclude=yes
Given that `ds9.reg' contains only the following:
physical;circle(1,2,3) # tag={Group1}
physical;polygon(4,5,6,7,8,9) # tag={Group1}
physical;box(10,11,12,13) # background tag={Group1}
This command will generate the following output in `ciao.src':
# Group1
circle(1,2,3)+polygon(4,5,6,7,8,9)
and the following in `ciao.bkg':
# Group1
rotbox(10,11,12,13)*!circle(1,2,3)+rotbox(10,11,12,13)*!polygon(4,5,6,7,8,9)
dmgroupreg ds9.reg ciao.src ciao.bkg exclude=yes
Given that `ds9.reg' contains only the following:
physical;-circle(1,2,3) # tag={Group1}
physical;polygon(4,5,6,7,8,9) # tag={Group1}
physical;box(10,11,12,13) # background tag={Group1}
This command will generate the following output in `ciao.src':
# Group1
polygon(4,5,6,7,8,9)*!circle(1,2,3)
and the following in `ciao.bkg':
# Group1
rotbox(10,11,12,13)*!polygon(4,5,6,7,8,9)+rotbox(10,11,12,13)*circle(1,2,3)
Parameter=infile (file required filetype=input stacks=no)
DS9 input file.
This is expected to be in DS9 format and in physical
coordinates. DS9 has the ability to tag regions as background
(`background') or source (no special tag) in addition to being able to
tag regions as being in a group (`tag={group name}').
Parameter=srcoutfile (file required filetype=output stacks=no)
Output filename for source region groups.
This is the file to which the source groups will be written;
one group per line. If no source regions exist for a
given group, no
output (including background regions) will be written
and the line will be
left blank. The group name will be listed as a comment
(Ie, on a line starting with '#') on the line
immediately preceding the actual group.
Parameter=bkgoutfile (file required filetype=output stacks=no)
Output filename for background region groups.
This is the file to which the background groups will be
written. Again, one group per line, and there is a line by line/group
by group correlation to the source file. If no background regions
exist for a given group, the output for the background group will be
simply `field()'.
Parameter=exclude (boolean not required default=yes)
Explicitly exclude source regions from background regions.
If true, all source regions from a given group will be
explicitly excluded from each background region in said group. (Eg,
for source A and B and bkg C and D, the background output when
EXCLUDE=false would be `C+D' but `C*!A*!B+D*!A*!B' when EXCLUDE=true.)
Verbose can be from 0 to 5, generating different
amounts of output.
If outfile already exists, clobber=yes will allow
you to overwrite it.
|
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}