From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 pkg/images/imcoords/doc/wcsctran.hlp | 340 +++++++++++++++++++++++++++++++++++
 1 file changed, 340 insertions(+)
 create mode 100644 pkg/images/imcoords/doc/wcsctran.hlp

(limited to 'pkg/images/imcoords/doc/wcsctran.hlp')

diff --git a/pkg/images/imcoords/doc/wcsctran.hlp b/pkg/images/imcoords/doc/wcsctran.hlp
new file mode 100644
index 00000000..c8ee4316
--- /dev/null
+++ b/pkg/images/imcoords/doc/wcsctran.hlp
@@ -0,0 +1,340 @@
+.help wcsctran May95 images.imcoords
+.ih
+NAME
+wcsctran -- use the image WCS to transform between IRAF coordinate systems
+.ih
+USAGE
+wcsctran input output image inwcs outwcs
+.ih
+PARAMETERS
+.ls input
+The list of input coordinate files. The number of input coordinate
+files must be one or equal to the number of input images. Coordinates
+may be entered by hand by setting input to "STDIN".
+.le
+.ls output
+The list of output coordinate files. The number of coordinate files
+must be one or equal to the number of input images. Results may be printed
+on the terminal by setting output to "STDOUT".
+.le
+.ls image
+The list of input images containing the WCS information.
+.le
+.ls inwcs, outwcs
+The input and output coordinate systems. Coordinates in the input
+file are assumed to be in the input system. Coordinates are written to
+the output file in the output system. The options are:
+.ls logical
+Logical coordinates are pixel coordinates relative to the current
+image. The logical coordinate system is the coordinate system used by
+the image input/output routines to access the image data on disk.
+.le
+.ls tv    
+Tv coordinates are pixel coordinates used by the ximtool and saoimage
+display servers.
+Tv coordinates include the effects of any input image section, but
+do not include the effects of previous linear transformations.
+If the input image name does not include an image section, then tv coordinates
+are identical to logical coordinates. If the input image name does include
+a section, and the input image has not been linearly transformed or 
+copied from a parent image, tv coordinates are identical to physical
+coordinates.
+.le
+.ls physical
+Physical coordinates are pixel coordinates invariant with respect to linear
+transformations of the physical image data.  For example, if the current
+image was created by extracting a section of another image, the physical
+coordinates of an object in the current image will be equal to the physical
+coordinates of the same object in the parent image, although the logical
+coordinates will be different.
+.le
+.ls world
+World coordinates are image coordinates in any units which are invariant with
+respect to linear transformations of the physical image data. For example, 
+the ra and dec of an object will always be the same no matter how the image
+is linearly transformed. The default world coordinate
+system is either 1) the value of the environment variable "defwcs" if
+set in the user's IRAF environment (normally it is undefined) and present
+in the image header, 2) the value of the "system"
+attribute in the image header keyword WAT0_001 if present in the
+image header or, 3) the "physical" coordinate system.
+.le
+.le
+.ls columns = "1 2 3 4 5 6 7"
+The list of columns separated by whitespace or commas in the input coordinate
+file containing the coordinate values.
+The number of specified columns must be greater than or equal to the
+dimensionality of the input image. The coordinates are read in the
+order they are specified in the columns parameter.
+.le
+.ls units = ""
+The units of the input coordinate values, normally degrees for the sky
+projection coordinate systems and angstroms for spectral coordinate
+systems. 
+The options are:
+.ls hours
+Input coordinates specified in hours are converted to decimal degrees by
+multiplying by 15.0.
+.le
+.ls native
+The internal units of the wcs. No conversions on the input coordinates
+are performed.
+.le
+
+Units conversions are performed only if the input wcs is "world".
+.le
+.ls formats = ""
+The format for the computed output coordinates. If the formats
+parameter is undefined then: 1) the value of the wcs format attribute
+is used if the output wcs is "world" and the attribute is defined, 2)
+%g format is used with the precision set to the maximum of the precision of
+the input coordinates and the value of the min_sigdigits parameter.
+.le
+.ls min_sigdigits = 7
+The minimum precision of the output coordinates if, the formats parameter
+is undefined, and the output coordinate system is "world" but the wcs
+format attribute is undefined.
+.le
+.ls verbose = yes
+Print comment lines to the output file as the task executes.
+.le
+
+.ih
+DESCRIPTION
+
+WCSCTRAN transforms a list of coordinates, read from  the input file
+\fIinput\fR, from the coordinate system defined by \fIinwcs\fR to the
+coordinate system defined by \fIoutwcs\fR using world coordinate system
+information in the input image \fIimage\fR header and writes the results
+to the output file \fIoutput\fR.
+
+The input coordinates are read from and written to the
+columns in the input / output file specified by the \fIcolumns\fR parameter. 
+The units of the input coordinate units are assumed to be the internal
+units of the coordinate system as defined in the image header, normally
+degrees for sky projection coordinate systems and angstroms for
+spectral coordinate systems. For convenience input coordinates in hours
+are accepted and converted to decimal degrees if the \fIunits\fR parameter
+is set appropriately.
+
+The format of the output units can be set using the
+\fIformats\fR parameter. If the  output formats are unspecified then the
+output coordinates are written using, 1) the value of wcs format attribute if
+outwcs = "world" and the attribute is defined, or, 2) the %g format and a 
+precision which is the maximum of the precision of the input coordinates
+and the value of the \fImin_sigdigits\fR parameter. All remaining
+fields in the input file are copied to the output file without modification.
+
+WCSCTRAN transforms coordinates from one builtin IRAF coordinate system
+to another.  The builtin coordinate systems are "logical", "physical", and
+"world". For convenience WCSCTRAN also supports the "tv" coordinate system
+which is not a builtin IRAF system, but is used by the display server tasks
+XIMTOOL, SAOIMAGE, and IMTOOL.
+
+The \fIlogical coordinate system\fR is the pixel coordinate system of the
+current image. This coordinate system is the one used by the image
+input/output routines to access the image on disk. In the
+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,
+the nx[i] refer to the dimensions of the section, not the dimensions
+of the full image.
+
+The \fItv coordinate system\fR is the pixel coordinate system used by the
+display servers XIMTOOL, SAOIMAGE, and IMTOOL. 
+For images which are not image sections
+the tv and logical coordinate systems are identical. For images which are
+image sections the tv and physical coordinate systems are identical if
+the image has not undergone any prior linear transformations such as
+axis flips, section copies, shifts, scale changes, rotations, etc.
+
+The \fIphysical coordinate system\fR is the coordinate system in which the
+pixel 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 remain the same, regardless of any section copies, shifts,
+rotations, etc on the image. For example, an object with the
+physical coordinates (x,y) in an image would still have physical 
+coordinates (x, y) in an image which is a section of the original image.
+
+The \fIworld coordinate system\fR 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.
+
+In most cases the number of input coordinates is equal to the number of
+output coordinates, and both are equal to the dimensions of the input image.
+In some cases however, the number of output coordinates may be greater or
+less than the number of input coordinates. This situation occurs
+if the input image has been dimensionally-reduced, i.e. is a section
+of a higher-dimensioned parent image, and the input coordinate system
+or the output coordinate system but not both is "logical" or "tv".
+For example, if the input image is a 1D line extracted from a 2D parent
+image with a sky projection world coordinate system, and the user
+specifies a transformation from the "logical" to "world" systems, 
+only one input coordinate (column number) is required, but two output
+coordinates (ra and dec) are produced. If the input and output coordinate
+systems are reversed, then two input coordinates (ra and dec) are required,
+but only one output coordinate (column number) is produced. If the number of
+output coordinates is less than the number of input coordinates, the extra
+input coordinate columns in the input file are set to INDEF in the output file.
+If the number of output columns is greater than the number of input columns,
+the extra coordinate columns are added to the end of the output line.
+
+.ih
+FORMATS
+
+A  format  specification has the form "%w.dCn", where w is the field
+width, d is the number of decimal places or the number of digits  of
+precision,  C  is  the  format  code,  and  n is radix character for
+format code "r" only.  The w and d fields are optional.  The  format
+codes C are as follows:
+  
+.nf
+b       boolean (YES or NO)
+c       single character (c or '\c' or '\0nnn')
+d       decimal integer
+e       exponential format (D specifies the precision)
+f       fixed format (D specifies the number of decimal places)
+g       general format (D specifies the precision)
+h       hms format (hh:mm:ss.ss, D = no. decimal places)
+m       minutes, seconds (or hours, minutes) (mm:ss.ss)
+o       octal integer
+rN      convert integer in any radix N
+s       string (D field specifies max chars to print)
+t       advance To column given as field W
+u       unsigned decimal integer
+w       output the number of spaces given by field W
+x       hexadecimal integer
+z       complex format (r,r) (D = precision)
+  
+
+Conventions for w (field width) specification:
+  
+    W =  n      right justify in field of N characters, blank fill
+        -n      left justify in field of N characters, blank fill
+        0n      zero fill at left (only if right justified)
+absent, 0       use as much space as needed (D field sets precision)
+  
+Escape sequences (e.g. "\n" for newline):
+  
+\b      backspace   (not implemented)
+\f      formfeed
+\n      newline (crlf)
+\r      carriage return
+\t      tab
+\"      string delimiter character
+\'      character constant delimiter character
+\\      backslash character
+\nnn    octal value of character
+  
+Examples
+  
+%s          format a string using as much space as required
+%-10s       left justify a string in a field of 10 characters
+%-10.10s    left justify and truncate a string in a field of 10 characters
+%10s        right justify a string in a field of 10 characters
+%10.10s     right justify and truncate a string in a field of 10 characters
+  
+%7.3f       print a real number right justified in floating point format
+%-7.3f      same as above but left justified
+%15.7e      print a real number right justified in exponential format
+%-15.7e     same as above but left justified
+%12.5g      print a real number right justified in general format
+%-12.5g     same as above but left justified
+
+%h          format as nn:nn:nn.n
+%15h        right justify nn:nn:nn.n in field of 15 characters
+%-15h       left justify nn:nn:nn.n in a field of 15 characters
+%12.2h      right justify nn:nn:nn.nn
+%-12.2h     left justify nn:nn:nn.nn
+  
+%H          / by 15 and format as nn:nn:nn.n
+%15H        / by 15 and right justify nn:nn:nn.n in field of 15 characters
+%-15H       / by 15 and left justify nn:nn:nn.n in field of 15 characters
+%12.2H      / by 15 and right justify nn:nn:nn.nn
+%-12.2H     / by 15 and left justify nn:nn:nn.nn
+
+\n          insert a newline
+.fi
+
+
+.ih
+REFERENCES
+
+Additional information on IRAF world coordinate systems can be found in
+the help pages for the WCSEDIT and WCRESET tasks.
+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. Find the pixel coordinates of a list of objects in an image, given a list
+of their ras and decs in hh:mm:ss.s and dd:mm:ss format. Limit the precision
+of the output coordinates to 3 decimal places. In this example, the input
+ras and decs are assumed to be in columns 1 and 2 of the input coordinate
+file, and the ras must be converted from hours to decimal degrees.
+
+.nf
+	im> wcsctran incoords outcoords image world logical units="h n" \
+	    formats="%8.3f %0.3f"
+.fi
+
+2. Repeat the previous example using the same input coordinate list to
+produce output coordinate lists for a list of input images.
+
+.nf
+	im> wcsctran incoords @outcoolist @imlist world logical units="h n" \
+	    formats="%8.3f %8.3f"
+.fi
+
+3. Transform pixel coordinates in a photometry file to ra and dec
+coordinates, writing the output coordinates in hh:mm:ss.ss and dd:mm:ss.s
+format. The input pixel coordinates are stored in columns 3 and 4 of the
+input coordinate file.
+
+.nf
+	im> wcsctran magfile omagfile image logical world col="3 4" \
+	    formats="%12.2H %12.1h"
+.fi
+
+4. Given a set of pixel coordinates in the parent image, find the pixel
+coordinates of the same objects in an image which is a shifted, rotated
+and scaled version of the parent image. The input coordinate list
+is created using the displayed parent image and the rimcursor task. 
+The output coordinate lists is marked on the displayed transformed 
+image using the tvmark task.
+
+.nf
+	im> display parent 1 fi+
+	im> rimcursor > coolist
+	im> imlintran parent image 45.0 45.0 1.5 1.5 xin=256 yin=256 \
+	    xout=281 yout=263
+	im> wcsctran coolist ocoolist image physical logical
+	im> display image 2 fi+
+	im> tvmark 2 outcoolist
+.fi
+
+.ih
+TIME REQUIREMENTS
+
+.ih
+BUGS
+
+.ih
+SEE ALSO
+wcsreset, wcsedit, rimcursor, listpixels, lintran
+
+.endhelp
-- 
cgit 

