NAME

wtraxy v2.3 -- Transform an X,Y position from input to output pixel position using the same conventions as drizzle -- with WCS and list support

USAGE

wtraxy xin yin

PARAMETERS

xin = [real]

The X pixel position in an input frame to be transformed.

yin = [real]

The Y pixel position in an input frame to be transformed.

(xylist = "") [file name]

A free-format list of X,Y positions to be converted. Each line of this file must have just an X and Y pixel position value, separated by white-space. If a file is specified the values of xin and yin are ignored. No comments or empty lines are permitted in this file.

(nxin = 800) [real]

The X dimension of the input image (this is used to determine the centre which is the origin of the transformations).

(nyin = 800) [real]

The Y dimension of the input image (this is used to determine the centre which is the origin of the transformations).

(nxout = 800) [real]

The X dimension of the output image (this is used to determine the centre which is the origin of the transformations).

(nyout = 800) [real]

The Y dimension of the output image (this is used to determine the centre which is the origin of the transformations).

(scale = 1.0) [real]

Linear size of output pixels in terms of input pixels. A scale of 0.5 means a magnification of two from input to output.

(xsh = 0.0) [real]

A shift in X to be applied to the input position after the geometric transform. This shift may be defined either in the input or output frame, according to the value of the "shft_fr" parameter. Shifts are always along the axes of the image. Positive values shift the image to the right. Units are determined by the "shft_un" parameter.

(ysh = 0.0) [real]

A shift in Y to be applied to the input position after the geometric transform. This shift may be defined either in the input or output frame, according to the value of the "shft_fr" parameter. Shifts are always along the axes of the image. Positive values shift the image upwards. Units are determined by the "shft_un" parameter.

(rot = 0.0) [real]

The rotation in degrees anti-clockwise to be applied to the input image after the non-linear part of the transform has been performed. Whether or not the rotation is applied after or before the shifts is determined by the value of the "shft_fr" parameter.

(coeffs = "") [file name]

The name of a text file containing the coefficients for the geometrical transformation to be applied. These geometric transformations are always applied before the shifts, rotations and scale changes specified by other parameters.

(shft_un = "input") [string]

Whether the shifts are specified in units of "input" or "output" pixels.

(shft_fr = "input") [string]

The frame in which the shifts are applied, or to put it another way, whether to apply the rotation before the shifts. If "output" the input image center is mapped to the center of the output grid, rotated about that center and then shifted along the grid of the output image. If "input" then the input image center is mapped to the center of the output image, shifted along the grid of the output image and then rotated about the center of the output image. See notes below for a definition of the center of rotation.

(xgeoim = "") [file name]

The name of an additional distortion correction image, in the X-direction. This is a real array, the same size as the input image, which represents an additional shift in the X direction which is applied after the polynomial distortion coefficients but before the linear transformation.

(ygeoim = "") [file name]

The name of an additional distortion correction image, in the Y-direction. This is a real array, the same size as the input image, which represents an additional shift in the Y direction which is applied after the polynomial distortion coefficients but before the linear transformation.

(align = "center") [string]

Whether the reference point used in transforming the input image coordinates to the output ones is aligned on the corner or center of a pixel. If the task is being used to mimic shift-and-add this should be set to "corner" otherwise, and particularly when performing interlacing, it should be set to "center". More details of the definition of the image centers are given below.

(lambda = 555.0) [real]

The wavelength (in nm) associated with the image. This is used for the "Trauger" style coefficients for which the distortion is a weak function of wavelength. It is only relevant for WFPC2 and is otherwise ignored.

(silent = no) [boolean]

Whether to run silently. If this is set to yes then the conversion is done silently, no output is written to the screen but the task parameters xout and yout are set and can be accessed by a subsequent task.

(geomode = user) [user|wcs]

The mode for determining the geometric transformation. There are two possibilities: geomode=user means that wtraxy works just like traxy and performs a direct transformation based on the coefficients and linear transformation parameters (xsh,ysh etc). If geomode=wcs then the transformation is determined by the World Coordinate Systems (WCS) of the input and output images, either explicitly specified for the output using the parameters given below, or from the header of images.

(refim = "") [file name]

The name of the reference output image from which the WCS is to be read in the case that geomode=wcs. The keywords CRVAL1/2 and CRPIX1/2 and CD1/2_1/2 are required to be present.

(refpref = "") [string]

An optional prefix which is prepended to the names of the WCS keywords in the header of the reference image. This allows keyword copies such as OCD1_1 to accessed but is not normally needed.

(inimage = "") [file name]

The name of the input image from which the WCS is to be read.

(outscl = 0.1) [double]

The output image scale in arcseconds/pixel for the case where geomode=wcs but there is no output reference image (refim="") to define the WCS.

(raref = 0.0) [double]

The Right Ascension in degrees of the output image reference point for the case where geomode=wcs but there is no output reference image (refim="") to define the WCS. This is equivalent to a CRVAL1 value.

(decref = 0.0) [double]

The Declination in degrees of the output image reference point for the case where geomode=wcs but there is no output reference image (refim="") to define the WCS. This is equivalent to a CRVAL2 value.

(xrefpix = 0.0) [double]

The X reference pixel position corresponding to raref,decref for the case where geomode=wcs but there is no output reference image (refim="") to define the WCS. This is equivalent to a CRPIX1 value.

(yrefpix = 0.0) [double]

The Y reference pixel position corresponding to raref,decref for the case where geomode=wcs but there is no output reference image (refim="") to define the WCS. This is equivalent to a CRPIX2 value.

(orient = 0.0) [double]

The orientation, expressed as the PA of the Y-axis of the output, in degrees from North through East, for the case where geomode=wcs but there is no output reference image (refim="") to define the WCS.

DESCRIPTION

This task transforms an X,Y position, assumed to be on an input virtual image of size nxin,nyin, onto a virtual output image of size nxout,nyout using the conventions of the drizzle task. So, if an object on an input image at a certain position is drizzled with a given set of parameters then the position of that object on the output can be predicted using traxy with the same parameter values. The inverse transformation can be accomplished using the companion task tranback.

This version (wtraxy) also supports mapping of positions using world coordinate systems rather than direct linear transformations. In this case the mapping can either be defined by giving and input and output image name (inimage and refim) or by giving an input image (inimage) and defining an output WCS using the outscl,raref,decref,xrefpix,yrefpix and orient parameters.

This version also supports transformation of lists of positions given in a text file. In this case (xylist != "") the xin,yin parameters are ignored.

IMPORTANT NOTE ON SECONDARY PARAMETERS

Versions of Traxy from V1.0 also use the "secondary geometric parameters" which are held in the pset dr2gpar. These allow for the possibility of an additional transformation after the standard geometrical distortion correction and linear transformation have been applied. More details of the use and value of this feature are given in the help file for drizzle which should be consulted. Note that these parameters may be inspected and modified using "epar dr2gpar" - they are not accessible from the traxy parameter list.

Users are warned to check the values of the parameters in this pset! If they are set they will be used and a warning message issued but they can easily be forgotten and hence lead to curious results.

EXAMPLES

If a star is at the position 123,456 on an input (800x800) WFPC2 image
where will it end up on an output drizzled image?

First the parameters of the wtraxy task are set to match those used by
drizzle then:

cl> wtraxy 123 456 
+ WTRAXY Version 2.3 (12th April 2004)
-Opening coefficients file: drizzle$coeffs/wf3-trauger
 Xin,Yin:  123.00000 456.00000  Xout,Yout:    542.64987  1071.76303

TIMINGS

It is, as one would expect, very quick!

SEE ALSO

drizzle, blot, wtranback