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
for testing, and also to modify bad pixel 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. For instance, the bad pixel files used by
ACIS pipeline tools are valid FITS region files, but may only
contain the shapes "point" and "rectangle". Consult the
documentation for the application in question to check for
such restrictions.
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.
dmmakereg can also be used to make ASCII region files from
FITS by the 'kernel=ascii' option. This has not been
extensively tested and may not work well for very complicated
regions. Note that 'dmlist reg.fits data' on a region file
will give the ASCII interpretation of the region before
dumping the lower level table information.
If a region is added to an existing FITS region file,
dmmakereg will check whether the output file is a bad-pixel
file or not. In the first case the new region will be inserted
at the beginning of the block that is being modified,
otherwise the new region will be appended at the end of the
file. The reason is that bad pixels (or bad columns) in a
block of a bad-pixel file should always be
time-sorted. dmmakereg will assign the new bad pixel(/column)
a time equal to the first time in the column TIME of the given
bad-pixel block.
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 "point(332,418)" "acisf00732_004N002_bpix1.fits[badpix3]"
append=yes
A new bad pixel at the coordinates (CHIPX,CHIPY) = (332,418)
is added to the "BADPIX3" extension of the specified bad-pixel
file. In this case, the existing bad pixels and columns in
this extension are appended to the the new bad pixel. The
file is modified in place; the clobber parameter is ignored.
If the BADPIX3 table does not exist, it is created.
dmmakereg "rectangle(332,1,332,1024)"
"acisf00732_004N002_bpix1.fits[badpix3]" append=yes
A new bad column for CHIPX = 332 and 1 <= CHIPY <=
1024 is added to the "BADPIX3" extension of the specified
bad-pixel file. In this case, the existing bad pixels and
columns in this extension are appended to the new bad
column. The file is modified in place; the clobber
parameter is ignored. If the BADPIX3 table does not exist,
it is created.
dmmakereg "region(region_list.txt)"
"acisf00732_004N002_bpix1.fits[badpix3]" append=yes
The new bad pixels and columns in the ASCII file
region_list.txt are added to the "BADPIX3" extension of
the specified bad-pixel file. The file region_list.txt
contains one pixel or column per line. For example,
point(332,418)
rectangle(332,1,332,1024)
point(10,13)
In this example, the existing bad pixels and columns in
the extension BADPIX3 are appended to the new bad column.
The file is modified in place; the clobber parameter is
ignored. If the BADPIX3 table does not exist, it is
created.
Input region string
The region ASCII string which will be turned into a region data file.
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.
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" (ie 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.
Verbose can be from 0 to 5, generating different
amounts of output.
If outfile already exists, clobber=yes will allow
you to overwrite it.
The wcsfile parameter is now used to convert regions such
as
circle(10:58:2.0134,-52:26:41.6329,0.05')
into pixel coordinates. Prior to CIAO 3.4 the coordinates
were converted into decimal degrees instead of applying the
coordinate transformation given in the wcsfile.
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 cloober 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.
|
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}