wcslab -- overlay a labeled world coordinate grid on an image
WCSLAB draws a labeled world coordinate grid on the graphics device device using world coordinate system (WCS) information stored in the header of the IRAF image image if usewcs is "no", or in wcspars if usewcs is "yes" or image is "". WCSLAB currently supports the following coordinate system types 1) the tangent plane, sin, and arc sky projections in right ascension and declination and 2) any linear coordinate system.
By default WCSLAB draws on the image display device, displacing the currently loaded image pixels with graphics pixels. Therefore in order to register the coordinate grid plot with the image, the image must loaded into the image display with the DISPLAY task, prior to running WCSLAB.
If the viewport parameters vl , vr , vb , and vt are left undefined, WCSLAB will try to match the viewport of the coordinate grid plot with the viewport of the currently displayed image in the selected frame frame . This scheme works well in the case where image is smaller than the display frame buffer, and in the case where image is actually a subsection of the image currently loaded into the display frame buffer. In the case where image fills or overflows the image display frame buffer, WCSLAB draws the appropriate coordinate grid but is not able to draw the titles and labels which would normally appear outside the plot. In this case the user must, either adjust the DISPLAY parameters xmag , and ymag so that the image will fit in the frame buffer, or change the DISPLAY viewport parameters xsize and ysize so as to display only a fraction of the image.
WCSLAB can create a new plot each time it is run, append = no and overplot = no, add a new graph to an existing plot if overplot = yes and append =no, or append to an existing plot if append = yes. For new or overplots WCSLAB computes the viewport and window, otherwise it uses the viewport and window of a previously existing plot. If device is "stdgraph", then WCSLAB will clear the screen between each new plot. This is not possible if device is one of the "imd" devices since the image display graphics kernel writes directly into the display frame buffer. In this case the user must redisplay the image and rerun WCSLAB for each new plot.
The parameters controlling the the detailed appearance of the plot are contained in the parameter set specified by wlpars .
The parameters in WCSPARS are used to define the world coordinate system only if, 1) the parameter usewcs is "yes" or, 2) the input image is undefined. This user-defined WCS specifies the transformation from the logical coordinate system, e.g. pixel units, to a world system, e.g. ra and dec.
Currently IRAF supports two types of world coordinate systems: 1) linear, which provides a linear mapping from pixel units to the world coordinate system 2) and the sky projections which provide a mapping from pixel units to ra and dec. The parameters ctype1 and ctype2 define which coordinate system will be in effect. If a linear system is desired, both ctype1 and ctype2 must be "linear". If the tangent plane sky projection is desired, and the first axis is ra and the second axis is dec, then cypte1 and ctype2 must be "ra---tan" and "dec--tan" respectively. To obtain the sin or arc projections "tan" is replaced with "sin" or "arc" respectively.
The scale factor and rotation between the logical and world coordinate system is described by the CD matrix. Using matrix multiplication, the logical coordinates are multiplied by the CD matrix to produce the world coordinates. The CD matrix is represented in the parameters as follows:
|---------------| | cd1_1 cd1_2 | | | | cd2_1 cd2_2 | |---------------|
To construct a typical CD matrix, the following definitions of the individual matrix elements may be used:
cd1_1 = xscale * cos (ROT) cd1_2 = -yscale * sin (ROT) cd2_1 = xscale * sin (ROT) cd2_2 = yscale * cos (ROT)
where xscale and yscale are the scale factors from the logical to world systems, e.g. degrees per pixel, and ROT is the angle of rotation between the two systems, where positive rotations are counter-clockwise.
The ra/dec transformation is a special case. Since by convention ra increases "to the left", opposite of standard convention, the first axis transformation needs to be multiplied by -1. This results in the following formulae:
cd1_1 = -xscale * cos (ROT) cd1_2 = yscale * sin (ROT) cd2_1 = xscale * sin (ROT) cd2_2 = yscale * cos (ROT)
Finally, the origins of the logical and world systems must be defined. The parameters crpix1 and crpix2 define the coordinate in the logical space that corresponds to the coordinate in world space defined by the parameters crval1 and crval2 . The coordinates (crpix1, crpix2) in logical space, when transformed to world space, become (crval1, crval2).
The last set of parameters, log_x1, log_x2, log_y1, log_y2, define the region in the logical space, e.g. in pixels, over which the transformation is valid.
For all linear transformations axis 1 and axis 2 specify which axis in the image is being referred to. For example in a 2-dimensional image, the FITS image header keywords CTYPE1, CRPIX1, CRVAL1, CDELT1, CD1_1, and CD1_2 define the world coordinate transformation for axis 1. Similarly the FITS image header keywords CTYPE2, CRPIX2, CRVAL2, CDELT2, CD2_1, CD2_2, define the world coordinate transformation for axis 2.
THIS RULE DOES NOT APPLY TO THE TANGENT PLANE, SIN, and ARC SKY PROJECTION WCS'S. For this type of WCS axis 1 and axis 2 always refer to right ascension and declination respectively, and WCSLAB assumes that all axis 1 parameters refer to right ascension and all axis 2 parameters refer to declination, regardless of which axis in the image WCS actually specifies right ascension and declination.
There are two types of grid lines / tick marks, "major" and "minor". The major grid lines / tick marks are the lines / ticks that will be labeled. The minor grid lines / tick marks are plotted between the major marks. Whether lines or tick marks are drawn is determined by the boolean parameters major_grid and minor_grid . If yes, lines are drawn; if no, tick marks are drawn. How the lines appear is controlled by the parameters major_line and minor_line .
The spacing of minor marks is controlled by the parameters axis1_minor and axis2_minor . These parameters specify the number of minor marks that will appear between the major marks along the axis 1 and axis 2 axes.
Spacing of major marks is more complicated. WCSLAB tries to present major marks only along "significant values" in the coordinate system. For example, if the graph spans several hours of right ascension, the interval between major marks will in general be an hour and the major marks will appear at whole hours within the graph. If what WCSLAB chooses is unacceptable, the interval and range can be modified by the parameters axis1_int , axis1_beg , axis1_end for the axis 1, and axis2_int , axis2_beg , and axis2_end for axis 2. All three parameters must be specified for each axis in order for the new values to take affect
WCSLAB supports three types of graph: normal, polar, and near_polar.
A normal graph is the usual cartesian graph where lines of constant axis 1 or 2 values cross at least two different sides of the graph. WCSLAB will by default plot a normal type graph for any image 1) which has no defined WCS 2) which has a linear WCS 3) where the sky projection WCS approximates a cartesian system.
A polar graph is one in which the north or south pole of the coordinate system actually appears on the graph. Lines of constant declination are no longer approximately straight lines, but are circles which may not intersect any of the edges of the graph. In this type of graph, axis 1 values are labeled all the way around the graph. Axis 2 values are labeled within the graph next to each circle. An attempt is made to label as many circles as possible. However, if the WCSLAB's defaults are not agreeable, the parameters, axis2_dir and justify , can be modified to control how this labeling is done. Axis2_dir specifies along which axis 1 value the axis 2 labels should be written. Justify specifies on which side of this value the label should appear.
The near_polar graph is a cross between the normal graph and the polar graph. In this case the pole is not on the graph, but is close enough to significantly affect the appearance of the plot. The near_polar graph is handled like a polar graph.
The parameter graph_type can be used to force WCSLAB to plot a graph of the type specified, although in this case it may be necessary to modify the values of other WLPARS parameters to obtain pleasing results. For example trying to plot a polar graph as cartesian may producing a strange appearing graph.
Due to the variety of graph types that can ber plotted (see above), and the arbitrary rotation that any WCS can have, the task of labeling the major grid lines in a coherent and pleasing manner is not trivial.
The basic model used is the cartesian or normal graph. Labels normally appear on the left and bottom edges of the graph with a side devoted solely to one of the WCS coordinate axis. For example, right ascension might be labeled only along the bottom edge of the graph and declination only along the left edge, or vice versa.
If the defaults chosen by WCSLAB are unacceptable, the parameters axis1_side and axis2_side , can be used to specify which side (or sides) the labels for axis 1 and axis 2 will appear. Either a single side or a list of sides can be specified for either axis. If a list is specified, labels will appear on each side listed, even if the same side appears in both of the parameters. In this way, labels can be made to appear on the same side of the graph.
Due to coordinate rotations, lines of constant axis 1 or axis 2 value may not intersect the edges of the graph perpendicularly. To help clarify which line belongs to which label, the labels will be drawn at an angle equal to that of the line which is being labeled. If this is not desired, the parameter rotate may be set to no, and labels will always appear "normal", i.e. the text will not be rotated in any way.
By default, all labels will be shortened to the smallest unit needed to indicate the value of the labeled line. For example, if the graph spans about 30 seconds of declination, the interval between the labels will be approximately 5 or 10 seconds. The first label will contain the full specification, i.e. -22:32:20. But the rest of the labels will only be the seconds, i.e. 30, 40, 50. However, at the change in minutes, the full format would be used again, -22:33:00, but then again afterwards only seconds will be displayed, i.e. 10, 20, etc. If this shortening of labels is undesirable, it can be turned off by setting the parameter full_label to yes. This forces every label to use the full specification.
Finally, the parameter label_size can be used to adjust the size of the characters used in the axis labels.
A graph title may specified using the parameter title . If title = "imtitle" a default title constructed from the image name and title is used. The location and size of the graph title are controlled by the parameters title_side and title_size . Similarly the content, placement and size of the axis titles are controlled by the parameters axis1_title , axis2_title , axis1_title_side , axis2_title_side , and axis_title_size .
If remember = yes, the coordinates are output to the parameter set WLPARS in a form suitable for the type of system the coordinates represent. For example right ascensions are output in HH:MM:SS (hours:minutes:seconds) and declinations are output in DD:MM:SS (degrees:minutes:seconds). If the input parameters are changed, for example axis1_int, their values must be input in the same format. If the WCS is linear, then the parameters will not be formatted in any special way; i.e. no assumptions are made about units, etc.
1. Display the 512 pixel square IRAF test image dev$pix in an 800 square display window and overlay it with a labeled coordinate grid. Since dev$pix does not have a defined WCS a pixel coordinate grid will appear.
cl> display dev$pix 1 ... display the image in frame 1 cl> wcslab dev$pix 1 ... the coordinate grid in green will be plotted on the display
2. Redisplay the previous image and by overlay the labeled coordinate grid on the inner 100 by 400 pixels in x and y.
cl> display dev$pix 1 ... erase the graphics by redisplaying the image cl> wcslab dev$pix[100:400,100:400] 1
3. Display an 800 square image which has a defined linear WCS in an 800 square display window and overlay it with the coordinate grid. Reduce the display viewport in order to leave space around the edge of the displayed image for the labels and titles.
cl> display image 1 xsize=0.8 ysize=0.8 fill+ cl> wcslab image 1 vl=.1 vr=.9 vb=.1 vt=.9
4. Repeat the previous example using a different combination of display and wcslab parameters to achieve the same goal.
cl> display image 1 xmag=0.8 ymag=0.8 cl> wcslab image 1
5. Display a section of the previous image and overlay it with a coordinate grid. Note that the same section should be specified in both cases.
cl> display image[101:700,101:700] 1 cl> wcslab image[101:700,101:700] 1
6. Display a 512 square image with a defined tangent plane sky projection in an 800 square frame buffer and overlay the labeled coordinate grid. The standard FITS keywords shown below define the WCS. This WCS is approximately correct for the IRAF test image dev$pix.
# IRAF image header keywords which define the WCS CRPIX1 = 257.75 CRPIX2 = 258.93 CRVAL1 = 201.94541667302 # RA is stored in degrees ! CRVAL2 = 47.45444 CTYPE1 = 'RA---TAN' CTYPE2 = 'DEC--TAN' CDELT1 = -2.1277777E-4 CDELT2 = 2.1277777E-4 cl> display dev$pix 1 cl> wcslab dev$pix 1
7. Display a 512 square image with a defined tangent plane sky projection approximately centered on the north celestial pole in an 800 square frame buffer. The FITS keywords shown below define the WCS.
# IRAF image header keywords which define the WCS CRPIX1 = 257.75 CRPIX2 = 258.93 CRVAL1 = 201.94541667302 # RA is stored in degrees ! CRVAL2 = 90.00000 CTYPE1 = 'RA---TAN' CTYPE2 = 'DEC--TAN' CDELT1 = -2.1277777E-4 CDELT2 = 2.1277777E-4 cl> display northpole 1 cl> wcslab northpole 1
8. Display and label a 512 square image which has no WCS information using the values of the parameters in wcspars. The center pixel (256.0, 256.0) is located at (9h 22m 30.5s, -15o 05m 42s), the pixels are .10 arcseconds in size, and are rotated 30.0 degrees counter-clockwise.
cl> lpar wcspars ctype1 = 'ra---tan' ctype2 = 'dec--tan' crpix1 = 256.0 crpix2 = 256.0 crval1 = 140.62708 crval2 = -15.09500 cd1_1 = -2.405626e-5 cd1_2 = 1.388889e-5 cd2_1 = 1.388889e-5 cd2_2 = 2.405626e-5 log_x1 = 1. log_x2 = 512. log_y1 = 1. log_y2 = 512. cl> display image 1 cl> wcslab image usewcs+
The WCSLAB task was written by members of the STScI SDAS programming group and integrated into the IRAF DISPLAY package by members of the IRAF programming group for version 2.10 IRAF.
display, gcur, imdkern