imagexform - transform an image from one coordinate system to another
imagexform infile=<filename> outfile=<filename>
This tool transforms an image from one coordinate system to another.
Both the original and transformed coordinate systems must be defined in a "teldef"
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.
- 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
The transformed image will have the same total number of counts as the
input image, unless some of the events fell outside the transformed
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"
- to_offx [real]
- The X offset of the transformed image. See the description of the "from_offx"
- to_offy [real]
- The Y offset of the transformed image. See the description of the "from_offx"
- 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
- 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
- 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
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
- (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.
The following examples illustrate running imagexform
1. run imagexform prompting for options
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