Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: December 2014

URL: http://cxc.harvard.edu/ciao/ahelp/wcs_update.html
AHELP for CIAO 4.9

wcs_update

Context: tools

Synopsis

Modify aspect solution file RA and Dec or infile WCS based on a transformation matrix.

Syntax

wcs_update  infile outfile transformfile [wcsfile] [logfile] [deltax]
[deltay] [rotang] [scalefac] [clobber] [verbose]

Description

wcs_update implements the frame transformation identified in the six element transformation matrix specified in transformfile, typically calculated by wcs_match. Either an aspect solution file or a FITS image or table file with a WCS can be updated. The asol file aspect solution or the FITS image or table file WCS tangent point should be in the same general region of the sky as the tangent point of the WCS from the transform file.

If the infile is an aspect solution file, changes are applied to the input RA, Dec, and roll columns and a new aspect solution file (outfile) is output with these columns modified. If the infile contains an image or table with a WCS ("EQPOS" or "EQSRC"), changes are applied to the WCS elements within the same file.

wcs_update implements the transformation file data by calculating four equivalent parameters to use to update the outfile; two translational, one rotational, and one scaling parameter. It is possible to input values for these four parameters directly (deltax, deltay, rotang, scale), in which case the transform file must be left blank. A wcsfile must then be specified, containing a WCS with a tangent point about which the four parameters can be applied.

Example 1

wcs_update infile=asol.fits transformfile=xfm.fits
outfile=new_asol.fits clobber=yes

Update RA, Dec and roll from asol.fits with data from transformation matrix in xfm.fits, and write output to new_asol.fits. Overwrite new_asol.fits, if it exists.

Example 2

wcs_update infile=image.fits transformfile=xfm.fits outfile=""

Update WCS in image.fits with data from transformation matrix in xfm.fits. image.fits is updated directly (i.e., no separate output file is created).

Example 3

wcs_update infile=sources.fits wcsfile=image.fits deltax=0.5 deltay=0.5
rotang=0.02 scale=1.001 outfile=""

Update WCS in sources.fits with input parameters. Apply a 0.5 sky pixel offset in the x direction, a 0.5 sky pixel offset in the y direction, a 0.02 degree rotation and a scale factor of 1.001. The x and y directions and scale factor are defined in the WCS from image.fits, and the rotation is applied about the WCS tangent point.

Parameters

name type ftype def min max units reqd
infile file input         yes
outfile file output         yes
transformfile file output         yes
wcsfile file input         no
logfile file output STDOUT       no
deltax real input 0     sky pixels no
deltay real input 0     sky pixels no
rotang real input 0     degrees no
scalefac real input 1.0       no
clobber boolean input no       no
verbose integer input 0 0 5   no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input file to be updated, either asol or FITS image or table.

If this input file is an asol file, update the RA, Dec., and roll columns of each row and write the output to outfile. If this input file is either a FITS image or table, update the WCS directly in this file.

The tool also updates keyword pairs: RA_NOM & DEC_NOM and RA_PNT & DEC_PNT.

Parameter=outfile (file required filetype=output)

Output aspect solution file.

This file is created when the input file is an aspect solution file. All data are copied from the aspect solution file and the RA, Dec, and roll are modified by values extracted from the transform. If the input file is not an aspect solution file, outfile must still be specified but is not used and can be blank.

Parameter=transformfile (file required filetype=output)

File containing transform matrix element data.

This file is contains the six elements of the transform matrix and WCS information used in calculating the transform. It must be specified unless individual update parameters are input (deltax, etc.).

Parameter=wcsfile (file not required filetype=input)

World Coordinate System (WCS) file.

The WCS file is only required when individual update parameters are input (delta_x, etc.). This file can be either a FITS image with WCS "EQPOS", or a FITS table with WCS "EQPOS" or "EQSRC".

Parameter=logfile (file not required filetype=output default=STDOUT)

Debug log file.

Allowable values are either a filename - to send the output to a given file - or one of stdout or STDOUT, which sends the information to the standard output (normally the screen).

Parameter=deltax (real not required filetype=input default=0 units=sky pixels)

Transform x offset

This value will be used to update WCS x direction in the input file, or RA, Dec., equivalent in the case of an input aspect solution file. transformfile must be left blank when this parameter is set, and wcsfile must be specified.

Parameter=deltay (real not required filetype=input default=0 units=sky pixels)

Transform y offset

This value will be used to update WCS y direction in the input file, or RA, Dec., equivalent in the case of an input aspect solution file. transformfile must be left blank when this parameter is set, and wcsfile must be specified.

Parameter=rotang (real not required filetype=input default=0 units=degrees)

Transform rotation angle

This value will be used to update WCS rotation in the input file or aspect roll in the aspect solution file. transformfile must be left blank when this parameter is set, and wcsfile must be specified.

Parameter=scalefac (real not required filetype=input default=1.0 units=)

Transform scale factor

This value will be used to update WCS scale factor. It is not used to update the aspect solution file. transformfile must be left blank when this parameter is set, and wcsfile must be specified.

Parameter=clobber (boolean not required filetype=input default=no)

Overwrite existing asol output dataset with same name?

Parameter=verbose (integer not required filetype=input default=0 min=0 max=5)

Level of debug detail.

Increasing amounts of debug information is printed to "logfile" as the value of verbose is increased from 0 to 5. Setting verbose=1 shows details of the source pair errors after applying the transform to the input source positions.

Changes in CIAO 4.9

  • Can now use be used to update an arbitrary FITS extension in the infile.

  • The quaternion values in the aspect solution file are now also updated.

  • Error message handling improvements.

Bugs

Quaternion values, q_att column, in aspect solution are not updated

The quaternion values in the aspect solution, the q_att array column, are not updated by wcs_update to match the modified values of the ra and dec columns.

SAOTrace, the offical Chandra mirror model simulator used by ChaRT uses the quaternion values. For ChaRT v2 simulations performed before 2016-06-10 where uses uploaded a wcs_update adjusted aspect solution file, the location of the PSF will not be adjusted for the astrometric shift. Typically this shift is very small, < 1 arcsec.

All the CIAO tools and MARX use the RA, Dec, & Roll values from the aspect solution rather than the quaternions.

The wcsfile parameter doesn't accept the virtual file syntax  (19 Aug 2011)
unix% pset wcs_update wcsfile="wcs.fits[bin sky=128]"

# wcs_update (CIAO): dsDMTABLEOPENERR -- ERROR: Failed to open a DM table in dataset ''. 
                         DM Error: '[dmi_block_parse_syntax]: null arguments'.
# wcs_update (CIAO): ERROR: Could not find WCS in wcsupdfile, and no separate wcsfile provided.

Workaround:

Copy the file before running wcs_update:

unix% dmcopy "wcs.fits[bin sky=128]" wcs.img
unix% pset wcs_update wcsfile=wcs.img

Caveats

The RA_PNT & DEC_PNT in the aspect solution files have shifted ~180 degrees.

The RA_NOM & DEC_NOM and the RA_PNT & DEC_PNT are always updated using the same matrix as the rest of the data in the file (RA & DEC columns or the event file's WCS).

For reasons beyond the scope of this bugs page, the aspect solution files use a different convention than the other Chandra files. In the aspect soluiton files, the RA_NOM & DEC_NOM keywords are the mean pointing of the telescope during the observation, where as in all the other data products, the RA_PNT & DEC_PNT are used for the mean pointing.

Thus in the aspect solution files, the RA_PNT and DEC_PNT keywords have no meaning, and have been both been set to 0.0.

Since tangent plane projections are only valid for the hemisphere in which the tangent point lies, when RA,DEC=(0,0) is used with some WCS parameters, it may end up being shifted approximately 180 degrees to land in the correct hemisphere as the tanget point.

CIAO tools never use the RA_PNT & DEC_PNT from the aspect solution files so the large shift in these values after applying wcs_update is irrelevant.

See Also

tools
reproject_aspect, reproject_events, sso_freeze, wcs_match

Last modified: December 2014
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.