NAME

imagexform - transform an image from one coordinate system to another

USAGE

imagexform infile=<filename> outfile=<filename>

DESCRIPTION

This tool transforms an image from one coordinate system to another. Both the original and transformed coordinate systems must be defined in a "teldef" calibration file.

For transforms to or from sky coordinates, imagexform uses the spacecraft attitude at the midpoint of the image exposure. The transformed image will be inaccurate if the spacecraft moved significantly during the exposure.

PARAMETERS

infile [filename]
Input image file and extension. Imagexform will assume the image is in the primary HDU if no extension is specified.

outfile [filename]
Output image file. If the output file exists, then imagexform will append the transformed image to it. Otherwise imagexform will create a new file and write the transfomed image to its primary HDU.

teldef [filename]
Telescope definition calibration file.

from [name]
Name of the coordinate system of the input image. Coordinate system names are as defined in the teldef file. They are three characters, all caps (e.g. "RAW", "DET", "SKY").

to [name]
Name of the coordinate system of the transformed image. See the description of the "from" parameter.

method [name]
The method used to transform the data. Two methods are available.

The "events" method is appropriate if the input image represents photon events. This method mimics the action of the coordinator tool. For each event, it chooses a random position of the event within its pixel and then determines the location of that event in the transformed image. This randomness eliminated artifacts due to the misalignment of the pixels in the two images. The transformed image will have the same total number of counts as the input image, unless some of the events fell outside the transformed image.

The "intensity" method is appropriate for other types of images (e.g. counts/s). For each pixel in the transformed image, it determines the corresponding pixel in the input image. The transformed pixel is assigned a value bi-linearly

The "center" method assigns the value of an input pixel to the output pixel containing the transformed input pixel center. If multiple input pixels are mapped to the same output pixel, their values are summed.

The "area" method distributes the value of the input pixel among the output pixels that are overlapped by the quadrilateral defined by transforming the corners of the input pixel. The input value is distributed according to the fractional overlap area.

from_offx [real]
The X offset in the input image between the first image pixel and the first pixel in the teldef cooridnate system. The offset is given in "unbinned" coordinates (i.e. those specified in the teldef file). This parameter may be used to specify "windowing" of the image.

from_offy [real]
The Y offset of the input image. See the description of the "from_offx" parameter.

to_offx [real]
The X offset of the transformed image. See the description of the "from_offx" parameter.

to_offy [real]
The Y offset of the transformed image. See the description of the "from_offx" parameter.

to_sizex [number]
The number of horizontal pixels in the output image. If this is negative, the output image will have the size of the coordinate system defined in the teldef file. Note that the image size is specified in binned coordinates.

to_sizey [number]
The number of vertical pixels in the output image. See the description of the "to_size_x" parameter.

binx [number]
The X binning factor of the images with respect to the coordinate system defined in the teldef file. For example, if there are two image pixels for every unit in the teldef coordinate system, then binx should be set to "2". If binx is zero or negative, it defaults to the value of the "IMGBIN" keyword in the input image, or to "1" if that keyword is missing.

biny [number]
The Y binning factor of the images with respect to the coordinate system defined in the teldef file. If biny is zero or negative, it defaults to the value of the binx parameter.

segment [string]
Detector segment number for multi-part detectors. This parameter is only used for RAW coordinates. If the parameter is a string, imagexform will try to read a keyword of that name from the input image to get the segment number. If it is a number, imagexform will use the given value. Note: all data are assumed to be on the same segment.

ra [real]
The right ascension at the center of the image in SKY coordinates. This parameter is only used when transforming to SKY coordinates. If transforming from SKY coordinates, the FITS WCS keywords are used to determine this value.

dec [real]
The declination at the center of the image in SKY coordinates. See the description of the "ra" parameter.

attfile [filename]
Attitude file name. This is used only when transforming to or from SKY coordinates. The attitude file gives a time history of the orientation of the spacecraft. Currently two formats are supported, quaternion-based FITS files (e.g. ASCA, Astro-E, Swift), or an ASCII whitespace-separated list of: time, R.A., Dec., and roll angle.

aberration [boolean]
If set to "yes", then aberration is taken into account in transformations to or from SKY coordinates. Aberration is the apparent shift in the positions of stars due to the motion of the observer. The dominant component of the motion is the Earth's orbital velocity around the Sun.

seed [number]
The seed for the random number generator used in the "events" method. See the description of the "method" parameter. A particular value of the seed will always generate the same series of random numbers.

copy_hdus [boolean]
If "yes", then imagexform will copy all the FITS extensions after the image into the output file. This is useful for retaining metadata like GTIs. If the inout file contains multiple images then copy_hdus should probably be set to "no".

(chatter = 1) [enumerated integer]
Standard HEAdas chatter parameter. A range of 0 to 5 is enforced by the min and max fields in the parameter file.

(history = yes) [boolean]
Standard HEAdas history parameter.

EXAMPLES

The following examples illustrate running imagexform

1. run imagexform prompting for options

      imagexform
2. run imagexform specifying parameters on the command line

      imagexform infile=IMAGE_RAW.fits outfile=IMAGE_SKY.fits \
		teldef=SAT_TELDEF.fits from=RAW to=SKY

SEE ALSO

LAST MODIFIED

June 2003