This module provides functions for mapping DS9 region files given in sky coordinates to DS9 region files specified in image coordinates of multiple images using the WCS information from the images.
Authors: | |
---|---|
Mihai Cara | |
License: | |
http://www.stsci.edu/resources/software_hardware/pyraf/LICENSE |
MapReg provides an automated interface for converting a region file to the image coordinate system (CS) of multiple images (and their extensions) using WCS information from the image(s) header(s). This conversion does not take into account pointing errors and, therefore, an examination and adjustment (if required) of output region files is highly recommended. This task is designed to simplify the creation of the exclusions and/or inclusions region files used with TweakReg task for sources finding.
Parameters: | |
---|---|
input_reg : string or list of strings (Default = ‘’)
images : string or list of strings (Default = *.fits)
img_wcs_ext : string or list of strings (Default = SCI)
refimg : string (Default = ‘’)
ref_wcs_ext : string (Default = SCI)
chip_reg : string or list of strings (Default = ‘’)
outpath : string (Default = ./regions)
filter : string {‘None’, ‘fast’, or ‘precise’ } (Default = ‘None’)
catfname : string (Default = exclusions_cat.txt)
append : bool (Default = False)
interactive : bool (Default = False)
verbose : bool (Default = False)
|
Notes
NOTE 1: This task takes a region file (or multiple files) that describe(s) what regions of sky should be used for source finding (include regions) and what regions should be avoided (exclude regions) and transforms/maps this region file onto a number of image files that need to be alighned.
The idea behind this task is automate the creation of region files that then can be passed to exclusions parameter of the TweakReg task.
The same thing can be achieved manually using, for example, external FITS viewers, e.g., SAO DS9. For example, based on some image refimg.fits we can select a few small regions of sky that contain several good (bright, not saturated) point-like sources that could be used for image alignment of other images (say img1.fits, img2.fits, etc.). We can save this region file in sky coordinates (e.g., fk5), e.g., under the name input_reg.reg. We can then load a specific extension of each of the images img1.fits, img2.fits, etc. one by one into DS9 and then load onto those images the previously created include/exclude region file input_reg.reg. Now we can save the regions using image coordinates. To do conversion from the sky coordinates to image coordinates, DS9 will use the WCS info from the image onto which the region file was loaded. The MapReg task tries to automate this process.
NOTE 2: MapReg relies on the pyregion package for region file parsing and coordinate transformation. Unfortunately, as of writing, pyregion does not consider distortion corrections when performing coordinate transformations. Therefore, there might be a slight discrepancy between the regions produced by MapReg and the DS9 regions obtained as described in the NOTE 1 above.
NOTE 3: MapReg does not take into account pointing errors and thus the produced region files can be somewhat misaligned compared to their intended position around the sources identified in the “reference” image. Threfore, it is highly recommended that the produced region files be loaded into DS9 and their position be adjusted manually to include the sources of interest (or to avoid the regions that need to be avoided). If possible, the include or exclude regions should be large enough as to allow for most pointing errors.
Examples
Let’s say that based on some image refimg.fits we have produced a “master” reference image (master.reg) that includes regions around sources that we want to use for image alignment in task TweakReg and excludes regions that we want to avoid being used for image alignment (e.g, diffraction spikes, saturated quasars, stars, etc.). We save the file master.reg in sky CS (e.g., fk5).
Also, let’s assume that we have a set of images img1.fits, img2.fits, etc. with four FITS extensions named ‘SCI’ and ‘DQ’. For some of the extensions, after analizing the img*.fits images we have identified parts of the chips that cannot be used for image alighnment. We create region files for those extensions and save the files in image CS as, e.g., img1_chip_sci2.reg (in our example this will be the only chip that needs “special” treatment).
Finally, let’s say we want to “replicate” the “master” region file to all SCI exctensions of the img*.fits images as well as to the 2nd DQ extension and to the 8th extension of the img*.fits images.
To do this we run:
>>> mapreg(input_reg = 'master.reg', images='img*.fits',
... img_wcs_ext='sci;dq,2;8', chip_reg='None,
... img1_chip_sci2.reg,None,None,None,None')
This will produce six region files in the ./regions subdirectory for each input image:
``img1_sci1_twreg.reg``, ``img1_sci2_twreg.reg``, ``img1_sci3_twreg.reg``,
``img1_sci4_twreg.reg``, ``img1_dq2_twreg.reg``, ``img1_extn8_twreg.reg``
...
``img2_sci1_twreg.reg``, ``img2_sci2_twreg.reg``, ``img2_sci3_twreg.reg``,
``img2_sci4_twreg.reg``, ``img2_dq2_twreg.reg``, ``img2_extn8_twreg.reg``
...
Print out syntax help for running astrodrizzle
Parameters: | |
---|---|
file : str (Default = None)
|