dmgroupreg

Synopsis

Translates DS9 regions and groups to CIAO format.

dmgroupreg  infile srcoutfile bkgoutfile [exclude] [verbose] [clobber]

Description

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.

Input

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 Translation

Region types and how they translate between DS9 and CIAO.

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.

Examples

Example 1

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':

  # Group1
  circle(1,2,3)

and the following in `ciao.bkg':

  # Group1
  circle(3,2,1)

Example 2

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)

Example 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)

Example 4

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)

Example 5

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)

Parameters

Detailed Parameter Descriptions

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.)

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

Verbose can be from 0 to 5, generating different amounts of output.

Parameter=clobber (boolean default=no)

If outfile already exists, clobber=yes will allow you to overwrite it.

Bugs

There are no known bugs for this tool.

See Also

concept

subspace

dm

dmmasks, dmregions

tools

convert_ds9_region_to_ciao_stack, dither_region, dmcontour, dmgroupreg, dmimgdist, dmimgfilt, dmimghull, dmimglasso, dmmakereg, get_src_region, mkbgreg, mksubbgreg, roi, splitroi, tg_create_mask