This tool performs arbitrary coordinate transforms on an image, such as translations, rotations, etc. The transform is specified by a FITS file, usually created by the getxform or combinexform tools. These transforms are primarily linear "affine" transforms. However, there is some support for arbitrary non-linear transforms specified by a map.
The transformed image will have no WCS keywords. These may be written by the user with the getwcs or transform_wcs tools. The former is useful if you are transforming between two coordinates systems specified in a teldef file. The latter is useful if you want the transformed image to have the same world coordinates as the original image.
Note that except for the special case where the original and transformed pixel grids coincide, transforming an image will reduce its resolution. Therefore it is best to not apply sucessive transforms to an image. Instead use the "combinexform" tool to combine the transforms and then apply that to the original image.
For convenince there may be mission-dependant scripts which tie together the process of generating a transform, transforming an image and writing its WCS keywords. Check the documentation for your mission for more details.
The image to be transformed.
The transformed image. If imagetrans can create a new file with the given name it will write the image to the primary HDU. Otherwise it will append a new HDU to the named file.
The FITS file specifying the transform to apply to the data. This file is usually generated by the getxform or combinexform tools.
Some transform methods (e.g. interpolate) allow providing the inverse transform instead of the forward transform. Note that it is never necessary to set both this parameter and the "transform" parameter.
The name of the method used to transform the pixel values. For a general transform, the original pixels do not correspond exactly to the transformed pixels. Therefore assigning values to the transformed pixels is not as simple as copying values from the original image. Imagetrans can do the following methods:
"events" - This method mimics the effect of the "coordinator" tool on an event list. It assumes that the value of each pixel gives the number of events in that pixel. It then assigns random positions for each event within the pixel and transforms those positions to the new coordinate system. Then the events are binned into the pixels of the transformed image. If the pixel values are not integers, imagexform gives a warning and converts the values to integers in an arbitrary way.
This method preserves the total number of counts in the image, and guarantees that the transformed pixel values will all be integers. This method is best for "counts" images.
"interpolate" - This method linearly interpolates the input image. The interpolation scheme depends on a forward or inverse transform is provided. When using the inverse transform, for each pixel in the transformed image it calculates the position of the center of that pixel in the original image. It then linearly interpolates the original image to get the transformed pixel value.
When using the forward transform, for each pixel in the transformed the value at the center of that pixel is calculated using inverse distance weighting of the values of the nearest corresponding pixels in the input image. The alpha parameter specifies the exponent.
The output pixel values will not generally be integers, so it may be necessary to force the transformed image to be floating point by setting the bitpix parameter to -32 or -64.
This is a common technique for transforming terrestrial images, but the sum of the pixels is not preserved, so fluxes derived from the transformed image will be innacurate. This method requires the inverse transform, so it may be undesirable if it is difficult to invert your transform.
"center" - This method assumes the "stuff" in each pixel is concentrated at the center. For each pixel in the original image, it transforms the position of the pixel center and then adds the full pixel value to the corresponding pixel in the transformed image.
This method is fast to calculate, and it preserves the sum over pixels and the "integerness" of the original image. However, it produces artifacts when the original and transformed pixel grids do not coincide. So this method should only be used for something like a "flip" or a translation by an integer number of pixels.
"area" - This method treats the "stuff" in each pixel as being spread evenly throughout the pixel. It distributes the value of each original pixel among the tranformed pixels it covers proportionally by the fraction of overlapping area.
This method preserves the sum over pixels, so the transformed image can be used to calculate fluxes. However, the transformed pixels values will not be all integers. This may not be desirable if you are transforming a counts image. Note that it may be necessary to set the "bitpix" parameter to -32 or -64 to properly represent the transformed image.
The BITPIX value for the output image. If this is zero, then the output image will have the same bitpix as the input image. Otherwise this parameter can have any of the legal FITS values. This parameter is useful to force an output image to have floating point pixels if the input image is stored in integers. Note that transformed images stored in integers retain the same BZERO and BSCALE scaling as the original image. Floating point images tend to require more storage that integer valued pixels, but many of the transform methods will produce fractional pixel values even from an all-integer input image.
Output verbosity
The horizontal size of the output image in pixels. If this is set to "-1", then the output image will have the same size as the input image.
The vertical size of the output image in pixels. If this is set to "-1", then the output image will have the same size as the input image.
Write HISTORY keywords to output?
Random number generator seed for the events method. The events method will produce exactly the same results for a given seed every time it is run.
If this is true, then null pixels in the input image will be treated as zeros.
Exponent for inverse distance weighting with method=interpolate and a forward transform.
getxform, combinexform, getwcs, transform_wcs