diff options
Diffstat (limited to 'pkg/images/immatch/doc/skyxymatch.hlp')
| -rw-r--r-- | pkg/images/immatch/doc/skyxymatch.hlp | 406 |
1 files changed, 406 insertions, 0 deletions
diff --git a/pkg/images/immatch/doc/skyxymatch.hlp b/pkg/images/immatch/doc/skyxymatch.hlp new file mode 100644 index 00000000..63485284 --- /dev/null +++ b/pkg/images/immatch/doc/skyxymatch.hlp @@ -0,0 +1,406 @@ +.help skyxymatch Dec96 images.immatch +.ih +NAME +skyxymatch -- match input and reference image x-y coordinates using the +celestial coordinate WCS +.ih +USAGE +skyxymatch input reference output +.ih +PARAMETERS +.ls input +The list of input images containing the input celestial coordinate wcs. +.le +.ls reference +The list of reference images containing the reference celestial coordinate +wcs. The number of reference images must be one or equal to the number +of input images. +.le +.ls output +The output matched coordinate lists containing: +1) the logical x-y pixel coordinates of a point +in the reference image in columns 1 and 2, 2) the logical x-y pixel +coordinates of the same point in the input image in columns 3 and 4, +3) the world coordinates of the point in the reference image in columns +5 and 6, and 4) the world coordinate of the point in the input image in +columns 7 and 8. The output coordinate list can be +input directly to the geomap task. The number of output files must be +equal to the number of input images or be the standard output STDOUT. +.le +.ls coords = "grid" +The source of the coordinate list. The options are: +.ls grid +Generate a list of \fInx * ny\fR coordinates evenly spaced over +the reference image, and beginning and ending at logical coordinates +\fIxmin\fR and \fIxmax\fR in x and \fIymin\fR and \fIymax\fR in y. +.le +.ls <filename> +The name of the text file containing the world coordinates of a set of +points in the reference image. +.le +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +The minimum and maximum logical x and logical y coordinates used to generate +the grid of control points if \fIcoords\fR = "grid". Xmin, xmax, ymin, and +ymax default to 1, the number of columns in the reference image, 1, and the +number of lines in the reference image, respectively. +.le +.ls nx = 10, ny = 10 +The number of points in x and y used to generate the coordinate grid +if \fIcoords\fR = "grid". +.le +.ls wcs = "world" +The world coordinate system of the coordinates. The options are: +.ls physical +Physical coordinates are pixel coordinates which are invariant with +respect to linear transformations of the physical image data. For example, +if the reference +image is a rotated section of a larger input image, the physical +coordinates of an object in the reference image are equal to the physical +coordinates of the same object in the input image, although the logical +pixel coordinates are different. +.le +.ls world +World coordinates are image coordinates which are invariant with +respect to linear transformations of the physical image data and which +are in decimal degrees for the celestial coordinate systems. Obviously if the +wcs is correct the ra and dec of an object +should remain 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. +Care must be taken that the wcs of the input and +reference images are compatible, e.g. it makes no sense to +match the coordinates of a 2D sky projection and a 2D spectral wcs. +.le +.le +.ls xcolumn = 1, ycolumn = 2 +The columns in the input coordinate list containing the x and y coordinate +values if \fIcoords\fR = <filename>. +.le +.ls xunits = "", ls yunits = "" +The units of the x and y coordinates in the input coordinate list +if \fIcoords\fR = <filename>, by default decimal degrees for celestial +coordinate systems, otherwise any units. +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 + +If the units are not specified the default is "native". +.le +.ls xformat = "%10.3f", yformat = "%10.3f" +The format of the output logical x and y reference and input pixel +coordinates in columns 1 and 2 and 3 and 4 respectively. By default the +coordinates are output right justified in a field of ten spaces with +3 digits following the decimal point. +.le +.ls rwxformat = "", rwyformat = "" +The format of the output world x and y reference image coordinates +in columns 5 and 6 respectively. The internal default formats will give +reasonable output formats and precision for sky projection coordinates. +.le +.ls wxformat = "", wyformat = "" +The format of the output world x and y input image coordinates +in columns 7 and 8 respectively. The internal default formats will give +reasonable output formats and precision for sky projection coordinates. +.le +.ls min_sigdigits = 7 +The minimum precision of the output coordinates if, the formatting parameters +are undefined, or the output world coordinate system is "world" and the wcs +cannot be decoded. +.le +.ls verbose = yes +Print messages about the progress of the task? +.le + +.ih +DESCRIPTION + +SKYXYMATCH matches the logical x and y pixel coordinates of a set of points +in the input image \fIinput\fR with the logical x and y pixels coordinates +of the same points in the reference image \fIreference\fR +using world celestial coordinate information +in the image headers. SKYXYMATCH writes its results to the +coordinate file \fIoutput\fR which is suitable for input to the GEOMAP task. +The input and reference images may be 1D or 2D but must both have +the same dimensionality. + +If \fIcoords\fR = "grid", SKYXYMATCH computes a grid of \fInx * ny\fR +logical x and y pixel coordinates evenly distributed over the +logical pixel space of the reference image defined by the +\fIxmin\fR, \fIxmax\fR, \fIymin\fR, \fIymax\fR parameters. +The logical x and y reference image pixel coordinates are transformed to +reference image celestial coordinates using +world coordinate information stored in the reference image header. +The reference image celestial coordinates are transformed to +input image celestial coordinates using world coordinate +system information in both the reference and the input image headers. +Finally the input image celestial coordinates are transformed to logical x and y +input image pixel coordinates using world coordinate system information +stored in the input image header. The transformation sequence looks +like the following for an equatorial celestial coordinate system: + +.nf + (x,y) reference -> (ra,dec) reference (reference image wcs) +(ra,dec) reference -> (ra,dec) input (reference and input image wcs) + (ra,dec) input -> (x,y) input (input image wcs) +.fi + +The reference and input image celestial coordinate systems +may be equatorial, ecliptic, galactic, or supergalactic. The equatorial systems +may be one of: 1) the mean place pre-IAU 1976 (FK4) system, 2) +the same as FK4 but without the E-terms (FK4-NO-E) system, 3) the mean +place post-IAU +1976 (FK5) system, 4) or the geocentric apparent place in the post-IAU 1976 +(GAPPT) system. + +SKYXYMATCH assumes that the celestial coordinate system is specified by the FITS +keywords CTYPE, CRPIX, CRVAL, CD (or alternatively CDELT / CROTA), RADECSYS, +EQUINOX (or EPOCH), MJD-WCS (or MJD-OBS, or DATE-OBS). USERS SHOULD TAKE NOTE +THAT MJD-WCS IS CURRENTLY NEITHER A STANDARD OR A PROPOSED STANDARD FITS +KEYWORD. HOWEVER IT OR SOMETHING SIMILAR, IS REQUIRED TO SPECIFY THE EPOCH OF +THE COORDINATE SYSTEM WHICH MAY BE DIFFERENT FROM THE EPOCH OF THE OBSERVATION. + +The first four characters of the values of the ra / longitude and dec / latitude +axis CTYPE keywords specify the celestial coordinate system. The currently +permitted values of CTYPE[1:4] are RA-- / DEC- for equatorial coordinate +systems, ELON / ELAT for the ecliptic coordinate system, GLON / GLAT for the +galactic coordinate system, and SLON / SLAT for the supergalactic coordinate +system. + +The second four characters of the values of the ra / longitude and dec / +latitude axis CTYPE keywords specify the sky projection geometry. IRAF +currently supports the TAN, SIN, ARC, and GLS geometries, and consequently the +currently permitted values of CTYPE[5:8] are -TAN, -ARC, -SIN, and -GLS. +SKYXYMATCH fully supports the TAN, SIN, and ARC projections, but does not fully +support the GLS projection. + +If the image celestial coordinate systems are equatorial, the value of the +RADECSYS keyword specifies which fundamental equatorial system is to be +considered. The permitted values of RADECSYS are FK4, FK4-NO-E, FK5, and GAPPT. +If the RADECSYS keyword is not present in the image header, the values of the +EQUINOX / EPOCH keywords (in that order of precedence) are used to determine +the fundamental equatorial coordinate system. EQUINOX or EPOCH contain the +epoch of the mean place and equinox for the FK4, FK4-NO-E, and FK5 systems +(e.g 1950.0 or 2000.0). The default equatorial system is FK4 if EQUINOX or +EPOCH < 1984.0, FK5 if EQUINOX or EPOCH >= 1984.0, and FK5 if RADECSYS, EQUINOX, +and EPOCH are undefined. If RADECSYS is defined but EQUINOX and EPOCH are not, +the equinox defaults to 1950.0 for the FK4 and FK4-NO-E systems, and 2000.0 for +the FK5 system. The equinox value is interpreted as a Besselian epoch for the +FK4 and FK4-NO-E systems, and as a Julian epoch for the FK5 system. Users are +strongly urged to use the EQUINOX keyword in preference to the EPOCH keyword, +if they must enter their own equinox values into the image header. The FK4 and +FK4-NO-E systems are not inertial and therefore also require the epoch of the +observation (the time when the mean place was correct), in addition to the +equinox. The epoch is specified, in order of precedence, by the values of the +keywords MJD-WCS or MJD-OBS (which contain the modified Julian date, JD - +2400000.5, of the coordinate system), or the DATE-OBS keyword (which contains +the date of the observation in the form DD/MM/YY, CCYY-MM-DD, +CCYY-MM-DDTHH:MM:SS.S). As the latter quantity is +only accurate to a day, the MJD-WCS or MJD-OBS specification is preferred. +If all 3 keywords are absent the epoch defaults to the value of equinox. +Equatorial coordinates in the GAPPT system require only the specification +of the epoch of observation which is supplied via the MJD-WCS, MJD-OBS, +or DATE-OBS keywords (in that order of precedence) as for the FK4 and +FK4-NO-E system. + +If the image celestial coordinate systems are ecliptic the mean ecliptic +and equinox of date are required. These are read from the MJD-WCS, MJD-OBS, +or DATE-OBS keywords (in that order or precedence) as for the equatorial FK4, +FK4-NO-E, and GAPPT systems. + +USERS NEED TO BE AWARE THAT THE IRAF IMAGE WORLD COORDINATE SYSTEM +CURRENTLY (IRAF VERSIONS 2.10.4 PATCH 2 AND EARLIER) SUPPORTS ONLY THE +EQUATORIAL SYSTEM (CTYPE<lngax> = "RA--XXXX" CTYPE<latax> = "DEC-XXXX") +WHERE XXXX IS THE PROJECTION TYPE, EVEN THOUGH THE SKYXYMATCH TASK +SUPPORTS GALACTIC, SUPERGALACTIC, AND ECLIPTIC coordinate systems. + +If \fIcoords\fR is a file name, SKYXYMATCH reads a list of x and y +reference image world coordinates from columns \fIxcolumn\fR and \fIycolumn\fR +in the input coordinates file and transforms these coordinates to +"native" coordinate units using the \fIxunits\fR and \fIyunits\fR parameters. +The reference image world coordinates are +transformed to logical reference and input image coordinates +using the value of the \fIwcs\fR parameter and world coordinate +information in the reference and input image headers. + +SKYXYMATCH will terminate with an error if the reference and input images +are not both either 1D or 2D. +If the world coordinate system information cannot be read from either +the reference or input image header, the requested transformations +from the world <-> logical coordinate systems cannot be compiled for either +or both images, or the world coordinate systems of the reference and input +images are fundamentally incompatible in some way, the output logical +reference and input image coordinates are both set to a grid of points +spanning the logical pixel space of the input, not the reference image, +and defining an identify transformation, is written to the output file. + +The computed reference and input logical and world coordinates +are written to the output file using +the \fIxformat\fR and \fIyformat\fR, \fIrwxformat\fr, \fIrwyformat\fR, +and the \fIwxformat\fR and \fIwxformat\fR +parameters respectively. If these formats are undefined and, in the +case of the world coordinates, a format attribute cannot be +read from either the reference or the input images reasonable defaults are +chosen. + +If the reference and input images are 1D then the +output logical and world y coordinates are +set to 1. + +If \fIverbose\fR is "yes" then a title section is written to the output +file for each set of computed coordinates, along with messages about +what if anything went wrong with the computation. + +.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 including +more detailed descriptions of the "logical", "physical", and "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 draft paper "World Coordinate Systems Representations Within the +FITS Format" by Hanisch and Wells, available from the iraf anonymous ftp +archive and the draft paper which supersedes it "Representations of Celestial +Coordinates in FITS" by Greisen and Calabretta available from the NRAO +anonymous ftp archives. + +The spherical astronomy routines employed here are derived from the Starlink +SLALIB library provided courtesy of Patrick Wallace. These routines +are very well documented internally with extensive references provided +where appropriate. Interested users are encouraged to examine the routines +for this information. Type "help slalib" to get a listing of the SLALIB +routines, "help slalib opt=sys" to get a concise summary of the library, +and "help <routine>" to get a description of each routine's calling sequence, +required input and output, etc. An overview of the library can be found in the +paper "SLALIB - A Library of Subprograms", Starlink User Note 67.7 +by P.T. Wallace, available from the Starlink archives. + +.ih +EXAMPLES + +1. Compute a matched list of 100 logical x and y coordinates for an X-ray +and radio image of the same field, both of which have accurate sky +projection world coordinate systems with different equinoxes. Print the +output world coordinates in hh:mm:ss.ss and dd:mm:ss.s format + +.nf + cl> skyxymatch image refimage coords rwxformat=%12.2H \ + rwyformat=%12.1h wxformat=%12.2H wyformat=%12.1h +.fi + +2. Given a list of ras and decs of objects in the reference image, +compute a list of matched logical x and y coordinates for the two images, +both of which have a accurate sky projection wcss, although the reference +wcs is in equatorial coordinates and the input wcs is in galactic +coordinates. The ras and decs are in +columns 3 and 4 of the input coordinate file and are in hh:mm:ss.ss and +dd:mm:ss.s format respectively. Print the output world coordinates +in the same units as the input. + +.nf + cl> skyxymatch image refimage coords coords=radecs \ + xcolumn=3 ycolumn=4 xunits=hours rwxformat=%12.2H \ + rwyformat=%12.1h wxformat=%12.2H wyformat=%12.1h +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +skyctran,wcsctran,geomap,geotran,skymap,sregister +.endhelp |