wcs_update

Synopsis

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

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.

Examples

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

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.

Bugs

Cannot use same file for infile and wcsfile

Users cannot use the same file for both the infile and the wcsfile parameters. Attempting to do so will cause the tool to quietly exit without making any updates to the infile.

See Also

tools::coordinates

reproject_aspect, reproject_events, sso_freeze, wcs_match