diff options
Diffstat (limited to 'pkg/images/imcoords/doc/wcsctran.hlp')
| -rw-r--r-- | pkg/images/imcoords/doc/wcsctran.hlp | 340 |
1 files changed, 340 insertions, 0 deletions
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 |