Repatch (from linux) of OSX IRAF

1 files changed, 272 insertions, 0 deletions

diff --git a/pkg/proto/doc/wcsreset.hlp b/pkg/proto/doc/wcsreset.hlp
new file mode 100644
index 00000000..6725aa7a
--- /dev/null
+++ b/pkg/proto/doc/wcsreset.hlp
@@ -0,0 +1,272 @@
+.help wcsreset Apr92 proto
+.ih
+NAME
+wcsreset -- reset the image coordinate system
+.ih
+USAGE
+wcsreset image wcs
+.ih
+PARAMETERS
+.ls image
+The list of images for which the coordinate system is to be reset.  Image
+sections are ignored.
+.le
+.ls wcs    
+The name of the coordinate system to be reset. The following systems are
+pre-defined:
+.ls physical
+Reset the physical coordinate system to the logical coordinate system, but
+leave the default world coordinate system unchanged.  This operation removes
+the history of past image operations such as imcopy, imshift, magnify, etc
+from the definition of the physical coordinate system, but not from the
+definition of the world coordinate system.
+.le
+.ls world
+Reset the default world coordinate system to the logical coordinate system.
+This operation removes all world coordinate system information from the
+image header.
+.le
+
+In addition to these two reserved world coordinate systems, the name of any
+other defined world coordinate system, for example "multispec" may be given.
+In this case WCSRESET resets the named coordinate system to the logical
+coordinate system only if it is present in the image header.
+.le
+.ls verbose = yes
+Print messages about actions taken by the task?
+.le
+.ih
+DESCRIPTION
+
+WCSRESET resets the coordinate system \fIwcs\fR in the images specified by
+\fIimage\fR to the logical coordinate system, and prints messages about the
+actions taken if \fIverbose\fR = "yes". Since WCSRESET modifies the
+image headers it should be used with caution.
+
+Logical coordinates are coordinates relative to the current image.  The
+logical coordinate system is the one used by the image input/output routines
+to access the image on disk.  In an image raster logical coordinate system,
+the coordinates of the pixel centers must lie within the following
+range: 1.0 <= x[i] <= nx[i], where x[i] is the coordinate in dimension i,
+nx[i] is the size of the image in dimension i, and the current maximum
+number of image dimensions is 7. In the case of an image section of an image
+raster, the nx[i] refer to the dimensions of the section, not the dimensions
+of the full image. The logical coordinate system cannot by definition be
+reset.
+
+The physical coordinate system is the coordinate system in which the
+coordinates of an object are invariant to successive linear transformations
+of the image. In this coordinate system, the pixel coordinates of an object
+in an image raster remain the same, regardless of any imcopy, imshift,
+rotate, etc operations on the image. The most common reason for desiring to
+reset the physical coordinate system to the logical coordinate system is to
+make the new image independent of its history by removing the effects of
+these linear transformation operations from its physical coordinate system.
+Resetting the physical coordinate system to the logical coordinate system,
+does not alter the default world coordinate system. If for example the input
+image is a spectrum, with a defined dispersion solution, resetting the
+physical coordinate system will not alter the dispersion solution.
+Similarly if the input image is a direct CCD image with a defined sky
+projection world coordinate system, resetting the physical coordinate system
+will not alter the sky projection.
+
+The world coordinate system is the default coordinate system for the
+image. The default world coordinate system is the one named by the
+environment variable "defwcs" if defined in the user environment (initially
+it is undefined) and present in the image header; else it is the first
+world coordinate system
+defined for the image (the .imh and .hhh image format support only one wcs
+but the .qp format can support more); else it is the physical coordinate
+system.  Resetting the default coordinate system to the logical
+coordinate system will destroy all coordinate information for that system,
+for that image.
+
+If the user sets the parameter wcs to a specific system, for example
+to "multispec", only images with the coordinate system "multispec"
+will have their coordinate system reset.
+
+.ih
+REFERENCES
+
+Detailed documentation for the IRAF world coordinate system interface MWCS
+can be found in the file "iraf$sys/mwcs/MWCS.hlp". This file can be
+formatted and printed with the command "help iraf$sys/mwcs/MWCS.hlp fi+ |
+lprint".  Details of the FITS header world coordinate system interface can
+be found in the document "World Coordinate Systems Representations Within the
+FITS Format" by Hanisch and Wells, available from our anonymous ftp
+archive.
+
+.ih
+EXAMPLES
+
+1. The user runs implot on a section of the spectrum outspec with the
+wcs parameter set to "physical".
+
+.nf
+	implot outsec[30:50] wcs=physical
+.fi
+
+To his/her surprise the range of the plot in x produced by implot is
+[129,149] not [30:50] as expected.  The user lists the image header with the
+imheader task and sees the following.
+
+.nf
+        WCSDIM  =                    1
+        CTYPE1  = 'LINEAR  '
+        CRVAL1  =     4953.94775390626
+        CRPIX1  =                 -98.
+        CDELT1  =   0.0714096948504449
+        CD1_1   =   0.0714096948504449
+        WAT0_001= 'system=linear
+        WAT1_001= 'wtype=linear label=Wavelength units=Angstroms 
+        LTV1    =                 -99.
+        LTM1_1  =                   1.
+.fi
+
+The standard FITS keywords CTYPE1, CRVAL1, CRPIX1, and CDELT1 are present.
+The CD1_1 keyword is part of the new FITS CD matrix notation and in this
+example duplicates the function of CDELT1.  The remaining keywords WCSDIM,
+WAT0_001, WAT1_001, LTV1, and LTM1_1 are IRAF specific keywords. The
+user notes that the LTV1 keyword is -99. not 0. and suddenly remembers that
+outspec was created by extracting a piece of a larger spectrum using the
+imcopy task as shown below.
+
+.nf
+	cl> imcopy inspec[100:200] outspec
+.fi
+
+The section [30:50] in outspec actually corresponds to the section [129:149]
+in inspec and it is this coordinate system that implot is plotting when
+wcs = "physical". The user decides has he/she does not want to know
+about the pixel coordinate system of the original image and runs wcsreset
+to reset the physical coordinate system to the logical coordinate system.
+
+.nf
+	wcsreset outspec physical
+.fi
+
+The new header of outspec looks like the following.
+
+.nf
+    WCSDIM  =                    1
+    CTYPE1  = 'LINEAR  '
+    CRVAL1  =     4953.94775390626
+    CRPIX1  =                 -98.
+    CDELT1  =   0.0714096948504449
+    CD1_1   =   0.0714096948504449
+    WAT0_001= 'system=linear                                                    
+    WAT1_001= 'wtype=linear label=Wavelength units=Angstroms
+    LTM1_1  =                   1.
+.fi
+
+It is identical to the header listed above except that the
+LTV1 keyword is not defined and is therefore 0. The user runs
+implot with wcs = "physical" as before and sees a plot which extends
+from 30 to 50 as expected.
+
+2. Reset the physical coordinate system of the direct CCD image skypix
+which has a defined sky projection system. Skypix was created by
+copying the central [129:384,129:384] of a 512 square image into a 256
+square image.
+
+The image header is the following.
+
+.nf
+	CRPIX1  =               129.75
+        CRPIX2  =               130.93
+        CRVAL1  =      201.94541667302
+        CRVAL2  =             47.45444
+        CTYPE1  = 'RA---TAN'
+        CTYPE2  = 'DEC--TAN'
+        CDELT1  =        -2.1277777E-4
+        CDELT2  =         2.1277777E-4
+        WCSDIM  =                    2
+        CD1_1   =  -2.1277777000000E-4
+        CD2_2   =  2.12777770000000E-4
+        LTV1    =                -128.
+        LTV2    =                -128.
+        LTM1_1  =                   1.
+        LTM2_2  =                   1.
+        WAT0_001= 'system=image
+	WAT1_001= 'wtype=tan axtype=ra
+	WAT2_001= 'wtype=tan axtype=dec
+.fi
+
+The user runs implot on skypix wcs = "physical"
+
+.nf
+	implot skypix wcs=physical
+.fi
+
+and sees a plot in x which extends from 129 to 384 which are the coordinates
+of skypix in the original image.
+The user resets the physical coordinate system to the logical coordinate
+system.
+
+.nf
+	cl> wcsreset m51 physical
+.fi
+
+The new header looks like the following. Note that the LTV1 and LTV2 keywords
+have disappeared, they are 0. but everything else is the same.
+
+.nf
+	CRPIX1  =               129.75
+        CRPIX2  =               130.93
+        CRVAL1  =      201.94541667302
+        CRVAL2  =             47.45444
+        CTYPE1  = 'RA---TAN'
+        CTYPE2  = 'DEC--TAN'
+        CDELT1  =        -2.1277777E-4
+        CDELT2  =         2.1277777E-4
+        WCSDIM  =                    2
+        CD1_1   =  -2.1277777000000E-4
+        CD2_2   =  2.12777770000000E-4
+        LTM1_1  =                   1.
+        LTM2_2  =                   1.
+        WAT0_001= 'system=image
+	WAT1_001= 'wtype=tan axtype=ra
+	WAT2_001= 'wtype=tan axtype=dec
+.fi
+
+When the user runs implot with wcs = "physical" he/she sees a plot which
+extends from 1 to 256 as expected.
+
+3. Initialize the world coordinate system of the previous image.
+
+.nf
+	cl> wcsreset skypix world
+.fi
+
+The header now looks like the following.
+
+.nf
+	WCSDIM  =                    2
+	LTM1_1  =                   1.
+	LTM2_2  =                   1.
+	WAT0_001= 'system=physical               
+	WAT1_001= 'wtype=linear
+	WAT2_001= 'wtype=linear
+.fi
+
+The world system defaults to the physical coordinates system and the
+physical coordinate system is identical to the logical coordinate system.
+All coordinate information has been destroyed.
+
+4. Initialize the world coordinate system "spec1". If the default world
+coordinate
+system "spec1" cannot be found in the image header a warning message
+will be issued and nothing will be changed.
+
+.nf
+	cl> wcsreset spectrum spec1
+.fi
+
+.ih
+TIME REQUIREMENTS
+.ih
+BUGS
+.ih
+SEE ALSO
+rimcursor,listpixels,wcsedit,hedit,hfix
+.endhelp