STScI

The MultiDrizzle Handbook

TOC PREV NEXT INDEX PDF

5.2 Drizzle


The Dither package consists of many separate tasks, each with targeted functionality designed to align observations and detect cosmic rays and other cosmetic defects. The drizzle code itself is actually a set of compiled Fortran code, which allows users to combine observations and improve the sampling of the overall dataset through the use of the drizzle algorithm. Supplemental tasks based on this drizzle code also provide the capability to perform coordinate transformations using the full drizzle algorithm, instead of going through all the effort of re-sampling images themselves. The coordinate transformation tasks include traxy, tranback, wtraxy, wtranback, and tran. The act of drizzling can encompass all of these features, or the user may simply choose to use the "drizzle" code itself to merely combine separate images. Using a scale and pixfrac of 1.0 is akin to performing shift-and-add combination, and there are science limitations where no additional benefit is gained through drizzling that cannot be achieved through a simple median combination. For a more complete discussion on when and how its appropriate to drizzle your dataset, please see Chapter 2 on Introduction to Dithering.

5.2.1 The IRAF Drizzle Task

The drizzle task in the Dither package provides the most basic application of the drizzle algorithm for re-sampling images. It relies on the user to provide all the inputs necessary for re-sampling the image; including, the distortion coefficients, the offsets, rotation or plate-scale changes, and the size of the output image itself. The full set of parameters for `drizzle' are found in the following table (Table 5.1).


Table 5.1: Input Parameters for the IRAF Task Drizzle
Parameter
Default Value
Description
Format
input
Input data image
as a single filename
string
outdata
output data image
string
outweig
output weight image
string
outcont
output context image
string
in_mask
input weighting mask
string
wt_scl
exptime
Weighting factor for
input data image
string
outnx
800
X dimension for created images (if outdata not extant)
integer
outny
800
Y dimension for created images (if outdata not extant)
integer
kernel
square
Shape of the kernel function
string [square,point,gaussian,
turbo,tophat,lanczos3]
pixfrac
1.0
drop size of each pixel,
in pixel units form 0->1
real
scale
1.0
Linear size of output pixels in terms of input pixels
real
coeffs
Geometrical distortion coefficients file name
string [filename, `header' or `wcs']
lambda
555.0
Effective Wavelength (nm), Trauger coefficients only
real
xsh
0.0
X shift (in pixels) to be applied to input image
real
ysh
0.0
Y shift (in pixels) to be applied to input image
real
rot
0.0
Rotation of input image to be applied (degrees anti-clockwise)
real
shft_un
input
Units of shifts (input or output pixels)
string [input, output]
shft_fr
input
Frame in which shifts are applied
string [input, output]
xgeoim
X-shifts geometric distortion image
string
ygeoim
Y-shifts geometric distortion image
string
align
center
Reference point: corner or center of pixel
string [center, corner]
dr2gpar
Secondary geometric parameters
pset
expkey
exptime
Exposure time keyword in input data image header
string
in_un
counts
Units of the input image
string [cps, counts]
out_un
counts
Units of the output image
string [cps, counts]
fillval
INDEF
Value to be assigned to undefined output points
string

The task understands how to work with single images and subarray images for WFPC2, STIS, NICMOS, ACS, and WFC3 observations for which the distortion coefficients are available in the correct format. The distortion coefficients required as input for the drizzle task need to be in ASCII files with the coefficients providing the transformation from input pixels to the output frame in pixels. The output frame is defined by drizzle as the frame which includes all chips from the observation. This requires the coefficients specified in the drizzle coefficients files to perform all the transformations necessary to properly place each chip in the output image taking into account all differences in orientation, plate-scale and offset between the chips to reproduce the entire field-of-view on the sky for the observation. The primary source of distortion coefficients for ACS, STIS and WFC3 are IDCTAB reference tables (Section 4.2.4), and the latest calibrations for the distortion for WFPC2 are also stored using IDCTAB reference tables. These tables can be automatically converted into ASCII coefficients files by running PyDrizzle (Section 5.3) on the input image with the PyDrizzle generated ASCII files being intended as input to the drizzle task.

The drizzle task does not compute cosmic ray masks, or calculate additional offsets and rotations that might be needed in order to get the best pixel alignment. If you have data for which cosmic ray rejection needs to be performed, please consider using MultiDrizzle (Section 5.4).

5.2.2 The IRAF Blot Task

The IRAF task blot from the Dither package performs the inverse operation of drizzle; namely, it converts an undistorted image back into the original distorted image. This task conceptually runs the drizzle algorithm in reverse on the median image to recover the original input image. This task is primarily used for identifying cosmic rays in the original image. Like the original drizzle task, blot requires the user to explicitly provide all the transformation details as inputs. The full set of parameters for this task are in the following table (Table 5.2).


Table 5.2: Input Parameters for the IRAF Task Blot
Parameter
Default Value
Description
Format
input
Input image as a single filename
string
outdata
output data image
string
scale
1.0
Linear size of output
pixels in terms of input pixels
real
coeffs
Geometrical distortion coefficients file name
string [filename, `header' or `wcs']
lambda
555.0
Effective Wavelength (nm), Trauger coefficients only
real
xsh
0.0
X shift (in pixels) to be
applied to input image
real
ysh
0.0
Y shift (in pixels) to be
applied to input image
real
rot
0.0
Rotation of input image to be applied (degrees anti-clockwise)
real
shft_un
input
Units of shifts
(input or output pixels)
string [input, output]
shft_fr
input
Frame in which shifts
are applied
string [input, output]
xgeoim
X-shifts geometric
distortion image
string
ygeoim
Y-shifts geometric
distortion image
string
align
center
Reference point: corner
or center of pixel
string [center, corner]
outnx
800
X dimension for created
images (if outdata not extant)
integer
outny
800
Y dimension for created
images (if outdata not extant)
integer
interpol
poly5
Interpolant
string [nearest,linear,poly3,
poly5,spline3]
sinscl
1.0
Scale for sinc interpolation kernel
real
fillval
INDEF
Value to be assigned to undefined output points
string
expkey
exptime
Exposure time keyword in input data image header
string
in_un
counts
Units of the input image
string [cps, counts]
out_un
counts
Units of the output image
string [cps, counts]
expout
input
Exposure time for output image
string

5.2.3 WCS-enabled Dither Tasks

Instead of explicitly providing all the alignment information, the WCS information for the input image can be used in conjunction with the distortion coefficients to place the image in the output frame. This can be done using WCS-enabled versions of the basic drizzle and blot tasks, as well as the coordinate transformation tasks traxy and tranback. These tasks allow the user to simply specify the output WCS information or use the WCS information of an existing drizzled image to define the output frame. The WCS keywords from the input image will then be fit to the WCS derived from the output frame to determine how to place the image in the output image without requiring the user to explicitly provide offsets, rotations and scale changes as required by the original drizzle task.

5.2.3.1 WCS-enabled Drizzle

The task wdrizzle provides the user with the ability to use the WCS information to apply the drizzle algorithm to an input image and place that corrected image in an output frame specified through the use of WCS information. The full parameter set for wdrizzle are in the following table (Table 5.3).


Table 5.3: Input Parameters for the IRAF Task Wdrizzle
Parameter
Default Value
Description
Format
input
Input data image
as a single filename
string
outdata
output data image
string
outweig
output weight image
string
outcont
output context image
string
in_mask
input weighting mask
string
wt_scl
exptime
Weighting factor for
input data image
string
outnx
800
X dimension for created
images (if outdata not extant)
integer
outny
800
Y dimension for created
images (if outdata not extant)
integer
geomode
user
Way of specifying geometry
string [wcs, user]
kernel
square
Shape of the kernel function
string [square,point,gaussian,turbo,tophat,lanczos3]
pixfrac
1.0
drop size of each pixel,
in pixel units form 0->1
real
coeffs
Geometrical distortion coefficients file name
string [filename, `header' or `wcs']
lambda
555.0
Effective Wavelength (nm),
Trauger coefficients only
real
xgeoim
X-shifts geometric
distortion image
string
ygeoim
Y-shifts geometric
distortion image
string
align
center
Reference point:
corner or center of pixel
string [center, corner]
scale
1.0
Linear size of output
pixels in terms of input pixels
real
xsh
0.0
X shift (in pixels) to be
applied to input image
real
ysh
0.0
Y shift (in pixels) to be
applied to input image
real
rot
0.0
Rotation of input image
to be applied
(degrees anti-clockwise)
real
shft_un
input
Units of shifts
(input or output pixels)
string [input, output]
shft_fr
input
Frame in which
shifts are applied
string [input, output]
outscl
0.1
Scale of output image,
arcsecs/pixel
real
raref
0.0
RA of reference point on
output image
(CRVAL1, degrees)
real
decref
0.0
Dec of reference point on output image
(CRVAL2, degrees)
real
xrefpix
0.0
Reference pixel Y position
on output (CRPIX1)
real
yrefpix
0.0
Reference pixel Y position
on output (CRPIX2)
real
orient
0.0
Orientation of output
(PA of Y axis, N through E)
real
dr2gpar
Secondary geometric parameters
pset
expkey
exptime
Exposure time keyword in
input data image header
string
in_un
counts
Units of the input image
string [cps, counts]
out_un
counts
Units of the output image
string [cps, counts]
fillval
INDEF
Value to be assigned to
undefined output points
string

If the output image already exists and the geomode parameter has been set to wcs, then the WCS information from that image will be used in place of the WCS parameter values specified for outscl, raref, decref, xrefpix, yrefpix, orient.

5.2.4 Coordinate Transformation Tasks

Several supplemental tasks have also been developed using the core drizzle Fortran code base, primarily to provide the ability to apply the drizzle transformations to coordinates rather than to whole images. This capability allows the user to measure an object of interest in one frame and find its exact position in the other frame making it possible to eliminate the effects of re-sampling of the PSF.

The tasks traxy and tranback require the user to provide the full set of transformation parameters as they would be given to drizzle or blot respectively. These tasks also have WCS-enabled versions; namely, wtraxy and wtranback. These WCS enabled versions accept the same inputs as wdrizzle or wblot to set up the parameters for the transformation, and will use the WCS from an existing image to compute the results.

The task tran, on the other hand, asks for the original input image as well as the output drizzled image as created by any of the drizzle tasks and a direction for the transformation. It then reads the drizzle parameters written to the header of the output image to set up the transformation, and will automatically use either tran or tranback depending on the direction of the transformation requested by the user.

All of these tasks support operations on either a single X,Y position or on a list of X,Y positions provided as an ASCII file with a column of X positions and a column of Y positions.


Space Telescope Science Institute
http://www.stsci.edu
Voice: (410) 338-1082
help@stsci.edu
TOC PREV NEXT INDEX PDF