From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- pkg/images/imcoords/doc/wcsreset.hlp | 272 +++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 pkg/images/imcoords/doc/wcsreset.hlp (limited to 'pkg/images/imcoords/doc/wcsreset.hlp') diff --git a/pkg/images/imcoords/doc/wcsreset.hlp b/pkg/images/imcoords/doc/wcsreset.hlp new file mode 100644 index 00000000..401e0ae0 --- /dev/null +++ b/pkg/images/imcoords/doc/wcsreset.hlp @@ -0,0 +1,272 @@ +.help wcsreset Apr92 images.imcoords +.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 -- cgit