dmcoords

Synopsis

Convert between Chandra coordinate systems

dmcoords infile asolfile [options]

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.

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 below.

Coordinate conversions and the aspect solution

Most of the coordinate conversions (e.g. SKY to CHIP) depend upon the aspect solution. This means that 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_NOM, DEC_NOM, and ROLL_NOM keywords.

The aspect solution file must be provided so that an accurate chip to sky conversion can be calculated. dmcoords does not automatically take into account drifts in the Chandra geometry when calculating sky coordinates. These drifts were negligible near the beginning of the mission, but have grown to the order of 10 arcseconds and so cannot be neglected.

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.

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:

   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.

Example 1

dmcoords acis.fits
asolfile="pcadf075214790N002_asol1.fits,pcadf075249320N002_asol1.fits"
option=cel ra=06:23:41 dec=-00:02:31 verbose=1
dmcoords acis.fits
asolfile="pcadf075214790N002_asol1.fits,pcadf075249320N002_asol1.fits"
option=cel celfmt=deg ra=95.92083 dec=-0.04194 verbose=1

These two equivalent uses read the header of acis.fits and print out (and write to the parameter file) values of sky, detector and chip coordinates corresponding to the given position. The celfmt paramer controls the format used (sexagesimal or degrees-hms/deg).

There are two aspect solution files for this observation, so they are entered as a comma-separated list.

The pget command can be used to access the values of the transformation. For example, to get the x value of the sky coordinate system:

   unix% pget dmcoords x

Example 2

dmcoords acis.fits asolfile=pcadf052378346N002_asol1.fits opt=chip
chip_id=7 chipx=963.0 chipy=512.0

This takes a chip position (including the number of the chip) and calculates the location in the other coordinate systems.

Example 3

dmcoords acis.fits asolfile=pcadf052378346N002_asol1.fits

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.

To repeat the calculation from example 2, one would enter:

   dmcoords:> set chip acis-7
   dmcoords:> chip 963 512

Example 4

dmcoords sim.fits asol=""
dmcoords>: set SIM/DISPLACE 0 -0.094 -0.239 0 0 0

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:

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 5

dmcoords none 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

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

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input file, or dm defined virtual file

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

Parameter=asolfile (file required filetype=input stacks=yes)

Aspect solution file(s)

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 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 (see "ahelp stack").

Parameter=option (string)

Which coordinate system to start from (cel/sky/det/chip/logical/msc).

The option parameter can have one of the following values:

• cel: specifies that ra and dec are the parameters given on input. The format assumed for ra and dec is specified by the celfmt parameter, see below.
• sky: the input parameters are x and y, the sky pixel coordinate values (`physical' coordinates in the language of ds9 if you have made a sky image).
• det: the input parameters are detx and dety, the focal plane pixel coordinate values.
• chip: the input parameters are chip_id, chipx and chipy.
• logical: the input parameters are image logical coordinates, i.e. the binned sky pixel coordinates. Only relevant if the input file is an image rather than an event list.
• msc: the input parameters are mirror spherical coordinates; theta is the off axis angle in arcmin and phi is the azimuth in degrees.

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

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)

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

Parameter=chipy (real units=pixels)

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

Parameter=tdetx (real units=pixels)

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)

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)

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)

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)

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)

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)

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)

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 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)

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)

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)

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)

The grating order, zero or positive or negative integer.

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

The energy in keV. Only relevant for grating observations.

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

The wavelength in Angstroms. Only relevant for grating observations.

Parameter=ra_zo (string)

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

Parameter=dec_zo (string)

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

Parameter=celfmt (string default=hms)

Celestial position format (hms/deg) i.e. sexagesimal or decimal-degree formats will be used for the RA,dec parameter pairs.

Parameter=detector (string)

Detector name (ACIS/HRC-I/HRC-S). If present, overrides the INSTRUME keyword in the input file.

Parameter=grating (string)

Grating name (NONE/LETG/HETG). If present, overrides the GRATING keyword in the input file.

Parameter=fpsys (string)

Focal plane coordinate system. ASC-FP-1.1 for ACIS; ASC-FP-2.1 for HRC. But see coordinates papers for more detail.

Parameter=sim (string)

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)

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 direction, in format specified by celfmt. This overrides the input file RA_NOM keyword.

Parameter=dec_nom (string)

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

Parameter=roll_nom (string units=degrees)

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

Parameter=ra_asp (string)

Instantaneous pointing direction, in format specifies by celfmt. If omitted, ra_nom is used.

Parameter=dec_asp (string)

Instantaneous pointing direction, in format specifies by celfmt. If omitted, dec_nom is used.

Parameter=roll_asp (string units=degrees)

Instantaneous roll angle, in degrees. Overrides the roll_nom parameter.

Parameter=geompar (file default=geom)

The name of the Pixlib Geometry parameter file.

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

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.

Changes in CIAO 4.4

• A tolerance check was added to the RA_NOM and DEC_NOM comparisons to improve the accuracy of the WCS comparison.

• The limits of the chip_id parameter are explicitly included in the parameter file (min=0, max=9).

Bugs

Incorrect values from CAR transform.  (08 Oct 2012)

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

Incorrect azimuth and off-axis angle for HRC event files

A keyword was dropped when filtering columns from HRC evt2 files in the pre-CIAO 3.0 data model. This causes dmcoords to not have correct knowledge of the aspect solution; the tool therefore computes an incorrect zero point for the azimuth (phi) and off-axis angle (theta).

Workaround:

Use dmstat to get the DETX,DETY values:

unix% dmstat "evt2[sky=region(reg)][cols det]"

and then use dmcoords to convert these to theta and phi values.

Caveats

dmcoords does not work correctly on the ACIS blank-sky background files  (28 Jan 2010)

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.

See Also

concept

subspace

dm

dm, dmascii, dmfiltering, dmopt

tools

aconvolve, acrosscorr, arestore, arfcorr, dmcopy, dmextract, dmfilth, dmlist, dmregrid, dmstat, make_psf_asymmetry_region, mkpsf, psf_project_ray