Synopsis
Convert the format of a region file (swap between ASCII and CXC FITS)
Syntax
dmmakereg region outfile [append] [kernel] [wcsfile] [verbose] [clobber]
Description
The dmmakereg tool converts regions between ASCII and CXC FITS format. Examples include converting the string "circle(2323.2,4982.6,12)" to a FITS format file, "region(reg.fits)" to an ASCII region file, and an ASCII file in celestial coordinates to one in physical coordinates.
ASCII support
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.
Editing FITS files
When kernel=fits, the tool will either create the output file or add to an existing block, depending on the append setting. This makes it possible to extend an existing region file.
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.
This can be particularly useful to convert an ASCII file in celestial coortinates to an ASCII file in physical coordinates.
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_build_hotpix or hrc_build_badpix to create new bad pixel files.
Examples
Example 1
unix% 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.
The output can be viewed as a table; for instance:
unix% dmlist reg.fits"[cols shape,pos]" data,clean Region Block: Circle(4183,5870,0)&!Annulus(4222,5970,0,0) # SHAPE POS(X,Y) Circle 4183.0 5870.0 !Annulus 4222.0 5970.0
Example 2
unix% cat example.reg circle(4183,5870,200)-annulus(4222,5970,100,1000) unix% dmmakereg "region(example.reg)" reg2.fits
The region can also be read in from an ASCII file, using the region() syntax of ahelp dmregions.
Example 3
unix% dmmakereg "region(src.fits)" src.reg kernel=ascii
The tool can also be used to convert a FITS region file - here src.fits - to an ASCII one (src.reg) by changing the kernel parameter to ascii (the default is fits).
Example 4
unix% 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 5
unix% dmmakereg "region(sky.reg)" phys.reg kernel=ascii wcsfile=broad_flux.img
Convert an ASCII region file in celestial coordinates (sky.reg) to an ASCII region file in physical coordinates (phys.reg), using the coordinate system in broad_flux.img to perform the conversion.
Example 6
unix% dmlist reg.fits counts 2 unix% dmmakereg "ellipse(4234.2,3948.7,53.4,37.4,132.8)" reg.fits append=yes unix% dmlist reg.fits counts 3
The append flag can be used to add data to an existing FITS region file. Here the file reg.fits originally contains 2 shapes, but the dmmakereg call adds one more to it.
Example 7
unix% dmmakereg "circle(4123,3800,400)+box(4555,3390,450,460,340)" r1.fits unix% 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 4.1 global color=blue dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1 physical Box(4284.05,3648.46,1122.1,1103.08,0) #
Example 8
unix% pset dmmakereg kernel=ascii wcsfile=evt2.fits unix% dmmakereg "circle(15:34:57,+23:30:13,10)" cel.reg
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 4.1 global color=blue dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1 physical Circle(4037.51,4137.54,10) #
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 string which will be turned into a region data file. See ahelp dmregions for the supported syntax.
Examples include an actual region specification, such as
region="ellipse(4239.3,6732.39,45.2,23.2,47.913)"
or using the region command to load in a file:
region="region(src.reg)" region="bounds(region(fov.fits[ccd_id=3]))
Parameter=outfile (file required filetype=output)
Output virtual filename
Name of the output file.
Parameter=append (boolean not required default=no)
Create or Append
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" the new region is appended to the existing regions in the output file.
Parameter=kernel (string not required default=fits)
Output file format type
The supported options are fits or ascii.
Parameter=wcsfile (file not required default=none)
File with coordinate mapping
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)
Debug Level(0-5)
Parameter=clobber (boolean default=no)
Clobber existing file (in create mode)
If the outfile already exists, clobber=yes will allow you to overwrite it. Also see the append parameter.
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.
Caveats
- ASCII regions always say "physical"
The ASCII regions produced with kernel=ascii will always indicate that the region is in physical coordiate.
See Also
- concept
- subspace
- dm
- dmmasks, dmregions
- tools::aspect
- dither_region
- tools::detect
- get_src_region
- tools::gratings
- tg_create_mask
- tools::image
- dmimgdist, dmimgfilt
- tools::region
- bkg_fixed_counts, convert_ds9_region_to_ciao_stack, dmcontour, dmgroupreg, dmimghull, dmimglasso, psf_contour, rank_roi, regphystocel, roi, splitroi