dmcoords

Synopsis

Convert between Chandra coordinate systems

dmcoords  infile [asolfile] [option] [chip_id] [chipx] [chipy] [tdetx]
[tdety] [detx] [dety] [x] [y] [logicalx] [logicaly] [ra] [dec] [theta]
[phi] [order] [energy] [wavelength] [ra_zo] [dec_zo] [celfmt]
[detector] [grating] [fpsys] [sim] [displace] [ra_nom] [dec_nom]
[roll_nom] [ra_asp] [dec_asp] [roll_asp] [geompar] [verbose]

Description

The dmcoords tool allows you to convert between the various coordinate systems used by Chandra (eg SKY to CHIP) and to predict the source location for a variety of instrumental configurations. It has limited support for data from other telescopes.

The tool has two modes of operation:

• parameter mode - where all the input and output options are set using the parameter interface.
• interactive mode - in which commands can be entered at a prompt and the output is to the screen.

The parameter mode is particularly useful in scripts since it can be run with no user interaction, whereas the interactive mode allows greater flexibility and the ability to perform multiple conversions in one session.

Parameter mode

To convert from a given position, set the option parameter to the name of the input coordinate system (e.g. option=sky) and the corresponding set of coordinate parameters (e.g. x and y for option=sky) to the input position. After running dmcoords the remaining coordinate parameters (e.g. chip_id, chipx, chipy, tdetx, ...) will have been set. The pget tool can then be used to access this information, for example:

unix% pget dmcoords chipx
662.0891847226883

When using the parameter mode it is recommended that the verbose parameter be set to 1 if you wish to see the output values (they will always be stored in the parameter value, whatever the value of verbose). The default setting for the verbose parameter (0) is intended for pipeline/batch use when screen output is undesireable.

Parameters for the various coordinate systems:

Interactive Mode

The interactive mode of dmcoords can be entered by not specifying a value for the option parameter. The prompt will change to 'dmcoords>:' and commands can then be entered to set or query the instrument configuration and to perform coordinate conversions. Unlike the parameter mode, more than one conversion may be calculated by dmcoords within a single session. Note that the commands are case-insensitive.

Interactive mode commands

Note that in interactive mode the "SET NOMINAL" command requires that the input be in sexagesimal format, whereas "SET ASPECT" uses the setting of the celfmt parameter to decode the supplied RA and DEC values. Use the "DEG" and "HMS" interactive commands to switch between formats.

Chandra Coordinate Systems

A number of coordinate systems have been defined for use with Chandra. They are described in Coordinate Systems Paper I: Imaging.

Examples

Example 1

unix% dmcoords evt2.fits asol=none option=sky x=4096.5 y=4096.5
verbose=1

Using the parameter mode

The dmcoords run will return the various coordinates that represent the SKY location (4095.6,4096.5). The values are written both to the screen and to the dmcoords parameter file (which can be accessed, as shown in the next example).

In this case, the input file contained the DY_AVG, DZ_AVG, and DTH_AVG keywords, which means that the asolfile argument could be set to none. The asolfile parameter is ignored if the input file contains the DY_AVG, DZ_AVG, and DTH_AVG keywords. If these keywords did not exist then the reported CHIP and TDET coordinates would be wrong, unless the aspect solution were also given; e.g.

unix% dmcoords evt2.fits asol=pcadf277305098N002_asol1.fits option=sky
x=4096.5 y=4096.5 verbose=1

Example 2

unix% punlearn dmcoords
unix% dmcoords img.fits asol=none option=sky x=4096.5 y=4096.5
unix% pget dmcoords chipx
961.3373175917339
unix% pget dmcoords chipy
1014.516913427166
unix% pget dmcoords chip_id
3
unix% pget dmcoords ra
00:33:44.817
unix% pget dmcoords dec
-43:21:30.12

Accessing the converted coordinates via the parameter file

With the verbose parameter set to 0 - its default value - there is no screen output. The converted values can be accessed from the parameter file using the pget tool, as shown above.

The format used for the celestial coordinates RA and DEC is controlled by the celfmt argument; the default value (celfmt=hms) was used above. To get values in decimal degrees use celfmt=deg, as shown here (the punlearn is to stop a warning message about an invalid format for the ra_zo parameter due to it being in sexagesimal format):

unix% punlearn dmcoords
unix% dmcoords img.fits none option=sky x=4096.5 y=4096.5 celfmt=deg
unix% pget dmcoords ra
8.436739892007701
unix% pget dmcoords dec
-43.358367970649

Finding the off-axis angle

One of the coordinate systems supported by dmcoords is the MSC system, which gives the off-axis angle and azimuth for the nominal aspect solution. The parameters representing this system are theta and phi; the units of the values stored in the parameter file are arcminute and degrees, respectively, so

unix% pget dmcoords theta
0

will give the off-axis angle of the source, in arcminutes; for this example we chose the on-axis ACIS location (4096.5,4096.5) which is why the answer is 0.

Note that the screen output - i.e. when verbose=1 - varies the units used for the THETA value, depending on its size (i.e. it switches between arcseconds and arcminutes). This is not the case for the theta parameter - i.e. the value stored in the parameter file - which is always in arcminutes.

Example 3

unix% punlearn dmcoords
unix% dmcoords img.fits asol=none opt=cel celfmt=hms ra="0h 32m 15s"
dec="-43d 42' 41"'"'
unix% pget dmcoords x
6075.899935710346
unix% pget dmcoords y
1508.92022472837

Using celestial coordinates

In this example we take advantage of the sexagesimal support by setting celfmt=hms; see the Supported formats for sexagesimal notation below for more information on the supported formats. For the tcsh shell used in this example, the declination value had to be specified as

dec="-43d 42' 41"'"'

in order for the " symbol to be passed through the shell to dmcoords. However, note that you can get the same result by saying

dec="-43d 42' 41"

(which ignores the arcsecond symbol). You can check what the value was parsed as by checking the ra and dec parameters with pget once the tool has run; for instance:

unix% pget dmcoords ra
00:32:15.000
unix% pget dmcoords dec
-43:42:41.00

Off chip locations

The input location need not land on a chip for the conversion to occur; in this case the result is not, as can be seen in the screen output (if verbose were not 0), which would say

CHIP ACIS-I1      2921.20       -264.34 (off chip)

or by checking for "invalid" values for the coordinate system (e.g. ACIS chip coordinates should be between 1 and 1024 inclusive):

unix% pget dmcoords chip_id
1
unix% pget dmcoords chipx
2921.19775645747
unix% pget dmcoords chipy
-264.3355687189608

Note that not all coordinate systems will be calculated in this case; for example

unix% pget dmcoords tdetx
0

Example 4

unix% dmcoords evt2.fits

Using the interactive mode

Since no option parameter was specified, this command puts you into the interactive version of the program. The prompt will change to 'dmcoords:>'; use the HELP command (case insensitive) to list the available commands. Note that you will get screen output in this mode even with verbose=0.

To repeat the calculation from Example 1, one would enter:

dmcoords:> sky 4095.6 4096.5
(RA,Dec):     00:33:44.817    -43:21:30.12
(RA,Dec):        8.43674      -43.35837 deg
THETA,PHI            0.0"        255.50 deg
(Logical):         226.50        170.50
SKY(X,Y):         4096.50       4096.50
DETX,DETY         4096.50       4096.50
CHIP ACIS-I3       961.34       1014.52
TDET              4117.48       4022.34

and from example 3:

dmcoords:> hms
dmcoords:> cel 0h 32m 15s -43d 42' 41"
(RA,Dec):     00:32:15.000    -43:42:41.00
(RA,Dec):        8.06250      -43.71139 deg
THETA,PHI         26.714'        292.93 deg
(Logical):         473.92       -152.95
SKY(X,Y):         6075.90       1508.92
DETX,DETY         5365.60       1096.00
CHIP ACIS-I1      2921.20       -264.34 (off chip)
TDET                 0.00          0.00	      

Example 5

unix% dmcoords evt2.fits asol=none opt=chip chip_id=3 chipx=123
chipy=1012

Using chip coordinates

Here the input position is given in CHIP coordinates, and so the chip number as well as (x,y) values need to be given.

Converting from CHIP coordinates

As converting from CHIP to other coordinates requires knowledge of the telescope drift, the input file should have the DY_AVG, DZ_AVG, and DTH_AVG keywords set when run with asolfile=none, or the aspect solution files set using the asolfile parameter, otherwise the conversion will not be correct.

Specifying CHIP coordinates in the interactive mode

The SET command is used to set the chip number; for example

dmcoords:> set acis-3
dmcoords:> chip 123 1012

Example 6

unix% dmcoords acis.fits
asolfile="pcadf075214790N002_asol1.fits,pcadf075249320N002_asol1.fits"

Using multiple aspect solution files

For observations with multiple asol files, the files can be given using the stack support of CIAO tools; in this case using a comma-separated list but a separate file can also be used. For example

unix% ls -1 pcad*asol1.fits > asol.lis
unix% dmcoords acis.fits asolfile=@asol.lis

Example 7

unix% punlearn dmcoords
unix% dmcoords a4059_nvss.fits

Support for non-Chandra data sets

In this example we use a non-Chandra image as input - in this case an image of Abell 4059 from the NVSS - which means that only a limited set of conversions are supported. Here we chose to find the celestial location of the bottom-left pixel, which has logical coordinates of (1,1):

dmcoords:> logical 1 1
(RA,Dec):     23:57:53.876    -34:55:16.64
(RA,Dec):      359.47449      -34.92129 deg
(Logical):           1.00          1.00
SKY(X,Y):            1.00          1.00

In this example, the axis transformations sections of 'dmlist a4059_nvss.fits cols' contains

   1   1,2    POS(X) = (#1)
                 (Y)   (#2)

and

   1   1,2    EQPOS(RA ) = (+359.1696) +SIN[(-0.0042)* (POS(X)-(+61.0))]
                   (DEC)   (-34.6717 )      (+0.0042)  (   (Y) (+61.0))

which indicate that the SKY transform (ds9 lists as the "Physical" coordinate system) is the same as the Logical system (ds9 lists this as the "Image" coordinate system) and the celestial projection uses the SIN transform, rather than the TAN transform used for Chandra data.

Handling multi-dimensional datasets

The first two axes found in the file are used for the conversion, so if these are not the desired axes, then you can use the CIAO DataModel "bin" expression to explicitly select the axes used. For example, the following select the pair of axes called POS, the (X,Y) pair, and the third and fourth axes of the image, respectively:

unix% dmcoords "img.fits[bin pos]"
unix% dmcoords "img.fits[bin x,y]"
unix% dmcoords "img.fits[bin #3,#4]"

Example 8

unix% dmcoords sim.fits none
dmcoords:> set SIM/DISPLACE 0 -0.094 -0.239 0 0 0

Advanced control of the aspect solution

Instead of providing an aspect solution file, the SIM displacement is set manually in interactive mode. This is useful, for instance, if you are applying an average aspect offset to a simulated event file.

The offset values were calculated as the mean of the dy and dz columns in the aspect solution file (or you can use the DY_AVG and DZ_AVG keywords in the header of the aspect file):

unix% dmstat pcadf084244404N002_asol1.fits"[cols dy,dz]"
dy[mm]
    min:        0.091324806213        @:        9498 
    max:        0.097047097981        @:        16625 
   mean:        0.093908689086 
  sigma:        0.00092756058414 
    sum:        3424.0047128 
   good:        36461 
   null:        0 

dz[mm]
    min:        0.23693628609         @:        33325 
    max:        0.24103234708         @:        29179 
   mean:        0.23898746577 
  sigma:        0.00082102345009 
    sum:        8713.7219896 
   good:        36461 
   null:        0 

Note that the sign on the values must be reversed when they are set in dmcoords. The output of the command looks like:

dmcoords>: sky 4070 4249
(RA,Dec):     18:33:33.661    -10:34:06.34   
(RA,Dec):      278.39026      -10.56843 deg
THETA,PHI          1.269'          6.67 deg
(Logical):        4070.00       4249.00
SKY(X,Y):         4070.00       4249.00
DETX,DETY         4250.24       4114.47
CHIP ACIS-S3       370.68        381.73
TDET              4287.68       2083.73

Example 9

unix% punlearn dmcoords
unix% dmcoords none asol=none opt=det detx=4963.0 dety=4012.0 \
sim="0.6 0.0 -192.3" detector=acis celfmt=deg \
ra_nom=96.1043 dec_nom=-0.0243 roll_nom=212.3 \
ra_asp=")ra_nom" dec_asp=")dec_nom" verbose=1

Manually setting the observation information

Instead of using an input file to set up the header, here we specify the configuration parameters explicitly.

The output of the command looks like:

----------------------------------------
Spacecraft Configuration:
----------------------------------------
Dataset:
Observatory:
Telescope:        CHANDRA
Grating:          HEG
Instrument:       ACIS
Detector:         ACIS
Chip:             ACIS-S4
SIM position:          0.600     0.000  -192.300
SIM offset:            0.000     0.000     0.000
SIM rotation:          0.000     0.000     0.000
Grating order: 0
Focal length:     10070.000000
Chip pixel scale: 0.023987 x 0.023987 mm/pixel
Chip size:        1024 x 1024 pixels

----------------------------------------
Sky Coordinate Configuration:
----------------------------------------
Sky coordinate pixel system: FP-1.1
Center pixel of sky plane:  (4096.500000,4096.500000)
Size of sky plane:          8192 x 8192
Sky pixel scale:            0.492000 arcsec/pixel
Nominal:          RA  96.104300 Dec  -0.024300 Roll   0.000000
Aspect:           RA  96.104300 Dec  -0.024300 Roll 212.300000


  --------

(RA,Dec):     06:24:47.574    +00:02:55.46
(RA,Dec):       96.19823        0.04874 deg
THETA,PHI          7.139'        354.43 deg
(Logical):        3409.23       4630.94
SKY(X,Y):         3409.23       4630.94
DETX,DETY         4963.00       4012.00
CHIP ACIS-S4        46.60        706.29
TDET              5005.60       2408.29
GDPX,GDPY        35955.90      15777.92
GAC R,D            0.00          0.00
ENERGY 1.000000
ZO(RA,Dec):     00:00:00.000    +00:00:00.00
ZO(RA,Dec):        0.00000        0.00000 deg
ZO SKY(X,Y):            0.00          0.00
ZO DETX,DETY            0.00          0.00

Example 10

unix% punlearn dmcoords
unix% dmcoords none asolfile=none detector="HRC-I" \
celfmt=deg ra_nom=0 dec_nom=0 roll_nom=0 \
op=cel ra=0 dec=0 \
ra_asp=")ra_nom" dec_asp=")dec_nom" roll_asp=")roll_nom" \
sim="0 0 126.98" displace="0 0 0 0 0 0" verbose=1 \
fpsys=ASC-FP-2.1

This is similar to the previous example, except now for HRC-I. In this case, the fpsys (focal-plane system) parameter must also be set. The default fpsys is for ACIS.

Example 11

unix% dmstat pcadf277305098N002_asol1.fits"[cols ra]" v=0
unix% set row = `pget dmstat out_max_loc`
unix% echo $row
37251
unix% set ramax = `dmkeypar pcadf277305098N002_asol1.fits"[#row=$row]"
ra echo+`
unix% set decmax = `dmkeypar pcadf277305098N002_asol1.fits"[#row=$row]"
dec echo+`
unix% echo $ramax $decmax
8.44036102660281 -43.3567792306377
unix% dmcoords img.fits asol=none opt=sky x=4124.2 y=3987.8 v=0
unix% echo "phi=`pget dmcoords phi` theta=`pget dmcoords theta`"
phi=269.8082763968602 theta=0.9198258175279874
unix% dmcoords img.fits asol=none opt=sky x=4124.2 y=3987.8 v=0
ra_asp=$ramax dec_asp=$decmax
unix% echo "phi=`pget dmcoords phi` theta=`pget dmcoords theta`"
phi=276.8311177394897 theta=1.059156578924503

Selecting a specific aspect solution for the conversion

In this example we use the ra_asp and dec_asp parameters to change the aspect solution used for the coordinate calculations (the roll is left at its default, nominal, value). We chose to use the point in the aspect solution with the maximum RA value by using dmstat to identify the row and dmkeypar to extract the RA and DEC values for that row. These are then fed to dmcoords using the ra_asp and dec_asp parameters, and the off-axis position (as reported by the MSC coordinate system) calculated for the nominal and instantaneous aspect values.

Example 12

unix% dmcoords acisf14661_001N002_evt1.fits.gz op=cel \
ra=257.34767 dec=-36.28015\
celfmt=deg order=1 energy=2.211 verbose=1

Compute sky coordinates for dispersed energy using gratings

When the input file is a Chandra observation which uses the transmission gratings and the energy parameter is not equal to zero (0), dmcoords will use the input RA and Dec as the zeroth order location of the gratings, and will then compute the dispersed coordinates for the specified energy and order. In this example, Chandra OBS_ID 14661 is an ACIS observation which uses the HETG grating. The energy and order parameters are specified so dmcoords uses the ra and dec parameters as the zeroth order location to compute the dispered location of that energy. The output looks like:

----------------------------------------
Spacecraft Configuration:
----------------------------------------
Dataset:           acisf14661_001N002_evt1.fits.gz
Observatory:         
Telescope:        CHANDRA
Grating:          HEG
Instrument:       ACIS
Detector:         ACIS
Chip:             ACIS-S4
SIM position:         -0.683     0.000  -185.255    
SIM offset:            0.000    -0.882    -0.894   
SIM rotation:         -0.004     0.000     0.000   
Grating order: 1
Focal length:     10070.000000
Chip pixel scale: 0.023987 x 0.023987 mm/pixel
Chip size:        1024 x 1024 pixels

----------------------------------------
Sky Coordinate Configuration:
----------------------------------------
Sky coordinate pixel system: FP-1.1
Center pixel of sky plane:  (4096.500000,4096.500000)
Size of sky plane:          8192 x 8192
Sky pixel scale:            0.492000 arcsec/pixel
Nominal:          RA 257.285758 Dec -36.408981 Roll   0.000000
Aspect:           RA 257.285758 Dec -36.408981 Roll 252.649293


  --------  

(RA,Dec):    17:09:39.111     -36:09:10.69   
(RA,Dec):       257.41296     -36.15297 deg
THETA,PHI         16.547'          4.52 deg
(Logical):        3344.94       5969.28
SKY(X,Y):         3344.94       5969.28
DETX,DETY         6108.19       4255.37
CHIP ACIS-S5       114.33        130.87
TDET              6115.33       1832.87
GDPX,GDPY        36522.39      16384.50
GAC R,D          0.160583             0 deg
ENERGY           2.211000 keV
ZO(RA,Dec):  17:09:23.440     -36:16:48.54   
ZO(RA,Dec):     257.34767     -36.28015 deg
ZO SKY(X,Y):      3731.31       5039.05
ZO DETX,DETY      5105.07       4163.99

In this example we see that the input RA,Dec values have been used for the zeroth order position: ZO(RA,Dec), and that the rest of the coordinates including the RA,Dec are for the dispersed location for the HEG, order=1, energy=2.211 keV events.

Example 13

unix% dmcoords acisf14661_001N002_evt1.fits.gz \
op=sky x=3731.30 y=5039.07 \
grating=meg order=1 energy="" ra_zo=257.28179 dec_zo=-36.40712 \
celfmt=deg verb=1

Compute dispersed energy for grating coordinates

This is similar to the previous example but instead we want to identify what dispersed energy events are imaged at an input location. In this example the zero order is explicitly specified using the ra_zo and dec_zo parameters. We also explicitly set the grating=MEG and order=1. The energy parameter is set to a blank string, eg "", as that is the quantity we are looking to determine. Lastly we specify the sky coordinate we are interested in using the x and y parameters. The output looks like

----------------------------------------
Spacecraft Configuration:
----------------------------------------
Dataset:           acisf14661_001N002_evt1.fits.gz
Observatory:         
Telescope:        CHANDRA
Grating:          MEG
Instrument:       ACIS
Detector:         ACIS
Chip:             ACIS-S4
SIM position:         -0.683     0.000  -185.255    
SIM offset:            0.000    -0.882    -0.894   
SIM rotation:         -0.004     0.000     0.000   
Grating order: 1
Focal length:     10070.000000
Chip pixel scale: 0.023987 x 0.023987 mm/pixel
Chip size:        1024 x 1024 pixels

----------------------------------------
Sky Coordinate Configuration:
----------------------------------------
Sky coordinate pixel system: FP-1.1
Center pixel of sky plane:  (4096.500000,4096.500000)
Size of sky plane:          8192 x 8192
Sky pixel scale:            0.492000 arcsec/pixel
Nominal:          RA 257.285758 Dec -36.408981 Roll   0.000000
Aspect:           RA 257.285758 Dec -36.408981 Roll 252.649293

  --------  

(RA,Dec):    17:09:23.441     -36:16:48.53   
(RA,Dec):       257.34767     -36.28015 deg
THETA,PHI          8.289'          3.83 deg
(Logical):        3731.30       5039.07
SKY(X,Y):         3731.30       5039.07
DETX,DETY         5105.09       4163.99
CHIP ACIS-S4       152.00        223.00
TDET              5111.00       1925.00
GDPX,GDPY        36463.00      17042.80
GAC R,D          0.158042    -0.0281604 deg
ENERGY           1.123178 keV
ZO(RA,Dec):  17:09:07.629     -36:24:25.63   
ZO(RA,Dec):     257.28179     -36.40712 deg
ZO SKY(X,Y):      4119.87       4110.12
ZO DETX,DETY      4102.53       4070.14

In this example we see that now we have started with sky (x,y)=(3731.30,5039.07) and have computed the other standard coordinates (celestial RA/Dec, chip, det, tdet, etc). Since we also specified the zeroth order location (ra_zo, dec_zo), dmcoords has also computed the grating coordinates including the ENERGY and GAC (Grating Angular Coordinates: aka tg_r,tg_d).

We can retrieve the dispersed energy using pget

unix% pget dmcoords energy
1.123178 

This value make sense since we changed from the HEG in the previous example to the MEG in this example.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input dataset/block specification

dmcoords uses the file header to initialize the configuration. You can enter 'none' and set up the configuration from the parameters.

Parameter=asolfile (file not required filetype=input default=none stacks=yes)

Input aspect solution file

dmcoords uses the aspect solution file(s) to get the aspect and sim offsets by calculating the mean of the dy column, the dz column, and the dtheta column. The asolfile parameter is ignored if the input file contains the DY_AVG, DZ_AVG, and DTH_AVG keywords.

The aspect solution is stored in the pcad*asol1.fits files for the observation. If there is more than one aspect solution file, enter all the files as a comma-separated list or stack.

Parameter=option (string)

Conversion option

Defines the coordinate system to start from, and it can have one of the following values:

Parameter=chip_id (integer min=0 max=9)

Chip ID number

The chip ID number; for ACIS, this lies between 0 and 9, for HRC between 0 and 3. Can be input or output.

Parameter=chipx (real units=pixels)

Chip X [pixel]

The chip X pixel coordinate. See the CXC Coordinates papers for definitions. Can be input or output.

Parameter=chipy (real units=pixels)

Chip Y [pixel]

The chip Y pixel coordinate. See the CXC Coordinates papers for definitions. Can be input or output.

Parameter=tdetx (real units=pixels)

TDETX [pixel]

The tiled detector X pixel coordinate. See the CXC Coordinates papers for definitions. Gives position on a fictitous plane on which each chip of the instrument is flattened out. Output only.

Parameter=tdety (real units=pixels)

TDETY [pixel]

The tiled detector Y pixel coordinate. See the CXC Coordinates papers for definitions. Gives position on a fictitous plane on which each chip of the instrument is flattened out. Output only.

Parameter=detx (real units=pixels)

FPC X [pixel]

The focal plane X pixel coordinate. See the CXC Coordinates papers for definitions. Gives position on the tangent plane to the mirror optical axis. Pixel size is fixed in angular size. Center of the image plane is the mirror axis. Can be input or output.

Parameter=dety (real units=pixels)

FPC Y [pixel]

The focal plane Y pixel coordinate. See the CXC Coordinates papers for definitions. Gives position on the tangent plane to the mirror optical axis. Pixel size is fixed in angular size. Center of the image plane is the mirror axis. Can be input or output.

Parameter=x (real units=pixels)

Sky X [pixel]

The sky plane X pixel coordinate. See the CXC Coordinates papers for definitions. Gives position on the tangent plane to the nominal celestial pointing direction. Pixel size is fixed in angular size. Center of the image plane is RA_NOM, DEC_NOM. Can be input or output.

Parameter=y (real units=pixels)

Sky Y [pixel]

The sky plane Y pixel coordinate. See the CXC Coordinates papers for definitions. Gives position on the tangent plane to the nominal celestial pointing direction. Pixel size is fixed in angular size. Center of the image plane is RA_NOM, DEC_NOM. Can be input or output.

Parameter=logicalx (real units=pixels)

X coordinate in binned image [pixel]

The sky plane logical X pixel coordinate, for a binned image. If you took the event list and binned by a factor of 32, say, then original sky pixels 1 to 8192 correspond to logical pixels 1 to 256. Can be input or output.

Parameter=logicaly (real units=pixels)

Y coordinate in binned image [pixel]

The sky plane logical Y pixel coordinate, for a binned image. If you took the event list and binned by a factor of 32, say, then original sky pixels 1 to 8192 correspond to logical pixels 1 to 256. Can be input or output.

Parameter=ra (string)

RA [deg or hh:mm:ss]

RA and Dec are the right ascension and declination corresponding to sky pixels X,Y. This is ra in sexagesimal format (if celfmt=hms) or in degrees (if celfmt=deg). Can be input or output.

Parameter=dec (string)

Dec [deg or dd:mm:ss]

RA and Dec are the right ascension and declination corresponding to sky pixels X,Y. If the celfmt parameter is `hms' use sexagesimal format, for example "06:23:11.21"; if the celfmt parameter is `deg' use decimal degrees, for example "95.79671". Can be input or output.

Parameter=theta (real min=0 max=10800 units=arcmin)

Off axis angle [arcmin]

The off axis angle coordinate in arcmin. See the CXC Coordinates papers for definitions. Can be input or output.

Parameter=phi (real min=0 max=360 units=degrees)

Azimuthal angle [deg]

The mirror spherical coordinate azimuth in degrees. See the CXC Coordinates papers for definitions. Theta and phi are polar coordinates whose tangent plane is given by detx and dety. Can be input or output.

Parameter=order (integer default=0)

Grating order

The grating order, which is zero or a positive or negative integer.

Parameter=energy (real default=1.0 units=keV)

Energy [keV]

The energy in keV. It is only relevant for grating observations.

Parameter=wavelength (real default=0 units=Angstrom)

Wavelength [A]

The wavelength in Angstroms. It is only relevant for grating observations.

Parameter=ra_zo (string)

RA of zero order

The RA of the zero order image, for grating observations.

Parameter=dec_zo (string)

Dec of zero order

The Dec of the zero order image, for grating observations.

Parameter=celfmt (string default=hms)

RA and Dec format [deg or hms] (xx.xx or xx:xx:xx.x)

Are celestial positions formatted in sexagesimal (hms) or decimal degrees (deg).

Parameter=detector (string)

Detector (ACIS or HRC-I or HRC-S)

If present, overrides the INSTRUME keyword in the input file.

Parameter=grating (string)

Grating

The grating name: allowed options are NONE, LEG, HEG, and MEG. LETG can be used as an alias for LEG and HETG is an alias for HEG. If present, overrides the GRATING keyword in the input file.

Parameter=fpsys (string)

FP convention

Focal plane coordinate system: ASC-FP-1.1 for ACIS; ASC-FP-2.1 for HRC. The by default, the ACIS focal plane system will be used. The HRC focal plane system must be specified if the infile is omitted. Users can also use the aimpoint names: "AI1", "AI2", and "AS1" for ACIS, and "HI1", "HS1" and "HS2" for HRC.

See the CIAO/CXC coordinates papers for more detail.

Parameter=sim (string)

SIM position (eg 0.0 0.0 -190.6)

The optical bench (SIM) position (in X,Y,Z), three real values separated by spaces. e.g. "0.0 0.0 -190.1". Overrides the SIM_X SIM_Y SIM_Z header values in the input file.

If an aspect solution file is supplied, the "sim" and "displace" values get added to the values obtained from the aspect solution file.

Parameter=displace (string)

STF displacement (X,Y,Z,AX,AY,AZ)

Optical bench misalignment, six space-separated real values corresponding to a translation and rotation of the STF origin with respect to the FC origin. For expert users only.

If an aspect solution file is supplied, the "sim" and "displace" values get added to the values obtained from the aspect solution file.

Parameter=ra_nom (string)

Nominal pointing RA [deg or hh:mm:ss]

Nominal pointing direction, in format specified by celfmt. This overrides the input file RA_NOM keyword.

Parameter=dec_nom (string)

Nominal dec [deg or dd:mm:ss]

Nominal pointing direction, in the format specified by celfmt. This overrides the input file DEC_NOM keyword.

Parameter=roll_nom (string units=degrees)

Nominal roll [deg]

Nominal roll angle, in degrees. This overrides the input file ROLL_NOM keyword.

Parameter=ra_asp (string)

Instantaneous pointing RA [deg]

Instantaneous pointing direction, in the format specified by celfmt. If not set, then the RA_PNT header keyword is used, with RA_NOM used if the former does not exist.

Parameter=dec_asp (string)

Instantaneous pointing Dec [deg]

Instantaneous pointing direction, in the format specified by celfmt. If not set, then the DEC_PNT header keyword is used, with DEC_NOM used if the former does not exist.

Parameter=roll_asp (string units=degrees)

Instantaneous Aspect roll [deg]

Instantaneous roll angle, in degrees. If not set, then the ROLL_PNT header keyword is used, with ROLL_NOM used if the former does not exist.

Parameter=geompar (file default=geom)

Parameter file for Pixlib Geometry files

Parameter=verbose (integer default=0 min=0 max=5)

Debug Level

Verbose can be from 0 to 5, generating different amounts of debugging output. Remember to set verbose=1 if you want to see the standard information. A setting of verbose=0 can be useful for scripts, when the parameter file is used to access the calulated values, using pget.

Note that the default value for verbose is 0, rather than the usual value of 1 used for most CIAO tools.

Supported formats for sexagesimal notation

The following tables show the various formats that are supported by dmcoords for the RA and Declination arguments, either when given as parameters or from within the program when using the interactive mode. When writing out values the colon-separated form is used.

Supported RA formats when celfmt=hms

Supported Declination formats when celfmt=hms

Setting the instrument configuration

The coordinate conversion depends upon the instrument configuration of Chandra (for instance, which instrument is in the focal plane). If you already have data for an observation then this information is available in the header of the event file (and files created from this one, such as images) and you can use the infile parameter to point to such a file.

However, if you do not have such a file (for instance you are planning an observation and want to know whether a particular source will fall on a chip) then you can set the various values using either the configuration parameters (detector, grating, fpsys, sim, displace, ra_nom, dec_nom, roll_nom, ra_asp, dec_asp, and roll_asp), or the SET command if in interactive mode. Note that settting the values in this manner overrides the values read in from the configuration file (i.e. the infile parameter). One time that this comes in handy is when you want to use a different aspect solution, as described in the "Coordinate conversions and the aspect solution" section below.

Coordinate conversions and the aspect solution

Most of the coordinate conversions (e.g. SKY to CHIP) depend upon the aspect solution; that is the conversion is time dependent due to the dither performed by Chandra during an observation. The dmcoords tool will perform the conversion using a single (ie instantaneous) aspect solution. Unless otherwise specified (i.e. using either the ra_asp, dec_asp, and roll_asp parameters or the SET ASPECT command) the nominal aspect solution from the configuration file is used, as given by the RA_PNT, DEC_PNT, and ROLL_PNT keywords (the *_NOM version is used if the *_PNT version is not defined).

Accounting for telescope drift

The conversion between CHIP and SKY coordinates requires accurate knowledge of the drifts of the telescope support structure relative to the detector. These drifts were negligible at the start of the mission but have now grown large enough - of order 10 arcseconds - that they must be accounted for. If the input file contains the DY_AVG, DZ_AVG, and DTH_AVG keywords, then the dmcoords tool will use them and the aspect solution need not be given (the default value of none can be used for the asolfile parameter). This can be seen by using the STATUS command and seeing if the SIM offset and rotation values include non-zero values - such as shown below:

SIM offset:            0.000    -0.474    -0.547
SIM rotation:         -0.001     0.000     0.000

For data processed before the Repro 4 run in the Chandra Data Archive, these values will be reported as

SIM offset:            0.000     0.000     0.000
SIM rotation:          0.000     0.000     0.000

and the aspect solution should be specified using the asolfile parameter.

The default dither values

Note that the default amplitudes of the Chandra dither motion are 16 and 40 arcseconds for ACIS and HRC observations respectively. The actual aspect solution information for a given observation is stored in the set of pcad*asol1.fits files.

Combining SIM displacment and aspect solution

When running dmcoords in parameter mode, the "sim" and "displace" values get added to the values obtained from the aspect solution file. If

Set SIM/DISPLACE [x y z ax ay az]

is used in interactive mode, however, those values are taken as absolute, even if an aspect solution file was specified.

Bugs

Incorrect values from CAR transform.

The WCS library that the DM uses has a problem computing coordinate transforms that involve the CAR transform.

Caveats

dmcoords does not work correctly on the ACIS blank-sky background files

The pointing (PNT) header keyword values in the background files are set to zero:

unix% dmlist bgevt2_c7.fits header |grep PNT
0058 RA_PNT                                  0           Real8        Pointing RA
0059 DEC_PNT                                 0           Real8        Pointing Dec
0060 ROLL_PNT                                0 [deg]     Real8        Roll (fake)

These values indicate where the optical axis was during the observation. Having zero-values will cause the CIAO tool dmcoords to produce incorrect results when run with the background file.

Workaround:

Follow the workaround in the The ACIS "Blank-Sky" Background Files thread to update the PNT header keyword values.

Switching between celfmt=deg and celfmt=hms can lead to a misleading error message.

When switching between using celfmt=hms to celfmt=deg, dmcoords may already have some RA/Dec values set: ra, dec, ra_zo, dec_zo, etc. Unless these parameters are explicitly set to a blank string, the tool will complain about an "Invalid entry" and will prompt for a new value.

unix% punlearn dmcoords
unix% dmcoords /export/byobsid/635/repro/acisf00635_repro_evt2.fits asol= op=sky x=4096 y=4096
unix% pget dmcoords ra dec
16:27:17.957
-24:34:24.40
unix% dmcoords /export/byobsid/635/repro/acisf00635_repro_evt2.fits asol= op=sky x=4096 y=4096 celfmt=deg
Invalid entry '16:27:17.957' - try again!
ra_zo[ deg ] : 

Workaround:

To work around the problem, simply

% punlearn dmcoords

between uses.

See Also

concept

subspace

dm

dm, dmascii, dmfiltering, dmopt

tools

aconvolve, acrosscorr, arestore, arfcorr, dmcoords, dmcopy, dmextract, dmfilth, dmlist, dmregrid, dmstat, install_marx, make_psf_asymmetry_region, psf_project_ray, psfsize_srcs, simulate_psf, src_psffrac