/ ciao4.17 / ahelp / dmmakereg.html

Jump to: Description · Examples · Parameters · Changes in CIAO 4.17 · Bugs · See Also

AHELP for CIAO 4.17

dmmakereg

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.

Changes in CIAO 4.17

Fix for unused array elements; they are now set to NaN instead of '0'. This includes columns such a 'R', 'ROTANG', as well as 'X' and 'Y' (especially when Polygon shapes are used).

This makes dmmakereg consistent with the region library including the python module, as well as the other tools that create region files.

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.