dmmakereg

Synopsis

Convert a region string to a CXC FITS region file

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

Example 4

dmmakereg region="circle(15:34:57,+23:30:13,10)" outfile=cel.reg
kernel=ascii wcsfile=evt2.fits

Convert a region in (RA,Dec) celestial coordinates to (x,y) physical coordinates. The output for this event file is:

unix% cat cel.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;Circle(4032.03,4138.1,10) #

Parameters

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 of dmmakereg does not work when kernel=ascii.  (07 Sep 2006)

unix% dmmakereg "circle(100,110,20)" file.out append=yes kernel=ascii
# dmmakereg (CIAO): ERROR: Could not create file 'file.out', it exists and 
clobber = no.

See Also

concept

subspace

dm

dmregions

tools

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