Skip to the navigation links
Last modified: December 2009

URL: http://cxc-newtest.cfa.harvard.edu/ciao4.2/dmmakereg.html
AHELP for CIAO 4.2

dmmakereg

Context: tools

Synopsis

Convert a region string to a CXC FITS region file

Syntax

dmmakereg  region outfile [append] [kernel] [wcsfile] [verbose]
[clobber]

Description

`dmmakereg' creates (or adds to) a FITS region file from an ASCII region description. It is intended to provide an easy way to generate such region files.

dmmakereg will accept any ASCII region description recognized by the CXC data model (see "ahelp dmregions"). However, note that not all tools which use FITS region files can handle arbitrary regions.

Using celestial coordinates

If your region is in celestial coordinates, you have to also supply a file which contains the WCS coordinate system (using the wcsfile parameter). The coordinate transformation to pixels will be read from this file.

Adding regions to a bad pixel file

Using dmmakereg to add regions to a bad pixel file is deprecated since the tool doesn't know all the details about how bad pixels should be added. In addition, it doesn't work at all for HRC data. Instead, use acis_run_hotpix or hrc_build_badpix to create new bad pixel files.

Example 1

dmmakereg "circle(4183,5870,200)-annulus(4222,5970,100,1000)" reg.fits

Create a region file that includes a circle centered a the coordinates (X,Y) = (4183,5870) with a radius of 200 and excludes the specified annulus.

Example 2

dmmakereg "circle(10:58:2.0134,-52:26:41.6329,0.05')" reg.fits
wcsfile=acisf00752_000N003_evt1.fits

Create a region file that includes a circle centered a the coordinates (RA,DEC) = (10:58:02.0134,-52:26:41.6329) with a radius of 0.05 armin (3 arcsec). The information required to convert from RA and DEC into X and Y is contained in the header of the file specified by the wcsfile parameter.

Example 3

dmmakereg "circle(4123,3800,400)+box(4555,3390,450,460,340)" r1.fits
dmmakereg "bounds(region(r1.fits))" r1_bounds.reg kernel=ascii

Here we have created a FITS region file r1.fits and then created an ASCII region file, r1_bounds.reg, which lists the boundary of the original region (i.e. that rectangle which encloses the regions in r1.fits).

unix% cat r1_bounds.reg
# Region file format: DS9 version 3.0
global color=blue font="helvetica 10 normal" select=1 edit=1 move=1 delete=1 include=1 fixed=0
physical;Box(4284.050000,3648.460000,1122.100000,1103.080000,0.000000) #  

Parameters

name type ftype def min max reqd
region string         yes
outfile file output       yes
append boolean   no     no
kernel string   fits     no
wcsfile file   none     no
verbose integer   0 0 5  
clobber boolean   no      

Detailed Parameter Descriptions

Parameter=region (string required)

Input region string

The region ASCII string which will be turned into a region data file.

Parameter=outfile (file required filetype=output)

Output file name and block name

Name of the output CXC region file

Parameter=append (boolean not required default=no)

Create a new file ("no") or merge the new region with existing regions in the output file ("yes")

The default value for this parameter is "no." In this case a new output file is created. If the output file exists, it is overwritten unless the clobber="no." If append="yes," then the existing regions in the output file are appended to the new region.

Parameter=kernel (string not required default=fits)

Output file format

Usually "FITS"; "ASCII" creates an ASCII region file.

Parameter=wcsfile (file not required default=none)

File containing coordinate information.

This parameter is only need if your region is given in celestial coordinates, such as "circle(10:58:2.0134,-52:26:41.6329,0.05')". In order to convert the coortinates into "sky" (i.e. pixel) coordinates, the details of the WCS transformation is read from the header of the file given in the wcsfile parameter.

If the parameter is not given, or set to "none", then the region coordinates will just be converted into decimal degrees.

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

The append option does not work with ASCII files

You can not append to an ASCII region file (i.e. when the kernel parameter is set to "ascii"). The tool will complain that the output file already exists and that the clobber parameter is set to no. If the clobber parameter is changed to yes then the outout file will be over-written, even if the append option is set to yes.

See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

See Also

concept
subspace
dm
dmregions
tools
dither_region, dmcontour, dmgroupreg, dmimgfilt, dmimglasso, get_src_region, mkbgreg, mksubbgreg, tg_create_mask

Last modified: December 2009