drizzle -- image coaddition using drizzling for the ESO Imaging Survey
drizzle data outdata
- data = "" [file name]
- The name of the input image file which is to be coadded.
- outdata = "" [file name]
- The name for the output data image onto which the data will be drizzled. If this image already exists the data will be drizzled on top of it, otherwise it will be created.
- (outweig = "") [file name]
- Output weight image. If this is null then no output weight image will be created. If outdata is a file which exists and is to be updated then outweig must also exist and be specified.
- (outcont = "") [file name]
- Output context image. If this is null then no context image will be created. The meaning and applications of the context image are described below.
- (in_mask = "") [file name]
- The optional weight image for the input data. This image will be multiplied by the wt_scl parameter before use, or, in the case of wt_scl=header, by the header keyword WGTSCALE. Weights should be positive real numbers. A pixel with zero weight will not affect the output image unless all other images mapped to the associated output pixel also have zero weight (see fillval). If no weight image is provided or the specified image cannot be accessed then all pixels in the input image will be given a weight equal to wt_scl.
- (wt_scl = "header") [real]
- Weight factor for input image. The value of this parameter is multiplied with the in_mask to form the input weight image. The user can either provide a positive real value, or set the weight factor equal to either the exposure time (wt_scl=exptime) or the square of the exposure time (wt_scl=expsq). In this case an exposure time header keyword must be provided using the expkey parameter. For EIS wt_scl=header is the standard method which will get the weighting factor from the data image header keyword WGTSCALE.
- (outnx = 4096) [integer]
- The size in X of the output pixel grid if creating a new output image. If one is drizzling onto an extant data array this number is ignored.
- (outny = 4096) [integer]
- The size in Y of the output pixel grid if creating a new output image. If one is drizzling onto an extant data array this number is ignored.
- (raref = 0.0) [real]
- The Right Ascension of the centre of the super-image in degrees (J2000.0). This is the reference point for the output image projection, not the centre of the output image.
- (decref = 0.0) [real]
- The Declination of the centre of the super-image in degrees (J2000.0). This is the reference point for the output image projection, not the centre of the output image.
- (xpoff = 0) [integer]
- The pixel offset in X of the output image relative to the centre of the super-image. If this is zero then the reference point, defined in "raref" and "decref" will be the lower-left corner of the output image.
- (ypoff = 0) [integer]
- The pixel offset in Y of the output image relative to the centre of the super-image. If this is zero then the reference point, defined in "raref" and "decref" will be the lower-left corner of the output image.
- (outscl = 0.27) [real]
- The scale of the output super-image in arcseconds per pixel.
- (pixfrac = "1.0") [real]
- A real number giving the linear size of the footprint, or "dropsize", of a pixel in units of the input pixel size. If pixfrac is set to less than 0.001 it is reset to 0.001 for processing. The standard, default, value for EIS is 1.0 but smaller values may be suitable in cases of well-dithered, undersampled input images.
- (proj = "TAN") [string TAN|COE]
- The projection for the output image. For small or modest fields (up to about 0.5 degrees) TAN is best as it is widely supported and understood. COE has advantages for very large fields to minimise distortion.
- (expkey = "") [string]
- The keyword in the header which specifies the exposure time (in seconds) of the image. The default is suitable for EIS images where the scaling is done using the FLXSCALE header keyword.
- (exp_sc = no) [boolean]
- This parameter controls whether the images are converted to counts-per-second before they are combined. For EIS this parameter should be set to "no" as the input images are scaled by the FLXSCALE header keyword.
- (out_un = "counts") [string]
- This parameter determines whether the output image will be the sum of the input images (counts) or will be scaled to an exposure time of one second (cps). In the former case the exposure time recorded in the header will be the sum of the exposure times of the input images and in the latter case it will be 1.0. Note that this parameter should set consistently throughout a series of drizzles onto the same output. For EIS "counts" should be used.
- (fillval = "INDEF") [string]
- This value is assigned to points in the output image which either have a weight of zero or which have remained "dry" during the drizzling process. If fillval="INDEF", and the weights in both the input and the output image at a given point are zero, that point will be set to the value it would have had if the input had a non-zero weight.
This task is an implementation of the image combination method known formally as variable-pixel linear reconstruction and informally as "drizzling" (http://www.stsci.edu/~fruchter/dither/drizzle.html).This version is somewhat specific to the ESO Imaging Survey (EIS) and the following public surveys and may not be suitable for other data.
When coadding EIS images suitable scripts are usually prepared using the "parapredriz" task and "drizzle" is not run directly. It is recommended that this route be followed.
Note that later versions have been optimised for maximum speed by using a constant kernel - a square on the output grid, aligned with the pixels. This makes the process faster with a minimal loss of quality.
Drizzling takes the input pixel grid and associates with each pixel a square region (a drop) whose size can vary between that of the original input pixel (pixfrac = 1.) down to a point (pixfrac=0). With uniform, equal weight images pixfrac=1 is equivalent to "shift-and-add". If the shifts and pixfrac are arranged so only one input pixel is drizzled onto an output pixel, the method is equivalent to interlacing. For EIS, where the data is well-sampled in all but the most exceptionally good seeing, a value of pixfrac=1.0 is used.
Drizzle has a rather daunting number of parameters to allow it to handle many different cases. However, the majority of applications can be handled by using the default values which have been set for standard EIS image coaddition. It is recommended that the parameters "wt_scl", "expkey", "outscl", "pixfrac", "exp_sc" and "out_un" should be changed from the defaults only after carefully reading the notes about them in this help file.
The geometrical transformation of pixels from input to output images is done in several stages:
Each input image can have associated with it a weight image. An output weight image is always created but is saved only at the request of the user. Multiple images are combined successively, with each image drizzled onto the output of the previous run of Drizzle. If multiple input images are to be drizzled onto a single output image (this is the usual case), the output weights of the intermediate drizzle operations must be saved and used in successive drizzle operations.i) The astrometric solution for the frame, coming from the EIS/LDAC pipeline processing, is read. If this solution is not available a standard WCS consisting of CRVAL1/2, CRPIX1/2 and a CD matrix is used.
ii) Pixel positions in the input are converted to tangent plane positions.
iii) The tangent plane positions are converted to RA,Dec on the sky.
iii) RA,Dec positions are converted to coordinates on the specified output projection corresponding to the appropriate section of the superimage (defined by raref,decref,xpoff,ypoff and outscl).
iv) These pixel positions are offset into the appropriate tile of the output using the xpoff,ypoff values.
The input weight image (in_mask) should contain only non-negative real numbers. The input weight image is multiplied by the parameter wt_scl before being used. For EIS wt_scl=header is normally used and this scaling of the weight image is taken from the WGTSCALE keyword in the input image header. The input weight image may be used as a pixel mask (good=1; bad=0). The final weight image is wt_scl*in_mask. Note that the in_mask is not a data quality image in which zero means good and non-zero values differentiate between failure modes.
If the image header contains an exposure time keyword, the user may set wt_scl=exptime (the user must then also supply Drizzle with the appropriate keyword). This weight is optimal when errors are Poisson and is appropriate for data limited by sky noise. Alternatively the weight scale can be set to the square of the exposure time by setting wt_scl=expsq. This weighting is appropriate for data limited by read noise. For EIS the weighting information is explicitly included in the weight image and the WGTSCALE keyword. In this case wt_scl=header should be used. Weighting by exposure time should not be used for EIS.
When performing photometry on a drizzled image one should, in theory, weight the image pixels by the values in the weight image. However, few photometry packages make such weighting a simple matter. One can largely avoid the need for this weighting, by choosing Drizzle parameters (in particular pixfrac and scale) so that the standard deviation of the weight image is not a large fraction of the final output weight. A rule of thumb is that one should produce an output weight image whose standard deviation is less than thirty percent of the average weight value. If this rule is followed, then use of the weight image in photometry adds little to the final signal-to-noise.
In order for the results of Drizzle to be meaningful, the input images must be converted to counts-per-second or have equal exposure times. The scaling to counts-per-second will be done internally if the user supplies the exposure time keyword and sets exp_sc to "yes". Drizzling preserves total counts, not counts per pixel. Therefore, if scale is not equal to one, then the counts per pixel will be reduced by the ratio of the areas of the pixels. For EIS this scaling is done in a relative way using the FLXSCALE keyword in the image header and exp_sc="no" should be specified.
The output can be written out as either total counts or counts-per-second. This choice is controlled by the parameter "out_un". Is is strongly recommended that a consistent value for this parameter is maintained throughout a series of drizzles onto the same output. The use of the cps option may be helpful in the creation of mosaics where the sum of the input exposure times does not generally reflect the typical exposure time of any particular region. For EIS out_un="counts" is normal.
The optional context image is a way of recording which of the input images have affected the pixel values at a given point in the output. The context image contains integer codes which act as an index into a table. This table lists which images (coded by their unique image ID, or if this isn't available simply by the number in which they were processed) contribute to a given context. The context image and the table are dynamically updated as drizzle runs are performed. The context table resides in the header of the context image if it is small but when it becomes larger it is written to a separate table text file the name of which is the context image with ".CON" appended at the end. The use of these files is handled in what should be a transparent manner but care should be taken only to delete .CON files along with the context images to which they belong.
When drizzling is run in parallel, or on separate output images in succession, the contexts associated with these output images will not be consistent with each other. This can be rectified using the task "mcon" which reads all the context tables for a set of context images, makes a "master context table" and updated the headers and context image file values accordingly.
Some of the parameter values used in the drizzling processing are appended to the output image header each time a drizzling operation is performed. The world coordinate system is also modified to reflect the projection of the sky used in the super image. This is done when the output file is created; subsequent drizzle run "on top" of the same file will not modify the WCS information in the header.
Note that the EIS super-image currently can use the conic-equal area projection (called COE by Greisen & Calabretta in their paper on FITS world coordinate systems) as well as the more familiar TAN tangent plane projection. The CTYPE keywords may hence be set to RA---COE and DEC--COE or RA---TAN and DEC--TAN. The COE WCS is formally correct but may cause problems with some software which doesn't support this projection. It is recommended that the projection "TAN" (normally specified in "parapredriz" rather than directly to "drizzle") is used for small fields (eg, "deep" exposures) and the "COE" option only for parts of large mosaics (eg, EIS wide - several degrees of sky).
If the output image already exists the parameters used for the previous drizzle are read and compared to the current ones. The user is alerted to possibly incompatible combinations. A total of 999 images may be drizzled onto the same output image without causing confusion of header information.
If the input image is defined as an image section, the WCS information in the outputs may be wrong and the geometric correction incorrectly applied.
The original Drizzle task was a collaborative effort between Andy Fruchter (STScI) and Richard Hook (ST-ECF/ESO). For more information see:
http://www.stsci.edu/~fruchter/dither/drizzle.htmlThe EIS version was developed by Richard Hook in conjunction with the EIS team.
To drizzle a set of input EMMI images, assumed to have the appropriate astrometry keywords in the headers, onto the appropriate output tiles one first runs parapredriz (within the IRAF cl):The result, in the file doit-001.cl, will be an IRAF script which contains the full details of the drizzle commands, and their parameters, needed to do all the coadditions. It is assumed that all the fits files in the current directory are to be coadded onto 4096x4096 output tiles.parapredriz image="*_??.fits" outmode="tiles" raref=340.725 \ decref=-39.4667 nx=4096 ny=4096 npara=1 stem=doit
This file may then be executed by typing:
The standard naming convention for EIS Wide has input images with names like: A_I_02_17.fits for data images - patch A, band I, row 2 frame 17 - and assumes that the weighting images are named A_I_02_17.weight.fits.cl <doit.cl
The naming for the output tiles of the super-image assumes that the centre of the super-image will be at the centre of a frame called A_I_CA+00+00 and the surrounding tiles will have names like: A_I_CA+02-03 for the one 2 along to the right and 3 lower. The corresponding output weight image would be named A_I_CA+02-03.weight.
There is one drizzle per input frame per output tile on which this image overlaps. So, if an input maps to the centre of an output tile there will be only one and if to a corner, four. Typically about 2.5 times as many drizzles are required as there are input images.
The simplified flux redistribution scheme used is not optimal in some cases.Not all combinations of input options may be supported.
Only TAN and COE projections are available.
A 2000x2000 EMMI image can be drizzled, using an appropriate weighting image, onto a 4096x4096 output image in about one minute on a SUN Ultra Enterprise E3002, 250MHz (Solaris 2.5.1).
parapredriz,dcon