|AHELP for CIAO 4.2||
Convert a region string to a CXC FITS region file
dmmakereg region outfile [append] [kernel] [wcsfile] [verbose] [clobber]
`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.
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.
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.
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.
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.
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) #
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.
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.