Space Telescope Science Institute
DrizzlePac 2012 Handbook
Table of Contents Previous Next Index Print

The DrizzlePac Handbook > Chapter 3: Astrometric Information in the Header > 3.3 Distortion Information in Pipeline Calibrated Images

ACS and WFC3 images retrieved from the HST Archive are processed via the 'On-The-Fly-Reprocessing' (OTFR) system that calibrates images using the best-available calibration file, including latest-available distortion correction models.
Calibrated science images from the HST Archive, with the suffix flt.fits, have undergone standard image reductions including flat fielding, but have not been corrected for geometric distortion. After the data calibration step in the pipeline, flt.fits images are processed by AstroDrizzle to produce drizzled images that are corrected for geometric distortion. If several images are part of an association, the images are drizzle-combined using pre-defined astrodrizzle settings stored in the MDRIZTAB reference file.
As described in the previous section, WCS information in flt.fits images are updated by AstroDrizzle in the pipeline to include the full distortion correction model:
Distortion correction polynomial function orders and coefficients from the IDCTAB are recorded as keyword values in the image header.
Optionally, any residual distortion corrections and detector corrections from the NPOLFILE and D2IMFILE reference files are appended to the science image as new FITS extensions of type WCSDVARR and D2IMARR, respectively.
Note: even though the IDCTAB and DGEOFILE reference files are no longer needed for post-pipeline reprocessing, these keywords have been retained in the new flt.fits files for users who prefer to process their images using MultiDrizzle. The new flt.fits files have been verified to be compatible with MultiDrizzle.
The figure below shows the new structure of an ACS/WFC image, generated by the IRAF command catfits:
Naming a Polynomial Distortion Solution
Polynomial distortion models for all HST images, which are used as the primary source of distortion information, are presented in the image headers using the SIP convention.
Some instrument modes, however, require additional distortion corrections. During pipeline processing, distortion correction information is obtained from reference files and stored in images as FITS extensions. For data processed in the OTFR pipeline, only ACS images require residual optical distortion corrections, stored in the image files as FITS extensions of type WCSDVAR. For ACS/WFC a correction for detector column width is also required, stored in image files as a FITS extension of type D2IMARR.
The name for a specific polynomial distortion model is recorded in the primary header of each image in a new keyword called SIPNAME. In the pipeline, the default distortion model is named after the image's rootname and its IDCTAB reference file. A name can also be assigned to this keyword by the user during post-pipeline processing. A value of 'N/A' or a blank string indicates that no SIP model was provided or applied. A value of UNKNOWN means that there's a SIP model but no record of the model's origin.
A unique description of the full distortion model is summarized in a new keyword called DISTNAME, in the primary header of the image file. The value for this keyword is a string comprised of the names of all distortion model components used for the image, described by the keywords SIPNAME, NPOLFILE, and D2IMFILE. A value of UNKNOWN is used if a distortion model was applied but the keyword values for SIPNAME, NPOLFILE, and D2IMFILE are not provided.
In the example below, hedit is used to query the SIPNAME and DISTNAME for an ACS/WFC image. The NPOLFILE and D2IMFILE keyword values are also obtained to show the naming nomenclature for the DISTNAME keyword value:
Even though there are several extensions appended to this FITS file, the sum total of them does not exceed 100 kB (ACS/WFC images require 97,200 bytes), making this a space-efficient way to manage all distortion and WCS information.
This effort to include distortion information in science images requires the use of multiple FITS conventions (proposed and improved) to support the full range of calibration distortion models used for HST data. The approved SIP Convention is used for describing polynomial terms of the distortion correction, while the proposed Paper IV FITS convention is used for NPOLFILE and D2IMFILE distortion corrections.
SIP Convention Keywords
IDCTAB reference files are used, in the pipeline, to populate science header keyword values that describe polynomial models as coefficients. A prime example is the implementation of SIP (a registered FITS convention) in the STScI_Python package stwcs (which relies on the FITS standard C package wcstools). The reliance on published or proposed FITS standards allows these updated HST headers to be understood by other standard astronomy-related tools such as the image display software ds9.
The keywords used for the SIP standard are shown in the table below.
Table 3.1: Standard SIP Keywords Keyword
CD1_1, CD1_2, CD2_1, CD2_2
A_ORDER, B_ORDER Order for distortion polynomials, along axis 1 and axis 2 respectively.
A_p_q, B_p_q
For A_p_q, (p + q) ≤ A_ORDER ; for B_p_q, (p + q) ≤ B_ORDER
Scale term for axis i [Optional keywords]
Excerpts from an ACS/WFC image header illustrate how distortion correction-related keywords, including standard SIP keywords, are presented:
Additional information:
LTV1, LTV2, x, and y position, respectively, of the first science pixel in the science array
WCSNAME and SIPNAME, while not standard SIP keywords, are new keywords to support the use of the SIP convention, with WCSNAME following FITS WCS Paper I standards.
Additional information:
OCX10, OCX11, OCY10, OCY11 are linear distortion terms without image scale, directly from the distortion model in the IDCTAB reference file.
IDCSCALE is the pixel scale from the IDCTAB reference file.
IDCTHETA is the orientation of the detector's y-axis relative to the V3 axis, as derived from the IDCTAB reference file.
IDCV2REF, IDCV3REF are the reference pixel's V2 and V3 positions, respectively, as derived from the IDCTAB reference file.
IDCXREF, IDCYREF are the reference pixel location in x and y as specified in the IDCTAB.
The SIP convention retains use of the current definition of the CD matrix where linear terms of the distortion model are folded in with the orientation, scale, and time-dependent skew at the reference point for each chip to provide the best linear approximation of the distortion. The SIP convention gets interpreted by applying higher-order coefficients A_p_q, B_p_q to the input pixel positions, then by applying the CD matrix and adding the CRVAL position to get the final world coordinates.
The SIP convention was created from the original form of the FITS Paper IV standards, but the Paper IV proposal since changed to use a different set of keywords and conventions. All of the FITS WCS Papers, including the draft for Paper IV, can be accessed through the HEASARC FITS WCS webpage.
Paper IV Proposal
The current Paper IV conventions provide a mechanism for specifying either a look-up table or polynomial model for the distortion of each axis. The standard states, in Section 2.1 of the Paper IV draft (as of November 2011):
Note that the prior distortion functions ... operate on pixel coordinates (i.e., p rather than p− r), and that the independent variables of the distortion functions are the uncorrected pixel or intermediate pixel coordinates. That is, for example, we do not allow the possibility of
The keywords used for describing these corrections use the syntax given in Table 2 of the draft Paper IV. For our purposes, the keywords of interest are those related to look-up tables, namely,
Table 3.2: Excerpt of Table 2 from Draft Paper IV with Keywords Related to Look-up Tables
Parameter for a prior distortion function, for use in the image head.
This syntax only provides the option to specify one correction at a time for each axis of the image. It precludes the use of this convention to specify both a look-up table and a polynomial model at the same time for the same axis. It does not state what should be done if the polynomial has been specified using a different convention, for example, the SIP convention. Therefore, SIP and Paper IV should not be seen as mutually exclusive. In fact, they will work together rather naturally since the SIP and Paper IV conventions both assume that the corrections will work on the input pixel and add to the output frame.
The only transformation that needs to be performed in this implementation is the adaptation of the DGEOFILE for use with the SIP coefficients, as performed by makewcs when the FITS header originally first gets updated in the pipeline. Corrections derived from the DGEOFILE, as well as corrections described by the SIP coefficients can then be added together as it was done in the original distortion calibration code. This has been documented in the paper describing the implementation of the distortion models in the draft of Paper IV.
The following header excerpt illustrates how the keywords get defined for an ACS/WFC image with an NPOLFILE reference image specified in the image header.
The DP<n>.EXTVER keywords point to the WCSDVARR extension associated with the correction, with one extension for each dimension of the image chip. In other words, there are two WCSDVARR extensions associated with this single chip, one containing the X corrections the other one containing the Y corrections.
Detector to Image Correction
The fixed column width correction, required only for ACS/WFC is applied at the very start of the distortion correction process. Its applied to flt.fits pixel positions, and the output positions are then used for computing the polynomial and other non-polynomial distortion corrections. The adopted implementation for describing this detector-to-image correction in the header, and how to apply it to the coordinates, is based on the Paper IV Look-up Table convention. It's assumed that the detector to image correction is the same for all chips, so only one look-up table needs to be specified and appended as a new FITS extension.
For ACS/WFC, the correction is a one-dimensional image extension of type D2IMARR. Each element in the row represents the correction for every pixel in the column of the science extension.
The following new keywords for this correction have been added to the science image's header.
Table 3.3: Standard Detector Distortion Correction Keywords
Name of reference file to be used for creating the look-up table. The task updatewcs creates an image extension of type D2IMARR, and populates it with column distortion information from this reference file.
Axis to which the DET2IM correction is applied. (1 - 'X' Axis, 2- 'Y' axis)
Name of reference file which was last used to create the look-up table. 'D2IMEXT' stores the name of the reference file used by updatewcs to create a D2IMARR extension. If 'D2IMEXT' is present in the 'SCI' extension header and is different from the current value of D2IMFILe in the primary header, the correction array in D2IMARR is updated.
For example:
These new keywords are added to the science image primary header when the keyword D2IMFILE has been assigned a reference file. Information in this reference file is used to create a look-up table containing column width corrections for both chips, stored in the D2IMARR image extension.
AstroDrizzle's primary product is a multi-extension FITS file with the suffix drz.fits.
The first extension contains the science (SCI) image which is corrected for distortion and, if applicable, dither-combined or mosaiced. The drizzled SCI image extension is typically in units of electrons per second which is the default for ACS and WFC3 images. (A user can choose to have the output in either electrons or electrons per second.) All image pixels have equal area on the sky and equal photometric normalization across the field of view, giving an image that is both photometrically and astrometricly accurate for point sources and extended sources. The dimensions of the output image are computed automatically by AstroDrizzle, and the default output plate scale value is given by the header keyword IDCSCALE (its value obtained from the IDCTAB reference file during pipeline processing). These astrodrizzle parameters and others may be changed by the user during post-pipeline reprocessing to best suit the actual data and user's needs–this will be covered in a later section of this handbook.
The WCS information for the science image of the drizzle product no longer contains any keywords related to distortion, as those models were removed from each input prior to being included in this combined image. Only the basic sky transformation gets written out to the drizzle science image header to reflect the uniform pixel scale and orientation of the image. The resulting header only contains the basic CD*, CRVAL, CRPIX, and CTYPE keywords to describe the transformation from each pixel position to a sky position, with a basic RA-TAN/DEC-TAN projection being provided in the header. This WCS solution also gets a default label, as the WCSNAME keyword, of DRZWCS to reflect the fact that it no longer contains any distortion model from any of the input images. Future versions of this code may allow each user to define the value to be written out as the WCSNAME keyword to be anything they want, but for now, this single default value will be provided in all AstroDrizzle products, especially those generated during pipeline processing.
The secondary outputs, available as image extension types WHT and CTX, are the the weight and context images, respectively. The weight image gives the relative weight of the output pixels, and can be considered an effective exposure time map. The context extension contains a map of the output images and a record of which image contributed to each pixel.
The WFC3/IR pipeline is based on the NICMOS pipeline, and produces a calibrated flt.fits file using the same up-the-ramp fitting procedure which rejects cosmic rays. The units of the WFC3/IR flt.fits file are electrons per second, rather than data numbers per second, to be more consistent with the calibrated WFC3/UVIS flt.fits files, which are in units of electrons.
ACS and WFC3 users should note that calibrated flt.fits files from the pipeline contain additional bits in the DQ mask that identify pixels flagged as cosmic rays by AstroDrizzle processing in the pipeline. The default value for these bits is 4096, and if AstroDrizzle is re-run off-line on those flt.fits files, it will be able to use these flags and proceed directly to the final drizzle step without the need to re-do cosmic ray masking, unless required; however, users should first verify that the images are properly aligned before proceeding to the final AstroDrizzle step. Alternatively, if the cosmic ray rejection needs to be improved, then cosmic rays identified in the pipeline can be ignored by setting the resetbits parameter to 4096 when re-running astrodrizzle.

Table of Contents Previous Next Index Print