Initial commit

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