4.3 PyDrizzle
For standard applications, all ACS observations will require a correction for geometric effects. The CALACS pipeline will calibrate and combine CR-SPLIT images. It will not, however, automatically correct for geometric distortion or combine images from multiple dither positions.
The IRAF package DITHER has provided users the basic tools for linear image combination via the task drizzle. This task can produce mosaics, correct for geometric distortion, and even remove cosmic rays, creating a single, undistorted output image with uniform photometric and astrometric properties.
A significant amount of work, however, is required to determine the necessary input parameters, causing drizzle to be fairly user-intensive. These steps include:
- requiring the offsets in x and y from the reference image as input.
- requiring the output image size and pixel scale as input.
- only working with a single image extension at a time.
- requiring the rotation of each image extension as input.
These requirements made it impossible to use drizzle in a pipeline environment to automatically process images.
A new task, PyDrizzle, has been written to automate the use of drizzle in the pipeline environment. It can also simplify using drizzle for manual image reprocessing. The PyDrizzle software uses the Python language and can only be executed in the PyRAF environment. PyRAF, developed at STScI, allows users to run tasks using the standard IRAF parameter-based interface or by using separate Python programs. (More information can be obtained from the WWW site: http://pyraf.stsci.edu.)
Pipeline use relies on default parameter values which are taken from the IDCTAB reference file, including the default plate scale and the distortion model. This file provides information about the position of each ACS detector on the sky, allowing PyDrizzle to combine images from multiple detectors at once. PyDrizzle, like drizzle, works with count rates, allowing images with differing exposure times to be combined easily. Regardless of whether observations were taken as a single image or a set of dithered exposures, PyDrizzle thus produces images which are both astrometrically and photometrically accurate.
|
The first draft of the PyDrizzle Handbook is currently being written. Please refer to this document for further details on information presented in the following sections.
|
4.3.1 Association Table Usage
Before the drizzle task could be used in an automated manner, two obstacles had to be overcome: calculating the required input parameters and working with a wide range of input image formats. PyDrizzle relies on several features to address these problems:
- An association table will relate multiple input images to an output product.
- Python "structures" will be created in memory for each input image and for the output field.
- Output field parameters (RA/Dec of center, pixel size, field of view) will be specified using a `SkyField' function.
The calibration pipeline uses association tables to define how multiple images, taken at different pointings, relate to a single output image. PyDrizzle relies on these association tables to automatically combine and correct ACS dithered observations or any other related set of observations. Each input/output exposure within PyDrizzle knows about:
- its own world coordinate system,
- the distortion model for its detector,
- the range of output pixels covered by the image, and
- any instrument specific characteristics.
The output product can then be constructed from any combination of exposures from instruments which are supported by PyDrizzle (currently ACS, WFPC2, and STIS).
The PyDrizzle design provides the flexibility to support multiple instruments simultaneously, and to combine observations from several instruments into a single output field with arbitrary specification. The virtual output image is built using the World Coordinate System (WCS) information from each input image and the distortion model. This provides all the information necessary to calculate the input parameters for drizzle. These parameters are then passed to drizzle which actually performs the image combination.
4.3.2 Creating Custom Association Tables
Association tables for dithered, REPEAT-OBS, or CR-SPLIT observations are generated by the CALACS pipeline. These tables keep track of the input exposure filenames and the output product filenames. Some types of observations, however, will not have association tables. Others will have multiple tables from different visits which need to be combined into one. In the following discussion, we present the methodology for creating custom association tables, either by merging association tables or creating them from scratch. Users also have the capability to manually edit association tables to include any known image offsets. This can be done using the TTOOLS task tedit in IRAF, where the user adds the columns XOFFSET, YOFFSET and/or ROTATION to the association table. The form of these offsets must be specified as a "delta" shift: the measured shift minus the shift listed in the image header.
Merging Association Tables
Observing programs which cover a large portion of the sky will generally be made up of multiple pointings. Each of these pointings may be dithered or split for cosmic-ray rejection and will possess their own association table. In order for PyDrizzle to produce a single mosaic product, a composite association table must be built from the separate association tables. Users can easily create this composite by merging the individual tables using the TTOOLS task tmerge with "option = append".
The default product rootname will be taken from the first listed DTH-PROD in the composite association table. This rootname can be modified by the user (with tedit) to suit the desired naming convention. Generally, this rootname should match the rootname of the composite association table.
Creating Association Tables from Scratch
Some images will not have association tables. These may be single exposures of a given target which were taken at different times and orientations. They may even be exposures taken with different instruments. Observations taken using POS-TARG offsets, which are specified manually in the proposal, will not have association tables either.
A Python tool called buildAsn has been developed to create association tables which may then be used by PyDrizzle. This task currently uses the Python command-line interface and can be run under PyRAF or under Python itself. Since it resides alongside the PyDrizzle code, no extra setup is required to use this task.
The following syntax illustrates how use buildAsn to create an association table from all suitable files (crj, sfl, and flt.fits) in a single directory:
-
import buildAsn
-
prodname = buildAsn.buildAsnTable(rootname=`mymosaic')
In this example, the command will return the name in the `prodname' variable and the association table will have the name `mymosaic_asn.fits'. A built-in help facility provides details on additional parameters which can be used with buildAsn. It can be accessed using:
If user determined offsets are available, buildAsn has the capability of incorporating them into the association table. These offsets (XOFFSET, YOFFSET, and/or ROTATION) are specified by the file listed in the `shiftfile' parameter.
-
prodname = buildAsn.buildAsnTable(`mymosaic',shiftfile=`shift.txt')
This option allows users to fine-tune the final image combination by providing corrections to the header WCS information.
4.3.3 PyDrizzle Syntax
IRAF Interface:
PyDrizzle must be executed from within PyRAF and may use either IRAF or Python syntax. The IRAF syntax (within PyRAF) would be:
- import pydrizzle
-
pydrizzle jxxxx010_asn.fits orient=90.0
The default ACS parameters for PyDrizzle are summarized in table 4.4. Several parameters (xsize, RA, etc.) do not have a simple default value and are computed by PyDrizzle during processing. The user can set these parameters manually from the PyRAF command-line (as shown above) or using the graphical epar tool: "epar pydrizzle".
Table 4.4: Default ACS parameters for PyDrizzle
| Parameter |
Default Value |
Description |
| INPUT |
|
Input data: ASN table or single image |
| OUTPUT |
|
Output drizzle image |
| KERNEL |
square |
Shape of kernel function (square,point,gaussian,turbo,tophat) |
| UNITS |
cps |
Units for output image (counts or cps) |
| PIXFRAC |
1.0 |
Linear size of drop in input pixels |
| ROTATE |
no |
Rotate output drizzle product? |
| ORIENT |
0.0 |
Orientation angle of North in drizzled output image |
| PSIZE |
(0.05, 0.025)1 |
Linear size of output pixels (arcsec) |
| RA |
|
Right ascension output frame center |
| DEC |
|
Declination output frame center |
| XSIZE |
|
Size of output frame X-axis (pixels) |
| YSIZE |
|
Size of output frame Y-axis (pixels) |
| USE_MASK |
yes |
Use mask files created from input files? |
| BITS |
8194 |
Integer mask bit values considered good |
| IDCKEY |
IDCTAB |
Key for selecting IDC table (idctab/cubic/trauger/none) |
| CLEAN |
yes |
Remove temporary files? |
| SAVE |
no |
Keep individual drizzle output files? |
| BUILD |
yes |
Create multi-extension output file? |
1 Taken from the IDCTAB if not provided by user. Default values are given for the WFC and HRC, respectively.
|
Python Interface:
Using the Python syntax (within PyRAF), we can specify the output field characteristics, set up the desired parameters, and then run drizzle on the ACS association.
- The PyDrizzle code is loaded into PyRAF with:
- The output image characteristics (psize, orient, RA, etc.) can then be defined using the `SkyField' function. In this case, we specify that the output image should be aligned with North at the top using:
-
f = pydrizzle.SkyField(); f.set(orient=0.0)
- The PyDrizzle function serves as primary interface to the drizzle task and it creates a Python structure (object) as the output. This object, called acs in this example, is created from a single input image or association table. It possesses knowledge of the input images' WCS information, the distortion model, and any instrument specific characteristics. It also contains the input parameters calculated for running drizzle. This object is generated using:
-
acs = pydrizzle.PyDrizzle(`jxxxxx010_asn.fits',field=f)
- The drizzle task is executed using the run function which gets created as part of the output object acs.
- PyDrizzle will run drizzle as many times as necessary to generate the desired output from all the input images.
This Python syntax allows the user to examine the results of PyDrizzle before actually running drizzle (with the .run() method). This allows the user to verify the offsets, for example, and even correct them, before spending time actually running drizzle. The result, whether created using the Python or the IRAF interface, is a single multi-extension output FITS image, as illustrated in figure 4.5.
PyDrizzle includes a built-in help facility. Help can be obtained using:
Each output object also has a help function created by PyDrizzle and, using the example above, this object can be accessed with:
Similarly, the output image parameter-set created with the `SkyField' function has a help function which can be accessed by typing:
These facilities describe the syntax and all optional parameters which can be used to customize the combination of images during manual reprocessing of ACS observations.
