siaper -- Draw the scientific instrument apertures for Hubble Space Telescope.
The siaper task draws the science instrument apertures of the Hubble Space Telescope (HST) on the specified graphics device. This task can be used to create overlays of the HST Field-of-View (FOV) onto images.
Aperture plots may overlay an image on the output device (using the imdkern task in the IRAF plot package). This is done by first displaying the image with the display task, and then drawing the aperture with siaper.
There is no real communication between display and siaper. Therefore, you must tell both tasks how to position the image and the overlay. The disconlab task in the STSDAS graphics.sdisplay package can be used to combine the aperture plot with other graphics, simplifying the overlay process.
The naming scheme of the apertures is non-obvious due to a 10 character limit imposed by the PDB. In general, each aperture contains a substring indicating which instrument it belongs to, beginning with the single letter designation of the instrument. The general categories are as follows:
ota - HST FOV fgs - FGS xf96, x96 - FOC f96 xkf96, xk96 - Post-COSTAR FOC f96 xf288, x28 - FOC f288 xkf288, xk28 - Post-COSTAR FOC f288 xf48, x48 - FOC f48 xkf48, xk48 - Post-COSTAR FOC f48 ybl, yrd - FOS Blue/Red detectors ykbl, ykrd - Post-COSTAR FOS Blue/Red detectors z - GHRS zk - Post-COSTAR GHRS v - HSP wwf, wpc - WF/PC uwf, upc - WF/PC II
There are over 586 apertures specified in the SIAF. The SIAF itself is used by the HST ground system specifically for target acquisitions and interactive offset information. The SIAF also contains older definitions of some of the apertures for historical purposes. Finally, some apertures have never been rigorously defined due to instrument problems or simple lack of use. Hence a number of the apertures are not useful for overlay purposes. Below is a discussion, per instrument, of the "real" physical apertures.
Two files, found in stsdaslib$ and distributed with STSDAS, contain lists of some of the "real" apertures. The file siaper_def_apers.txt contains the major apertures for Post-Costar. The file siaper_def_apers_pc.txt contain the major Pre-Costar apertures.
"xk96n512", "xk96n256", and "xk96n128" are the normal or unzoomed 512x512, 256x256, and 128x128 image formats. The zoomed formats replace the "n" with "z".
"xk28n512", "xk28n256", and "xk28n128" are the normal or unzoomed 512x512, 256x256, and 128x128 image formats. The zoomed formats replace the "n" with "z".
"xk48n512", "xk48n256", and "xk48n128" are the normal or unzoomed 512x512, 256x256, and 128x128 image formats. The zoomed formats replace the "n" with "z".
FOC entries which end with "a4" or "a8" are apertures used when acquiring targets for occulting or spectroscopy modes of the FOC for the f96 or f288 cameras.
FOC f48 entries which end with "s" are apertures used to acquire and place targets on the slit.
The paired apertures have either "pra" or "prb" appended to the name corresponding to the pair identification, A or B.
The bar apertures have "bar" in their designation.
Finally, the apertures "ykbl" and "ykrd" alone define the circular entrance apertures to the FOS in the HST FOV.
"zk1n2_0" and "zk2n2_0" is the Large Science Aperture (LSA) for each detector.
"zk1n_25" and "zk2n_25" is the Small Science Aperture (SSA) for each detector.
The "n" can be replaced by "a" to use the apertures related to the attenuated mirrors. The other apertures are used for engineering purposes.
"uwf2", "uwf3", and "uwf4" are the wide-field chips.
Note that the chips overlay each other when all plotted. This is due to the fact that the edges near the pyramid do not appear on the sky. The SIAF has defined the full sizes of the chips but has positioned them such that their appropriate areas are illuminated by the sky.
The optimum apertures for the methane quad filters are identified by names which begin with "ufqch".
The optimum apertures for the polarizer have "pol" in their names.
The optimum apertures for the redshifted OII filter are identified by names beginning with "ufqu".
The Woods filter optimum apertures begin with "uf160".
^ - Matches the beginning of the line. $ - Matches the end of the line. * - Matches zero or more occurrences of the proceeding character. ? - Matches any single character. [xy] - Match a character if it appears in the list of characters "xy". [^xy] - Match a character if it does not appear in the list of characters "xy".
See the EXAMPLE section for use of pattern matching.
cl> tread stsdas$data/scidata/cosiaf columns=siap_id
To get a printout of the column, use tprint:
cl> tprint stsdas$data/scidata/cosiaf columns=siap_id
The names can also be placed in a text file. To specify the file name as the parameter value proceeded with the "@" character. The default value "@stsdaslib$siaper_def_apers.txt" specifies a file.
The center aperture will not be drawn. If the center aperture is to be plotted, it must also be included in the apertures parameter.
If the graphics are to be overlaid on an imtool display, append should be set to "no".
If fill = no, the default, then the viewport is sized to preserve the aspect ratio of the image.
The next few examples demonstrate general usage of the task.
1. Getting the default SIAF table. In general, the table should be located in stsdas$data/scidata/cosiaf.dat. It is possible that the file was not created by the STSDAS system administrator when STSDAS was installed.
If this is the case, the distributed FITS file should be located in stsdas$data/scidata/fits/cosiaf.fits. A user can use this file to create their own version of cosiaf.tab as follows:
cl> cd home$ cl> strfits stsdas$data/scidata/fits/cosiaf.fits "" \ >>> cosiaf.tab oldirafname+
If the STSDAS administrator has "stripped" the installation, the FITS files will no longer be present. In this case, contact STScI on how to obtain a new copy.
2. Display the default apertures on an image displayed on either Imtool, SAOimage, or Ximtool. The V1 axis, center of the HST FOV, will be placed at the reference coordinate in the image's WCS. This position is specified by the keywords CRVAL1 and CRVAL2.
cl> display dev$wpix 1 xsize=0.8 ysize=0.8 fill+ cl> siaper dev$wpix device=imd left=.1 right=.9 \ >>> bottom=.1 top=.9
Note that the task "stsdas.graphics.sdisplay.disconlab" automates display and overlay of apertures on an image. The above could be accomplished by:
cl> disconlab dev$wpix cont=no label=no doapers=yes
Note that the image dev$wpix covers an area just larger than the WF/PC II, hence most of the other apertures fall outside the image.
3. On dev$wpix, place the FOC f96 on the reference coordinate of the image WCS. Show only the 512x512 normal format.
cl> display dev$wpix 1 xsize=0.8 ysize=0.8 fill+ cl> siaper dev$wpix apertures=xkf96,xk96n512$ \ >>> center_ap=xk96n512 \ >>> device=imd left=.1 right=.9 bottom=.1 top=.9
4. Same as example number 3. However, place the aperture on the object located at R.A=13:28:01.2, Dec=47:29:49.7. Also, roll the HST by ~35 degrees to place the 512x512 aperture parallel to North and East. Do this with only the relevant image section.
cl> display dev$wpix[1:160,380:512] 1 xsize=0.8 ysize=0.8 fill+ cl> siaper dev$wpix[1:160,380:512] apertures=xkf96,xk96n512$ \ >>> center_ap=xk96n512 ra=13:28:01.2 dec=47:29:49.7 roll=35 \ >>> device=imd left=.1 right=.9 bottom=.1 top=.9
The following examples demonstrate how to specify apertures, in particular using the regular expression syntax.
Note that all the following examples do not use an image, but the contents of the pset wcspars. The default "wcspars" pset is not used, but a pset called "siaper_defwcs". This pset defines a WCS transformation for a region, measured in arcseconds, which just covers the HST FOV. These are examples of simply creating plots of the HST FOV without an image.
5. Display every aperture found in the SIAF file.
cl> siaper "" apertures=* wcspars=siaper_defwcs \ >>>sky_project=no
6. Specify a file as the source of aperture names. The file in the example, stsdaslib$siaper_def_apers_pc.txt, is distributed with STSDAS. It contains a list of apertures prior to the first Service Mission, SM94, or Pre-COSTAR.
cl> siaper.wcspars=siaper_defwcs cl> siaper.sky_project=no cl> siaper "" apertures=@stsdaslib$siaper_def_apers_pc.txt
7. Matching groups of apertures. All the apertures for a particular instrument will be plotted on separate graphs. Since each instrument is identified by the leading character, the match needs to be forced at the beginning of line. The use of the "^" accomplishes this task. Also, for each plot, the ota will be included. Each command will plot, respectively, the apertures for the FGS', FOC f96, FOC f288, FOC f48, GHRS, and WF/PC II.
cl> siaper.wcspars=siaper_defwcs cl> siaper.sky_project=no cl> siaper "" apertures=ota,^fgs cl> siaper "" apertures=ota,^xk96,xkf96 cl> siaper "" apertures=ota,^xk28,xkf288 cl> siaper "" apertures=ota,^xk48,xkf48 cl> siaper "" apertures=ota,^zk cl> siaper "" apertures=ota,^u
8. Matching an exact aperture. Since the default matching will match a string to anywhere in an aperture name, it may be necessary to further constrain the match to get an exact aperture. For example, to plot the 512x512 image format of the FOC F96, the end of line match needs to be specified, "xk96n512$". If one just specified, "xk96n512", the following apertures would be matched: xk96n512, xk96n512_4, xk96n512a4, xk96n512_8, and xk96n512a8. Compare the plots from the following two commands.
Note: the "=gcur" command can be used to zoom the plots to see more detail.
cl> siaper.wcspars=siaper_defwcs cl> siaper.sky_project=no cl> siaper "" apertures=xk96n512$ cl> siaper "" apertures=xk96n512
9. Complicated matching. Draw all the FOC f96 512x512 formats, both zoomed and normal. This happens to be two, xk96n512 and xk96z512. Since the single character, "n" or "z", is the wildcard, use the "?" pattern match. Also match the end of line to avoid the occulting finger apertures.
cl> siaper.wcspars=siaper_defwcs cl> siaper.sky_project=no cl> siaper "" apertures=xk96?512$
The following examples discuss the use of the wcspars parameters.
10. This example demonstrates the use of the wcspars parameters. This example will use wcspars to reproduce the information that is found in image dev$wpix. This should reproduce example 2. Note that no image is specified to siaper and the default wcspars pset is used (wcspars="").
cl> display dev$wpix 1 xsize=0.8 ysize=0.8 fill+ cl> wcspars.ctype1 = "ra---tan" cl> wcspars.ctype2 = "dec--tan" cl> wcspars.crpix1 = 257.75 cl> wcspars.crpix2 = 258.93 cl> wcspars.crval1 = 201.94541667302 cl> wcspars.crval2 = 47.45444 cl> wcspars.cd1_1 = -2.1277777E-4 cl> wcspars.cd2_2 = 2.1277777E-4 cl> wcspars.log_x1 = 1 cl> wcspars.log_x2 = 512 cl> wcspars.log_y1 = 1 cl> wcspars.log_y2 = 512 cl> siaper "" wcspars="" device=imd left=.1 right=.9 \ >>> bottom=.1 top=.9
11. This examples explains the values found in the siaper_defwcs pset. The goal of this transformation is to create a plot of the HST FOV in V2-V3 coordinates. The "logical" or "pixel" space will be V2-V3 in arcseconds. Since the V1 axis is at the center of V2-V3, both the CRPIX and CRVAL values are 0.0, the origin of V2-V3.
The CTYPE values are set to "linear". There is no need to complicate things any more.
siaper assumes the WCS is a transformation between degrees and "pixels". Since our "pixels" in this case are arcseconds, the transformation found in the CD matrix is the conversion from degrees to arcsecond, 1/3600. Since no rotation exists, the cross terms of the CD matrix are zero.
Finally, the size of the "logical" space needs to be defined. The HST FOV is just less than 1800 arcseconds in diameter. Since V2-V3 is centered on (0,0), the logical domain to be covered is from -950 to +950. One may note that the Y axis is reversed. This is because, as convention in most HST documentation, V2-V3 is shown with V3 increasing downward.
The effect of this transformation is to cancel the transformation in siaper from arcseconds to the assumed units of degrees of an image's WCS. If one were to use "=gcur" to query the positions of the plotted apertures, the reported positions will be the V2-V3 coordinates as specified in the SIAF.
The SIAF is not the best suited for overlay capability. The information is present, but the large number of apertures and lack of definition provided for each aperture is not user-friendly. Unfortunately, this file is the only official source of aperture characteristics at the Institute.
Jonathan Eisenhamer, STSDAS
dvpar, wcspars, display, imdkern,tread