transform: Resample longslit spectra

Package: specred

Usage

transform input output fitnames

Parameters

input: List of input images to be transformed.

output: List of output images. The number of output images in the list must match the number of input images.

minput = "": List of input masks or references. This mask is used to create an output mask and is currently not used in the calculation of the output pixel values. The list may be empty, a single element to apply to all input images, or a list that matches the input list. A element in the list may be "BPM" to use the mask referenced by the standard bad pixel mask keyword "BPM", "!<keyword>" to use another header keyword pointing to a mask, or a mask filename. The mask file is typically a pixel list file but it may also be an image. The mask values are interpreted as zero and greater than zero with the actual values ignored. The mask is assumed to be registered with the input and no coordinate system matching is used. The mask maybe smaller or larger than the input image with non-overlapping pixels ignored and missing pixels assumed to be zero valued. The mask

moutput = "": List of output masks to be created. The list may be empty or must match the input list. Output masks may be specified even if no input mask is specified, in which case the output mask will identify pixels which map to regions outside the input images (also see the blank parameter). If an explicit extension is not specified a FITS mask is extension is created unless the environment variable "masktype" is set to "pl".

fitnames: Names of the user coordinate maps in the database to be used in the transform. If no names are specified, using the null string "", the world coordinate system (WCS) of the image is used. This latter case may be used to resample previously WCS calibrated images to a different linear range or sampling.

database = "database": Database containing the coordinate map to be used in transforming the images.

interptype = "spline3": Image interpolation type. The allowed types are "nearest" (nearest neighbor), "linear" (bilinear), "poly3" (bicubic polynomial), "poly5" (biquintic polynomial), and "spline3" (bicubic polynomial).

flux = yes: Conserve flux per pixel? If "no" then each output pixel is simply interpolated from the input image. If "yes" the interpolated output pixel value is multiplied by the Jacobean of the transformation (essentially the ratio of pixel areas between the output and input images).

x1 = INDEF, y1 = INDEF: User coordinates of the first output column and line. If INDEF then the smallest value corresponding to a pixel from the image used to create the coordinate map is used. These values are in user units regardless of whether logarithmic intervals are specified or not.

x2 = INDEF, y2 = INDEF: User coordinates of the last output column and line. If INDEF then the largest value corresponding to a pixel from the image used to create the coordinate map is used. These values are in user units regardless of whether logarithmic intervals are specified or not.

dx = INDEF, dy = INDEF: Output pixel intervals. If INDEF then the interval is set to yield the specified number of pixels. Note that for logarithmic intervals the interval must be specified as a base 10 logarithm (base 10) and not in user units.

nx = INDEF, ny = INDEF: Number of output pixels. If INDEF and if the pixel interval is also INDEF then the number of output pixels is equal to the number of input pixels.

xlog = no, ylog = no: Convert to logarithmic intervals? If "yes" the output pixel intervals are logarithmic.

blank = INDEF: Value to put in the output transformed image when it transforms to regions outside the input image. The special value INDEF will use the nearest input pixel which is the behavior before the addition of this parameter. Using special blank values allows other software to identify such out of input pixels. See also the moutput parameter to identify out of input pixels in pixel masks.

logfiles = "STDOUT,logfile": List of files in which to keep a log. If null, "", then no log is kept.

Description

The coordinate maps U(X,Y) and V(X,Y), created by the task fitcoords, are read from the specified database coordinate fits or from the world coordinate system (WCS) of the image. X and Y are the original untransformed pixel coordinates and U and V are the desired output user or world coordinates (i.e. slit position and wavelength). If a coordinate map for only one of the user coordinates is given then a one-to-one mapping is assumed for the other such that U=X or V=Y. The coordinate maps are inverted to obtain X(U,V) and Y(U,V) on an even subsampled grid of U and V over the desired output image coordinates. The X and Y at each output U and V used to interpolate from the input image are found by linear interpolation over this grid. X(U,V) and Y(U,V) are not determined at every output point because this is quite slow and is not necessary since the coordinate surfaces are relatively slowly varying over the subsampling (every 10th output point).

The type of image interpolation is selected by the user. Note that the more accurate the interpolator the longer the transformation time required. The parameter flux selects between direct image interpolation and a flux conserving interpolation. Flux conservation consists of multiplying the interpolated pixel value by the Jacobean of the transformation at that point. This is essentially the ratio of the pixel areas between the output and input images. Note that this is not exact since it is not an integral over the output pixel. However, it will be very close except when the output pixel size is much greater than the input pixel size. A log describing the image transformations may be kept or printed on the standard output.

The output coordinate grid may be defined by the user or allowed to default to an image of the same size as the input image spanning the full range of user coordinates in the coordinate transformation maps. When the coordinate maps are created by the task fitcoords the user coordinates at the corners of the image are recorded in the database. By default these values are used to set the limits of the output grid. If a pixel interval is not specified then an interval yielding the specified number of pixels is used. The default number of pixels is that of the input image. Note that if a pixel interval is specified then it takes precedence over the number of pixels.

The pixel intervals may also be logarithmic if the parameter xlog or ylog is "yes". Generally, the number of output pixels is specified in this case . However, if the interval is specified it must be a base 10 logarithmic interval and not in units of the x and y limits which are specified in user units.

The transformation from the desired output pixel to the input image may fall outside of the input image. In this case the output pixel may be set to the nearest pixel value in the input image or to a particular value using the blank parameter. Also if an output mask is created this pixels will have a value of one in the mask.

The parameters minput and moutput provide for input and output pixel masks. An input mask is not used in calculating the transformed pixel value but is used to identify the output pixels in the output mask which make a significant contribution to the interpolated value. The significance is determined as follows. The input mask values above zero are converted to one hundred. The mask is then interpolated in the same way as the input image. Any interpolated value of ten or greater is then given the value one in the output mask. This means if all the input pixels had mask values of zero a result of zero means no bad pixels were used. If all the input pixels had values of 100 then the result will be 100 and the output mask will flag this as a bad pixel. Other values are produced by a mixture of good and bad pixels weighted by the interpolation kernel. The choice of 10% is purely empirical and gives an approximate identification of significant affected pixels. zero and is created with values of 100

Examples

Arc calibration images were used to determine a two dimensional dispersion map called dispmap. Stellar spectra were used to determine a two dimensional distortion map call distort. These maps where made using the task fitcoords. To transform a set of input images into linear wavelength between 3800 and 6400 Angstroms (the user coordinate units) with a dispersion of 3 Angstroms per pixel:

cl> transform obj001,obj002 out001,out002 dispmap,distort \
>>> y1=3800 y2=6400 dy=3

To use logarithmic intervals in the wavelength to yield the same number of pixels in the output images as in the input images:

cl> transform obj001,obj002 out001,out002 dispmap,distort \
>>> y1=3800 y2=6400 ylog=yes

Timings

The following timings were obtained for transforming a 511x512 real image to another 511x512 real image using two Chebyshev transformation surface functions (one for the dispersion axis, "henear", and one in spatial axis, "object") of order 6 in both dimensions created with the task fitcoords. The times are for a UNIX/VAX 11/750.

cl> $transform input output henear,object interp=linear
TIME (transform)  173.73  5:13  55%
cl> $transform input output henear,object interp=poly3
TIME (transform)  266.63  9:17  42%
cl> $transform input output henear,object interp=spline3
TIME (transform)  309.05  6:11  83%
cl> $transform input output henear,object interp=spline3
TIME (transform)  444.13  9:44  76%
cl> $transform input output henear interp=linear
TIME (transform)  171.32  7:24  38%
cl> $transform input output henear interp=spline3
TIME (transform)  303.40  12:17  41%
cl> $transform input output henear,object interp=spline3 flux=no
TIME (transform)  262.42  10:42  40%

The majority of the time is due to the image interpolation and not evaluating the transformation functions as indicated by the last three examples.

Notes

TRANSFORM: V2.12.2: The use of bad pixel masks, a specified "blank" value, and use of a WCS to resample a WCS calibrated image was added.

TRANSFORM: V2.6: With Version 2.6 of IRAF the algorithm used to invert the user coordinate surfaces, U(X,Y) and V(X,Y) to X(U,V) and Y(U,V), has been changed. Previously surfaces of comparable order to the original surfaces were fit to a grid of points, i.e. (U(X,Y), V(X,Y), X) and (U(X,Y), V(X,Y), Y), with the same surface fitting routines used in fitcoords to obtain the input user coordinate surfaces. This method of inversion worked well in all cases in which reasonable distortions and dispersions were used. It was selected because it was relatively fast. However, it cannot be proved to work in all cases; in one instance in which an invalid surface was used the inversion was actually much poorer than expected. Therefore a more direct iterative inversion algorithm is now used. This is guaranteed to give the correct inversion to within a set error (0.05 of a pixel in X and Y). It is slightly slower than the previous algorithm but it is still not as major a factor as the image interpolation itself.